17370845950

必须使用 gRPC 的 status 和 codes 包进行标准化错误处理：codes 定义整数状态码（如 codes.NotFound），status 封装码、消息与详情为可序列化 *status.Status 对象；服务端用 status.Errorf 或 WithDetails 返回，客户端用 status.FromError 解析，禁用字符串匹配。

Go 语言中使用 gRPC 时，错误处理不能只靠 error.Error() 字符串判断——必须用 gRPC 的 status 包和 codes 包 来标准化表达错误类型、状态码和附加信息。

status 和 codes 是什么关系

google.golang.org/grpc/codes 定义了标准的 HTTP 类似状态码（如 codes.NotFound、codes.InvalidArgument），但只是整数常量；google.golang.org/grpc/status 则封装了这些码 + 错误消息 + 可选的详细信息（Details），形成可序列化、跨语言兼容的 *status.Status 对象。

你返回给客户端的 error，**必须是 *status.Status 转成的 error**（通过 .Err() 方法），否则 gRPC 框架无法正确识别状态码，客户端拿到的永远是 codes.Unknown。

服务端怎么返回规范错误

• 用 status.Errorf(codes.XXX, "message %s", args) 快速构造带码的 error
• 需要传额外结构化信息（比如字段校验失败详情）时，先建 *status.Status，再用 .WithDetails(...) 添加实现了 protobuff.Message 的 detail 对象（如 &errdetails.BadRequest{}）
• 不要直接 return errors.New("xxx") 或 fmt.Errorf("xxx")，这类 error 会被转为 codes.Unknown
• 拦截器里也可统一处理：对非 *status.Status 错误，用 status.Convert(err).Err() 尝试转换，或兜底转成 codes.Internal

客户端怎么解析服务端错误

调用 RPC 后，先用 status.FromError(err) 解包：

• 如果返回 ok == true，说明是标准 gRPC 错误，可用 s.Code() 拿状态码，s.Message() 拿提示，s.Details() 拿结构化详情
• 如果 ok == false，说明是网络错误、超时、取消等底层错误，不是业务逻辑错误，不应按业务码处理
• 别用 strings.Contains(err.Error(), "Not Found") 这种字符串匹配——既脆弱又不跨语言

常见误区与建议

• codes.Internal 不等于 “服务炸了”：它代表服务器内部未预期错误，应记录日志并告警；而 codes.Unavailable 才适合服务暂时不可用（如依赖下游挂了）
• 自定义错误码？不推荐。优先用已有 codes，语义不清时考虑用 codes.Unknown + detail 补充上下文
• 日志中打印错误时，用 status.Convert(err).String() 而非 err.Error()，能同时看到 code、msg 和 details
• HTTP/JSON 代理（如 grpc-gateway）会自动把 codes 映射为对应 HTTP 状态码，前提是服务端用了 status 包

基本上就这些。用好 status 和 codes，错误才真正可读、可查、可路由、可监控。