SuperAPI AI 工具集

tRPC

编程与开发

查看项目

更新于 11-02 01:30

技能介绍

tRPC 用于在 TypeScript 中构建完全类型安全的 API,核心特点是服务端到客户端的完整类型推导,无需代码生成即可获得自动补全和类型检查,并可与 Next.js、React Query 等配合使用。

安装与初始化:安装 @trpc/server、@trpc/client、@trpc/react-query,以及对等依赖 @tanstack/react-query 和 zod。通过 initTRPC.create() 创建实例,导出 router 与 procedure。定义应用路由后导出 AppRouter 类型,供客户端创建类型化调用。在 Next.js App Router 中可用 fetchRequestHandler 创建 /api/trpc 路由,并用 createTRPCReact 生成客户端钩子。

路由与过程:路由支持 query(读取)、mutation(增删改)和 subscription(实时更新);可嵌套组合多个子路由,也可合并路由。使用 Zod 对输入进行校验,从简单对象到嵌套、默认值、数组长度限制等复杂结构,并可复用和派生 schema(如 omit、partial)。

上下文与中间件:通过 createContext 注入 session、db 等依赖,使用 inferAsyncReturnType 推导 Context 类型。中间件可实现日志、鉴权、角色校验等,并通过 use 组合为 publicProcedure、protectedProcedure 等不同类型的过程,鉴权中间件可在 ctx 中收窄 session 的非空类型。

客户端使用:基于 React Query 的 useQuery、useMutation 提供加载与错误状态;支持禁用查询、轮询、缓存时间等选项。变更后可失效重取,也可实现乐观更新(onMutate 快照与回滚)。支持 useInfiniteQuery 配合游标分页实现无限加载。

错误处理:服务端通过 TRPCError 抛出 BAD_REQUEST、UNAUTHORIZED、FORBIDDEN、NOT_FOUND、TIMEOUT、CONFLICT、TOO_MANY_REQUESTS、INTERNAL_SERVER_ERROR 等标准错误码,客户端可根据 error.data.code 做差异化处理。

服务端调用:通过 createCallerFactory 创建 caller,可在服务端组件中直接调用路由过程,无需经过 HTTP。其他能力包括请求批处理(httpBatchLink)、请求去重(React Query 自动处理)、自定义请求头及错误格式化。

适用场景为 TypeScript 全栈项目,尤其是 Next.js + React Query 技术栈的内部或前后端同仓应用。限制方面:tRPC 依赖 TypeScript 类型系统,不适合非 TypeScript 客户端或需要公开的跨语言 API;本资料未提供收费、价格、性能指标或独立部署要求等信息。