GORM不支持开箱即用的企业级多维度分页，需手动拼接条件并严格隔离COUNT与主查逻辑；Limit+Offset在多条件场景下易导致数据重复或丢失，游标分页才是高维筛选的可靠解法。
GORM 本身不提供企业级多维度分页的开箱即用能力，所谓“多维度”（如按状态+时间+关键词+排序方向动态组合）必须靠手动拼接查询条件 + 显式控制分页逻辑，否则极易因链式调用污染、COUNT 与主查不一致、游标值类型错位等问题导致数据错乱或性能崩溃。
为什么 Limit + Offset 在多条件场景下更危险
多维度筛选（比如 WHERE status IN ? AND created_at > ? AND name LIKE ?）会让 OFFSET 的物理偏移意义彻底失效：数据变动时，同一页可能重复出现某条记录，或直接跳过一条——尤其当索引未覆盖全部 WHERE 字段时，数据库执行计划可能改变扫描顺序。
- 常见错误现象：
page=100&size=20&status=active&keyword=admin返回空数组，但page=99最后一条和page=101第一条是同一记录 - 复合 WHERE 条件必须和
COUNT查询完全一致，否则前端页码控件计算出错；但 GORM 链式调用中Where状态容易残留，Count()调用前没重置 DB 实例就会漏条件 - 如果用了
Preload关联查询，Count(&total)不会统计关联表行数，但Find()结果集大小受关联数据爆炸影响（N+1 变成 N×M），导致实际返回条数却无感知 - 排序字段没建联合索引时，
ORDER BY status, created_at DESC可能全表文件排序，OFFSET 10000直接触发慢查询告警
Paginate 第三方插件在多维条件下不可信
像 github.com/joshbetz/pagination 这类库虽简化了 Offset 计算，但它无法感知你的 WHERE 条件是否动态拼接、也无法保证 COUNT 和主查使用同一份过滤逻辑。一旦你用 db.Where(...).Where(...) 动态追加条件，插件内部封装的 Count 很可能只作用于初始 DB 实例。
- 它默认不校验
page和size上限，恶意请求size=10000会穿透到数据库 - 对时间范围查询（如
created_at BETWEEN ? AND ?）不做参数类型检查，time.Time传错成字符串会导致 SQL 报错invalid time format - 游标分页模式下，它要求你手动传
cursor值并指定字段名，但若前端传next_cursor=1623456789（Unix 时间戳秒级），而后端排序字段是created_at DATETIME(6)（微秒级），值比较就失效 - 不支持嵌套结构体字段排序，比如想按
user.profile.age ASC排序，插件解析Order("profile.age")会失败，只能靠原生Order("users.age")手写 JOIN
手写安全分页函数必须隔离 COUNT 和主查
企业级接口要求每次请求都明确知道“总条数”和“本页数据”，且两者条件绝对一致。唯一可靠方式是构造两个独立的 *gorm.DB 实例，共享 WHERE 条件逻辑但不共享链式状态。
- 定义一个条件构建函数，接收参数并返回
func(*gorm.DB) *gorm.DB：
func buildUserQuery(p *PageParams) func(*gorm.DB) *gorm.DB {
return func(db *gorm.DB) *gorm.DB {
if p.Status != "" {
db = db.Where("status = ?", p.Status)
}
if !p.CreatedAfter.IsZero() {
db = db.Where("created_at > ?", p.CreatedAfter)
}
if p.Keyword != "" {
db = db.Where("name LIKE ?", "%"+p.Keyword+"%")
}
return db
}
}
- 分页主逻辑中分别应用：
cond := buildUserQuery(&p)
var total int64
cond(db.Model(&User{})).Count(&total) // 单独 COUNT
<p>var users []User
cond(db.Order("id DESC")).Offset((p.Page - 1) * p.Size).Limit(p.Size).Find(&users)</p>
-
PageParams必须做字段级校验：例如p.Size用min(p.Size, 100)截断，p.Page强制 ≥ 1，p.CreatedAfter校验是否早于当前时间 - 所有字符串模糊搜索必须加
%包裹，禁止前端透传原始 keyword，防止 SQL 注入或意外全表匹配
游标分页才是高维筛选的真正解法
当维度增加（状态+时间+分类+评分）、数据实时写入频繁、且用户可能翻到 page > 50 时，OFFSET 必须放弃。游标分页依赖上一页最后一条记录的排序字段值，每次只扫增量数据，天然规避偏移漂移问题。
- 必须确保排序字段有索引，且是**确定性单调递增字段**（如
id或created_at+id复合）；避免用updated_at（可能重复）或score（可能大量重复）作游标主键 - 请求首次不带
cursor，返回数据后附带next_cursor: users[len(users)-1].ID；下一次请求用WHERE id - 注意 NULL 处理：如果排序字段允许 NULL，需显式写
WHERE (id 并在代码中过滤掉 NULL 结果，否则游标失效 - 多字段游标要严格按
ORDER BY顺序拼条件，例如ORDER BY status ASC, created_at DESC, id DESC，则游标条件为：WHERE (status > ?) OR (status = ? AND created_at
游标值类型错配、排序字段无索引、或忘记处理 NULL，这三个点只要踩中一个，游标分页就退化成随机分页——这是生产环境最常被忽略的细节。
