错误码必须用字符串标识并集中管理，结构体需含Code、HTTPStatus、Message三字段，gRPC透传须用status.FromError解包重建，registry校验唯一性并生成文档。
Go 微服务里错误码不该用 int 直接传
跨服务传递错误时，用 int 表示错误码看似简单，实则埋雷：不同服务对同一数字的语义理解可能不一致，HTTP 状态码、gRPC 状态码、业务码混在一起，序列化后丢失上下文，调试时只能靠猜。
- 错误码必须携带可读标识，比如
"USER_NOT_FOUND"，而不是404 - 所有错误码定义集中在一个包（如
errors），禁止分散在各 service 内 - 对外暴露的错误码字段统一命名为
code（JSON key）或Code（Go struct field），避免err_code、errorCode等变体 - gRPC 场景下，错误码需映射到
status.Code，但业务码本身不能直接复用codes.NotFound—— 它只表示传输层失败，不是业务语义
定义错误码结构体时别漏掉 HTTP 状态码字段
一个错误码要同时支撑 HTTP 和 gRPC 两种协议，就必须明确区分「业务含义」和「传输响应」。只存 code 和 message 不够，客户端没法自动设 Status Code。
- 结构体至少包含三个字段：
Code（字符串业务码）、HTTPStatus（int）、Message（用户可见提示） - 示例：
var ErrUserNotFound = &BizError{ Code: "USER_NOT_FOUND", HTTPStatus: http.StatusNotFound, Message: "用户不存在", } - 不要把
HTTPStatus写死在 handler 里——它属于错误定义本身，否则同一错误在不同接口返回不同状态码 - 注意：gRPC 的
status.Code应由中间件根据BizError.HTTPStatus自动映射，而非手动调用status.Errorf
gRPC 错误透传时必须用 status.FromError 检查原始错误
下游服务返回错误，上游直接 return err，前端拿到的往往是 rpc error: code = Unknown desc = ...，原始业务码彻底丢失。
- 正确做法是用
status.FromError(err)解包，再判断是否为自定义BizError - 若解包成功且含已知业务码，应重建带
Code和HTTPStatus的新错误；否则保留原status.Error - 别用
errors.Is或errors.As直接判别 gRPC 错误——它们对status.Error不生效 - 中间件里统一做这件事，避免每个 handler 重复写解包逻辑
错误码注册表必须支持运行时校验和文档生成
靠人肉维护 README.md 同步错误码列表，不出三个月就失效。上线后发现两个服务对 "ORDER_TIMEOUT" 的 HTTPStatus 定义不一致，排查成本远高于预防成本。
立即学习“go语言免费学习笔记（深入）”；
- 所有错误码变量必须注册到全局 registry（如
errors.Register(ErrOrderTimeout)），启动时校验Code唯一性 - 提供命令行工具，从 registry 自动生成 JSON Schema 或 OpenAPI
components.schemas.Error片段 - registry 本身不导出具体错误实例，只管理元信息——防止被误用为普通 error 返回
- 测试里加一条断言：所有注册的错误码
HTTPStatus必须落在 4xx/5xx 范围，避免不小心设成200
最麻烦的不是定义错误码，而是让所有服务用同一套规则解析它。一旦某个中间件跳过解包步骤，或者某次重构删掉了 registry 注册调用，整条链路的错误语义就断了——这种问题不会报错，只会静默降级。
