分页：Cursor vs Offset

分页方案对比

GraphQL API 中最常见的两种分页方案各有适用场景：

Offset 分页的局限

# Offset 分页：skip/take
type Query {
  posts(skip: Int = 0, take: Int = 20): [Post!]!
}

query {
  posts(skip: 0, take: 20)  # 第1页
  posts(skip: 20, take: 20) # 第2页
}

Relay Cursor Connection 规范

Schema 定义

# Connection 模式的通用结构
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type PostEdge {
  node: Post!
  cursor: String!  # 不透明的分页游标（通常是 base64 编码的 ID）
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String     # 当前页第一个元素的 cursor
  endCursor: String       # 当前页最后一个元素的 cursor
}

type Query {
  posts(
    first: Int    # 向前分页：取前 N 条
    after: String # 从指定 cursor 之后开始
    last: Int     # 向后分页：取后 N 条
    before: String # 从指定 cursor 之前开始
  ): PostConnection!
}

客户端查询示例

# 第1页：获取前20条
query {
  posts(first: 20) {
    edges {
      cursor
      node { id title createdAt author { name } }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

# 第2页：从 endCursor 之后获取下20条
query {
  posts(first: 20, after: "Y3Vyc29yOjIw") {
    edges {
      cursor
      node { id title }
    }
    pageInfo { hasNextPage endCursor }
  }
}

服务器实现

function encodeCursor(id: string): string {
  return Buffer.from(`cursor:${id}`).toString('base64');
}

function decodeCursor(cursor: string): string {
  return Buffer.from(cursor, 'base64').toString().replace('cursor:', '');
}

const resolvers = {
  Query: {
    posts: async (_, { first = 20, after, last, before }, { db }) => {
      const take = first ?? last ?? 20;
      const cursor = after ? { id: decodeCursor(after) } : undefined;

      const posts = await db.posts.findMany({
        take: take + 1, // 多取1条用于判断 hasNextPage
        cursor,
        skip: cursor ? 1 : 0,
        orderBy: { createdAt: 'desc' },
      });

      const hasNextPage = posts.length > take;
      const nodes = hasNextPage ? posts.slice(0, -1) : posts;
      const totalCount = await db.posts.count();

      return {
        totalCount,
        edges: nodes.map(post => ({
          node: post,
          cursor: encodeCursor(post.id),
        })),
        pageInfo: {
          hasNextPage,
          hasPreviousPage: !!after,
          startCursor: nodes[0] ? encodeCursor(nodes[0].id) : null,
          endCursor: nodes.at(-1) ? encodeCursor(nodes.at(-1)!.id) : null,
        },
      };
    },
  },
};

Cursor 的编码原理

游标（Cursor）是一个不透明（Opaque）的字符串，客户端不应该尝试解析它的内容，只需原样传回给服务器。服务器内部决定游标的编码方式：

前端无限滚动实现

// React 无限滚动示例（配合 Apollo Client）
import { useQuery } from '@apollo/client';
import { useRef, useCallback } from 'react';

const GET_POSTS = gql`
  query GetPosts($first: Int!, $after: String) {
    posts(first: $first, after: $after) {
      edges {
        cursor
        node { id title createdAt }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
`;

function PostFeed() {
  // fetchMore 是 Apollo 提供的追加数据方法
  const { data, loading, fetchMore } = useQuery(GET_POSTS, {
    variables: { first: 20 },
  });

  // IntersectionObserver 监听"加载更多"触发元素
  const observer = useRef<IntersectionObserver>();
  const lastPostRef = useCallback((node: Element | null) => {
    if (loading) return;
    if (observer.current) observer.current.disconnect();

    observer.current = new IntersectionObserver(entries => {
      if (entries[0].isIntersecting && data?.posts.pageInfo.hasNextPage) {
        // 用 endCursor 获取下一页
        fetchMore({
          variables: { after: data.posts.pageInfo.endCursor },
          updateQuery: (prev, { fetchMoreResult }) => {
            if (!fetchMoreResult) return prev;
            return {
              posts: {
                ...fetchMoreResult.posts,
                // 合并 edges 数组：旧数据 + 新数据
                edges: [
                  ...prev.posts.edges,
                  ...fetchMoreResult.posts.edges,
                ],
              },
            };
          },
        });
      }
    });

    if (node) observer.current.observe(node);
  }, [loading, data?.posts.pageInfo]);

  const posts = data?.posts.edges ?? [];

  return (
    <div>
      {posts.map((edge, i) => (
        // 最后一条加 ref，触发加载更多
        <PostCard
          key={edge.node.id}
          post={edge.node}
          ref={i === posts.length - 1 ? lastPostRef : null}
        />
      ))}
      {loading && <Spinner />}
    </div>
  );
}

两种分页方案选择指南

本章小结