ts-rest项目中React组件与AppRouter的泛型集成实践

背景介绍

在React应用开发中，我们经常需要创建可复用的通用组件，这些组件需要与后端API进行交互。ts-rest作为一个类型安全的API契约库，能够帮助我们更好地管理前端与后端的通信。然而，在实际开发中，将ts-rest与React组件结合使用时，特别是在处理泛型组件和AppRouter时，开发者可能会遇到类型定义上的挑战。

核心问题分析

当尝试创建一个通用的React组件，该组件需要接收一个ts-rest路由作为属性(prop)时，我们面临的主要困难是如何正确定义组件的类型。具体来说，我们需要：

1. 确保组件能够接受不同类型的ts-rest路由
2. 在组件内部正确使用这些路由的方法，如useInfiniteQuery
3. 保持完整的类型安全性和IDE智能提示

解决方案探索

方案一：直接传递路由属性

最初的想法可能是直接在组件属性中传递路由，如：

interface Props {
  keys: QueryKey;
  route: ???; // 类型定义困难
}

然而，这种方法会遇到类型定义困难的问题，因为ts-rest的路由类型较为复杂，难以直接作为属性类型使用。

方案二：使用路径字符串标识路由

更可行的方案是使用路径字符串来标识路由，同时传递完整的contract和client：

<MyComponent 
  queryKey={["products"]} 
  contract={contract} 
  client={client} 
  route="products.list" 
  args={...} 
/>

这种方式的优势在于：

1. 避免了直接处理复杂的路由类型
2. 保持了类型安全性
3. 使用起来更加直观

实现细节

路径类型定义

我们可以借鉴其他库的经验，定义一个能够深度遍历对象路径的类型：

type Path<T> = T extends object
  ? { [K in keyof T]: `${Exclude<K, symbol>}${Path<T[K]> extends never 
      ? '' 
      : '.'}${Path<T[K]>}` }[keyof T]
  : never;

这个类型可以帮助我们确保route属性只能是contract中存在的有效路径。

请求参数类型推断

对于args属性，我们可以使用ts-rest提供的ClientInferRequest工具类型来确保传递的参数与API契约匹配：

type RequestArgs = ClientInferRequest<typeof contract.products.list>;

组件内部实现

在组件内部，我们可以通过路径字符串来动态获取对应的路由方法。虽然这会导致一些类型推断的困难，但可以通过类型断言或@ts-expect-error来暂时绕过：

export function MyComponent({queryKey, contract, client, route, args}) {
  // 动态获取路由方法
  const routeFn = getRouteFromPath(client, route);
  
  // @ts-expect-error 类型推断困难
  const infiniteQuery = routeFn.useInfiniteQuery(
    queryKey,
    ({ pageParam = 1 }) => ({
      query: { page: Number(pageParam) },
      ...args
    })
  );
  
  // 组件渲染逻辑...
}

最佳实践建议

1. 保持组件接口简洁：尽量使用路径字符串而非直接传递路由对象
2. 合理使用类型工具：充分利用ts-rest提供的类型工具如ClientInferRequest
3. 适度使用类型断言：在确实难以类型推断的地方，可以使用@ts-expect-error
4. 文档和注释：为复杂组件添加详细注释，说明预期的使用方式

总结

将ts-rest与React组件结合使用时，通过路径字符串而非直接传递路由对象的方式，可以更优雅地解决类型定义问题。虽然组件内部可能需要一些类型断言，但对外提供了简洁、类型安全的接口。这种方法既保持了ts-rest的类型安全优势，又提供了良好的开发者体验。