GORM 批量插入回调:只有第一条被填充

2026-11-19 后端开发 有希 42 views

批量插入角色菜单、批量导入用户、批量写日志时,代码只调用了一次 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)
        }
    }
})

三层保护:

  1. Dest 是 map 时跳过,调用方显式指定了要写入的列,回调不覆盖;
  2. 字段按 FieldsByDBName 查找;
  3. 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 时同样要检查每一批的每一行,不要只断言总数或第一行。

验证清单

  1. 单条 Create 和批量 Create 各跑一次,检查每一行的租户、创建人、更新人。
  2. 把软删除默认值设成非零值,确认每一行都写入。
  3. 打开 SQL 日志,确认批量 INSERT 的 VALUES 里每一组参数都带上了这些列。
  4. 按 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

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles