graphql-ruby 稳定分页(Stable Relation Connections):基于列值的光标分页实战指南
graphql-ruby 稳定分页(Stable Relation Connections):基于列值的光标分页实战指南
导读
在 GraphQL API 中,默认的 ActiveRecord::Relation 分页基于 offset 偏移量 生成光标,这在数据持续变化(新增/删除记录)时会产生漏项与重复项的经典缺陷。graphql-ruby 的 GraphQL::Pro 提供了一套基于列值的稳定连接(Stable Relation Connections),它把排序字段的真实值编码进光标,从而让分页在数据变更时依然稳定连续。本文将先剖析 offset 分页的缺陷与稳定分页的解决思路,再完整讲解 Schema 级/字段级的接入方式、分组关系的正确写法、数据库差异(NULL 排序)处理、向后兼容策略与版本约束,并结合当前仓库源码给出底层实现证据,帮助你平滑迁移到稳定分页。
为什么需要稳定分页:offset 分页的缺陷
默认实现:GraphQL::Pagination::ActiveRecordRelationConnection
graphql-ruby 开箱即用的 ActiveRecord::Relation 连接实现在 lib/graphql/pagination/active_record_relation_connection.rb,它继承自通用的 lib/graphql/pagination/relation_connection.rb。从源码可以确认,这套实现的核心逻辑是把“页码”建模为 offset(偏移量):
- cursor_for 方法 用
nodes.index(item) + 1 + (@paged_nodes_offset || 0) - (relation_offset(items) || 0)计算出当前条目在集合中的偏移序号,再把它编码成光标字符串; - offset_from_cursor 方法 从光标解码出偏移量,若解码结果不是正整数(如
-1、0、abc、1e10),会抛出GraphQL::ExecutionError, "Invalid cursor: ..."。这一点也有测试用例佐证:spec/graphql/pagination/array_connection_spec.rb 和 spec/graphql/pagination/connection_spec.rb 均断言这些畸形光标被拒绝。
这种“按偏移量跳页”的方式,正是原文档指出的缺陷根源。
偏移量翻页的经典缺陷:漏项与重复
假设每页 10 条,你正在看第 2 页(LIMIT 10 OFFSET 10)。此时第 1 页中的某一条记录被删除,那么当你翻到第 3 页(LIMIT 10 OFFSET 20)时,由于整个列表因为前面的删除而“上移”了一位,你会漏掉原本应该出现在第 3 页的一条记录。反过来,如果在分页期间新增了记录,则可能造成同一记录在相邻两页重复出现。
原文档给出的解法是用值(value)而不是偏移量来翻页。例如按 id 排序时,用 id 作为分页键:
LIMIT 10 -- 第 1 页
WHERE id > :last_id LIMIT 10 -- 第 2 页
这样,无论分页过程中有多少记录被新增或删除,翻页都不会被中断——这就是“稳定连接”名称的由来。
稳定连接的实现原理:数据库相关的值型光标
GraphQL::Pro 的稳定连接(GraphQL::Pro::PostgresStableRelationConnection、GraphQL::Pro::MySQLStableRelationConnection、GraphQL::Pro::SqliteStableRelationConnection)与默认实现的本质区别在于:
- 默认实现:光标编码的是条目在结果集中的位置(offset);
- 稳定实现:光标编码的是排序列的列值(value),翻页时把光标值转换成
WHERE条件(如WHERE id > :last_id)。
因此稳定连接是数据库特定的,必须在构造 SQL 时正确处理 NULL 值。原文档明确指出三种数据库对 NULL 的排序约定不同:
| 数据库 | NULL 排序行为 |
|---|---|
| PostgreSQL | NULL 被视为 大于 其他值(NULLS LAST 方向) |
| MySQL | NULL 被视为 小于 其他值 |
| SQLite | NULL 被视为 小于 其他值 |
也就是说,同样的 ORDER BY,在 Postgres 与 MySQL/SQLite 上产生的结果顺序不同,稳定连接必须针对各自的语义生成正确的 WHERE 条件与 IS NULL 分支。这一设计也在仓库的 CHANGELOG 中有迹可循:CHANGELOG-pro.md 记录了“支持 NULLS LAST in stable cursors”、“stable connections: fix condition grouping with IS NULL”、“对已知 null: false 的列不输出 OR ... IS NULL(以改善索引利用率)”等一系列迭代,说明 NULL 处理正是稳定连接的核心难点之一。
使用稳定连接需要注意的三点实现细节
原文档给出三条值得铭记的注意事项,这里结合源码逐一展开:
- 只能使用该模型自身的列进行分页。因为列名会被拼进
WHERE条件(如WHERE id > :last_id),所以对于一个给定的ActiveRecord::Relation,只有该模型自己的列才能用于分页,不能引用其他表(如 join 进来的表)的列。 - 连接可能追加
primary_key排序以保证光标值唯一。这一行为借鉴了 Rails 的Relation#reverse_order——它同样假设primary_key是默认排序键。当业务排序不唯一时,追加主键排序可以确保每个光标对应唯一的行,避免“多条记录拥有相同光标”的歧义。 - 连接会向关系(relation)的
SELECT子句追加字段,以便从数据库查询结果中可靠地构造光标。也就是说,稳定连接并非只做WHERE过滤,它还会确保查询结果携带构造光标所需的列值。
稳定连接也会追加主键排序?——“跳页准确性”的代价
需要澄清一点:稳定连接通过值型光标解决了“数据变更导致漏项”的问题,但如果你在分页过程中同时依赖 hasNextPage 判断“还有更多数据”,仍需注意:当 first 与 max_page_size 同时出现且使用了 before 光标时,曾出现过 hasNextPage 判断不准确的 bug(见 CHANGELOG-pro.md 中的修复记录:“StableRelationConnection: properly return hasNextPage: true when before and max_page_size are used”)。这说明稳定连接同样需要精心处理 pageInfo 的边界语义,使用时应关注相关版本更新。
接入方式一:Schema 级全局安装
如果你想为所有 ActiveRecord::Relation 启用稳定连接,可以在 Schema 类中通过 connections.add 注册与你的数据库匹配的实现:
class MyAppSchema < GraphQL::Schema
# 根据你的数据库,挂载对应的稳定连接实现
connections.add(ActiveRecord::Relation, GraphQL::Pro::PostgresStableRelationConnection)
# 或者...
# connections.add(ActiveRecord::Relation, GraphQL::Pro::MySQLStableRelationConnection)
# connections.add(ActiveRecord::Relation, GraphQL::Pro::SqliteStableRelationConnection)
end
这个 API 对应仓库中的 lib/graphql/pagination/connections.rb:
- add 方法 把“节点类 → 连接实现类”的映射存入
@wrappers; - 运行时 wrap 方法 会通过
wrapper_for(connections.rb)在items.class.ancestors中向上查找注册的实现,若找不到则抛出ImplementationMissingError; - 默认注册(add_default 方法)中,
ActiveRecord::Relation默认绑定的是GraphQL::Pagination::ActiveRecordRelationConnection——所以上面的connections.add实际上是覆盖默认绑定,让全 Schema 的 ActiveRecord 关系都改用稳定连接。
由于连接类会从 field、context 等处获得 max_page_size、default_page_size、first/after/last/before 等参数(见 connections.rb 与 lib/graphql/pagination/connection.rb),因此 Schema 级安装后,所有连接字段仍能正常响应这些分页参数与页面大小限制(default_max_page_size、default_page_size 的使用方式见 guides/pagination/using_connections.md)。
接入方式二:字段级按需包装
如果你只想逐步采用稳定光标(比如先在一个查询字段上试点),可以不走 Schema 级安装,而是在字段的 resolver 里手动包装连接:
field :items, Types::ItemType.connection_type, null: false
def items
# 先构建 ActiveRecord::Relation
relation = Item.all
# 再用连接实现把它包装起来并返回
GraphQL::Pro::MySQLStableRelationConnection.new(relation)
end
字段级包装的好处是“bit-by-bit”渐进式迁移:一次只让一个字段切换到稳定光标,风险可控。原文档也提示了两种方向的精细控制:
- 如果你全局启用了稳定连接,但对某些排序过于复杂、无法生成光标的 relation 想继续使用基于索引(offset)的光标,可以针对这些特定关系显式包装成默认实现:
def items
# 这个 relation 的排序对光标生成来说太复杂了,
# 所以为它单独回退到基于 offset 的默认实现:
GraphQL::Pagination::ActiveRecordRelationConnection.new(relation)
end
这套“schema 级注册 + resolver 级手动包装”的组合方式,在 guides/pagination/using_connections.md 的 “Special Cases” 一节也有同源说明:某些集合需要特殊处理时,可以在 resolver 中手动应用连接包装器。
分组(Grouped)关系的正确姿势
使用分组后的 ActiveRecord::Relation 时,必须保证结果中每一行都有一个唯一的光标。原文档给出了典型对比:
# 不好:如果两条结果的 max(price) 相同,
# 它们从分页角度看是完全相同的:
Products.select("max(price) as price").group("category_id").order("price")
# 好:category_id 被用来区分任何价格相同的结果:
Products.select("max(price) as price").group("category_id").order("price, category_id")
也就是说,分组关系必须把能唯一标识分组的列(如 category_id)一并放进 ORDER BY。对于未分组的 relation,这个唯一性问题由连接自动处理——它会把模型的 primary_key 追加到排序值中(见上文“实现细节”第 2 点)。
此外还有一条硬性约束:如果你传入一个无序的分组关系,GraphQL::Pro::RelationConnection::InvalidRelationError 会被抛出,因为一个没有排序的关系无法以稳定的方式进行分页。这一点在 CHANGELOG-pro.md 中也有记录:“Raise GraphQL::Pro::RelationConnection::InvalidRelationError when a grouped, unordered relation is returned from a field. (This relation can't be stably paginated.)”——换句话说,稳定分页的前提是排序确定,无序集合在稳定分页下是明确的错误而非可降级场景。
向后兼容:offset 光标与值型光标的混用
GraphQL::Pro 的稳定连接是向后兼容的。原文档给出的行为是:
如果它收到一个基于 offset 的光标,它会用该光标完成本次查询,然后在下一批结果中返回基于值的光标。
这意味着迁移过程对客户端友好:客户端不必一次性全部改用新光标。老的 offset 光标仍可被解析使用,而新的响应会逐步“升级”为值型光标。这种渐进策略也呼应了 CHANGELOG-pro.md 中 “New stable connection support based on GraphQL-Ruby 1.10's new pagination implementation ... they can be applied on a field-by-field basis” 的描述——新稳定连接从设计之初就支持字段级、渐进式采用。
版本与兼容性约束
原文档明确:稳定连接支持 ActiveRecord >= 4.1.0。在使用前请确认你的项目满足该版本要求。
同时需要注意,稳定连接属于 GraphQL::Pro(付费/企业版) 功能,本文及原文档中的 GraphQL::Pro::* 类需要相应的 Pro 安装环境;当前开源仓库仅包含默认连接实现(lib/graphql/pagination/ 下的 ArrayConnection、ActiveRecordRelationConnection、MongoidRelationConnection、SequelDatasetConnection、RelationConnection 等),Pro 稳定连接类本身不在开源仓库内,这一点从 CHANGELOG-pro.md 与 guides/pagination/stable_relation_connections.md 的 pro: true 元数据可以确认。
小结与迁移建议
| 维度 | 默认连接(offset 光标) | Pro 稳定连接(值型光标) |
|---|---|---|
| 光标内容 | 条目在结果集中的偏移序号 | 排序列的列值 |
| 数据变更影响 | 可能漏项/重复 | 不受新增或删除干扰 |
| 数据库适配 | 通用 | Postgres / MySQL / SQLite 各自实现,正确处理 NULL 排序 |
| 分组关系 | 通用 offset 逻辑 | 必须保证每行排序唯一,否则抛 InvalidRelationError |
| 接入方式 | 默认内置 | Schema 级 connections.add 或字段级手动包装 |
| 迁移成本 | — | 向后兼容,可渐进切换 |
实践建议:如果你正在使用 ActiveRecord 分页且数据量大、写入频繁,可以按以下顺序平滑迁移——
- 先在单个字段上用
GraphQL::Pro::*StableRelationConnection.new(relation)试点,观察 SQL 与pageInfo是否符合预期; - 确认无误后,在 Schema 级用
connections.add(ActiveRecord::Relation, ...)全局启用; - 对排序过于复杂的 relation,按需回退到
GraphQL::Pagination::ActiveRecordRelationConnection; - 使用分组关系时,始终把分组键追加到
ORDER BY,避免触发InvalidRelationError。
通过这套组合拳,你可以在不破坏现有客户端的前提下,把 ActiveRecord 分页升级为“数据再变,分页不乱”的稳定模式。