如何在 Go 中编写通用的分页逻辑代码

从现在开始，我们要努力学习啦！今天我给大家带来《如何在 Go 中编写通用的分页逻辑代码》，感兴趣的朋友请继续看下去吧！下文中的内容我们主要会涉及到等等知识点，如果在阅读本文过程中有遇到不清楚的地方，欢迎留言呀！我们一起讨论，一起学习！

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、一致性要求，而不是套个模板就完事。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~