直接用find和where不适合封装通用查询，因find强制查全字段、where链式调用难复用、缺乏分页/软删除/字段过滤统一入口；应结构化表达查询意图，用queryoption组合可配置行为，确保条件一致性与安全性。
为什么直接用 Find 和 Where 不适合封装通用查询
因为 Find 会强制加载全部字段，Where 链式调用后无法复用条件逻辑，且没有统一处理分页、软删除、字段过滤的入口。真实项目里一写就是 db.Where("status = ?", 1).Where("deleted_at IS NULL").Order("created_at DESC").Limit(20).Offset(0).Find(&users) —— 这种写法没法抽象成可配置的查询方法。
通用查询封装的核心不是“把 DB 对象传进去”，而是把「查询意图」结构化表达出来。比如分页参数、字段白名单、模糊搜索字段、排序字段这些，都应该作为输入参数显式声明。
- 别在封装函数里硬编码
deleted_at IS NULL，GORM 的Unscoped()是开关，不是默认行为 - 字段投影（
Select）必须由调用方决定，通用层只做白名单校验，不替用户选字段 -
Order参数要支持多字段，如"name ASC, created_at DESC"，不能只接受单个字符串
如何设计一个安全的通用查询函数签名
关键不是功能多，而是边界清晰。下面这个 QueryList 函数只负责组装条件、分页、排序和投影，不碰业务逻辑：
func QueryList[T any](db *gorm.DB, cond map[string]any, opts ...QueryOption) ([]T, int64, error) {
var list []T
var count int64
// 构建查询链
tx := db.Model(new(T))
tx = applyConditions(tx, cond)
tx.Count(&count)
// 应用分页/排序/字段筛选
for _, opt := range opts {
tx = opt(tx)
}
if err := tx.Find(&list).Error; err != nil {
return nil, 0, err
}
return list, count, nil
}
其中 QueryOption 是函数类型：type QueryOption func(*gorm.DB) *gorm.DB，这样就能灵活组合 Paginate(1, 20)、Select("id,name,updated_at")、OrderBy("updated_at DESC") 等行为，又不污染主逻辑。
- 用
map[string]any接收条件，比 struct 更灵活，适配动态筛选场景 -
db.Model(new(T))是必须的，否则泛型 T 的表名和字段映射会丢失 - 先
Count再Find是为了兼容 SQLite（不支持子查询计数），MySQL 可优化为单次查询，但通用层不做数据库分支判断
软删除和字段白名单怎么安全集成
软删除不能全局启用，必须按需注入；字段白名单也不能靠反射自动过滤，得由上层明确指定允许返回的字段，否则 Select("*") 会拖垮性能或泄露敏感字段。
推荐两个独立的 QueryOption：
// 软删除过滤（仅对启用了 gorm.DeletedAt 的模型生效）
func WithSoftDelete() QueryOption {
return func(db *gorm.DB) *gorm.DB {
return db.Where("deleted_at IS NULL")
}
}
// 字段白名单（防 SQL 注入，只允许字母、数字、下划线、逗号、空格）
func SelectFields(fields string) QueryOption {
re := regexp.MustCompile(`^[a-zA-Z0-9_,\s]+$`)
if !re.MatchString(fields) {
return func(db *gorm.DB) *gorm.DB { return db }
}
return func(db *gorm.DB) *gorm.DB {
return db.Select(fields)
}
}
-
WithSoftDelete不该自动加，因为有些接口要查已删除数据（如回收站） -
SelectFields的正则校验是底线，不依赖用户传进来的字段是否真实存在——存在性由 GORM 自己报错 - 不要在通用层做
LIKE模糊匹配封装，那是业务逻辑，应由调用方用map[string]any{"name LIKE ?": "%xxx%"}显式表达
分页参数校验和性能陷阱
Limit 和 Offset 直接拼进 SQL 很危险：前端传 limit=9999999 会导致全表扫描；offset 过大会让 MySQL 性能断崖下跌。
- 必须限制最大
limit，比如if limit > 100 { limit = 100 }，并在文档里写明 - 避免用
OFFSET做深分页，通用层不强制游标分页，但应在示例中给出WHERE id > ? ORDER BY id LIMIT 20的替代写法 -
Count查询本身可能很慢，尤其带复杂WHERE条件时，高并发下建议加缓存或改用估算值（如SELECT COUNT(*) FROM (SELECT 1 FROM table WHERE ...) AS t）
最常被忽略的是：通用查询函数返回的 count 和 list 必须基于完全相同的 WHERE 条件。如果中间某个 QueryOption 悄悄改了 Where（比如加了额外时间范围），count 就不准了——这种 bug 很难测出来，只能靠 Code Review 卡住非幂等的条件修改。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
