灰度发布分页必须严格隔离查询上下文，需为分页主查与count分别创建独立db会话，灰度标识须显式写入where条件，count应手写子查询，排序字段须有索引，优先采用带灰度标识的游标分页。
灰度发布场景下分页必须隔离查询上下文
灰度发布时，同一接口可能同时服务新旧两套逻辑（比如部分用户走新模型、部分走旧逻辑），如果分页查询复用同一个 *gorm.DB 实例，Where 条件、Limit、Offset 甚至 Preload 都可能被意外继承或污染。最典型的现象是：灰度用户看到的列表页数异常、总数不准、甚至混入非灰度数据。
根本原因在于 GORM 的链式调用是 mutable 的——db.Where("version = ?", "v2") 返回的是原 db 的引用，后续任何 .Limit() 或 .Count() 都会带上这个条件，除非显式新建会话。
- 灰度标识（如
gray_tag、user_group）必须作为Where条件写在分页主查询和Count查询里，且二者不能共用 db 实例 - 用
db.Session(&gorm.Session{NewDB: true})创建全新会话做Count，避免受主查询的Limit/Offset影响 - 若灰度逻辑涉及 JOIN 或子查询，
Count务必手写子查询（如db.Raw("SELECT COUNT(*) FROM (...) AS t")），否则 GORM 自动拼的 COUNT 可能漏掉灰度过滤 - 不要在中间件里全局设置
db = db.Where(...)，这会让所有后续查询都带上灰度条件，破坏非灰度路径
灰度分页参数校验要叠加业务维度
普通分页只校验 page 和 limit 是否合法，灰度场景下还得检查灰度标识是否匹配当前请求上下文。比如后端从 header 解析出 X-Gray-Group: canary，但数据库查不到对应配置，就该拒绝而非 fallback 到全量数据。
-
page小于 1 时设为 1，但若灰度策略已关闭（如配置中心返回enabled: false），应直接返回空列表 +is_gray: false字段，而不是静默切到全量 -
limit不仅要限制在 1–100，还要根据灰度流量比例动态缩容：比如灰度只放 5% 流量，limit可设为配置值的 1/20，防止单个灰度请求拖垮数据库 - 前端传的
cursor（游标分页）必须校验是否由本灰度版本生成，防止旧版游标混入新版查询导致越界或重复 - 用
c.ShouldBindQuery(&req)绑定结构体时，在bindingtag 里加required约束灰度字段，比如GrayGroup string `form:"gray_group" binding:"required,oneof=canary stable"`
灰度数据分页必须强制 ORDER BY + 索引字段
灰度发布常伴随 schema 变更（如新增字段、调整索引），若排序字段没在灰度表中建索引，OFFSET 分页会直接变慢十倍以上。更危险的是：灰度表和主表排序结果不一致，导致同一页数据在灰度/非灰度路径下顺序错乱，前端“加载更多”时出现重复或丢失。
- 排序字段必须是灰度表中已存在且有索引的列，优先选
id ASC或created_at DESC, id DESC；禁用ORDER BY RAND()或无索引字段 - 如果灰度逻辑引入了新时间字段（如
updated_at_v2），必须同步在该字段上建索引，否则OFFSET查询会触发 filesort - 避免在灰度查询中用
Preload加载关联数据后再分页——GORM 会先查主表再批量查关联，灰度条件下关联数据可能未同步上线，导致 N+1 或 panic - 用
EXPLAIN检查灰度 SQL 的执行计划，确认key列显示用了预期索引，rows值不随OFFSET增大而线性增长
大数据量灰度分页优先用游标，别碰 OFFSET
灰度环境通常数据量小、验证快，但一旦灰度放量到 10% 以上，OFFSET 分页在百万级表上就会暴露性能问题。此时不是换数据库，而是换分页模型：游标分页天然适合灰度隔离，因为它的 “上一页最后一条 ID” 是灰度数据集内部的局部锚点，不依赖全局偏移。
- 灰度游标必须包含灰度标识字段，例如
cursor := base64Encode(fmt.Sprintf("%d_%s", lastID, grayGroup))，防止跨灰度组误用 - 查询条件要严格对齐：游标解码出的
lastID必须配合相同灰度条件（如WHERE gray_group = ? AND id > ? ORDER BY id LIMIT 20） - 灰度上线初期可双写游标：同时生成传统
page参数和游标，前端按需切换；等灰度稳定后，逐步下线page接口 - 注意时钟漂移——如果灰度服务跨多个时区部署，别用纯
created_at做游标，改用id或created_at + id复合键
