Kotaemon分页查询接口设计规范-平芜编程栈

Kotaemon分页查询接口设计规范

在构建企业级服务平台的过程中，我们常常面临一个看似简单却极易引发连锁问题的设计环节——如何正确地实现分页查询。表面上看，它只是“一页显示10条数据”，但深入到高并发、大数据量和复杂交互的场景中时，错误的分页策略可能导致数据库负载飙升、前端渲染卡顿、甚至出现数据幻读等严重问题。

Kotaemon作为支撑多业务线的核心平台，在长期实践中逐步沉淀出一套兼顾性能、一致性与开发效率的分页接口规范。这套规范不仅解决了“怎么分页”的技术选型问题，更统一了团队协作的语言，让前后端对“第几页”“有没有下一页”达成一致理解。

分页的本质，是对无限数据的一种可控切片方式。而选择哪种切片机制，则直接决定了系统的可扩展性。

目前主流方案有两种：基于偏移（Offset-Based）和基于游标（Cursor-Based）。它们各有适用场景，不能一概而论。

Offset 分页使用page和size参数定位数据位置，例如：

GET /api/v1/users?page=2&size=10

后端执行类似 SQL：

SELECT * FROM users ORDER BY created_at DESC LIMIT 10 OFFSET 10;

这种写法直观易懂，适合后台管理系统或报表类需求，用户常需要跳转到第5页、第10页。但在数据量大时，OFFSET 10000意味着数据库必须先扫描并跳过前一万条记录，性能随页码增长显著下降。更麻烦的是，如果在这期间有新数据插入，原本的第2页内容可能重复出现或遗漏——这就是所谓的“幻读”问题。

相比之下，游标分页通过上一页最后一个元素的某个有序字段值（如时间戳、ID）来获取下一页：

GET /api/v1/messages?cursor=1718923400&direction=next&size=10

对应的查询逻辑为：

-- 下一页 SELECT * FROM messages WHERE created_at < 1718923400 ORDER BY created_at DESC LIMIT 10;

这种方式始终利用索引进行范围扫描，性能稳定且不受数据总量影响。更重要的是，它天然避免了因中间写入导致的数据错位，非常适合消息流、动态Feed、日志列表这类高频更新的场景。

当然，代价也很明显：你无法直接跳转到“第100页”，只能逐页翻阅。此外，游标依赖排序字段的唯一性和稳定性，若多个记录拥有相同的created_at，还需引入辅助字段（如主键）确保顺序一致。

特性	Offset-Based	Cursor-Based
实现难度	简单	中等
支持跳页	✅ 是	❌ 否
性能稳定性	⚠️ 随偏移增大而下降	✅ 恒定
数据一致性	❌ 易受写入影响	✅ 强一致性
适用场景	后台管理、静态列表	动态流式数据

在Kotaemon的设计建议中，我们采取“默认偏移 + 关键场景切换游标”的策略。对于大多数内部管理界面，Offset 已足够；而对于实时性要求高的外部服务接口，则优先启用游标模式，并在文档中标注其不可跳页的特性。

参数设计是接口可用性的第一道门槛。一个清晰、安全、可验证的输入结构，能让开发者快速上手而不必反复查阅文档。

我们定义的标准分页参数如下：

参数名	类型	必选	示例值	说明
`page`	integer	否	`1`	当前页码，从1开始计数
`size`	integer	否	`10`	每页数量，最大不超过`100`
`sort`	string	否	`created_at:desc,name:asc`	排序规则，格式为`field:order`多个用逗号分隔
`cursor`	string	否	`1718923400`	游标值，用于游标分页
`direction`	enum(string)	否	`next`,`prev`	分页方向，仅用于游标模式

这些参数都应通过严格的校验流程。比如：

page至少为1，小于1自动归正；
size默认10，超过100则拒绝请求；
direction只允许"next"或"prev"；
sort字段必须经过白名单过滤，防止恶意传入非公开字段造成信息泄露或SQL注入风险。

以下是Go语言中的典型实现：

type PaginationParams struct { Page int `json:"page"` Size int `json:"size"` Sort []SortCondition `json:"sort,omitempty"` Cursor string `json:"cursor,omitempty"` Direction string `json:"direction,omitempty"` // "next" or "prev" } type SortCondition struct { Field string Order string // "asc" or "desc" } func (p *PaginationParams) Validate() error { if p.Page < 1 { p.Page = 1 } if p.Size < 1 { p.Size = 10 } else if p.Size > 100 { return fmt.Errorf("size cannot exceed 100") } if p.Direction != "" && p.Direction != "next" && p.Direction != "prev" { return fmt.Errorf("invalid direction: must be 'next' or 'prev'") } return nil }

这个结构体可以在 Gin、Echo 等主流框架中直接用于绑定查询参数，配合中间件实现统一校验。值得注意的是，虽然我们将page和size设为可选，但实际处理时仍需设置合理的缺省值，以降低客户端调用负担。

如果说请求参数是“命令”，那么响应体就是“结果报告”。一个好的分页响应不仅要返回数据，还要告诉调用方：“你现在在哪？还能不能往前走？总共有多少条？”

我们采用如下标准JSON格式：

{ "code": 0, "message": "success", "data": { "content": [ { "id": 1, "name": "Alice", "createdAt": "2024-06-01T10:00:00Z" }, { "id": 2, "name": "Bob", "createdAt": "2024-06-01T09:30:00Z" } ], "pagination": { "page": 1, "size": 10, "total": 156, "pages": 16, "hasNext": true, "hasPrev": true, "first": false, "last": false, "cursor": "1718923400" } } }

其中关键字段包括：

content: 当前页数据列表；
total: 总记录数，可用于展示“共156条”；
pages: 总页数，由(total + size - 1) / size计算得出；
hasNext/hasPrev: 是否存在下一页/上一页，前端据此控制按钮禁用状态；
first/last: 是否首尾页，便于UI做特殊样式处理；
cursor: 当前页最后一个元素的游标值，供下次请求使用。

这样的设计极大减轻了前端的计算压力。过去常见的情况是前端自己根据total和size去算pages，稍有不慎就会因整除逻辑出错而导致分页器异常。现在所有元信息均由后端统一生成，保证准确无误。

对应的Go实现如下：

type PageResult struct { Content interface{} `json:"content"` Pagination Meta `json:"pagination"` } type Meta struct { Page int `json:"page"` Size int `json:"size"` Total int64 `json:"total"` Pages int `json:"pages"` HasNext bool `json:"hasNext"` HasPrev bool `json:"hasPrev"` First bool `json:"first"` Last bool `json:"last"` Cursor string `json:"cursor,omitempty"` } func NewPageResult(data interface{}, total int64, page, size int, cursor string) *PageResult { pages := int((total + int64(size) - 1) / int64(size)) hasNext := page*size < int(total) hasPrev := page > 1 return &PageResult{ Content: data, Pagination: Meta{ Page: page, Size: size, Total: total, Pages: pages, HasNext: hasNext, HasPrev: hasPrev, First: !hasPrev, Last: !hasNext, Cursor: cursor, }, } }

该构造函数封装了所有计算逻辑，控制器只需一行代码即可返回完整响应，减少了重复编码。

在整个系统架构中，分页功能贯穿于多个层次：

[前端 UI] ↓ (HTTP 请求携带 page/size/sort) [API Gateway / Controller] ↓ (参数解析与校验) [Service Layer] ↓ (构建查询条件) [Repository / ORM] ↓ (执行数据库查询) [Database]

通常情况下，Controller 负责接收并绑定参数，Service 层负责组合业务逻辑和分页条件，Repository 返回原始数据与总数。这种职责划分清晰，也便于单元测试和Mock。

以用户列表为例，典型工作流程如下：

前端发起请求：
http GET /api/v1/users?page=2&size=10&sort=created_at:desc
控制器接收并校验：
go var params PaginationParams if err := c.ShouldBindQuery(&params); err != nil { return ErrorResponse(c, 400, "invalid params") } if err := params.Validate(); err != nil { return ErrorResponse(c, 400, err.Error()) }
Service 层调用数据访问层：
go users, total, err := userService.ListUsers(ctx, params) if err != nil { return err }
构造并返回响应：
go result := NewPageResult(users, total, params.Page, params.Size, "") return Success(c, result)

整个过程简洁明了，各层职责分明。特别值得一提的是，ListUsers方法内部会根据是否存在cursor自动判断使用哪种分页模式，对外保持接口一致性。

这套规范之所以能在Kotaemon多个模块落地成功，是因为它切实解决了许多现实痛点：

实际问题	规范解决方案
列表加载慢	限制`size`不得超过100，防止单次拉取过多数据
页面跳转错乱	提供`hasNext/hasPrev`字段，前端可精准控制分页按钮状态
数据重复或丢失	在关键链路启用游标分页，消除幻读风险
排序混乱	强制`sort`字段白名单校验，防止无效或危险排序
文档不一致	统一响应结构，Swagger 自动生成准确文档