iris.OnErrorCode仅捕获HTTP状态码≥400的错误，不处理业务错误；需自建错误码映射、用中间件统一拦截panic和BizError，并推荐使用ctx.Problem()实现RFC 7807标准化错误响应。
iris.OnErrorCode 只负责状态码，不处理业务错误码
很多人一上来就用 app.OnErrorCode(iris.StatusNotFound, handler)，以为能覆盖所有错误场景。其实它只捕获 HTTP 状态码 ≥400 的响应（比如 404、500），但你业务里抛出的 ErrUserNotFound 或 ErrInsufficientBalance 完全不会触发这个回调——它们还没走到 HTTP 层，甚至可能根本没设置 StatusCode。
真正需要封装的是「业务错误 → HTTP 响应」这一转换链。Iris 本身不提供错误码映射表，得你自己建。
- 错误码必须和 HTTP 状态码解耦：比如
USER_NOT_FOUND对应 404，INVALID_PARAM对应 400，但同一个错误码在不同接口里也可能返回 200 + error 字段（如 RPC 风格） - 别把错误码硬编码进
ctx.StatusCode()调用里，否则后期改状态码要全局搜 - 推荐用枚举或结构体封装错误码，带
HTTPStatus()和Code()方法，而不是字符串常量
用中间件统一拦截 panic 和自定义 error
业务逻辑里 return zerr.New("user not found") 或 panic(errors.New("db timeout")) 都得被兜住，转成标准 JSON 响应。靠 OnErrorCode 拦不住这些。
正确做法是写一个 recover 中间件，在 ctx.Next() 后检查是否 panic 或 ctx.Values().Get("bizErr") 是否非空：
func BizRecovery() iris.Handler {
return func(ctx iris.Context) {
defer func() {
if r := recover(); r != nil {
err, ok := r.(error)
if !ok {
err = errors.New(fmt.Sprint(r))
}
renderBizError(ctx, ErrInternalServer.WithDetail(err.Error()))
ctx.StopExecution()
return
}
}()
ctx.Next()
if bizErr := ctx.Values().Get("bizErr"); bizErr != nil {
renderBizError(ctx, bizErr.(BizError))
ctx.StopExecution()
}
}
}
- 中间件必须放在所有路由注册之前（
app.Use(BizRecovery())） - 别用
ctx.StatusCode()直接设值，而是调用封装好的renderBizError()，它内部根据错误的HTTPStatus()设置状态码并写 JSON - 避免在中间件里直接
ctx.JSON()，因为可能被后续中间件覆盖；ctx.StopExecution()后必须立刻 return
错误码枚举要带 Feedback 和 HTTP 映射
参考 Java 的 ErrorCode 枚举设计，Go 里可以用 struct + 方法模拟：
type BizError interface {
error
Code() string
HTTPStatus() int
Message() string
WithDetail(string) BizError
}
var (
ErrUserNotFound = &bizErr{
code: "USER_NOT_FOUND",
httpStatus: iris.StatusNotFound,
message: "用户不存在",
}
ErrInternalServer = &bizErr{
code: "INTERNAL_ERROR",
httpStatus: iris.StatusInternalServerError,
message: "服务器内部错误",
}
)
- 每个错误实例预设好
httpStatus，避免每次手动传；但允许用WithDetail()动态追加上下文（如 SQL 错误原文） - 别把错误信息拼在
Message()里，比如"用户不存在: " + userID—— 这会让日志和前端翻译变困难；用WithDetail()单独传变量 - 如果项目有国际化需求，
Message()应该返回 key，由 i18n 服务查翻译，而不是固定字符串
别忽略 ctx.Problem 的存在
Iris 内置了 RFC 7807 标准的 ctx.Problem()，比手写 JSON 更规范，尤其适合对外 API：
ctx.Problem(iris.NewProblem().
Type("/errors/user-not-found").
Title("User Not Found").
Status(iris.StatusNotFound).
Detail("The requested user does not exist in our system.").
Key("userID", userID))
- 它自动设 Content-Type 为
application/problem+json，前端可统一解析type字段做错误分类 - 不要为了省事全用
ctx.JSON()，当错误需要标准化描述（比如审计、第三方集成）时，Problem是更可靠的选择 -
Problem不会触发OnErrorCode回调，它是主动写的响应，和错误码封装是正交关系
最易被忽略的一点：错误封装不是越深越好。BizError 接口里塞太多方法（比如 LogFields()、ToTrace()）会让简单接口也得实现一堆空方法。先保证 Code()、HTTPStatus()、Message() 三个核心字段可用，其余按需扩展。
