Iris接口设计核心是路由分组、参数约束与错误响应一致性：用Party分组管理版本与权限，按Content-Type选ReadJSON/ReadForm，StatusCode后必跟StopExecution，结构体字段须大写导出。
直接上手 Iris 的 API 接口设计，关键不是“怎么写路由”，而是「路由分组 + 参数约束 + 错误响应一致性」这三点没对齐，接口就容易散、难维护、调试时反复查 ctx.StatusCode()。
如何用 Party 分组管理 API 版本与权限域
Iris 的 Party 不是装饰用的，它是实际路由注册和中间件挂载的最小作用域单元。抽奖系统里把用户操作和后台管理拆成两个分组，不是为了看着整齐，而是因为它们天然需要不同的中间件链：
-
/api/v1/lottery需要 JWT 验证 + 限流中间件，但不需要管理员权限 -
/api/v1/admin必须叠加adminAuth中间件，且所有 handler 都应拒绝非 admin 用户的ctx.User().GetRole()不为"admin"的请求 - 分组后，
app.Party("/api/v1/lottery").Use(jwtMiddleware, rateLimit)这种写法比每个路由单独.Use(...)更可靠，避免漏挂
ctx.ReadJSON 和 ctx.ReadForm 的选择依据
不是“能用就行”，而是看客户端发的是什么 Content-Type：
- 前端用
fetch(..., { body: JSON.stringify(...) })→ 必须用ctx.ReadJSON(&req)，否则ctx.FormValue拿不到字段 - 表单提交或 Postman 选
form-data→ 用ctx.ReadForm(&req)，它会自动解析 multipart 和 urlencoded 两种格式 - 混用会导致结构体字段始终为空，且
ctx.StatusCode()还是 200，容易误判为逻辑成功 - 建议在 handler 开头加
if err := ctx.ReadJSON(&req); err != nil { ctx.StatusCode(400); ctx.JSON(map[string]string{"error": "invalid json"}); return }主动拦截
为什么 ctx.StatusCode(404) 后还要调用 ctx.StopExecution()
这是 Iris 里最容易被忽略的执行流陷阱。Iris 默认不中断后续 handler 执行 —— 即使你写了 ctx.StatusCode(404)，只要没显式终止，控制权仍会往下走，可能触发数据库查询、Redis 操作甚至二次 ctx.JSON，导致响应体错乱或状态码被覆盖。
- 所有提前返回的分支（如参数校验失败、资源未找到、权限不足）都必须跟
ctx.StopExecution() - 不要依赖 defer 或 middleware 的“兜底”逻辑来统一处理错误，那会掩盖真实执行路径
- 一个典型反例：
if !exists { ctx.StatusCode(404); return }→ 错，return 只退出当前函数，不阻止路由链中下一个 handler 被调用
接口返回结构体字段名大小写不一致的坑
Iris 默认用 Go 原生 json.Marshal，所以结构体字段必须首字母大写才能导出。但很多人写 type LotteryResp struct { code int `json:"code"` }，结果 code 字段永远不出现 —— 因为小写字段无法被 json 包访问。
- 正确写法：
Code int `json:"code"`（字段大写 + tag 小写） - 如果想全局统一响应格式，别用匿名 struct 临时拼，定义一个
BaseResp并复用：ctx.JSON(BaseResp{Code: 200, Data: data}) - 注意
time.Time字段默认序列化为长数字（Unix 纳秒），加json:"created_at,omitempty,time_rfc3339"才输出可读字符串
