道术合一

Appearance

错误码规范 MD 指南 ​

1. 设计目标 ​

  • 错误语义清晰、稳定
  • 前后端统一理解
  • 方便定位问题与监控
  • 支持模块化扩展
  • 支持长期演进与国际化

2. 基本原则 ​

  • 一个错误码对应一个明确业务语义
  • 错误码不可随意修改含义
  • 不直接暴露系统异常或堆栈信息
  • 错误码必须文档化
  • 错误码与 HTTP 状态码协同使用

3. 错误码分层设计（推荐） ​

3.1 协议层错误码（网关 / 框架） ​

  • 字符串型
  • 与 HTTP 状态码对齐
  • 用于 API Gateway 或通用异常

示例：

INVALID_ARGUMENT
UNAUTHENTICATED
FORBIDDEN
NOT_FOUND
CONFLICT
RATE_LIMIT_EXCEEDED
INTERNAL
UNAVAILABLE
DEADLINE_EXCEEDED

3.2 系统级错误码（通用） ​

范围：10000 - 19999

Code含义
10000成功
10001非法请求
10002参数错误
10003数据不存在
10004数据已存在
10005请求过于频繁
10006请求超时
10007服务不可用
10008签名无效
10009无接口权限
10010系统繁忙

3.3 业务级错误码（按模块划分） ​

模块范围
用户模块20000 - 29999
订单模块30000 - 39999
权限模块40000 - 49999
支付模块50000 - 59999
商品模块60000 - 69999

示例（用户模块）：

20001 用户不存在
20002 用户已存在
20003 用户名或密码错误
20004 用户被禁用
20005 Token 无效

示例（订单模块）：

30001 订单不存在
30002 库存不足
30003 订单状态异常

4. 错误码与 HTTP 状态码对应 ​

场景HTTP错误码示例
成功200 / 20110000
参数错误40010002
未登录40120005
无权限40340001
资源不存在40410003 / 20001
冲突40910004
限流42910005
系统异常50010010

说明：

  • HTTP 状态码表示协议层结果
  • 错误码表示业务层语义

5. 统一返回格式 ​

json
{
  "code": 20001,
  "message": "用户不存在",
  "data": null,
  "requestId": "abc123"
}

字段说明：

字段说明
code业务错误码
message用户可读提示
data返回数据
requestId请求追踪 ID

6. 错误信息设计规范 ​

6.1 message（给用户） ​

  • 简短
  • 友好
  • 不暴露系统细节
  • 可支持多语言

6.2 detail（仅日志） ​

  • 技术错误信息
  • SQL / 第三方返回值
  • 异常堆栈

7. 错误码命名规则（可选字符串枚举） ​

推荐使用大写下划线：

USER_NOT_FOUND
ORDER_NOT_EXIST
PERMISSION_DENIED
INVALID_ARGUMENT
RATE_LIMIT_EXCEEDED

8. 错误码管理规范 ​

  • 错误码集中定义（单一文件或表）
  • 新增可扩展，不可随意删除
  • 已发布错误码不可修改语义
  • 废弃标记 deprecated
  • 维护错误码字典文档

示例（代码）：

go
const (
  Success        = 10000
  UserNotFound   = 20001
  OrderNotFound  = 30001
)

9. 国际化（可选） ​

通过错误码映射文案：

20001 -> 用户不存在
20001 -> User not found

10. 禁止行为 ​

❌ 使用 HTTP 状态码作为业务错误码
❌ 所有错误统一返回一个 code
❌ 返回异常堆栈给前端
❌ 使用随意数字（1,2,3,-1）
❌ 无错误码文档
❌ 错误码含义频繁变更

11. 推荐最小通用错误码集合 ​

10000 成功
10002 参数错误
10003 数据不存在
10004 数据已存在
10005 请求频繁
10010 系统异常

20001 用户不存在
20003 用户名或密码错误
20005 Token 无效

30001 订单不存在

40001 无权限访问
50001 支付失败

12. 最佳实践总结 ​

  • 分层（协议 / 系统 / 业务）
  • 分段（模块区间）
  • 错误码 + message + HTTP 状态码
  • 文档化管理
  • 可监控、可统计、可扩展

13. 参考 ​