Golang微服务错误处理规范详解

Golang不知道大家是否熟悉？今天我将给大家介绍《Golang微服务错误处理与规范设计》，这篇文章主要会讲到等等知识点，如果你在看完本篇文章后，有更好的建议或者发现哪里有问题，希望大家都能积极评论指出，谢谢！希望我们能一起加油进步！

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

• 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 字段做分支处理。

终于介绍完啦！小伙伴们，这篇关于《Golang微服务错误处理规范详解》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布Golang相关知识，快来关注吧！