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 结构，否则问题无法归因。
