gRPC错误必须用status.Error()包装才能正确传递，否则调用方收到codes.Unknown；应映射到标准codes.XXX，用status.FromError()解包并依据st.Code()判断，避免字符串匹配或errors.Wrap导致语义丢失。

gRPC 错误码必须用 status.Error() 包装才能跨服务传递

直接返回 errors.New("xxx") 或 fmt.Errorf("xxx")，调用方收到的永远是 codes.Unknown，且原始错误信息被截断或丢失。gRPC 协议要求错误必须序列化为 status.Status，否则底层无法识别语义。

正确做法是显式构造带 code 和 message 的状态：

import "google.golang.org/grpc/status"

func (s *UserService) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
    if req.Id == 0 {
        return nil, status.Error(codes.InvalidArgument, "user ID cannot be zero")
    }
    // ...
}

• 所有业务错误都应映射到标准 codes.XXX（如 InvalidArgument、NotFound、PermissionDenied），避免滥用 Unknown 或 Internal
• 不要在错误消息里拼接敏感字段（如数据库密码、token），message 会被日志和监控系统捕获
• 若需透传额外结构化数据（如错误码、trace ID），用 status.WithDetails() 添加 protos 定义的 Any 类型元数据

客户端如何安全提取 gRPC 错误详情

调用方不能直接对 error 做字符串匹配或类型断言 *errors.errorString —— 这种方式在跨语言或升级 gRPC 版本后极易失效。

必须用 status.FromError() 解包：

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

resp, err := client.GetUser(ctx, &pb.GetUserRequest{Id: 123})
if err != nil {
    st, ok := status.FromError(err)
    if !ok {
        log.Printf("non-gRPC error: %v", err)
        return
    }
    switch st.Code() {
    case codes.NotFound:
        log.Printf("user not found: %s", st.Message())
    case codes.InvalidArgument:
        log.Printf("invalid request: %s", st.Message())
    default:
        log.Printf("unexpected error: %v", st)
    }
    return
}

• status.FromError() 对非 gRPC error 返回 ok=false，务必先检查
• st.Message() 是用户可读文本，st.Code() 才是程序判断依据；不要用 message 做分支逻辑
• 若服务端用了 WithDetails()，可用 st.Details() 取出 proto 消息，但需提前注册对应类型到 protoregistry.GlobalTypes

HTTP/JSON 网关层会自动转换 gRPC 错误，但状态码映射有陷阱

使用 grpc-gateway 时，codes.NotFound → HTTP 404、codes.InvalidArgument → 400 看似合理，但以下情况会破坏一致性：

• 服务端返回 codes.Internal，网关默认转成 500，但真实原因是下游超时还是 panic？调用方无法区分
• 自定义错误详情（如 RetryInfo）在 JSON 响应中被忽略，除非显式配置 runtime.WithProtoErrorHandler
• 如果网关开启了 runtime.WithForwardResponseOption 但没处理 error 分支，可能把空响应体当成功返回

建议在网关中间件中统一补全错误上下文：

func customErrorHandler(ctx context.Context, mux *runtime.ServeMux, marshaler runtime.Marshaler, w http.ResponseWriter, r *http.Request, err error) {
    st, ok := status.FromError(err)
    if !ok {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    // 补充 trace_id 到 response header
    if tid := grpc_ctxtags.Extract(ctx).Values()["trace_id"]; tid != nil {
        w.Header().Set("X-Trace-ID", fmt.Sprintf("%v", tid))
    }
    runtime.DefaultHTTPError(ctx, mux, marshaler, w, r, err)
}

跨服务链路中错误不应“吞掉”原始 cause

服务 A 调用 B，B 报错后 A 直接 return errors.Wrap(err, "call B failed")，会导致原始 status.Status 被转成普通 Go error，B 的 codes.NotFound 在 A 的下游眼里变成 codes.Unknown。

• 若 A 是纯 gRPC 服务，应将 B 的 error 原样返回（或重新包装为同 code 的新 status.Error）
• 若 A 需添加上下文（如记录请求 ID），用 status.Convert(err).WithMessage(...)，而非 errors.Wrap
• 绝对避免在中间层做 if errors.Is(err, xxx) { return nil, status.Error(...) } 这类“错误降级”，会掩盖真实失败原因

错误传播不是层层加壳，而是保持语义可追溯。最外层网关或 API 入口才做最终的用户友好翻译，中间每一跳都该保留原始错误意图。