74 lines
1.9 KiB
Markdown
74 lines
1.9 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) |
|
||
| 系统 | `GET /health` | 健康检查，详见[系统接口](/api/system) |
|
||
| 系统 | `GET /ping` | 连通性测试，详见[系统接口](/api/system) |
|
||
|
||
## Swagger UI
|
||
|
||
启动服务后访问 `http://localhost:2222/swagger/index.html` 查看交互式 API 文档。
|