必须在 .proto 中定义 ErrorReason 枚举并为每项显式标注 (errors.code),所有业务错误须用 errors.Xxx() 封装返回,否则 HTTP 状态码、gRPC Code、Swagger 文档及 errors.Is() 判断全部失效。

必须在服务对应的 .proto 文件中定义 ErrorReason 枚举,每个值显式绑定 (errors.code),且所有业务错误必须通过 errors.Xxx() 封装返回——否则 HTTP 状态码、gRPC Code、Swagger 文档、跨服务 errors.Is() 判断全部失效。
错误码必须定义在 .proto 里,不能 runtime 拼凑
Kratos 不接受 errors.New("user not found") 或 fmt.Errorf("invalid token: %s", t) 这类运行时构造的错误。这类错误会被 transport 层 fallback 到 500 Internal Server Error,丢失语义和状态码控制。
-
ErrorReason枚举需与 service 同级声明,命名非强制但强烈推荐为ErrorReason - 每个枚举项必须加
(errors.code) = NNN注解,例如:USER_NOT_FOUND = 0 [(errors.code) = 404]; - 未加注解的项默认走
(errors.default_code) = 500,但不可依赖——它会让前端无法按状态码分支处理 - 生成代码后,会产出类型安全的错误变量,如
helloworld.ErrUserNotFound
返回错误必须用 errors.Xxx() 封装,不是直接 return
handler 里不能直接 return errors.New(...),而要调用 Kratos 提供的封装函数,把底层 error 转成 proto 中定义的 enum 实例。
- 函数签名是
errors.BadRequest(errReason, "描述"),第一个参数是.proto中定义的枚举值(如helloworld.USER_NOT_FOUND),第二个是 human-readable 描述 - 这样返回后,HTTP 层自动设
Status: 404,gRPC 层设Code: NotFound,message 字段含你传的描述 -
errors.New和errors.WithMessage只能用于内部包装,比如数据库层报错后加 context,但最终仍需用errors.NotFound(...)封装再向上抛 - 手动在 middleware 里调
w.WriteHeader(404)会覆盖框架自动提取的 status,导致文档与实际响应不一致
验证是否生效:看 curl 响应头 + errors.Is() 匹配
最直接的验证方式是调用接口并检查原始响应,而不是只看 JSON body。
- 执行
curl -v http://localhost:8000/v1/user/999,确认响应头中Status: 404 Not Found与 proto 中(errors.code) = 404一致 - 在另一个服务或单元测试中,用
errors.Is(err, helloworld.ErrUserNotFound)判断类型,而非字符串匹配strings.Contains(err.Error(), "not found") - 如果始终返回 500,优先检查:
.proto是否漏了(errors.code);返回 error 是否来自errors.Xxx();errors.Xxx()第一个参数是否拼写正确(大小写、包路径)
最容易被忽略的是:错误码的语义一致性依赖于团队对 ErrorReason 枚举的共同维护——一旦某个枚举值被多个服务复用(如 INVALID_ARGUMENT),它的 (errors.code) 就必须统一,否则跨服务调用时 errors.Is() 会因包路径不同而失败。这不是框架限制,而是契约约定。


















