Go微服务中错误必须结构化处理：统一用NewError构造带code、message、traceID的bizError，gRPC用status.Error包装，HTTP返回JSON错误体+标准状态码，错误码需分层唯一且不透传reason给前端。
Go 微服务中 error 不该直接返回给调用方
跨服务调用时，原始 error（比如 fmt.Errorf("db timeout")）直接透传会导致下游无法解析语义、日志混乱、重试策略失效。核心原则是：**所有向外暴露的错误必须结构化、可序列化、带上下文元信息**。
- 避免用
errors.New或裸字符串构造 error —— 它们无法携带 code、http status、trace id - 不要在 RPC 响应体里塞
error string字段 —— 与 gRPC/HTTP 协议层错误处理机制冲突 - gRPC 场景下，必须用
status.Error()包装；HTTP 场景下，统一走 JSON 错误响应体 + 标准 HTTP 状态码
定义跨服务错误码体系：code + reason + httpStatus
错误码不是随意编号，需按领域分层（如 1xx 网关层、2xx 用户层、3xx 支付层），且每个 code 对应唯一 reason 和推荐 httpStatus。不推荐用字符串枚举（难维护），推荐用 int const + 映射表。
const (
ErrCodeUserNotFound = 2001
ErrCodeInvalidToken = 2002
ErrCodeRateLimited = 1003
)
var ErrCodeMeta = map[int]struct {
Reason string
HTTPStatus int
}{
ErrCodeUserNotFound: {Reason: "user not found", HTTPStatus: 404},
ErrCodeInvalidToken: {Reason: "invalid auth token", HTTPStatus: 401},
ErrCodeRateLimited: {Reason: "rate limit exceeded", HTTPStatus: 429},
}
- code 全局唯一，不随语言/服务变化 —— 前端、网关、监控系统都依赖它做决策
-
reason仅用于日志和 debug，**不返回给前端用户**；面向用户的 message 应由调用方根据 code 查 i18n 表生成 - 同一个 code 在 gRPC 和 HTTP 场景下可能映射不同
httpStatus（例如 gRPC 内部重试失败后转成 503，而直连 HTTP 调用仍是 500）
封装统一错误构造函数：NewError(code, msg, fields...)
所有服务内部错误创建必须走统一入口，禁止手写 errors.New 或 fmt.Errorf。该函数负责注入 traceID、service name、timestamp，并确保 error 实现 status.Coder（gRPC）或可 JSON 序列化（HTTP）。
func NewError(code int, msg string, fields ...map[string]interface{}) error {
e := &bizError{
Code: code,
Message: msg,
Time: time.Now().UnixMilli(),
TraceID: trace.FromContext(context.Background()).String(), // 实际应从入参 ctx 提取
Service: "user-svc",
}
for _, f := range fields {
for k, v := range f {
e.Fields[k] = v
}
}
return e
}
type bizError struct {
Code int `json:"code"`
Message string `json:"message"`
Time int64 `json:"time"`
TraceID string `json:"trace_id"`
Service string `json:"service"`
Fields map[string]interface{} `json:"fields,omitempty"`
}
func (e *bizError) Error() string { return e.Message }
func (e *bizError) GRPCStatus() *status.Status {
return status.New(codes.Code(ErrCodeToGRPC[code]), e.Message)
}
- 字段
Fields用于临时透传调试信息（如db_query,upstream_latency_ms），但不应包含敏感数据 - 必须实现
GRPCStatus()方法，否则 gRPC middleware 拦截不到 code - HTTP handler 中，用
json.Marshal(e)直接输出 —— 因为bizError已是标准 struct，无需额外包装
中间件拦截并标准化错误响应
HTTP 和 gRPC 的错误出口必须收口到中间件，避免每个 handler 重复写错误转换逻辑。重点在于：**把任意 error 类型转成协议兼容格式，并统一记录结构化日志**。
立即学习“go语言免费学习笔记（深入）”；
- gRPC server interceptor：捕获 panic 和 error，调用
status.Convert(err).Code()提取 code，再查表补全details - HTTP middleware：检查返回值是否为
*bizError，是则设置对应httpStatus并写 JSON；否则 wrap 成ErrCodeInternalError - 日志必须打全：
code,trace_id,service,method,duration_ms—— 缺一不可，否则链路排查失效
最易被忽略的是：下游服务收到错误后，**不能只看 HTTP status 判断失败类型**。比如 500 可能是上游 DB 连接失败（code=1001），也可能是参数校验失败（code=2002），必须解析响应体里的 code 字段做分支处理。
