Iris框架需手动实现分页,最常用方式是通过URL参数解析page和size,校验并限制范围后计算offset=(page-1)*size,再调用db.Offset(offset).Limit(size)执行SQL分页,同时用COUNT查询总数并设X-Total-Count响应头。

Iris 框架本身不内置分页器,必须手动实现或封装 —— 这和 Django REST Framework 或 FastAPI 的 SQLModelPaginator 不同,没有开箱即用的 PageNumberPagination 类。
怎么在 Iris 中做基础分页(offset + limit)
最常用、也最可控的方式是用 SQL 的 LIMIT 和 OFFSET 手动计算。关键不是框架“支持与否”,而是你如何把请求参数转成数据库查询条件。
常见错误现象:page=1&size=10 传进来,但没校验 page 是否 ≤ 0,导致 OFFSET -10 报错;或没限制 size 上限,被恶意请求拖垮数据库。
- 从
ctx.URLParamInt("page")和ctx.URLParamInt("size")提取参数 - 强制设定默认值:
page := max(1, page),size := clamp(size, 1, 100) - 计算
offset := (page - 1) * size,再传给db.Limit(size).Offset(offset) - 查总数用
db.Model(&items).Count(&total)(entgo)或原生SELECT COUNT(*)(gorm)
为什么不能直接用 ORM 的 FindAll + 切片分页
看似简单:db.Find(&all, "status = ?", 1); items = all[offset:offset+size] —— 但这是严重反模式。
性能影响非常直接:10 万条数据时,每次请求都全量查出再内存切片,CPU 和内存压力陡增,GC 频繁,延迟飙升。数据库索引也完全失效。
真正该做的只有两件事:
- 确保
WHERE条件字段有索引(比如status,created_at) - 让分页逻辑下沉到 SQL 层,用
LIMIT/OFFSET或游标(见下一条)
游标分页(cursor-based)在 Iris 里怎么落地
当数据高频写入、排序字段存在重复值(如 created_at),OFFSET 分页会出现漏数据或重复数据。这时必须换游标分页 —— Iris 不拦你,但你要自己拼 WHERE id > ? ORDER BY id LIMIT ?。
使用场景:后台管理列表、消息流、订单列表等强一致性要求的接口。
实操要点:
- 前端传
cursor=12345(通常是上一页最后一条记录的id或复合主键值) - 后端构造查询:
db.Where("id > ?", cursor).Order("id ASC").Limit(size) - 返回结果时,把新一批第一条和最后一条的
id作为next_cursor/prev_cursor透出 - 注意:游标分页无法跳转任意页,只能前后翻,且必须有唯一、有序、非空的排序字段
最容易被忽略的一点:无论用哪种分页,HTTP 响应头里加 X-Total-Count 是基本素养,前端分页控件依赖它算总页数;而 Iris 默认不设这个头,得手动 ctx.Header("X-Total-Count", strconv.Itoa(total))。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!











