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 入口才做最终的用户友好翻译，中间每一跳都该保留原始错误意图。
