统一错误处理需从创建源头控制:业务错误必须用工厂函数(如user.NewNotFoundErr)生成,禁用fmt.Errorf;底层错误用errors.Wrap包装;ErrorCode()方法名固定;错误码与HTTP状态码解耦,通过映射表转换;HTTP中间件和gRPC拦截器须覆盖所有调用方式。

直接用 fmt.Errorf 或 errors.New 返回业务错误,中间件拿不到错误码、日志查不到来源、前端收不到结构化响应——统一错误处理不是加个中间件就行,而是从错误创建那一刻就决定整条链路是否可控。
为什么不能用 fmt.Errorf 包装业务错误
它生成的是纯字符串 error,没有字段、无法提取 Code 或 HTTPStatus;%w 包装后 errors.Is(err, user.ErrNotFound) 会失效,因为底层类型丢失;日志里只看到 "user not found: pq: no rows in result set",根本不知道这是业务语义缺失还是 DB 连接失败。
- 所有业务错误必须由工厂函数创建,比如
user.NewNotFoundErr(),禁止裸写&UserError{...} - 底层依赖(DB/gRPC/HTTP client)返回的 error,要用
errors.Wrap或自定义Wrap包装,再向上抛 -
ErrorCode()方法名必须固定,中间件、日志器、响应层才好统一反射或类型断言提取
如何设计可扩展的错误结构与错误码映射
错误码 Code 是业务唯一标识(如 10001 表示用户不存在),而 HTTPStatus 是协议层状态(如 404),二者硬绑定会导致改状态码就得动所有错误定义。
- 建一张轻量映射表,在中间件序列化响应前查表:
statusCodeMap = map[int]int{10001: 404, 10002: 400, 50001: 500} - 映射表只在初始化时加载一次,线程安全,不支持运行时修改
- 未显式映射的
Code默认 fallback 到500,避免因遗漏导致返回空状态 - 同一个
Code在 gRPC 场景下可映射为codes.NotFound,HTTP 层再查表转成404——这才是真正的解耦
HTTP 中间件和 gRPC 拦截器怎么真正起作用
只加 recovery.UnaryServerInterceptor 不够:流式方法(如 rpc Chat(stream ChatMessage) returns (stream ChatMessage))不会触发它;HTTP handler 里没手动设 w.WriteHeader(),错误会被吞掉或返回 200 + 错误体。
立即学习“go语言免费学习笔记(深入)”;
- HTTP 中间件必须包裹 handler 函数,且 handler 签名要改为返回
error,中间件统一捕获并调用w.WriteHeader()+json.NewEncoder(w).Encode() - gRPC 拦截器需同时配
UnaryServerInterceptor和StreamServerInterceptor,否则流式方法 panic 后协程直接退出 -
panic只能用于不可恢复场景(空指针、越界),业务错误必须走error显式返回,否则中间件无法区分是参数错还是系统崩了 - 日志记录时用
fmt.Sprintf("%+v", err),才能展开整个错误链,看到每一层的文件/行号和包装上下文
最容易被忽略的是错误创建那一刻的约束:没人检查 fmt.Errorf 是否混入了业务逻辑,也没人确保每个新错误都进了映射表。统一错误体系不是靠文档约定,而是靠编译期约束(如工厂函数强制返回接口)、CI 检查(扫描源码中禁止出现 fmt.Errorf 业务错误)、以及日志告警(未映射 Code 达到阈值自动报障)——否则半年后又回到满屏字符串 error 的状态。


















