Go错误处理在RPC调用中的设计_Go跨服务错误传递方案

go rpc错误不能直接返回Error的根本原因是其不可序列化，需用gRPC的status.Status封装以支持跨语言解析、http状态码映射及details透传；非gRPC场景须手动定义错误结构并统一处理panic与TraceID。

Go RPC调用中错误不能直接返回 error 的根本原因

Go 标准库的 net/rpc 和主流 gRPC（google.golang.org/grpc）都要求错误必须可序列化。原生 error 接口本身不实现 encoding.BinaryMarshaler 或 proto.Message，无法跨网络传输。直接 return fmt.Errorf("xxx") 在服务端看似成功，但客户端收到的是空错误或 rpc: service/method request failed 这类泛化提示，丢失关键上下文。

gRPC 场景下用 Status 封装错误比自定义 error Struct 更可靠

gRPC 官方推荐使用 google.golang.org/grpc/status 包，而非在 response 结构体里加 ErrorCode 字段。因为 status.Status 会被自动映射为 HTTP 状态码（如 CANCELLED → 499）、写入 trailer，并被所有语言客户端统一解析。

• status.New(codes.NotFound, "user not found") 生成带 code + message 的状态对象
• 用 .Err() 转成实现了 error 接口的值，可直接 return 给 gRPC 框架
• 客户端用 status.FromError(err) 解包，安全获取 Code() 和 Message()，不依赖字符串匹配
• 若手动在 proto 中定义 int32 error_code = 1;，需自行维护 code 映射表，且无法携带 details（如重试策略、定位日志 ID）

需要透传原始错误堆栈时，必须显式注入 status.WithDetails()

默认 status.Status 不包含 stack trace，客户端无法看到服务端 panic 位置或中间件拦截点。要暴露调试信息，需用 WithDetails 注入实现了 protoreflect.ProtoMessage 的 detail 对象：

import "google.golang.org/genproto/googleapis/rpc/errdetails"  s := status.New(codes.Internal, "db timeout") s, _ = s.WithDetails(     &errdetails.ErrorInfo{         Reason: "DB_CONN_TIMEOUT",         Domain: "payment.svc.example.com",         Metadata: map[string]string{"trace_id": traceID},     }, ) return s.Err()

注意：detail 类型必须在 .proto 中声明并生成 Go 代码，否则客户端解包失败；生产环境应限制堆栈输出，避免泄露敏感路径。

HTTP/jsON-RPC（如 gin + jsonrpc2）需手动映射 error 到结构体字段

非 gRPC 的 RPC（如基于 HTTP 的 json-RPC）没有标准错误信道，必须约定响应格式。常见错误字段名是 error 或 code，但含义易混淆：

• 不要用 code: 500 表示业务错误——这和 HTTP 状态码冲突，应统一用 200 OK 响应体携带错误
• 建议结构体定义为：

  type RPCResponse struct {     Result json.RawMessage `json:"result,omitempty"`     Error  *RPCError       `json:"error,omitempty"` }  type RPCError struct {     Code    int    `json:"code"`    // 自定义业务码，如 1001     Message string `json:"message"`     TraceID string `json:"trace_id,omitempty"` }

• 服务端 panic 时，中间件必须 recover 并转成 *RPCError，否则返回 html 错误页或空 body

跨服务链路中，TraceID 必须从上游 header 透传并写入 error 结构，否则问题无法归因。