#tRPC ## 概述 tRPC 通过在服务器和客户端之间共享 TypeScript 类型来实现端到端类型安全的 API，而无需生成代码或模式。服务器在路由器中定义过程（查询、突变、订阅），客户端从导出的“AppRouter”类型推断所有类型。 **何时使用：** TypeScript 全栈应用程序需要类型安全的 API 层、monorepos 共享类型、实时订阅、快速 API 迭代，而无需 OpenAPI/GraphQL 开销。 **何时不使用：** 非 TypeScript 客户端使用的公共 API（使用 REST/GraphQL）、多语言后端、需要 OpenAPI 规范生成作为主要输出的项目。 ## 快速参考图案|应用程序接口 |要点 ---|---|--- 初始化| `initTRPC.context().create()` |单一入口点，配置一次路由器| `t.router({ ... })` |使用“t.mergeRouters()”嵌套路由器查询 | `t.procedure.input(schema).query(fn)` |读取操作，由客户端缓存突变| `t.procedure.input(schema).mutation(fn)` |写操作订阅 | `t.procedure.subscription(fn)` |通过 WebSocket 或 SSE 实时中间件| `t.middleware(fn)` |使用 `.use()` 进行链接，通过 `next({ ctx })` 扩展上下文独立中间件| `experimental_standaloneMiddleware<{}>()` |可在显式类型约束下重用背景 | `createContext({ req, res })` |每个请求，传递给所有过程服务器调用者| `t.createCallerFactory（路由器）` |类型安全的服务器端过程调用错误 | `抛出新的 TRPCError({ 代码, 消息 })` |映射到 HTTP 状态代码错误格式化程序 | `initTRPC.create({ errorFormatter })` |自定义错误形状，暴露 Zod 错误输入验证 | `.input(zodSchema)` |多个 .input() 调用合并（交集）输出验证 | `.output(zodSchema)` |从响应中删除额外的字段反应钩子 | `trpc.useQuery()` / `trpc.useMutation()` |基于@tanstack/react-query 构建反应实用程序 | `trpc.useUtils()` |缓存上的无效、预取、setData 悬疑查询| `trpc.useSuspenseQuery()` |与 Suspense 兼容的数据获取反应订阅 | `trpc.useSubscription（输入，选择）` |实时事件的“onData”回调普通客户端 | `createTRPCClient({ links })` |没有 React 依赖批量链接 | `httpBatchLink({ url })` |在单个 HTTP 调用中批量请求串流链接 | `httpBatchStreamLink({ url })` |解决问题时流式传输响应 WS链接| `wsLink({ 客户端: wsClient })` |用于订阅的 WebSocket 传输分割链接 | `splitLink({ 条件, true, false })` |将操作路由到不同的交通工具记录器链接 | `loggerLink()` |开发中调试请求/响应数据转换器 | `initTRPC.create({ 变压器 })` |序列化日期、地图、集合 (superjson) 获取适配器 | `fetchRequestHandler({ 端点, req })` | Cloudflare Workers、Deno、Bun、Next.js 过程链接| `publicProcedure.use(auth).use(rateLimit)` |建立可重用的程序库 ## 常见错误错误|正确的模式 ---|--- 导出完整的“t”对象 |仅导出`t.router`、`t.procedure`、`t.middleware`、`t.createCallerFactory` 在过程中创建上下文 |在适配器设置中创建上下文，自动流动使用“any”作为上下文类型 |使用 `initTRPC.context().create()` 定义上下文类型捕获程序中的错误|让错误传播；在适配器或错误格式化程序中使用“onError” 在客户端导入服务器代码 |仅导入`type AppRouter`，从不导入运行时服务器代码在生产请求处理程序中使用“createCaller” |使用“createCallerFactory”作为类型安全的可重用调用者定义输入而不验证 |始终使用 Zod、Valibot 或 ArkType 模式进行验证错误地嵌套路由器 |在键或“t.mergeRouters()”中使用点表示法，而不是深度嵌套客户端/服务器上的不同变压器 |双方必须使用相同的变压器（例如 superjson）在组件渲染中创建 QueryClient |在外部组件创建一次或使用 useState 初始值设定项钩子上的手动 TypeScript 泛型 |输入路由器程序；让推理传播给客户端未传递“信号”以在 queryFn 中获取 | tRPC React 自动处理中止信号 ## 安装 pnpm 添加 @trpc/服务器 @trpc/客户端 @trpc/react-query @tanstack/react-query zod 对于订阅，添加“ws”（服务器）并配置“wsLink”（客户端）。对于基于 SSE 的订阅，请改用“httpBatchStreamLink”。 ## 代表团 * **过程发现** ：使用 `Explore` 代理 * **路由器架构回顾** ：使用 `Task` 代理 * **代码审查** ：委托给 `code-reviewer` 代理 > 如果“tanstack-query”技能可用，请将查询/变异缓存、失效和乐观更新模式委托给它。如果“zod-validation”技能可用，请将输入模式设计和验证模式委托给它。如果“drizzle-orm”技能可用，请将过程中的数据库查询模式委托给它。如果“vitest-testing”技能可用，请将测试运行器配置和断言模式委托给它。如果“hono”技能可用，请将 Hono 框架路由和中间件模式委托给它。 ## 参考文献 * [路由器和过程定义]() * [中间件和上下文模式]() * [错误处理和格式化]() * [React 客户端与 @trpc/react-query 集成]() * [服务器端调用者和普通客户端]() * [独立、Express、Fastify 和 Hono 的适配器设置]() * [订阅和实时模式]() * [测试 tRPC 程序]()

特尔普克

包含技能