Golang中的错误包裹与GRPC状态码转换 Go语言微服务错误透传

用 status.Errorf 包裹错误才能保留原始状态码；status.fromerror 只识别 status.status 实例，其他包装会导致 code 降级为 unknown，自定义错误需实现 grpcstatus() 方法返回真实 status.status。

go 错误包裹后如何让 gRPC 客户端拿到原始状态码

直接结论：用 status.Errorf 包裹错误，而不是 fmt.Errorf 或 errors.Wrap；gRPC 的 status.FromError 只认 *status.Status 实例，其他包装都会丢掉码和详情。

常见错误现象是客户端调用后只看到 rpc error: code = Unknown desc = ...，明明服务端写了 codes.NotFound，但一包裹就降级成 Unknown。

• 必须用 status.Errorf(codes.NotFound, "user %s not found", id) 构造初始错误
• 后续包裹要用 status.WithDetails + status.Convert 配合，不能简单套 fmt.Errorf("wrap: %w", err)
• 如果中间用了 errors.Join 或自定义错误类型，status.FromError 会返回 nil，Code() 默认变成 codes.Unknown

在中间件或 handler 中透传 gRPC 状态码的正确姿势

微服务链路里常在中间件统一加日志、指标或重试逻辑，但一不小心就把状态码“吃掉”了——比如用 err != nil 判断后直接 return，没把原始 *status.Status 提出来。

使用场景：http-to-gRPC 网关、auth 拦截器、重试 wrapper。

立即学习“go语言免费学习笔记（深入）”；

• 拦截器中判断错误类型优先用 s, ok := status.FromError(err)，不是 errors.Is 或 strings.Contains
• 需要透传时，不要 new 一个新 error，直接 return 原始 err；若要加 context，用 status.WithDetails(s, d) 而非字符串拼接
• HTTP 中间件转 gRPC 错误时，别用 http.Error 后再 try-catch，应提前映射：http.StatusNotFound → codes.NotFound

自定义错误类型与 gRPC 状态码共存的坑

团队常封装 AppError 类型来统一携带 traceID、业务码，但这类结构体默认不兼容 status.FromError，导致下游无法解析。

参数差异在于：gRPC 只信任实现了 GRPCStatus() *status.Status 方法的错误类型。

• 必须为自定义错误实现 GRPCStatus() 方法，返回一个真实 *status.Status 实例（不能返回 new(status.Status)）
• 不要在 GRPCStatus() 里做 lazy 初始化或依赖外部状态，gRPC 可能在任意 goroutine 调用它
• 如果错误本身含多个状态（如重试聚合），GRPCStatus() 应返回最严重那个，别试图 merge codes —— gRPC 不支持“多状态”

客户端收到 error 后怎么安全提取状态码和详情

很多客户端直接 log.printf("err: %v", err) 就完事，结果调试时看不到真实 code 和 details，只能靠猜。

性能影响很小，但缺失这步会导致线上问题定位延迟数小时。

• 永远先调 s, ok := status.FromError(err)，ok 为 false 说明不是标准 gRPC 错误，可能是网络断开或 context cancel
• s.Code() 是唯一可信的状态码来源，别从 err.Error() 里正则匹配 “NOT_FOUND”
• 取 details 要用 s.Details()，注意它返回 []Interface{}，需 type assert 成具体 proto message，比如 *errdetails.BadRequest

复杂点在于：状态码可能被多层中间件覆盖，而 details 在每次 WithDetails 时是追加而非替换——容易漏掉最早那次关键信息。这点很容易被忽略。