Spectrum 的 GraphQL 分页实战：基于 Relay Connections 规范的游标分页指南

• 后端
• 前端
• 即时通讯
• 社交

本文以 Spectrum 开源项目（Simple, powerful online communities）的后端 API 文档 docs/backend/api/pagination.md 为核心骨架，结合api/下的真实 GraphQL schema 与 resolver 源码，系统讲解该项目如何用Relay Connections Specification实现 GraphQL 游标分页：包括messageConnection的标准用法、cursor/pageInfo的语义、first/after参数与默认值规则、以及Connection/Edge的命名约定。读完后你将掌握在 Spectrum（以及同类 graphql-tools 项目中）分页查询的完整写法，并理解底层 resolver 的分页实现原理。

为什么 GraphQL 需要一套自己的分页规范

GraphQL 本身没有内置的分页机制。你可以把查询写成返回整个列表，但这在大数据量场景下既浪费带宽又无法实现"加载更多"这类交互。社区（包括 Spectrum）普遍遵循的准标准是Relay Connections Specification（Relay 连接规范）。该规范的核心思想是：不直接返回一个列表，而是返回一个"连接（Connection）"，连接内通过**不透明的游标（cursor）**定位分页边界，并通过pageInfo暴露是否还有更多数据。

Spectrum 在实现时参考了 Apolo Data 的两篇经典文章（理解分页问题与 GraphQL Connections 结构），并声明"严格按该结构实现，仅在命名上有一处细微改动"（详见下文命名约定小节）。

核心用法速览：以 thread 的消息分页为例

1. 获取第一页

要读取某个 thread 下的消息列表，直接查询messageConnection即可。默认返回第一页（默认条数见下文"默认值"小节）：

{ thread(id: "some-thread-id") { # 获取某个 thread 的消息 messageConnection { pageInfo { # 是否还有下一页可以继续获取 hasNextPage } edges { # 把最后一条消息的 cursor 传给 messageConnection 即可取下一页 cursor # 真正的消息实体 node { id message { content } } } } } }

这条查询会拿到该 thread 的前 10 条（或更少，如果总数不足 10 条）消息。

2. 获取下一页

要翻页，取edges中最后一条消息的cursor，作为after参数传入messageConnection：

{ thread(id: "some-thread-id") { # 获取上一条消息之后的下一条消息 messageConnection(after: $lastMessageCursor) { edges { node { message { content } } } } } }

3. 用first控制每页条数

{ thread(id: "some-thread-id") { # 获取最后一条消息之后的 5 条消息 messageConnection(first: 5, after: $lastMessageCursor) { edges { node { message { content } } } } } }

这就是完整的分页循环：读第一页 → 取最后一个 edge 的 cursor → 把它作为after传给下一页 → 直到pageInfo.hasNextPage为 false。

cursor 是不透明的：只用于翻页，不要解析

注意：cursor 是一种不透明（opaque）的数据结构，它可能指代你能理解的内容，也可能不能。它也不保证稳定一致，尤其在不同会话、不同资源之间。结论是——除了把它传给查询以获取下一页之外，不要对 cursor 做任何其他用途，无论你多想用它做点别的。

Spectrum 的源码严格遵循这一原则。看 api/queries/thread/messageConnection.js，每个 edge 的 cursor 是通过encode(message.timestamp.getTime().toString())生成的，而 api/utils/base64.js 中的encode只是用 Node 内置Buffer做了 base64 编码：

export const encode = (string: string) => Buffer.from(string).toString('base64');

也就是说 cursor 本质上是"消息时间戳的 base64 字符串"，但这个内部格式随时可能改变，客户端不应依赖、解码或反推它。同理，在 channel 的 thread 分页（api/queries/channel/threadConnection.js）中，cursor 是encode(String(thread.lastActive.getTime()))；而 member 分页（api/queries/channel/memberConnection.js）中，cursor 是encode(${user.id}-${lastUserIndex + index + 1})。每种资源的 cursor 内部格式各不相同，这恰恰印证了"不要假设 cursor 结构"的原因。

默认值：first的默认条数因资源而异

注意：first的默认值通常是 10，但可能因所取资源不同而改变。请务必查看 GraphiQL 或类型定义来确认默认值。

这一点在 Spectrum 的 schema 中体现得淋漓尽致——不同资源的默认分页大小并不一致：

特别值得注意thread.messageConnection：schema 中它声明为messageConnection(first: Int, after: String, last: Int, before: String)（见 api/types/Thread.js），并没有写死默认值，而是在 resolver 中动态决定：

• 传了after（或before）但没传first（或last）时，默认取 25 条，方便直接写messageConnection(after: "cursor")；
• 一个参数都没传时，同样默认取前 25 条。

let options = { first: first ? first : after ? 25 : null, last: last ? last : before ? 25 : null, after: after ? cursor : null, before: before ? cursor : null, }; // 如果什么都没传，默认取前 25 条 if (Object.keys(options).every(key => !options[key])) { options = { first: 25 }; }

所以文档"默认值是 10"只是一个笼统说法，实战中必须按资源确认默认值，最稳妥的做法是显式传first。

命名约定：Connection / Edge / node 的标准结构

所有资源的连接（connection）与边（edge）都遵循统一的标准命名和结构。以"story 到 messages"为例，文档给出如下骨架：

# 一个 story 到 messages 的连接 type StoryMessagesConnection { pageInfo: PageInfo! edges: [StoryMessageEdge!] } # 从 story 到 message 的一条边 type StoryMessageEdge { cursor: String! node: Message! } type Story { messageConnection(first: Int = 10, after: String): StoryMessagesConnection! }

这套结构在 Spectrum 中逐一落地，三个典型示例：

Thread 的消息连接（api/types/Thread.js）：

type ThreadMessagesConnection { pageInfo: PageInfo! edges: [ThreadMessageEdge!] } type ThreadMessageEdge { cursor: String! node: Message! }

Channel 的成员连接与话题连接（api/types/Channel.js）：

type ChannelMembersConnection { pageInfo: PageInfo! edges: [ChannelMemberEdge!] } type ChannelMemberEdge { cursor: String! node: User! } type ChannelThreadsConnection { pageInfo: PageInfo! edges: [ChannelThreadEdge!] } type ChannelThreadEdge { cursor: String! node: Thread! }

私信线程的消息连接（api/types/DirectMessageThread.js）：

type DirectMessagesConnection { pageInfo: PageInfo! edges: [DirectMessageEdge!] } type DirectMessageEdge { cursor: String! node: Message! }

可以归纳出三条通则：连接类型用<Resource>Connection命名，其下固定是pageInfo: PageInfo!与edges列表；边类型用<Resource>Edge命名，其下固定是cursor: String!与node（指向真正的实体类型）；资源类型上暴露<something>Connection(first: Int, after: String): <Resource>Connection!这样的分页字段。

唯一的命名偏离：Edge 用单数

注意：这是与上文推荐的文章略有分歧的地方。它建议把 edge 命名为复数（StoryMessagesEdge）以与 connection 保持一致，但 Spectrum 团队发现使用单数（StoryMessageEdge）能更清楚地表达"一次只取一个资源"这一语义，并且认为这一点更重要。

从上面的源码可以确认，Spectrum 确实全线采用了单数 edge 命名：ThreadMessageEdge、ChannelMemberEdge、ChannelThreadEdge、DirectMessageEdge，而 connection 类型保留复数（ThreadMessagesConnection、ChannelMembersConnection等）。这是团队有意的取舍，接手的开发者应沿用这一约定以保持一致。

深入 resolver：分页背后的实现原理

理解了客户端写法之后，再看 api/queries/thread/messageConnection.js 这个 resolver，能完整揭示连接规范在服务端的实现套路，主要包含四步：

1. 参数合法性校验。first/last与after/before不允许混用（否则无法确定分页方向），一旦同时传入(first && last)、(after && before)、(first && before)或(after && last)中的任意组合，直接返回UserError：

return new UserError( 'Cannot paginate back- and forwards at the same time. Please only ask for the first messages after a certain point or the last messages before a certain point.' );

2. 解码 cursor 并定位起始点。先用decode(cursor)还原出内部值（消息场景是时间戳字符串，再parseInt成数字）；解码失败或值非法时同样返回UserError('Invalid cursor passed to thread.messageConnection.')。

3. 多取一条，判断是否还有下一页。这是整个实现最精巧的一点：真正查库时把first（或last）加 1，多加载一条，然后比较实际返回数量与请求数量：

options.first && options.first++; options.last && options.last++; return getMessages(id, options).then(result => { const loadedMoreFirst = options.first && result.length > options.first - 1; const loadedMoreLast = options.last && result.length > options.last - 1; // 去掉多取的那一条 if (loadedMoreFirst) { messages = result.slice(0, result.length - 1); } else if (loadedMoreLast) { messages = result.reverse().slice(1, result.length); } ...

4. 组装pageInfo与edges。hasNextPage由"是否多取到了消息"推导，并结合before/after是否存在进行兜底；每个 edge 的 cursor 用 base64 编码时间戳生成：

return { pageInfo: { hasNextPage: loadedMoreFirst || !!options.before, hasPreviousPage: loadedMoreLast || !!options.after, }, edges: messages.map(message => ({ cursor: encode(message.timestamp.getTime().toString()), node: message, })), };

Channel 下的两个分页 resolver 用了更简洁的等价写法：threadConnection直接以"返回条数是否 ≥first"判定hasNextPage（api/queries/channel/threadConnection.js），memberConnection除了校验canViewChannel私有频道权限外，还把 cursor 解码成用户下标索引传入数据层（api/queries/channel/memberConnection.js）。这些细节印证了规范只约束"返回形状"，cursor 内部编码与 hasNextPage 的判定策略完全由各实现自行决定。

另外，api/utils/paginate-arrays.js 还提供了一个通用的数组分页工具函数：给定数组、{ first, after }与可选的getAfter回调，返回切片后的{ list, hasMoreItems }，适合在纯内存数据上快速实现同样的分页语义。

小结与实践建议

综合文档与源码，在 Spectrum 中使用 GraphQL 分页可以总结为以下要点：

1. 永远走连接（Connection）形态：查询xxxConnection字段，读取edges[].cursor与pageInfo.hasNextPage，而不是自己去做偏移量分页。
2. 翻页只依赖 cursor：把最后一条 edge 的cursor作为after传给下一次查询；不要解析、缓存或跨资源复用 cursor。
3. 显式传first：各资源的默认条数不统一（10 / 20 / 25），依赖默认值容易产生意外行为。
4. 单向分页：不要同时混用first/last与after/before，服务端会直接拒绝这类请求。
5. 遵循命名约定：<Resource>Connection+<Resource>Edge（单数）+pageInfo+cursor+node，新资源照此模板扩展即可。
6. 理解不透明性带来的演进空间：正因为 cursor 对外不透明，服务端未来可以自由更换内部编码方式（时间戳、索引、ID 等）而不破坏客户端。

这套基于 Relay Connections 规范的分页模式贯穿了 Spectrum 的 thread 消息、channel 话题与成员、私信消息等所有列表型数据，是理解该项目 API 数据流的一把关键钥匙。

• 后端
• 前端
• 即时通讯
• 社交