TRPC项目中无限查询(infiniteQuery)的正确使用方法

在TRPC项目中，开发者经常会遇到无限查询(infiniteQuery)的使用问题。本文将通过一个典型错误案例，深入分析TRPC无限查询的正确实现方式。

问题现象

许多开发者在尝试为带有输入参数的TRPC过程(procedure)使用infiniteQueryOptions时，会遇到TypeScript类型错误提示该属性未定义。这通常发生在过程定义中包含输入参数但未正确配置无限查询所需参数的情况下。

根本原因

TRPC的无限查询机制有一个关键要求：过程必须接受一个名为cursor的输入参数，其类型可以是字符串或数字。这个参数用于实现分页功能，是无限查询的核心机制。

错误示例分析

以下是一个典型的错误实现：

// 错误的过程定义
test2: publicProcedure
  .input(z.object({ limit: z.number(), offset: z.number() }))
  .query(async () => {
    return await Promise.resolve([]);
  })

这种定义虽然包含了分页参数limit和offset，但缺少了TRPC无限查询必需的cursor参数，因此无法使用infiniteQueryOptions。

正确实现方式

要实现可用的无限查询，过程定义应如下：

// 正确的无限查询过程定义
test2: publicProcedure
  .input(z.object({ 
    limit: z.number(), 
    cursor: z.number().optional() // 必须包含cursor参数
  }))
  .query(async ({ input }) => {
    // 实现逻辑
  })

实现要点

1. 必须参数：输入对象中必须包含cursor字段，类型为number或string，通常标记为可选

2. 分页逻辑：在查询实现中，需要根据cursor值获取对应数据页

3. 返回结构：响应应包含数据列表和下一条记录的cursor值

4. 客户端使用：正确配置后，客户端可以调用infiniteQueryOptions方法

最佳实践建议

1. 统一命名：建议始终使用cursor作为游标参数名，保持一致性

2. 类型安全：使用Zod严格定义cursor类型，避免运行时错误

3. 文档注释：为无限查询过程添加详细注释，说明其特殊要求

4. 错误处理：考虑cursor无效时的处理逻辑

总结

TRPC的无限查询功能为分页场景提供了强大支持，但需要遵循特定的参数约定。理解cursor参数的核心作用，可以帮助开发者避免类型错误并实现高效的分页查询。在实际项目中，建议团队建立统一的无限查询实现规范，确保代码的一致性和可维护性。

通过本文的分析，开发者可以掌握TRPC无限查询的正确使用方法，避免常见的配置错误，充分发挥TRPC在数据分页场景下的优势。