Kratos统一错误处理由.proto中ErrorReason枚举与errors.New共同驱动:必须在服务.proto中定义带(errors.code)注解的枚举,业务层调用errors.New(int32(pb.ENUM), msg),缺一即导致状态码、日志、Swagger、gRPC Status.Code全部失效。

Kratos 的统一错误码返回不是靠中间件“兜底”或手动写 http.Error 实现的,而是由 .proto 文件中的 ErrorReason 枚举 + errors.New 调用共同驱动的。漏掉任一环节,状态码、日志、Swagger 文档、gRPC Status.Code 全部失效。
proto 里必须定义带 (errors.code) 注解的 ErrorReason 枚举
这是整个机制的前提。框架只认这个枚举,且每个值必须显式绑定 HTTP 状态码:
-
ErrorReason必须定义在服务对应的.proto文件中(比如api/greeter/greeter.proto),不能放在别处或运行时拼字符串 - 必须
import "errors/errors.proto",否则注解不生效 - 每个枚举项要写全注解,例如:
USER_NOT_FOUND = 0 [(errors.code) = 404];只写USER_NOT_FOUND = 0不加注解,框架视为无效项,降级为 500 - 生成代码后,会产出
pb.ErrUserNotFound这类常量,业务层要用它,而不是数字404或字符串"USER_NOT_FOUND"
业务层必须用 errors.New(int32(pb.USER_NOT_FOUND), msg) 构造错误
不能直接 return errors.New("user not found"),也不能用 fmt.Errorf,更不能手动设 w.WriteHeader(404):
-
errors.New第一个参数必须是pb.USER_NOT_FOUND这种枚举值(转成int32),不是状态码数字,也不是字符串名 - 第二个参数是 human-readable 描述,会被填入响应体的
message字段,不影响状态码和reason - HTTP 响应头
Status、gRPC 的Status.Code、Swagger 中的responses全部由框架自动提取(errors.code)注解生成,手动覆盖会导致三者不一致 - 如果 handler 里 panic 或收到第三方裸 error,中间件兜底时也得用
errors.New包一层,否则框架识别不了,直接 fallback 到 500
自定义响应字段名(如 err_code)要改 errorEncoder,不能动业务逻辑
默认响应结构是 {"code":404,"reason":"USER_NOT_FOUND","message":"..."}。想改成公司内部约定的字段名,不能在每个 handler 里手拼 JSON:
- 找到初始化
http.Server的地方(通常是cmd/xxx/main.go) - 在配置中传入自定义
errorEncoder函数,签名必须是func(ctx context.Context, err error, w http.ResponseWriter) - 函数内部仍需调用
errors.FromError(err)解析原始错误,再按需序列化到自定义结构体 - 注意:这个改动只影响 HTTP,gRPC 错误编码走的是独立的
grpc.Server的errorCodec,要另配
最常被忽略的一点:错误码定义和使用必须严格对齐。proto 里没加 (errors.code),或者业务层用了裸 error 或错传参数类型,都会导致框架无法提取语义信息——此时你看到的永远是 500,而日志里连 reason 字段都没有。


















