GraphQL-Ruby 自定义连接(Custom Connections)实战指南:为自有数据对象构建游标分页
GraphQL-Ruby 自定义连接(Custom Connections)实战指南:为自有数据对象构建游标分页
自定义连接(Custom Connection)是 GraphQL-Ruby 中把任意 Ruby 集合对象接入 Relay 风格游标分页(cursor-based pagination)的官方方案。内置连接只覆盖 Array、ActiveRecord::Relation、Sequel::Dataset 和 Mongoid 查询对象;当你希望对外部搜索引擎结果、文件服务器列表等自有数据源做分页时,就需要按本文的“应用对象 → 连接包装器 → 连接类型”三段式实现一个自定义连接。读完本文,你将掌握连接包装器的四个必需方法如何实现、两种接入 Schema 的方式(schema 级自动映射与 resolver 级手动包装),以及如何定制连接/边(Edge)的 GraphQL 类型。配套的 Using Connections 基础指南见 guides/pagination/using_connections.md。
一、三个组成部分:先理解连接的结构
GraphQL-Ruby 官方文档将自定义连接的实现拆成三个各司其职的部分:
- 应用对象(Application Object):你要在 GraphQL 中分页的条目列表本身,例如一个
Array、一个ActiveRecord::Relation,或应用自定义的集合类; - 连接包装器(Connection Wrapper):在应用对象与 GraphQL 连接类型之间充当适配器,把分页参数翻译成对底层列表的切片操作;
- 连接类型(Connection Type):一个符合 Relay connection 规范 的 GraphQL 对象类型,对外暴露
edges、nodes、pageInfo等字段。
以官方文档的示例场景来说:假设你的应用通过外部搜索引擎获取结果,所有搜索结果都用 SearchEngine::Result 类表达(这是一个虚构的、用来演示“应用自有的条目集合”的例子)。我们要做的,就是让返回 SearchEngine::Result 列表的字段也能享受到和内置连接一致的游标分页能力。
二、应用对象:列表也是对象
Ruby 中“万物皆对象”,列表也不例外。Array 是一个对象,同时也是一个对象的列表;ActiveRecord::Relation 更复杂一些——它收集了 SQL 查询的各个片段,在合适的时机才向数据库派发调用取回对象,但它同样是一个列表对象。
你的应用里很可能还有其它想通过 GraphQL 连接来分页的列表对象:一组搜索结果、文件服务器上的一组文件……这些列表都以“列表对象”的形式建模,而它们都可以被连接包装器包裹。这正是 GraphQL::Pagination::Connection 基类把构造参数命名为 items 的原因——在 lib/graphql/pagination/connection.rb 中:
# @return [Object] A list object, from the application. This is the unpaginated value passed into the connection.
attr_reader :items
也就是说,无论底层列表长什么样,只要它作为一个对象传入连接包装器即可。
三、连接包装器:必须实现的四个方法
连接包装器是纯 Ruby 列表对象(Array、Relation 或应用自定义类)与 GraphQL 连接类型之间的适配层:GraphQL 连接类型要求的方法,由包装器基于底层列表对象来实现。
3.1 继承基类开始
继承 GraphQL::Pagination::Connection 即可起步:
# app/graphql/connections/search_results_connection.rb
class Connections::SearchResultsConnection < GraphQL::Pagination::Connection
# implementation here ...
end
如果这四个必需方法没有实现,基类会直接抛出 PaginationImplementationMissingError(见 lib/graphql/pagination/connection.rb),用报错文本提示你补全哪个方法:
#nodes:根据给定的分页参数,返回@items中分页后的切片;#has_next_page:当#nodes之后还有条目时返回true;#has_previous_page:当#nodes之前还有条目时返回true;#cursor_for(item):为item返回一个作为游标的字符串。
3.2 基类已经替你处理好的部分
Connection 基类不只是抛错,它还承担了大量通用逻辑,让你的子类只需聚焦“如何高效切片”这一件事:
- 分页参数规范化:
before、after会把客户端传来的空字符串""视为nil(connection.rb);first与last则通过limit_pagination_argument做钳制——负值被归零、超过max_page_size的被压回上限,且在first/last都未提供时会用default_page_size或max_page_size兜底(connection.rb)。max_page_size与default_page_size的取值优先级是“连接自身覆写 > Schema 配置”,对应has_max_page_size_override?、has_default_page_size_override?两个开关,Schema 侧配置来自default_max_page_size/default_page_size(见 lib/graphql/schema.rb)。 - 游标编解码:
encode/decode通过context.schema.cursor_encoder完成,且使用nonce: true增加不可猜测性(connection.rb)。你的cursor_for只需要生成“纯文本游标内容”,基类负责加密封装。 edges与start_cursor/end_cursor:edges会把nodes逐一包成Edge实例;start_cursor/end_cursor则基于nodes.first/nodes.last调用你的cursor_for得出(connection.rb)。Edge类:基类内置了Connection::Edge,它的cursor方法同样委托给@connection.cursor_for(@node)(connection.rb)。你可以在子类中覆写edge_class来提供携带更多关联数据的边对象。
3.3 参考内置实现:四种典型策略
“如何高效实现这四个方法”完全取决于你的后端与通信方式。官方内置了四种连接,是绝佳的灵感来源:
| 连接类 | 适用数据源 | 实现文件 |
|---|---|---|
GraphQL::Pagination::ArrayConnection |
Ruby Array |
lib/graphql/pagination/array_connection.rb |
GraphQL::Pagination::ActiveRecordRelationConnection |
ActiveRecord::Relation |
lib/graphql/pagination/active_record_relation_connection.rb |
GraphQL::Pagination::SequelDatasetConnection |
Sequel::Dataset |
lib/graphql/pagination/sequel_dataset_connection.rb |
GraphQL::Pagination::MongoidRelationConnection |
Mongoid 查询对象 | lib/graphql/pagination/mongoid_relation_connection.rb |
以 ArrayConnection 为例,它的游标策略是“元素下标 + 1 再编码”:cursor_for(item) 取 items.find_index(item) + 1 编码为游标(array_connection.rb);load_nodes 则一次性完成 before/after 切片、计算 has_previous_page / has_next_page、再按 first/last 截取(array_connection.rb),并通过 @nodes ||= 保证后续调用不再重复计算。
而后三者共享基类 GraphQL::Pagination::RelationConnection(lib/graphql/pagination/relation_connection.rb),它把“切片”翻译成数据库查询对象的 offset / limit 操作:sliced_nodes 负责把 before / after 游标换算成偏移与上限,build_limited_nodes 再叠加 first / last(relation_connection.rb)。不同 ORM 的子类只需实现四个私有抽象方法:relation_offset、relation_limit、relation_count、null_relation(比如 ActiveRecord 用 relation.unscope(:order).count(:all) 计数、用 relation.none 表达空集,见 active_record_relation_connection.rb)。这条抽象路径正是你为数据库类自定义连接时最值得复用的模板:继承 RelationConnection,把 relation_* 四个方法适配到你的 ORM 即可。
四、使用自定义连接:两种接入方式
包装器写好之后,如何让它被 GraphQL 运行时用上?官方提供两种方式:
- Schema 级映射:把包装器与某个列表类绑定,凡是返回该类实例的字段都会被自动包装;
- Resolver 级手动包装:在 resolve 方法里直接
new包装器返回,用于覆盖自动映射、处理特殊情况。
4.1 方式一:Schema 级自动映射
在 Schema 中把包装器“挂”到目标类上:
class MySchema < GraphQL::Schema
# Hook up a custom wrapper
connections.add(SearchEngine::Result, Connections::SearchResultsConnection)
end
此后,任何字段只要返回 SearchEngine::Result 的实例,就会自动被 Connections::SearchResultsConnection 包裹。
connections 是 GraphQL::Schema 暴露出来的 GraphQL::Pagination::Connections 管理器实例(见 lib/graphql/schema.rb,其核心逻辑在 lib/graphql/pagination/connections.rb)。它的工作机制值得注意:
- 默认注册表:构造时即注册
Array→ArrayConnection、ActiveRecord::Relation→ActiveRecordRelationConnection、Sequel::Dataset→SequelDatasetConnection以及多种 Mongoid 目标类(connections.rb); - 按祖先链匹配:
wrapper_for遍历items.class.ancestors,遇到第一个注册过包装器的类就采用(connections.rb)——所以你的自定义列表类即使“继承自某个已注册基类”,也能命中正确包装器;反过来,你也可以用connections.delete(Array)移除内置的 Array 支持(此时数组仍可被手动包装); - 继承与覆写:
all_wrappers会沿schema.ancestors向上合并各 Schema 的注册表,子 Schema 的add能覆写父级映射(connections.rb)。这一点在 spec/graphql/pagination/connections_spec.rb 中有专门用例验证:Set、Hash用各自包装器,而Array被子 Schema 覆写为OtherArrayConnection; - 找不到包装器时报错:
wrap在无法为列表类找到任何包装器时会抛出ImplementationMissingError并指明字段路径与对象 inspect 信息(connections.rb),便于排查。 RawValue豁免:GraphQL::Execution::Interpreter::RawValue会原样透传、不做包装(connections.rb)。
此外,运行时包装发生在字段解析的 after_resolve 阶段:ConnectionExtension 会自动为连接字段加上 after / before / first / last 四个参数(并在 resolve 前把它们从参数中剥离,避免污染你的方法签名),解析完成后调用 populate_connection 完成包装或补全(见 lib/graphql/schema/field/connection_extension.rb)。
4.2 方式二:Resolver 级手动包装
对于“某些字段想特殊处理”的场景,直接在 resolve 方法(或 GraphQL::Schema::Resolver)中返回包装器实例:
field :search, Types::SearchResult.connection_type, null: false do
argument :query, String
end
def search(query:)
search = SearchEngine::Search.new(query: query, viewer: context[:current_user])
results = search.results
# Apply the connection wrapper and return it
Connections::SearchResultsConnection.new(results)
end
GraphQL-Ruby 会直接采用你提供的连接包装器,从而绕过 Schema 级映射。这种细粒度方式适合处理特殊用例或实施针对性的性能优化(例如跳过包装、直接传入预切好的切片)。
值得一提的是,populate_connection 对“已经是连接包装器实例”的返回值会做补全而非替换:它会补上可能缺失的 context、parent、first_value、after_value、last_value、before_value、arguments、field,并仅在字段配置了且连接未自行覆写时设置 max_page_size / default_page_size(见 connections.rb)。所以你在 resolver 里手动 new 包装器时,不必把参数凑齐。
五、连接类型:让包装器暴露为 GraphQL 类型
连接类型是符合 Relay 规范的 GraphQL 对象类型。GraphQL-Ruby 提供了一套开箱即用的工具:
GraphQL::Types::Relay::BaseConnection与GraphQL::Types::Relay::BaseEdge是规范的示例实现(分别见 lib/graphql/types/relay/base_connection.rb 与 lib/graphql/types/relay/base_edge.rb)。它们继承自GraphQL::Schema::Object,不继承你应用的 BaseObject,因此未必能直接拿来用——更常见的做法是把它作为灵感,复制其行为到你自己的基类层次中。.connection_type动态生成:任何类型类都响应.connection_type,会基于该类生成一个连接类型。默认继承GraphQL::Types::Relay::BaseConnection,但你可以通过connection_type_class(Types::MyBaseConnectionObject)覆写默认基类。
connection_type 与 edge_type 的生成逻辑位于 lib/graphql/schema/member/relay_shortcuts.rb:connection_type 以 self.graphql_name + "Connection" 命名,并用 Class.new(connection_type_class) 创建子类;edge_type 则生成 graphql_name + "Edge" 类型并调用 node_type 绑定节点类型。connection_type_class 在查找时只沿祖先链取“第一个显式配置过的值”,否则回退到 Types::Relay::BaseConnection(relay_shortcuts.rb)。
5.1 定制基类并挂到你的类型层次
你可以先实现一个应用自己的连接基类:
class Types::BaseConnectionObject < Types::BaseObject
# implement based on `GraphQL::Types::Relay::BaseConnection`, etc
end
然后把它挂到所有基础类型上:
class Types::BaseObject < GraphQL::Schema::Object
# ...
connection_type_class(Types::BaseConnectionObject)
end
class Types::BaseUnion < GraphQL::Schema::Union
connection_type_class(Types::BaseConnectionObject)
end
module Types::BaseInterface
include GraphQL::Schema::Interface
connection_type_class(Types::BaseConnectionObject)
end
之后定义字段时,.connection_type 就会使用你的连接类层次:
field :posts, Types::Post.connection_type, null: false
(这些字段默认会带上 connection: true——因为生成的连接类型名以 *Connection 结尾,运行时据此自动识别并附加 ConnectionExtension。)
5.2 理解 ConnectionBehaviors 的默认行为
若你选择继承/参考 GraphQL::Types::Relay::BaseConnection,其行为由 lib/graphql/types/relay/connection_behaviors.rb 定义,默认会做这些事:
- 自动添加
pageInfo字段(类型为GraphQL::Types::Relay::PageInfo,非空); - 默认开启
nodes字段(has_nodes_field(true))、node_nullable(true)、edges_nullable(true)、edge_nullable(true)——分别对应nodes字段的有无、node/nodes可空、edges字段可空、edge可空,均可在你的基类中用node_nullable(false)等重设; edge_type(...)会同时生成edges与nodes字段、设置描述,并允许通过field_options传入额外字段配置(connection_behaviors.rb);nodes/edges的解析直接委托给包装器对象的@object.nodes/@object.edges(connection_behaviors.rb),并在解析前把was_authorized_by_scope_items?同步给运行时状态,避免节点被二次鉴权。
同理,GraphQL::Types::Relay::BaseEdge 的行为在 lib/graphql/types/relay/edge_behaviors.rb 中:默认包含非空的 cursor 字段(解析时调用包装器的 cursor_for),node 字段由你在边子类里通过 node_type(Types::Post) 绑定,且默认 node_nullable(true)。
六、实战落地要点小结
- 能复用的就别重写:处理数据库查询对象时优先继承
RelationConnection,只适配relation_offset/relation_limit/relation_count/null_relation四个方法;处理纯内存集合时可参考ArrayConnection的下标游标方案。 - 别忘记页信息:
has_next_page/has_previous_page必须基于切片后剩余的条目判断(例如“切片条数 > first”),而不是简单返回false,否则pageInfo会失真。 - 游标只需返回“明文内容”:加密封装由基类
encode完成;同时游标必须能被你的nodes逆向解码成切片位置,并在解码失败时抛出可读的GraphQL::ExecutionError(内置连接对非法游标均会报"Invalid cursor: ...")。 - 两种接入方式按需选择:想让某类列表全局获得分页能力,用
connections.add;只想让个别字段走特殊包装(或做性能优化),就在 resolver 里直接Connections::YourConnection.new(results)。 - 类型层优先定制基类:在你的应用
BaseObject/BaseUnion/BaseInterface上统一调用connection_type_class,让所有.connection_type生成物都落到你自己的连接类层次上。
掌握了这三段式结构(应用对象 + 连接包装器 + 连接类型)与两种接入方式,你就能让任何自有数据集合获得与内置连接一致的、符合 Relay 规范的游标分页能力。