iris.Context.JSON() 是 Iris MVC 中最直接、官方推荐的 JSON 返回方式，自动设置 Content-Type 和状态码，需避免手动序列化或错误调用顺序。

iris.Context.JSON() 是最直接的返回方式

在 Iris 的 MVC 结构中，控制器方法（如 Get()、Post()）接收 iris.Context 参数，它自带 JSON() 方法，无需手动设置 Header 或序列化。这是官方推荐、最轻量且默认处理好 Content-Type 和状态码的方式。

常见错误是先调用 ctx.StatusCode(200) 再调用 ctx.JSON() —— 实际上 JSON() 会自动设为 200，重复设置反而可能干扰内部逻辑；更危险的是手动用 json.Marshal() + ctx.ResponseWriter().Write()，这会绕过 Iris 的中间件和错误恢复机制。

• ✅ 正确写法：ctx.JSON(map[string]interface{}{"code": 0, "data": users})
• ⚠️ 避免手动序列化：bs, _ := json.Marshal(...); ctx.ResponseWriter().Write(bs) —— 丢失 Content-Type、不触发 JSON 格式化中间件（如时间字段格式化）、无法被 ctx.OnErrorCode() 捕获异常
• ? JSON() 默认使用 encoding/json，若需 jsoniter 或自定义 marshal 行为，应通过 app.JSONEncoder() 全局配置，而非单次替换

在 Controller 中返回结构体时注意字段导出与 Tag

Iris 的 JSON() 底层仍走 Go 原生 json.Marshal()，所以结构体字段必须首字母大写（导出），且推荐显式声明 json tag，否则字段名会按 Go 命名规则转成小驼峰（如 UserEmail → userEmail），容易和前端约定脱节。

尤其要注意嵌套结构体或 map 类型字段：如果嵌套结构体字段未导出，整个字段会被忽略；map 的 key 必须是可序列化的类型（string、int 等），不能是 struct 或 func。

• ✅ 推荐结构体定义：

  type UserResp struct {
      Code int    `json:"code"`
      Data []User `json:"data"`
  }
  type User struct {
      ID   uint   `json:"id"`
      Name string `json:"name"`
      CreatedAt time.Time `json:"created_at"`
  }

• ❌ 错误示例：email string（未导出，JSON 输出为空对象或跳过）
• ⚠️ 时间字段默认输出为 Go 默认格式（含时区信息），如需 ISO8601 格式，应在结构体 tag 中加 time_format（Iris 支持）：CreatedAt time.Time `json:"created_at" time_format:"2006-01-02T15:04:05Z07:00"`

配合 MVC 路由注册时别漏掉依赖注入绑定

如果你用 app.RegisterDependency() 注入了 service 或 repository 到 controller，但返回 JSON 时数据为空或 panic，大概率是依赖没正确绑定——Iris MVC 不会自动扫描构造函数参数，必须显式注册。

Expanso yaml-to-json

使用 Expanso Edge 管道将 YAML 输入转换为 JSON 格式。

下载

典型表现：controller 的字段（如 usersService UsersService）为 nil，调用其方法时 panic；或者 JSON() 返回空对象，实际数据没传进去。

• ✅ 正确绑定：app.RegisterDependency(&UsersService{}) 或 app.RegisterDependency(func() *UsersService { return NewUsersService() })
• ✅ Controller 构造函数需匹配注册类型：

  type UserController struct {
      usersService *UsersService // 类型必须与 RegisterDependency 一致
  }

• ⚠️ 注意生命周期：默认是 singleton，如需每次请求新建实例，要用 app.RegisterDependency(...).Transient()
• ? 若 controller 方法返回 error，Iris 不会自动转成 JSON 错误响应——需自己判断并调用 ctx.JSON() 或交由全局 error handler 处理

需要自定义状态码或 Header 时，JSON() 仍可配合使用

不是所有 JSON 响应都是 200。比如创建资源成功应返回 201，权限不足要返回 403。Iris 允许在调用 JSON() 前设置状态码，它不会覆盖你设的值；Header 同理，只要在 JSON() 前写入即可生效。

关键点在于顺序：必须先 ctx.StatusCode() / ctx.Header()，再 ctx.JSON()。反过来会导致 Header 被重置或状态码被覆盖。

• ✅ 正确顺序：

  ctx.StatusCode(201)
  ctx.Header("X-Resource-ID", "123")
  ctx.JSON(map[string]string{"msg": "created"})

• ❌ 错误顺序：ctx.JSON(...); ctx.StatusCode(201) —— 此时响应已写出，状态码无效
• ? 如果多个接口需统一添加 Header（如 X-Server-Time），建议用中间件，而不是每个 controller 里重复写

真正容易被忽略的是错误路径下的 JSON 返回：很多人只测试了正常流程，却没验证 service 层返回 error 时 controller 是否做了判空/判错处理，导致 panic 或返回空响应。Iris 不会帮你兜底，JSON(nil) 会输出 null，而 JSON(&struct{}) 中字段为 nil 指针也会输出 null —— 这些都得靠你自己在业务逻辑里控制。