GORM 批量插入回调:只有第一条被填充
批量插入角色菜单、批量导入用户、批量写日志时,代码只调用了一次 Create(&list),数据库里却出现一半字段为空:
id tenant_id creator
1 1 42
2 0
3 0
单条插入正常,批量插入只有第一条带租户和创建人。接口不报错,直到按 tenant_id 过滤的列表页只剩一条数据,才发现问题。
根因通常在 GORM 的创建回调里:Statement.SetColumn 默认只写 CurDestIndex 指向的那一条,批量场景必须显式让它遍历整个切片。本文基于 GORM 1.31.2,源码位置是 pkg/gormx/column.go。
最小复现:第一行有值,后面都是零
用临时表和一个创建回调复现:
type TenantRow struct {
ID int64 `gorm:"column:id;primaryKey"`
TenantID int64 `gorm:"column:tenant_id"`
}
db.Callback().Create().Before("gorm:create").Register("repro:fill_tenant", func(tx *gorm.DB) {
if f, ok := tx.Statement.Schema.FieldsByDBName["tenant_id"]; ok {
tx.Statement.SetColumn(f.DBName, int64(100))
}
})
rows := make([]TenantRow, 3)
db.Create(&rows)
输出:
fromCallbacks=false tenants=100,0,0
只传两个参数时,SetColumn 只写当前目标行。回调执行时 CurDestIndex 指向第一条,后面两条没有被赋值。
把调用改成第三个参数 true:
tx.Statement.SetColumn(f.DBName, int64(100), true)
输出变成:
fromCallbacks=true tenants=100,100,100
这是批量插入回调必须显式传 true 的直接原因。
为什么传 false 也不行
GORM 的 SetColumn 签名是可变参数:
func (stmt *Statement) SetColumn(name string, value interface{}, fromCallbacks ...bool) {
// ...
switch stmt.ReflectValue.Kind() {
case reflect.Slice, reflect.Array:
if len(fromCallbacks) > 0 {
for i := 0; i < stmt.ReflectValue.Len(); i++ {
stmt.AddError(field.Set(stmt.Context, stmt.ReflectValue.Index(i), value))
}
} else {
stmt.AddError(field.Set(stmt.Context, stmt.ReflectValue.Index(stmt.CurDestIndex), value))
}
}
}
判断条件是 len(fromCallbacks) > 0,不是 fromCallbacks[0] == true。所以:
| 调用方式 | len(fromCallbacks) | 实际行为 |
|---|---|---|
SetColumn(name, value) | 0 | 只写 CurDestIndex 那一行 |
SetColumn(name, value, false) | 1 | 仍然遍历整个切片 |
SetColumn(name, value, true) | 1 | 遍历整个切片 |
传 false 看起来像“关闭”,实际效果和传 true 一样。要么不传第三个参数,要么传 true,不要用 false 表达“只写第一条”。
字段查找:DB 名和 Go 字段名不是一回事
回调里经常需要按列名找字段。GORM 的 Schema 有两个映射:
if _, ok := db.Statement.Schema.FieldsByDBName[cfg.Field]; ok {
// 按数据库列名
}
复现输出:
FieldsByName[tenant_id]=false FieldsByDBName[tenant_id]=true
Go 字段是 TenantID,数据库列是 tenant_id。FieldsByName 按 Go 字段名索引,用 tenant_id 去查永远找不到;FieldsByDBName 才对应建表列名。
用错映射的直接后果是回调里的 if 永远不成立,租户和审计字段一个都不填。更隐蔽的情况是字段名刚好与列名相同(例如 Deleted 配 column:deleted),开发环境能跑,换一张表又失效。
项目里的统一写法
项目把填充逻辑收进一个函数:
// setCreateColumn 为待插入的记录填充列值
// GORM 的 Statement.SetColumn 默认只写 CurDestIndex 指向的那一条,批量 Create(Dest 为切片)时
// 即只有第一条被填充,其余记录的租户号、审计字段会落成库默认值——回调场景必须传
// 第三个参数 fromCallbacks=true,它才会遍历切片的每个元素
// Dest 为 map 时表示调用方显式指定了要写入的列,回调不覆盖
func setCreateColumn(db *gorm.DB, column string, value interface{}) {
if _, ok := db.Statement.Dest.(map[string]interface{}); ok {
return
}
db.Statement.SetColumn(column, value, true)
}
租户、审计、软删除三个创建回调都调用它:
db.Callback().Create().Before("gorm:create").Register("soft_delete:create", func(db *gorm.DB) {
if db.Statement.Schema != nil {
if field, ok := db.Statement.Schema.FieldsByDBName[cfg.Field]; ok {
setCreateColumn(db, field.DBName, cfg.Active)
}
}
})
三层保护:
Dest是 map 时跳过,调用方显式指定了要写入的列,回调不覆盖;- 字段按
FieldsByDBName查找; SetColumn固定传true,批量切片逐条填充。
测试怎么覆盖批量场景
单条插入的测试抓不到这个问题。项目里专门写了批量用例:
func TestBatchCreateFillsEveryRow(t *testing.T) {
db := newVerifyDB(t)
ctx := SetTenantIDToContext(context.Background(), 100)
ctx = SetUserIDToContext(ctx, 42)
list := []verifyModel{
{Name: "a"},
{Name: "b"},
{Name: "c"},
}
tx := db.WithContext(ctx).Create(&list)
if tx.Error != nil {
t.Fatalf("batch create failed: %v", tx.Error)
}
for i, m := range list {
if m.TenantId != 100 {
t.Fatalf("第 %d 条 tenant_id = %d,期望 100", i+1, m.TenantId)
}
if m.Creator == nil || *m.Creator != "42" {
t.Fatalf("第 %d 条 creator = %v,期望 42", i+1, m.Creator)
}
if m.Updater == nil || *m.Updater != "42" {
t.Fatalf("第 %d 条 updater = %v,期望 42", i+1, m.Updater)
}
}
}
运行结果:
=== RUN TestBatchCreateFillsEveryRow
--- PASS: TestBatchCreateFillsEveryRow (0.01s)
=== RUN TestBatchCreateFillsSoftDeleteDefault
--- PASS: TestBatchCreateFillsSoftDeleteDefault (0.00s)
PASS
ok app/pkg/gormx 1.022s
第二个用例把软删除默认值设为非零的 5,专门避免“零值刚好等于期望值”导致测试误通过。
这个用例来自一次真实故障:新建租户批量分配角色菜单后,只有第一条带 tenant_id,登录后按租户过滤只剩一条菜单。单条插入测试全部通过,因为问题只出现在切片路径上。
边界与常见错误
Dest是[]map[string]interface{}时,SetColumn会遍历每个 map;但项目的setCreateColumn只跳过单个 map,不跳过 map 切片。批量写 map 的场景要单独确认语义。Update回调也使用SetColumn,但它操作的是单条模型,不需要担心切片遍历;不要为了“统一”给更新回调也传true,语义会变。- 软删除默认值如果是 0,结构体零值也是 0,测试无法区分“填充成功”和“根本没填”。测试配置要用非零值。
- 批量插入的审计字段依赖请求 context。没有用户上下文时,回调会跳过填充,落库的值就是零值;这不是批量 bug,但会让测试误判。
- 使用
CreateInBatches时同样要检查每一批的每一行,不要只断言总数或第一行。
验证清单
- 单条
Create和批量Create各跑一次,检查每一行的租户、创建人、更新人。 - 把软删除默认值设成非零值,确认每一行都写入。
- 打开 SQL 日志,确认批量 INSERT 的
VALUES里每一组参数都带上了这些列。 - 按
tenant_id查询刚插入的数据,确认条数与插入条数一致。
SELECT tenant_id, creator, updater, COUNT(*)
FROM verify_table
WHERE deleted = 0
GROUP BY tenant_id, creator, updater;
如果结果里出现 tenant_id = 0 或 creator IS NULL 的分组,回调就没有覆盖到全部行。
相关工具
排查批量 INSERT 的列和值可以用 SQL 格式化工具 对照生成的 SQL;GORM 回调、软删除和多租户的整体设计见 GORM 使用心得,更多后端文章在 后端开发分类。
FAQ
为什么单条插入没问题,批量插入就漏字段?
SetColumn 默认写 CurDestIndex 指向的单行。单条插入时目标只有一行,看起来正常;切片场景下索引停在第一条,后面的行不会被写入。
传 false 和传 true 有什么区别?
在 SetColumn 里没有区别,判断只看可变参数的长度。传 false 仍然算“传了参数”,会遍历整个切片。要只写第一条,必须省略第三个参数。
用 field.Set 直接遍历切片不行吗?
可以,但要自己处理索引、错误和 map 目标,还要重复 GORM 内部的反射逻辑。SetColumn(..., true) 已经封装了这些行为,优先用它。
为什么字段查找要用 FieldsByDBName?
FieldsByName 的键是 Go 字段名(如 TenantID),FieldsByDBName 的键是数据库列名(如 tenant_id)。回调配置通常写列名,用错映射会静默跳过填充。
结语:批量插入的回调问题不会报错,只会留下零值数据。把 SetColumn 的第三个参数固定为 true,按数据库列名查字段,再用逐行断言覆盖批量路径,才能让租户和审计字段真正落到每一行。
Comments
No comments yet — be the first to say something