mengstack-website/api/overview.md

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	获取当前用户，详见认证接口
系统	GET /health	健康检查，详见系统接口
系统	GET /ping	连通性测试，详见系统接口

Swagger UI

启动服务后访问 http://localhost:2222/swagger/index.html 查看交互式 API 文档。