Iris 本身不提供统一响应封装机制，必须手动在每个 handler 或中间件里实现，而采用 mvc.Result + 自定义 Response 结构体是最轻量、最可控的方式。
直接说结论：Iris 本身不提供统一响应封装机制，必须手动在每个 handler 或中间件里做，但用 mvc.Result + 自定义结构体是最轻量、最可控的方式。
为什么不能依赖 ctx.JSON() 直接返回业务结构体
Iris 的 ctx.JSON() 只负责序列化，不处理状态码、错误包装、字段过滤等常见需求。比如你写 ctx.JSON(200, user)，一旦后续要加 code、message、data 三层嵌套，所有地方都得改；更麻烦的是，错误路径（如数据库查不到）和成功路径的结构不一致，前端难处理。
- 不要在每个 handler 里重复写
map[string]interface{}—— 易错、难测试、无法复用字段校验逻辑 - 别用
ctx.StatusCode()+ctx.JSON()分两步设状态码 —— 中间件可能覆盖或干扰，且没做 error 转换 - 避免在 handler 内部调
panic()交由全局 recover 中间件处理 —— panic 后 context 已不可用，ctx.Values()丢失，无法补日志或 traceID
用 mvc.Result 实现可复用的响应封装
如果你走 MVC 模式（推荐），mvc.Result 是唯一被框架识别的返回类型，天然支持拦截、复用和类型安全。它不是装饰，是强制契约。
- 定义统一响应结构体，例如：
type Response struct { Code int `json:"code"` Message string `json:"message"` Data interface{} `json:"data,omitempty"` } func (r Response) Dispatch(ctx iris.Context) { ctx.StatusCode(r.Code) ctx.JSON(r) } - 控制器方法直接返回：
func (c *UserController) Get() mvc.Result { user, err := c.service.FindByID(c.Ctx.Params().Get("id")) if err != nil { return Response{Code: 404, Message: "user not found"} } return Response{Code: 200, Data: user} } - 注意：不要在
Dispatch方法里调ctx.StopExecution()或修改 response writer 多次 —— Iris 会自动终止链，重复写会 panic
非 MVC 场景下如何避免重复代码
纯路由 handler（如 app.Get("/api/user", handler)）没法用 mvc.Result，此时靠中间件 + 公共函数兜底最稳。
- 写一个
WriteResponse(ctx iris.Context, code int, data interface{}, err error)函数，内部统一处理err != nil→400/500+ 错误消息，err == nil→200+ data - 把该函数注册为
ctx.Values().Set("writeResp", writeResponse)，让 handler 通过ctx.Values().Get("writeResp")拿到并调用 —— 避免闭包传参污染 - 千万别在中间件里直接
ctx.JSON()—— 它会提前写出响应，导致后续 handler panic；中间件只该设 header、记录耗时、注入值，不该终结响应
容易被忽略的边界点
响应封装看似简单，但三类情况常被跳过：
- 空数据场景：比如分页接口返回
data: []，但message写成 "success" 就不够语义；建议统一用message: "ok"或留空，靠code表达含义 - 敏感字段过滤：用户结构体带
PasswordHash字段？别指望 JSON tag 一劳永逸 —— 前端可能调错接口拿到全量数据；应在 service 层返回前就剔除，或用structs.Map()投影字段 - Content-Type 不显式设：Iris 默认设
application/json，但若你返回text/plain日志或application/octet-stream文件，必须手动ctx.ContentType()，否则浏览器乱码或下载失败
