gorm scope 函数必须接收并返回 *gorm.db，否则调用链中断；需链式返回、禁用终结方法、用闭包处理动态参数、谨慎使用 preload/joins，并通过 dryrun 单元测试 sql。
Scope 函数必须接收 *gorm.DB 并返回 *gorm.DB
这是 GORM Scope 的硬性签名要求，不是约定俗成。如果函数返回 error、interface{} 或直接修改传入的 *gorm.DB（比如用 db.Session(...) 赋值但不返回），调用链就会中断或静默失效。
常见错误是写成：
func WithStatusActive(db *gorm.DB) { // ❌ 没返回值，后续 .Find() 用的是原始 db
db = db.Where("status = ?", "active")
}
正确写法必须链式返回：
func WithStatusActive(db *gorm.DB) *gorm.DB {
return db.Where("status = ?", "active") // ✅
}
- 所有条件拼接都得基于输入的
db，不能新建gorm.DB实例 - 如果内部需要调用其他 Scope，直接组合：
return WithStatusActive(WithDeleted(db)) - 不要在 Scope 里调用
.Find()、.Count()等终结方法——它只负责“修饰查询上下文”
多个参数的 Scope 要用闭包封装
像分页、模糊搜索这类需要动态传参的逻辑，不能把参数塞进 Scope 函数签名里（GORM 不支持）。必须用闭包捕获参数，返回符合签名的函数。
例如带关键词的搜索：
func WithKeyword(keyword string) func(*gorm.DB) *gorm.DB {
return func(db *gorm.DB) *gorm.DB {
if keyword == "" {
return db
}
return db.Where("title LIKE ? OR content LIKE ?", "%"+keyword+"%", "%"+keyword+"%")
}
}
- 调用时写成：
db.Scopes(WithKeyword("go")).Find(&posts) - 闭包内做空值判断很关键——否则
WHERE title LIKE '%%' OR content LIKE '%'会拖慢查询 - 注意 SQL 注入风险：
keyword必须走?占位符，不能拼字符串 - 如果参数多（如分页的
page和limit），建议封装为结构体传入，再在闭包里解构
关联预加载和 Joins 容易破坏 Scope 链
在 Scope 里用 Preload 或 Joins 是常见需求，但它们对主表别名、JOIN 条件敏感，容易因调用顺序出错。
比如用户文章列表要预加载作者头像：
func WithAuthor(db *gorm.DB) *gorm.DB {
return db.Preload("Author.Avatar").Joins("JOIN users ON posts.author_id = users.id")
}
- 必须确保
Joins的表别名和Preload路径一致；GORM 默认用 struct 字段名当 JOIN 别名，别手写AS u后又用Preload("Author") - 多个 Scope 同时做
Joins可能冲突（如都 JOIN users 表），此时应合并到一个 Scope 里统一控制 - 慎用
Preload在复杂 Scope 中——它会触发 N+1 查询优化逻辑，若主查询已含SELECT *，可能重复加载字段
测试 Scope 时别依赖真实数据库
Scope 函数本质是构建 SQL 查询条件，完全可单元测试，没必要启动数据库。
GORM 提供 gorm.io/gorm/clause 和内存 DB 支持，但最轻量的方式是检查生成的 SQL：
db := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
var posts []Post
sql := db.Scopes(WithStatusActive).Session(&gorm.Session{DryRun: true}).Find(&posts).Statement.SQL.String()
// 断言 sql 包含 "WHERE status = 'active'"
-
DryRun: true是关键，它跳过执行，只生成 SQL - 避免在测试里写
db.Create(...)再查——这测的是整个流程，不是 Scope 本身 - 多个 Scope 组合时，SQL 顺序可能影响结果（如
Where在Joins前后语义不同），测试要覆盖组合场景
Scope 封装的难点不在语法，而在理解它如何参与 GORM 的查询构建流水线——条件叠加、别名继承、SQL 片段拼接，每一步都可能被后续操作覆盖或误解。写完一个 Scope，先用 DryRun 看 SQL，比跑一遍接口更早暴露问题。
