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