对于 NestJS + TypeORM 查询构造器分页功能的简单二次封装

NestJS 作为 Node.js 领域备受欢迎的框架，其与 TypeORM 的结合为开发者提供了强大的 ORM 能力，简化了数据库操作。然而，在处理分页查询时，直接在每个服务方法中重复编写分页逻辑既不高效也容易出错。为此，我们可以通过创建一个通用的分页处理函数，将分页逻辑从业务逻辑中抽离出来，达到代码复用和模块化的目的。

本文将介绍如何对 TypeORM 的查询构造器（QueryBuilder）进行简单的二次封装，以便于我们在 API 层快速实现分页功能，同时保持代码的整洁与可维护性。我们将通过一个具体示例来演示这一过程，即通过封装一个分页查询方法，来查询用户列表并进行相应的数据处理。

我们的目标是设计一个函数setQueryBuilderPagination，它接受一个查询构造器实例、分页参数以及一个可选的回调函数作为参数，返回一个包含分页信息的对象。这个函数将负责处理查询构造器的分页逻辑，如设置每页数量、跳过行数等，同时也支持通过回调函数对查询结果进行后处理。

功能实现

export interface IBackendPaginatedQueryParams {
  currentPage: number;
  pageSize: number;
}

interface IBackendPaginatedList {
  currentPage: number;
  totalPages: number;
  total: number;
  pageSize: number;
  records: any[];
}

/**
 * 为查询构造器设置分页功能。
 * @async
 * @template T 泛型类型，继承自 ObjectLiteral。
 * @param {SelectQueryBuilder<T>} queryBuilder 查询构造器实例。
 * @param {IBackendPaginatedQueryParams} paginationQueryParams 分页查询参数。
 * @param {((records: T[]) => T[])?} [callback] 可选的回调函数，用于处理记录数据。
 * @returns {Promise<IBackendPaginatedList>} 包含当前页、总页数、总数和记录数据的分页信息对象。
 */
export const setQueryBuilderPagination = async <T extends ObjectLiteral>(
  queryBuilder: SelectQueryBuilder<T>,
  paginationQueryParams: IBackendPaginatedQueryParams,
  callback?: (records: Record<string, any>[]) => Record<string, any>[]
): Promise<IBackendPaginatedList> => {
  const { pageSize, currentPage } = paginationQueryParams;
  queryBuilder.take(pageSize).skip((currentPage - 1) * pageSize);
  const [recordsRaw, total] = await queryBuilder.getManyAndCount();

  const records = callback ? callback(recordsRaw) : recordsRaw;

  return {
    currentPage: Number(currentPage),
    totalPages: Math.ceil(total / pageSize),
    total: Number(total),
    pageSize: Number(pageSize),
    records,
  };
};

核心逻辑讲解

首先，封装的核心在于如何处理分页参数。在setQueryBuilderPagination函数中，我们接收两个主要参数：查询构造器实例queryBuilder和分页查询参数paginationQueryParams。分页参数包括每页显示的记录数pageSize和当前请求的页码currentPage。函数内部首先读取这两个参数，然后利用它们设置查询构造器的分页行为：通过.take(pageSize)限制查询结果的数量，通过.skip((currentPage - 1) * pageSize)确定从哪条记录开始获取数据。这样就完成了基本的分页设置。

数据获取与计数

紧接着，通过调用.getManyAndCount()方法，我们一步完成数据的获取及总记录数的统计。这一步骤至关重要，因为它既高效地获取了当前页面的数据，又提供了计算总页数所需的信息。返回的结果是一个数组，其中第一个元素是查询结果，第二个元素是总记录数。

后处理回调

为了增强灵活性，我们引入了一个可选的回调函数callback，它允许在返回最终结果前对原始查询数据进行进一步加工。例如，我们可以利用这个回调来格式化数据、添加额外属性或进行数据筛选。在示例中，processQueryRecords函数就是一个典型的后处理示例，它遍历查询结果，为每个用户添加一个roleIds属性，该属性包含了用户所有角色的 ID。

返回分页信息对象

最后，我们将分页后的数据整理成统一格式返回给调用者。这个格式通常包含当前页码、总页数、总记录数、每页大小以及具体的记录数据。这样的返回结构对于前端分页展示非常友好，易于解析和处理。

应用实例：用户列表查询

接下来，我们将展示如何在实际业务场景中应用此封装函数。假设我们有一个需求，要查询用户列表，同时需要对查询结果中的角色进行处理，提取每个用户的角色 ID 数组。

export class UserService {
  constructor(
    private roleService: RoleService,
    @InjectRepository(User) private readonly userRepository: Repository<User>
  ) {}

  async findList(
    filterDto: UserFilterDto,
    queryParams: IBackendPaginatedQueryParams
  ) {
    const queryBuilder = this.userRepository
      .createQueryBuilder("user")
      .select([
        "user.id",
        "user.userName",
        "user.email",
        "user.createdTime",
        "user.updatedTime",
        "user.status",
        "user.remark",
      ])
      .leftJoinAndSelect("user.roles", "roles");

    const processQueryRecords = (records: Record<string, any>[]) => {
      return records.map((item: Record<string, any>) => {
        item.roleIds = item.roles.map((item) => item.id);
        return item;
      });
    };

    return await setQueryBuilderPagination<User>(
      queryBuilder,
      queryParams,
      processQueryRecords
    );
  }
}