gRPC状态码仅用于传输层错误，业务错误须用自定义error_code字段；proto中显式定义error_code和error_message，网关层统一返回200并透传业务错误；错误码需集中管理、按域分组，并与error_domain绑定传递。
gRPC Status Code 和业务错误码怎么分开用
gRPC 的 Status 本质是传输层语义，比如 UNAVAILABLE 表示服务连不上，DEADLINE_EXCEEDED 表示超时——这些不该被当成业务失败返回给前端。业务错误（如“余额不足”“订单不存在”）必须走自定义错误码字段，否则前端一看到 NOT_FOUND 就跳 404 页面，实际可能是用户输错了手机号。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 所有 gRPC 方法的响应结构体里，显式加一个
error_code字段（int32 或 string），和message配套使用 - 服务端永远只用
status.Error()返回真正的传输/系统错误；业务错误统一返回status.OK+ 自定义字段 - 不要重载
status.Code去表达业务含义，比如把“库存不足”映射成RESOURCE_EXHAUSTED——这个码在网关、重试逻辑里会被当成可重试的系统瓶颈，引发误行为
Go 里怎么安全地透传错误码到 HTTP/JSON 网关层
很多项目用 grpc-gateway 把 gRPC 接口转成 REST，这时候容易踩坑：默认会把 status.Code 直接映射成 HTTP 状态码（INVALID_ARGUMENT → 400），但业务错误不该触发状态码变更。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在 proto 文件里为每个 RPC 响应 message 显式定义
int32 error_code = 1;和string error_message = 2; - 用 grpc-gateway 的
google.api.http注解时，禁用自动状态码映射：additional_bindings中不设response_body: "*"，改用手动构造 JSON 响应 - 在 gateway 的 middleware 或 response handler 里，统一检查
error_code字段，非零时固定返回200 OK，把业务错误包进 JSON body，避免前端被 HTTP 状态码误导
错误码定义怎么避免多服务间冲突和维护散乱
各微服务各自定义 ERROR_BALANCE_INSUFFICIENT = 1001，不出三个月就会撞码、漏文档、改一个要 grep 全库。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 所有错误码集中定义在独立的 Go module（如
github.com/yourorg/errors），用 const + iota，按域分组：AuthErrorCode、OrderErrorCode - proto 里不写裸数字，用
enum引用该 module 导出的值（通过option go_package关联），生成代码时能保证一致性 - 加 CI 检查：每次 PR 提交 proto，跑脚本校验 enum 值是否在 errors module 中存在且注释非空——漏写说明的错误码禁止合入
客户端解析错误时，为什么不能只看 error_code 数值
数值本身没上下文。error_code == 1001 在订单服务是“地址超长”，在支付服务可能是“银行卡过期”，客户端 if-else 写死就废了。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 服务端响应里必须带
error_domain字段（如"order"、"payment"），和error_code成对出现 - 客户端 SDK 封装统一的
ParseError(resp)函数，内部根据 domain 查对应错误码表，再抛出带语义的 error 类型（如order.ErrAddressTooLong） - 避免在日志或监控里只打
error_code=1001，必须拼上domain=order，否则排查时根本分不清是谁的 1001
真正难的不是定义几个常量，而是让 error_code 始终和 domain、message、可恢复性标记（比如是否允许前端重试）绑在一起传递——少一个，下游就得靠猜。
