---
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 文档。