Golang微服务如何统一错误处理_跨服务错误规范设计-Golang-PHP中文网

Go微服务中错误必须结构化处理：统一用NewError构造带code、message、traceID的bizError，gRPC用status.Error包装，HTTP返回JSON错误体+标准状态码，错误码需分层唯一且不透传reason给前端。

golang微服务如何统一错误处理_跨服务错误规范设计

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）。

Expanso yaml-to-json

使用 Expanso Edge 管道将 YAML 输入转换为 JSON 格式。

下载

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 类型转成协议兼容格式，并统一记录结构化日志**。

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 —— 缺一不可，否则链路排查失效