新增操作必须绑定结构体而非map[string]interface{},因Iris不支持直接绑定map,否则会导致字段丢失、类型错误或SQL插入全NULL;需定义带db/json标签的导出结构体,用ctx.ReadJSON解析JSON请求体,并通过RowsAffected()和事务确保插入可靠性。

新增操作必须绑定结构体,不能直接用 map
Iris 默认不支持直接将 map[string]interface{} 绑定到数据库操作,强行这么做会导致字段丢失或类型错误。你得先定义一个 Go 结构体,字段名要和数据库列名(或标签)对齐,并带上 db 标签(如果用的是 GORM)或适配你实际 ORM 的标签。
常见错误现象:INSERT INTO ... VALUES (?, ?, ?) 插入全为 NULL,或者报 sql: converting argument $1 type: unsupported type map[string]interface {}, a map。
- 结构体字段必须导出(首字母大写)
- 推荐显式使用
json:和db:标签,避免依赖默认命名规则 - 如果用 GORM,
CreatedAt/UpdatedAt字段需设为autoCreateTime/autoUpdateTime,否则可能插入零值时间
路由里用 ctx.ReadJSON() 解析请求体,别用 ctx.FormValue()
新增接口基本都是 POST + JSON,ctx.FormValue() 只读表单数据(application/x-www-form-urlencoded 或 multipart/form-data),对 JSON 无效,会返回空字符串或 panic。
正确做法是先声明结构体变量,再调用 ctx.ReadJSON(&v)。它会自动处理 Content-Type、解码失败返回 400 错误,比手动 io.ReadAll + json.Unmarshal 更安全。
- 如果解析失败,Iris 默认返回
400 Bad Request和错误详情,无需额外判断 - 想自定义错误响应,可提前用
if err := ctx.ReadJSON(&v); err != nil { ... } - 注意:结构体字段类型必须和 JSON 值严格匹配,比如 JSON 传
"123",Go 字段是int就会失败
插入后必须检查 result.RowsAffected() 或错误,不能只看 err == nil
GORM 的 Create() 或原生 db.Exec() 即使 SQL 执行成功,也可能因唯一键冲突、外键约束等导致实际未插入任何行。只判 err == nil 会掩盖这类“静默失败”。
尤其在并发场景下,比如用户注册时昵称唯一,两个请求几乎同时提交相同昵称,其中一个会触发唯一约束,但 err 可能为 nil(取决于驱动和配置),必须靠 RowsAffected() 或更稳妥的 db.First() 回查确认。
- GORM v2 推荐用
result.Error+result.RowsAffected双检 - 原生
sql.DB用res, err := db.Exec(...)后调res.RowsAffected() - 不要依赖
lastInsertId判断是否成功——SQLite 可能返回 0,MySQL 在批量插入时也不可靠
事务不是默认开启的,高一致性场景必须显式控制
Iris 本身不介入数据库事务,所有事务逻辑完全由你使用的数据库驱动或 ORM 控制。比如新增用户的同时要插入关联的 profile 记录,没加事务就可能出现用户写入成功但 profile 失败,造成数据不一致。
GORM 示例中常漏掉 tx.Rollback() 的 defer,或在多个 if 分支里忘记统一 commit/rollback,导致连接卡住或脏数据残留。
- 用
db.Transaction(func(tx *gorm.DB) error { ... })最省心,失败自动 rollback - 手动事务务必用
defer tx.Rollback()开头,然后在成功路径末尾tx.Commit() - 事务内不要跨 handler 传递
*gorm.DB实例,避免复用非事务连接
Iris 的 HTTP 层很轻量,真正决定新增是否可靠的是结构体定义、JSON 解析方式、ORM 调用细节和事务边界——这些地方一松动,线上就容易出现“明明返回成功却查不到数据”或者“重复插入”的问题。











