GORM 软删除 JOIN 报 deleted 歧义:全局回调与手写 SQL

2026-11-19 后端开发 有希 41 次浏览

一个原本正常的查询,加上 JOIN 之后突然报:

Error 1052 (23000): Column 'deleted' in where clause is ambiguous

SQL 里明明只写了一张表的过滤条件,为什么 MySQL 说 deleted 有歧义?问题通常不在手写 SQL,而在全局软删除回调自动补上的那半句 deleted = 0。

本文基于 GORM 1.31.2、MySQL 8,源码位置是 pkg/gormx/soft_delete.go 和 pkg/gormx/tenant.go。

最小复现:JOIN 后突然歧义

在开发库直接执行一条普通的关联查询:

SELECT a.id
FROM article a
JOIN article_tag t ON t.article_id = a.id
WHERE deleted = 0
LIMIT 1;

返回:

ERROR 1052 (23000): Column 'deleted' in where clause is ambiguous

两张表都有 deleted 列,WHERE deleted = 0 没有说明是哪一张。手写 SQL 时这个问题很容易发现,因为列名是你自己写的。真正麻烦的是 GORM 自动追加的条件。

用项目里的软删除回调复现同样的查询:

db.Model(&Article{}).
    Joins("JOIN article_tag t ON t.article_id = article.id").
    Where("t.deleted = 0").
    Find(&list)

实际生成的 SQL 是:

SELECT `article`.`id`
FROM `article`
JOIN article_tag t ON t.article_id = article.id
WHERE t.deleted = 0 AND `deleted` = 0
LIMIT 1

最后那个 `deleted` = 0 不在业务代码里,是全局回调加的。它没有表前缀,JOIN 之后就变成歧义列。

回调为什么会加这一句

pkg/gormx/soft_delete.go 在查询前注册了一个回调:

db.Callback().Query().Before("gorm:query").Register("soft_delete:query", func(db *gorm.DB) {
    if db.Statement.Schema != nil {
        if _, ok := db.Statement.Schema.FieldsByDBName[cfg.Field]; ok {
            if !whereHasEqColumn(db, cfg.Field, cfg.Active) {
                db.Statement.AddClause(clause.Where{
                    Exprs: []clause.Expression{
                        clause.Eq{Column: clause.Column{Name: cfg.Field}, Value: cfg.Active},
                    },
                })
            }
        }
    }
})

几个关键点:

  • 只有 Statement.Schema != nil 时才加条件,也就是用 Model、Find 这类带模型的方式查询时;
  • 列名直接用 clause.Column{Name: "deleted"},没有指定表;
  • whereHasEqColumn 只能判断“条件里有没有同名列”,无法判断这个条件属于哪张表。

租户回调用的是同一套写法,tenant_id 也会以不带表前缀的形式追加。两张表都有 tenant_id 时,报错会换成:

Column 'tenant_id' in where clause is ambiguous

三种修法,按场景选

1. 放弃 JOIN,分两次查

本项目工具列表最后采用的就是这个方案。分组和工具都在 tool 表里,但查询时没有自连接,而是先查工具,再查分组,最后在内存里排序:

list, err := query.Find(&list).Error
if err != nil {
    return nil, err
}

groups, err := r.FindListGroups(ctx)
if err != nil {
    return nil, err
}
if len(groups) > 0 {
    groupOrder := make(map[int64]int, len(groups))
    for i := range groups {
        groupOrder[groups[i].ID] = i
    }
    sort.SliceStable(list, func(i, j int) bool {
        oi, oj := groupOrderOf(groupOrder, list[i].ParentID), groupOrderOf(groupOrder, list[j].ParentID)
        if oi != oj {
            return oi < oj
        }
        if list[i].Sort != list[j].Sort {
            return list[i].Sort < list[j].Sort
        }
        return list[i].ID < list[j].ID
    })
}

优点是完全绕开 JOIN 的列名歧义,两张表各自走自己的回调和索引;缺点是数据量大时要把两张表的数据都取回内存。适合分组、字典这类小表。

2. 用子查询代替 JOIN

如果只是按关联表过滤主表,可以写成子查询:

db.Model(&Article{}).
    Where("id IN (?)",
        db.Table("article_tag").
            Select("article_id").
            Where("tag_id = ? AND deleted = 0 AND tenant_id = ?", tagID, tenantID),
    ).
    Find(&articles)

外层查询只有 article 一张表,软删除回调追加的 `deleted` = 0 不会歧义;子查询里的 deleted 和 tenant_id 要自己写全,因为它是 Table 查询,回调不会自动补。

3. 用 Table + 显式列名,接管过滤条件

必须 JOIN 时,可以不用 Model,改用 Table,让 Statement.Schema 为空,从源头跳过自动回调:

var ids []int64
err := db.Table("article AS a").
    Select("a.id").
    Joins("JOIN article_tag t ON t.article_id = a.id").
    Where("a.deleted = 0 AND t.deleted = 0 AND a.tenant_id = ?", tenantID).
    Limit(1).
    Scan(&ids).Error

实测这条查询可以正常返回。代价是软删除和租户过滤都要自己写,漏掉任何一条都会把已删除或别的租户的数据查出来。只建议在确实需要复杂 JOIN、且能保证每条 SQL 都带全条件的仓储方法里使用。

修法是否保留自动过滤适合的表规模主要风险
两次查询 + 内存排序是分组、字典等小表数据量大时内存和延迟上升
子查询外层保留中等规模子查询要手写 deleted/tenant_id
Table + 显式条件否复杂 JOIN漏写条件会越权或读到已删除数据

不要用 Unscoped 绕过

看到歧义后,一个常见的反应是加 Unscoped():

db.Unscoped().Model(&Article{}).Joins(...).Find(&list)

Unscoped 是 GORM 原生软删除的开关,但本项目用的是自定义回调。回调只检查 Statement.Schema 和条件里有没有同名列,不检查 Unscoped 标记,所以这句 Unscoped() 不一定能去掉自动追加的 deleted = 0,却会让开发者误以为已经处理完了。

要绕过自动过滤,应该让 Schema 为空(Table)或者不要用会触发回调的模型查询,而不是靠一个语义不匹配的开关。

验证时看生成的 SQL

这类问题只看结果很难判断,必须看最终 SQL。两种方式:

// 开发环境临时打开
db = db.Debug()

或者打开 GORM 的日志级别,把慢查询和错误 SQL 打出来。重点确认三件事:

  1. WHERE 里有没有不带表前缀的 deleted 或 tenant_id;
  2. JOIN 的每张表是否都有自己的 deleted = 0;
  3. Table 查询是否手动补了租户条件。
Model+Join auto deleted => err=Error 1052 (23000): Column 'deleted' in where clause is ambiguous rows=0
Table+Join explicit deleted => err=<nil> ids=[15]

上面两行是本地复现的真实输出:同一个 JOIN,用 Model 触发回调就报 1052,用 Table 显式写全条件就正常。

边界与常见错误

  • 只给 JOIN 表加 t.deleted = 0 不够,回调仍会追加外层的 `deleted` = 0;要么让回调不触发,要么两张表都显式限定。
  • whereHasEqColumn 的去重是按列名判断的,不能拿来区分表。两张表都有同名列时,它不会帮你消歧。
  • 租户回调和软删除回调是两套,JOIN 时可能先报 deleted 歧义,修完再报 tenant_id 歧义,两个都要检查。
  • Table 查询不会自动加租户过滤,手写 SQL 时必须显式带 tenant_id,否则是数据越权,不只是查询报错。
  • 分两次查时,排序逻辑要自己保证稳定;本项目用 sort.SliceStable,并在分组缺失时用哨兵值排到最后。

相关工具

排查时可以把最终 SQL 贴进 SQL 格式化工具 看清 JOIN 和 WHERE 的层次;软删除、多租户回调的完整背景见 GORM 使用心得,更多数据库与服务端文章在 后端开发分类。

FAQ

为什么单表查询从来不报这个错?

单表只有一份 deleted 列,MySQL 不需要判断归属。JOIN 之后同名列出现两份,未限定表名的条件才会触发 1052。

把回调里的列名改成带表前缀不就行了?

回调执行时不一定知道最终 SQL 的主表别名,而且 JOIN 表的别名由业务代码决定。让框架替所有查询猜表名,比在业务侧显式写清楚更危险。

Table 查询为什么不会自动加软删除条件?

回调判断的是 Statement.Schema,Table("article AS a") 没有绑定模型,Schema 为空,回调直接跳过。这是绕过机制,不是 bug,但要把过滤条件补全。

两次查询会不会有数据一致性问题?

两条查询不在同一个事务里时,理论上可能读到两次查询之间的变更。工具列表这类允许最终一致的场景可以接受;强一致场景应使用事务或子查询。

结语:软删除回调替你省掉了重复的 deleted = 0,代价是它不知道你的 JOIN 长什么样。手写关联查询时,先看最终 SQL,再决定是拆查询、用子查询,还是接管过滤条件。

评论

登录后即可参与评论

还没有评论,来说两句吧

相关文章