本文详解如何在 supabase 的 graphql api 中正确使用游标分页（cursor-based pagination），包括获取总记录数、计算总页数、跳转任意页（如第 3 页）的实践方法，并提供可运行的查询示例与关键注意事项。
本文详解如何在 supabase 的 graphql api 中正确使用游标分页（cursor-based pagination），包括获取总记录数、计算总页数、跳转任意页（如第 3 页）的实践方法，并提供可运行的查询示例与关键注意事项。
Supabase 基于 pg_graphql 提供的 GraphQL 接口默认采用游标分页（Cursor-based Pagination），而非传统的 offset/limit 或页码式分页。这种设计更高效、稳定，尤其适用于大数据集和实时更新场景——但其代价是：无法直接通过 page=3 获取第 3 页，也不能仅凭 first: 10 推导出总页数。要支持“跳转至任意页”或显示“共 N 页”，需结合 totalCount 字段与游标策略协同实现。
✅ 正确启用并使用 totalCount
Supabase 的 pg_graphql 默认开启 totalCount 字段（自 v0.7.0+ 起），它会出现在 Connection 类型的顶层响应中（注意：不是 pageInfo 下）。你只需在查询中显式请求：
{
postsCollection(first: 10) {
totalCount # ← 关键：直接请求 totalCount
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
edges {
cursor
node {
id
title
}
}
}
}
✅ 响应示例片段：
{
"data": {
"postsCollection": {
"totalCount": 127,
"pageInfo": { /* ... */ },
"edges": [ /* ... */ ]
}
}
}
⚠️ 注意：若 totalCount 返回 null，请检查是否被禁用。某些旧版 Schema 或手动添加的 @pggraphql 注释可能含 totalCount: false；可通过移除相关 directive 或升级 Supabase 项目确保启用（详见 pg_graphql#68）。
? 计算总页数 & 跳转任意页（如第 3 页）
游标分页本身不支持 page=3 直接跳转，因为游标是不透明的字符串（如 "YXJyYXljb25uZWN0aW9uOjEw"），不代表顺序索引。但借助 totalCount 和固定 first 值，你可估算逻辑页数，并通过「递归游标获取」模拟跳页：
-
估算总页数（仅作 UI 展示，非精确导航）：
const pageSize = 10; const totalPages = Math.ceil(totalCount / pageSize); // e.g., 127 → 13 pages
-
跳转至第 N 页的可靠方式：
必须从第 1 页开始，连续 N−1 次调用 after: $endCursor 查询，直到抵达目标页。例如跳转第 3 页：- 第 1 页：first: 10 → 得到 endCursor
- 第 2 页：first: 10, after: "
" → 得到新 endCursor - 第 3 页：first: 10, after: "
"
? 实际项目中，建议封装为工具函数（如 fetchPage(n: number)），内部维护游标链表缓存，避免重复请求。参考社区实现：supabase-graphql-example。
? 重要限制与替代建议
- ❌ 不要尝试解析或构造游标：游标由 pg_graphql 内部生成（Base64 编码的内部标识符），结构不公开且可能变更。
- ❌ 避免 offset 模拟：GraphQL 层不支持 skip 或 offset 参数；强行在客户端丢弃前 20 条数据（模拟 page=3）会浪费带宽且破坏游标语义。
- ✅ 高频跳页场景？考虑混合方案：
若业务强依赖随机页码（如后台管理列表），可额外创建一个视图（View）暴露 row_number() OVER (ORDER BY ...) 列，再通过 filter: { rowNumber: { eq: 30 } } 精确定位——但这需权衡一致性与复杂度。
✅ 总结
| 目标 | 实现方式 |
|---|---|
| 获取总记录数 | 显式查询 totalCount 字段（默认启用） |
| 显示“共 N 页” | Math.ceil(totalCount / first)（UI 友好估算） |
| 跳转至第 N 页 | 连续 N−1 次 after 查询（推荐封装为分页器） |
| 避免陷阱 | 不解析游标、不模拟 offset、不忽略 totalCount: false 配置 |
游标分页不是缺陷，而是为可扩展性做出的明确取舍。理解其原理并善用 totalCount，你就能在 Supabase GraphQL 中构建既健壮又用户友好的分页体验。
