| title |
| API接口概览 | 统一响应格式与错误码说明 - MengStack官方文档 |
API 概览
MengStack API 基于 RESTful 设计，所有接口统一前缀 /api/v1。
基础信息
| 项目 |
值 |
| Base URL |
http://localhost:2222/api/v1 |
| 数据格式 |
JSON |
| 认证方式 |
Bearer Token (JWT) |
| API 文档 |
http://localhost:2222/swagger/index.html |
统一响应格式
所有接口返回统一格式：
{
"code": 0,
"message": "success",
"data": {},
"trace_id": "req-abc-123"
}
| 字段 |
类型 |
说明 |
code |
int |
状态码，0 表示成功 |
message |
string |
状态描述 |
data |
any |
响应数据 |
trace_id |
string |
请求追踪 ID |
错误码
| HTTP 状态码 |
说明 |
| 200 |
成功 |
| 400 |
请求参数错误 |
| 401 |
未认证或 Token 过期 |
| 403 |
无权限 |
| 404 |
资源不存在 |
| 409 |
资源冲突（如邮箱已注册） |
| 500 |
服务器内部错误 |
认证
需要认证的接口，在请求头中携带：
Authorization: Bearer <access_token>
X-Tenant-ID: <tenant_id>
接口列表
认证模块
| 方法 |
端点 |
说明 |
| POST |
/auth/register |
用户注册，详见认证接口 |
| POST |
/auth/login |
用户登录，详见认证接口 |
| POST |
/auth/refresh |
刷新令牌，详见认证接口 |
| POST |
/password |
修改密码，详见认证接口 |
| GET |
/profile |
获取当前用户，详见认证接口 |
RBAC 权限模块
| 方法 |
端点 |
说明 |
| GET |
/api/v1/rbac/permissions |
列出权限，详见RBAC 接口 |
| POST |
/api/v1/rbac/roles |
创建角色 |
| GET |
/api/v1/rbac/roles |
列出角色 |
| GET |
/api/v1/rbac/roles/:id |
获取角色详情 |
| PUT |
/api/v1/rbac/roles/:id |
更新角色 |
| DELETE |
/api/v1/rbac/roles/:id |
删除角色 |
| PUT |
/api/v1/rbac/roles/:id/permissions |
设置角色权限 |
| GET |
/api/v1/rbac/roles/:id/permissions |
获取角色权限 |
| POST |
/api/v1/rbac/users/:userId/roles |
分配角色给用户 |
| DELETE |
/api/v1/rbac/users/:userId/roles/:roleId |
移除用户角色 |
| GET |
/api/v1/rbac/users/:userId/roles |
获取用户角色 |
组织管理模块
| 方法 |
端点 |
说明 |
| POST |
/api/v1/org/tenants |
创建租户，详见组织管理接口 |
| GET |
/api/v1/org/tenants |
列出所有租户 |
| GET |
/api/v1/org/tenants/:id |
获取租户详情 |
| PUT |
/api/v1/org/tenants/:id |
更新租户 |
| DELETE |
/api/v1/org/tenants/:id |
删除租户 |
审计日志模块
| 方法 |
端点 |
说明 |
| GET |
/api/v1/audit/logs |
查询审计日志，详见审计日志接口 |
配置管理模块
| 方法 |
端点 |
说明 |
| GET |
/api/v1/settings |
列出全局配置，详见配置管理接口 |
| GET |
/api/v1/settings/global/:key |
获取全局配置 |
| PUT |
/api/v1/settings/global/:key |
更新全局配置 |
| GET |
/api/v1/settings/tenant |
列出租户配置 |
| GET |
/api/v1/settings/tenant/:key |
获取租户配置 |
| PUT |
/api/v1/settings/tenant/:key |
更新租户配置 |
| DELETE |
/api/v1/settings/tenant/:key |
删除租户配置 |
通知模块
| 方法 |
端点 |
说明 |
| POST |
/api/v1/notifications |
创建通知，详见通知接口 |
| GET |
/api/v1/notifications/:id |
获取通知详情 |
| GET |
/api/v1/notifications/user/:userId |
获取用户通知列表 |
| PUT |
/api/v1/notifications/:id/read |
标记通知已读 |
| PUT |
/api/v1/notifications/read-all |
全部标记已读 |
| GET |
/api/v1/notifications/unread-count |
获取未读数量 |
| DELETE |
/api/v1/notifications/:id |
删除通知 |
系统模块
| 方法 |
端点 |
说明 |
| GET |
/health |
健康检查，详见系统接口 |
| GET |
/ping |
连通性测试，详见系统接口 |
Swagger UI
启动服务后访问 http://localhost:2222/swagger/index.html 查看交互式 API 文档。
fca3326e34