ez-api/docs/response-codes.md

EZ-API Response Envelope 规范

本文档定义响应信封结构及业务码表。HTTP 状态码保留用于传输层语义。

Envelope 结构

{
  "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	请求超时

示例

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "name": "example"
  },
  "trace_id": "req_abc123"
}

错误响应（简单）

{
  "code": 4001,
  "message": "master not found",
  "data": null,
  "trace_id": "req_abc123"
}

错误响应（带 details）

{
  "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