fca3326e34
- 更新 changelog.md: v0.2.0 记录 M2-M8 全部完成，路线图更新 - 新增 5 篇指南: RBAC、组织管理、审计日志、通知模块、质量横切 - 新增 5 篇 API 文档: RBAC(11)、Org(5)、Audit(1)、Settings(7)、Notification(7) - 更新 api/overview.md: 完整 37 端点列表 - 更新 config.ts: 侧边栏分组 + 11 页 SEO 元数据
137 lines
4.3 KiB
Markdown
137 lines
4.3 KiB
Markdown
---
|
||
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` |
|
||
|
||
## 统一响应格式
|
||
|
||
所有接口返回统一格式：
|
||
|
||
```json
|
||
{
|
||
"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` | 用户注册，详见[认证接口](/api/auth) |
|
||
| POST | `/auth/login` | 用户登录，详见[认证接口](/api/auth) |
|
||
| POST | `/auth/refresh` | 刷新令牌，详见[认证接口](/api/auth) |
|
||
| POST | `/password` | 修改密码，详见[认证接口](/api/auth) |
|
||
| GET | `/profile` | 获取当前用户，详见[认证接口](/api/auth) |
|
||
|
||
### RBAC 权限模块
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/rbac/permissions` | 列出权限，详见[RBAC 接口](/api/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` | 创建租户，详见[组织管理接口](/api/org) |
|
||
| 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` | 查询审计日志，详见[审计日志接口](/api/audit) |
|
||
|
||
### 配置管理模块
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/settings` | 列出全局配置，详见[配置管理接口](/api/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` | 创建通知，详见[通知接口](/api/notification) |
|
||
| 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` | 健康检查，详见[系统接口](/api/system) |
|
||
| GET | `/ping` | 连通性测试，详见[系统接口](/api/system) |
|
||
|
||
## Swagger UI
|
||
|
||
启动服务后访问 `http://localhost:2222/swagger/index.html` 查看交互式 API 文档。
|