go分页需统一处理参数校验、查询构造、总数获取、结果组装四环节：校验page≥1且page_size∈[1,100]，offset=(page-1)*size防溢出；总数须独立count且条件严格一致；响应用泛型pageresult封装并向上取整计算totalpages；大数据量优先游标分页。
Go 里没有内置的分页抽象，直接写 offset 和 limit 容易出错，尤其在跳页、边界值、总数统计不一致时。通用分页逻辑的关键不是封装一个函数，而是统一处理「请求参数校验 → 查询构造 → 总数获取 → 结果组装」这四个环节。
如何安全解析和校验分页参数
用户传的 page 和 page_size 往往是字符串，可能为空、负数、超大值或非数字。硬转 int 会 panic，不校验则导致 SQL 注入风险（比如 page_size=9999999 拖垮数据库）。
建议用如下方式处理：
- 用
strconv.ParseInt转换，并设合理上限（如page≤ 10000，page_size≤ 100） -
page小于 1 时强制设为 1；page_size小于 1 或大于上限时设为默认值（如 20） - 计算
offset时用(page - 1) * page_size，避免整数溢出（可加if offset > maxOffset { offset = maxOffset }防御）
为什么不能只查一次数据库就分页
很多新手会写 SELECT * FROM users LIMIT $1 OFFSET $2 然后靠 len(rows) 判断是否最后一页——这无法知道总记录数，前端做分页控件（如“共 127 条，第 3/13 页”）就缺数据。
必须额外查总数，但要注意：
- 不要用
SELECT COUNT(*)加原始 WHERE 条件——WHERE 中若含JOIN或子查询，COUNT 可能慢且语义不同 - 推荐先构建查询条件（如
whereSQL, args := buildWhereClause(filters)），再复用到SELECT COUNT(*) ... WHERE ...和SELECT ... WHERE ... ORDER BY ... LIMIT ... OFFSET ... - 如果业务允许误差（如百万级用户列表），可用估算总数（如 PostgreSQL 的
reltuples）避免 COUNT 全表扫描
如何设计返回结构体避免字段重复和序列化混乱
常见错误是把 data []interface{} 和分页元信息塞进 map[string]interface{}，导致 JSON 字段顺序不可控、类型丢失、无法加 Swagger 注释。
应定义明确结构体：
type PageResult[T any] struct {
Data []T `json:"data"`
Total int `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
TotalPages int `json:"total_pages"`
}
注意：
-
TotalPages要用(Total + PageSize - 1) / PageSize向上取整，不是Total / PageSize - 如果
Total为 0，TotalPages应为 0，而非 1 - 泛型参数
T必须是导出类型，否则 JSON 序列化为空对象
ORM 场景下怎么避免 Offset 性能陷阱
GORM、sqlc 等工具默认支持 Limit/Offset，但 MySQL 在 OFFSET 很大时（如 100 万行后取 20 条）会扫描前 N 行，响应变慢。PostgreSQL 好些，但仍有代价。
更可靠的方案是「游标分页（cursor-based pagination）」：
- 用排序字段（如
id或created_at）+ 上一页末尾值作为条件，例如WHERE id > ? ORDER BY id LIMIT 20 - 不依赖页码，适合无限滚动场景；但无法跳转任意页，也不适用于需要显示总页数的后台管理页
- 若必须支持跳页，可对高频访问页（如前 100 页）缓存
offset对应的主键范围，减少扫描
通用分页最难的不是写代码，而是决定什么时候该用 offset、什么时候该切游标、以及总数要不要实时算——这些得看你的数据量、QPS、一致性要求，而不是套个模板就完事。
