mirror of
https://github.com/EZ-Api/ez-api.git
synced 2026-01-13 17:47:51 +00:00
8331fab8d5
Add comprehensive documentation for the API response structure, including the standard envelope format, business code ranges, and client handling guidelines.
117 lines
2.9 KiB
Markdown
117 lines
2.9 KiB
Markdown
# EZ-API Response Envelope 规范
|
||
|
||
本文档定义响应信封结构及业务码表。HTTP 状态码保留用于传输层语义。
|
||
|
||
## Envelope 结构
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": { "user_id": 123, "name": "example" },
|
||
"trace_id": "req_abc123"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `code` | number | ✅ | 业务码，0=成功，非0=错误 |
|
||
| `message` | string | ✅ | 成功时 `"success"`，错误时具体描述 |
|
||
| `data` | object/array/null | ✅ | 成功时返回业务数据，错误时为 `null` |
|
||
| `trace_id` | string | ✅ | 请求追踪 ID，复用 `X-Request-ID` 或自动生成 |
|
||
| `details` | object/null | ❌ | 可选，错误时的补充信息（如字段级校验错误） |
|
||
|
||
## 业务码表
|
||
|
||
### 码段划分
|
||
|
||
| 范围 | 类别 | 说明 |
|
||
|------|------|------|
|
||
| 0 | 成功 | 请求成功 |
|
||
| 1000-1999 | 通用错误 | 参数错误、认证失败等通用场景 |
|
||
| 4000-4999 | 客户端错误 | 业务级客户端错误 |
|
||
| 5000-5999 | 服务端错误 | 服务端内部错误 |
|
||
|
||
### 通用错误 (1xxx)
|
||
|
||
| Code | 名称 | HTTP Status | 说明 |
|
||
|------|------|-------------|------|
|
||
| 1001 | invalid_param | 400 | 参数校验失败 |
|
||
| 1002 | unauthorized | 401 | 未认证或认证失效 |
|
||
| 1003 | forbidden | 403 | 无权限访问 |
|
||
| 1004 | rate_limited | 429 | 请求频率超限 |
|
||
|
||
### 客户端错误 (4xxx)
|
||
|
||
| Code | 名称 | HTTP Status | 说明 |
|
||
|------|------|-------------|------|
|
||
| 4001 | resource_not_found | 404 | 资源不存在 |
|
||
| 4002 | resource_conflict | 409 | 资源冲突（如重复创建） |
|
||
| 4003 | invalid_state | 400 | 资源状态不允许此操作 |
|
||
|
||
### 服务端错误 (5xxx)
|
||
|
||
| Code | 名称 | HTTP Status | 说明 |
|
||
|------|------|-------------|------|
|
||
| 5001 | internal_error | 500 | 服务器内部错误 |
|
||
| 5002 | service_unavailable | 503 | 服务暂不可用 |
|
||
| 5003 | timeout | 504 | 请求超时 |
|
||
|
||
## 示例
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "example"
|
||
},
|
||
"trace_id": "req_abc123"
|
||
}
|
||
```
|
||
|
||
### 错误响应（简单）
|
||
|
||
```json
|
||
{
|
||
"code": 4001,
|
||
"message": "master not found",
|
||
"data": null,
|
||
"trace_id": "req_abc123"
|
||
}
|
||
```
|
||
|
||
### 错误响应（带 details）
|
||
|
||
```json
|
||
{
|
||
"code": 1001,
|
||
"message": "参数校验失败",
|
||
"data": null,
|
||
"details": {
|
||
"user_id": "必填",
|
||
"email": "格式错误"
|
||
},
|
||
"trace_id": "req_abc123"
|
||
}
|
||
```
|
||
|
||
## 客户端处理指南
|
||
|
||
1. **判断成功/失败**：检查 `code === 0`
|
||
2. **获取业务数据**：成功时从 `data` 读取
|
||
3. **展示错误信息**：使用 `message` 字段
|
||
4. **排查问题**：记录/上报 `trace_id`
|
||
5. **字段级错误**：检查 `details` 是否存在
|
||
|
||
## 不包装的端点
|
||
|
||
以下端点不使用 envelope 包装：
|
||
- Swagger UI (`/swagger/*`)
|
||
- 健康检查 (`/health`)
|
||
- Metrics (`/debug/vars`, `/internal/metrics`)
|
||
- CORS preflight
|