微服务中Go的error不应直接返回调用方，须统一映射为语义明确的状态码（HTTP）或标准gRPC code，封装为可识别类型并保留错误链，携带trace ID，禁止字符串匹配，确保可观测性与重试策略分层可控。
微服务中 Go 的 error 不该直接返回给调用方
在微服务间通信（如 HTTP/gRPC）中，直接把 fmt.Errorf("db timeout") 或底层库的原始 error 返回，会导致调用方无法区分是临时故障、业务拒绝还是系统崩溃。Go 的 error 接口本身不带状态码、重试建议或上下文标识，裸 error 会破坏服务契约。
- HTTP 接口应统一转为
400 Bad Request、503 Service Unavailable等语义明确的状态码，而非全塞500 Internal Server Error - gRPC 接口必须映射到标准
codes.Code（如codes.Unavailable、codes.InvalidArgument），不能靠字符串匹配错误信息做判断 - 跨服务传递的 error 需携带 trace ID 和发生位置（如
"svc-order:payment_client_timeout"），否则链路追踪里只剩"context deadline exceeded"这种泛化提示
用自定义 error 类型封装底层错误并保留因果链
Go 1.13 引入的 errors.Is 和 errors.As 让错误分类成为可能，但前提是错误类型可识别。推荐定义一组核心 error 类型，并用 fmt.Errorf("xxx: %w", err) 包裹底层 error，形成可展开的错误链。
type PaymentFailedError struct {
OrderID string
Code string // "PAYMENT_DECLINED", "INSUFFICIENT_BALANCE"
}
func (e *PaymentFailedError) Error() string {
return fmt.Sprintf("payment failed for order %s: %s", e.OrderID, e.Code)
}
// 使用时
if errors.Is(err, context.DeadlineExceeded) {
return &PaymentFailedError{OrderID: orderID, Code: "TIMEOUT"}, codes.DeadlineExceeded
}
- 避免用字符串比较判断错误类型（如
strings.Contains(err.Error(), "timeout")），脆弱且无法跨语言兼容 - 所有包装 error 必须用
%w，否则errors.Unwrap()失效，链路中断 - 日志记录时用
log.Error("payment failed", "err", err)，而不是err.Error()，确保结构化字段和堆栈完整
gRPC 错误码与 HTTP 状态码的双向映射要显式声明
Protobuf 定义的 gRPC 接口默认通过 status.Error(codes.XXX, msg) 构造错误，但前端或网关常消费 HTTP 接口。若未显式配置映射规则，codes.Unauthenticated 可能被转成 500 而非预期的 401，导致前端鉴权逻辑失效。
- 使用
google.golang.org/grpc/codes和google.golang.org/grpc/status构建错误，而非手动拼接字符串 - 在 HTTP 网关层（如 grpc-gateway）配置
runtime.WithErrorHandler，按 code 映射 HTTP 状态码，例如：codes.Unavailable → 503，codes.ResourceExhausted → 429 - 禁止在 handler 里写
http.Error(w, "bad request", http.StatusBadRequest)，绕过统一错误处理管道
超时与重试场景下 error 的处理必须分层决策
微服务调用链中，一个 context.DeadlineExceeded 可能来自客户端、网关、下游服务或 DB 连接池。盲目重试会放大雪崩风险；完全不重试又降低可用性。关键是在每层明确“谁该重试、重试几次、什么条件下跳过”。
- 客户端发起调用时设置短于上游 deadline 的 context（如上游给 5s，本地设 4.5s），留出缓冲时间做降级
- 对
codes.Unavailable/codes.DeadlineExceeded可启用指数退避重试（最多 2 次），但对codes.InvalidArgument或codes.AlreadyExists绝对禁止重试 - DB 层错误（如
sql.ErrNoRows）不应向上抛成codes.Internal，而应转为业务语义错误（如codes.NotFound）并由上层决定是否兜底
最易被忽略的是 error 的可观测性：同一个错误在不同服务日志里应有相同 trace ID、一致的 error code 字段、可被 Prometheus 按 error_code 标签聚合。否则排查时只能靠猜。
