错误码必须带服务标识前缀（如usr-001），禁止纯数字；grpc需显式返回error_code字段，不映射http状态码；错误码须结构化透传、配固定文案、禁客户端逻辑分支、变更需兼容评审。
错误码必须带服务标识前缀，不能只用数字
微服务里 5001 这种纯数字错误码在跨服务调用时根本没法溯源——你收到一个 5001，不知道是用户服务返回的，还是订单服务返回的，更没法判断该重试还是告警。
正确做法是每个服务定义自己的前缀，比如用户服务用 USR，订单服务用 ORD，错误码变成 USR-001、ORD-002。前缀要短、固定、全大写，且写死在服务启动时的配置里，不靠拼接或运行时推导。
- 前缀必须全局唯一，建议在公司级文档中注册，避免冲突
- 不要用服务名全称（如
user-service-001），太长且含特殊字符，HTTP Header 或日志解析会出问题 - 后缀数字建议从
001开始，不用1，对齐便于排序和 grep 查找
gRPC 错误码不能直接映射 HTTP 状态码
很多人图省事，在 gRPC 的 StatusError 里塞个 codes.Internal，然后在网关层硬映射成 500。问题在于：同一个 gRPC 错误码可能对应多个业务含义，比如 codes.NotFound 可能是用户不存在，也可能是订单已删除，但 HTTP 层无法区分，前端统一显示“资源未找到”，体验差，排查也难。
- 真实做法是在 gRPC 响应体里显式携带
error_code字段（string 类型），值为带前缀的业务错误码，如"USR-003" - 网关层只负责透传该字段到 HTTP 响应 body 或自定义 header（如
X-Error-Code），不参与翻译 - 禁止在中间件里根据
codes.XXX自动改写响应体内容，那会让错误语义失真
错误码要随错误上下文一起序列化，不能只打日志
只在日志里输出 USR-002: user not active 没用——调用链断了，下游服务拿不到这个信息，监控系统也聚合不了。错误码必须作为结构化字段，随 RPC 响应或 HTTP body 一起发出。
- Go 中推荐用自定义 error 类型实现
GRPCStatus()和HTTPResponse()方法，把code、message、details都塞进去 - 避免用
fmt.Errorf("USR-002: %w", err)包装，这样下游errors.Is()判断会失效；要用专门的错误构造函数，如user.NewErrUserInactive() - 所有错误码必须有对应文案，且文案不含变量（如不写 “用户
%s不存在”），防止日志脱敏失败或前端直用导致 XSS
客户端不能靠错误码字符串做逻辑分支
前端或下游服务写 if (err.code === 'USR-004') { ... } 是危险的——一旦上游加了新子状态（比如拆出 USR-004a），客户端就漏处理；更糟的是，不同版本服务可能对同一错误码返回不同行为。
立即学习“go语言免费学习笔记（深入）”；
- 客户端只应基于错误码做展示或埋点，核心流程控制必须依赖明确的响应字段，比如
is_retryable: true、redirect_url: "..." - 服务端若需引导客户端行为，应在 response body 中显式提供 action 字段，而不是让客户端“猜”错误码含义
- 所有错误码变更（新增/废弃/语义调整）必须走接口兼容性评审，且至少保留一个大版本的双写过渡期
最麻烦的不是定义规则，而是让所有人一致地填充 details 字段并验证它是否真的被序列化出去——漏掉这一环，错误码就只剩名字，没有上下文。
