分页参数解析应使用c.DefaultQuery设默认值并显式转换,校验边界避免负offset;SQL分页优先游标分页,页码分页需限总数;响应结构需含page/size/total等字段;GORM插件仅简化语法,复杂场景需手写优化。

分页参数怎么解析才不会出错
Gin 本身不提供自动分页解析,c.Query 是最直接也最容易翻车的方式。常见错误是没做类型校验或默认值兜底,比如用户传 page=abc 或直接不传,strconv.Atoi 会 panic,或者返回 0 导致 SQL offset 为负数。
推荐用 c.DefaultQuery + 显式转换,并设合理边界:
page := c.DefaultQuery("page", "1")
size := c.DefaultQuery("size", "10")
<p>pageNum, <em> := strconv.Atoi(page)
pageSize, </em> := strconv.Atoi(size)</p><p>// 强制最小页码为 1,最大单页限制 100
if pageNum < 1 {
pageNum = 1
}
if pageSize < 1 || pageSize > 100 {
pageSize = 10
}</p><p>offset := (pageNum - 1) * pageSize
- 别依赖
c.GetQuery返回的 bool 判断是否存在——它只表示 URL 里有没有该 key,不表示值合法 - 避免用
int(c.MustGet("page").(int))这类中间件透传方式,除非你全程控制参数注入链路 - 前端传
page=0很常见,但数据库 offset 从 0 开始,语义上第 0 页不合理,应统一转成第 1 页
SQL 分页怎么写才安全又高效
MySQL 用 LIMIT offset, size 简单,但 offset 超大时(比如第 10000 页)性能急剧下降。PostgreSQL 同理。关键不是“能不能分页”,而是“要不要允许跳到任意页”。
生产环境建议两种策略并存:
- 对普通列表接口,用游标分页(cursor-based)替代页码分页:要求前端传上一页最后一条记录的
id或时间戳,SQL 改为WHERE id > ? ORDER BY id LIMIT ?,避免 offset 扫描 - 若必须支持页码跳转,务必加总条数限制(如最多查 50 万条),并在 COUNT 查询前加 where 条件索引覆盖检查
- 别在 COUNT 和 LIST 查询之间做业务逻辑变更,否则总数和结果可能不一致;如需强一致,用事务或缓存总数 + 版本号
示例中先查总数再查数据,适合中小数据量场景:
var total int64
db.Model(&User{}).Where("status = ?", 1).Count(&total)
<p>var users []User
db.Model(&User{}).Where("status = ?", 1).Offset(offset).Limit(pageSize).Find(&users)
响应结构怎么组织才方便前端用
不要只返回 data: [...] ,前端分页控件需要知道当前页、总页数、是否还有下一页。Gin 没有内置分页响应模板,得自己封装。
一个轻量但够用的结构:
type PageResult struct {
Data interface{} `json:"data"`
Page int `json:"page"`
Size int `json:"size"`
Total int64 `json:"total"`
TotalPages int `json:"total_pages"`
HasMore bool `json:"has_more"`
}
-
TotalPages计算用(int(total + int64(pageSize) - 1) / int64(pageSize)),避免浮点误差 -
HasMore直接用len(users) == pageSize判断,比Page 更可靠(避免总数不准导致误导) - 别把分页元信息塞进 HTTP Header——前端要取还得额外 parse,不如放 body 里直给
GORM 分页插件要不要用
像 github.com/unknwon/com 或 github.com/gookit/goutil 提供的分页辅助函数,看似省事,但多数只是封装了 offset/limit 计算,没解决 COUNT 性能、游标分页、缓存等核心问题。
更值得关注的是 GORM v2 的 Scopes 和自定义方法:
func Paginate(page, size int) func(db *gorm.DB) *gorm.DB {
return func(db *gorm.DB) *gorm.DB {
offset := (page - 1) * size
return db.Offset(offset).Limit(size)
}
}
<p>// 使用
db.Scopes(Paginate(pageNum, pageSize)).Find(&users)
- 这类封装只解决语法糖问题,COUNT 仍需单独写,别误以为调了
Paginate就自动带总数 - 如果项目已重度使用 GORM,可基于
gorm.Callbacks注入 COUNT 逻辑,但要注意事务上下文和预加载冲突 - 真正复杂的分页(如多表 JOIN 后分页),GORM 的 COUNT 可能生成错误 SQL,此时宁可手写原生 COUNT 子查询
分页真正的复杂点不在 Gin 或 GORM 怎么写,而在于你是否清楚这个接口的 QPS、数据增长速度、以及用户真实会不会翻到第 500 页——这些决定了该用 offset 还是 cursor,该不该加缓存,甚至该不该禁掉页码输入框。


















