GORM 软删除 JOIN 报 deleted 歧义:全局回调与手写 SQL
一个原本正常的查询,加上 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 打出来。重点确认三件事:
WHERE里有没有不带表前缀的deleted或tenant_id;- JOIN 的每张表是否都有自己的
deleted = 0; 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,再决定是拆查询、用子查询,还是接管过滤条件。
評論
還沒有評論,來說兩句吧