Pothos项目中实现可复用的GraphQL分页功能

在GraphQL API开发中，分页是一个常见需求。本文将介绍如何在Pothos项目中实现一个类型安全、可复用的分页功能解决方案。

分页功能的基本结构

一个典型的分页响应通常包含以下字段：

• items: 当前页的数据项数组
• total: 总记录数
• per_page: 每页显示数量
• total_pages: 总页数
• current_page: 当前页码

在TypeScript中，我们可以定义一个通用的分页接口：

export interface Pagination<T> {
  items: T[];
  total: number;
  per_page: number;
  total_pages: number;
  current_page: number;
}

基础实现方案

最简单的实现方式是创建一个生成分页类型的工厂函数：

export function createPagination<T>(type: ObjectRef<any, T>) {
  const PaginationReference = builder.objectRef<Pagination<T>>(
    `${type.name}Paginate`
  );

  return builder.objectType(PaginationReference, {
    fields: (t) => ({
      items: t.expose('items', {
        type: [type],
      }),
      per_page: t.exposeInt('per_page'),
      total: t.exposeInt('total'),
      total_pages: t.exposeInt('total_pages'),
      current_page: t.exposeInt('current_page'),
    }),
  });
}

使用方式如下：

const Users = builder.objectType(UsersReference, {
  fields: (t) => ({
    name: t.exposeString('name'),
    email: t.exposeString('email')
  })
});

builder.queryField('usersPaginated', (t) =>
  t.field({
    type: createPagination(Users),
    resolve: async () => {
      return {
        items: [/* 用户数据 */],
        total: 1,
        per_page: 10,
        total_pages: 1,
        current_page: 1
      };
    }
  })
);

进阶：自定义分页字段

为了提供更优雅的API，我们可以扩展Pothos的RootFieldBuilder，添加一个paginatedField方法：

declare global {
  export namespace PothosSchemaTypes {
    export interface RootFieldBuilder<
      Types extends SchemaTypes,
      ParentShape,
      Kind extends FieldKind = FieldKind
    > {
      paginatedField: <
        Type extends ObjectRef<Types, unknown>,
        ResolveShape,
        ResolveReturnShape,
        Args extends InputFieldMap = {},
        Nullable extends FieldNullability<Type> = Types['DefaultFieldNullability']
      >(
        options: PaginatedFieldOptions</* 类型参数 */>
      ) => FieldRef</* 类型参数 */>;
    }
  }
}

实现部分需要处理分页参数和返回类型：

rootBuilderProto.paginatedField = function paginatedField(options) {
  const PaginationReference = this.builder
    .objectRef<Pagination<unknown>>(`${options.type.name}Paginate`)
    .implement({
      fields: (t) => ({
        items: t.expose('items', {
          type: [options.type],
        }),
        // 其他分页字段...
      }),
    });

  return this.field({
    ...options,
    type: PaginationReference,
    args: {
      ...options.args,
      perPage: this.arg.int(),
      page: this.arg.int(),
    },
  });
};

这种实现方式允许我们直接使用：

builder.queryField('users', (t) =>
  t.paginatedField({
    type: Users,
    resolve: async (_, args) => {
      const { page = 1, perPage = 10 } = args;
      // 实现分页逻辑
    }
  })
);

最佳实践建议

1. 命名一致性：保持分页类型名称一致，如UserPaginate、PostPaginate等

2. 参数默认值：为分页参数(page, perPage)设置合理的默认值

3. 性能考虑：在resolve函数中实现高效的分页查询，避免全表扫描

4. 扩展性：考虑添加排序、过滤等参数支持

5. 文档注释：为分页类型和字段添加清晰的文档注释

通过以上方案，我们可以在Pothos项目中实现类型安全、可复用的分页功能，既能满足简单场景的需求，也能通过扩展支持更复杂的业务场景。