如何用tRPC构建第一个类型安全API：10分钟快速上手完全指南（附最小示例代码）

如何用tRPC构建第一个类型安全API10分钟快速上手完全指南附最小示例代码【免费下载链接】trpc‍♀️ Move Fast and Break Nothing. End-to-end typesafe APIs made easy.项目地址: https://gitcode.com/GitHub_Trending/tr/trpctRPCTypeScript Remote Procedure Call是一个帮你轻松构建端到端类型安全 API的开源框架——无需手写 schema、无需代码生成客户端直接通过 TypeScript 类型推断获得完整的自动补全与类型检查。本指南带你 10 分钟跑通第一个 tRPC 项目初始化路由 → 定义接口 → 启动服务 → 客户端类型安全调用。为什么选择 tRPC告别 API 契约不同步的痛点在 TypeScript 全栈开发中客户端与服务端的 API 契约经常“脱节”接口改个字段名前端要等到运行时报错才发现。tRPC 的思路很简单也很巧妙——直接复用 TypeScript 的类型系统‍♂️ 客户端对输入、输出、错误都有完整的静态类型安全与自动补全 零代码生成、零构建管道、零运行时依赖开箱即用 客户端包体积极小可轻松嵌入现有项目brownfield 支持订阅实时推送与请求批处理batching 官方提供 React / Next.js / Express / Fastify 等主流框架适配器更多特性说明可参考官方文档 www/docs/main/introduction.mdx。 如果需要使用 AI 编码助手如 Cursor、Windsurf还可以安装 tRPC 的 AI skills 以获得更准确的代码生成安装方式见 README.md 中的 AI Agents 章节。快速上手前环境准备一步到位tRPC 的包按职责拆分按需安装即可核心只需两个npm i trpc/server trpc/client环境要求TypeScript 5.7.2且强烈建议tsconfig.json中开启strict: true若用到 zod 校验输入再额外安装zod⚠️ 新手提醒不要把 tRPC 初始化和路由定义写在同一个文件里官方推荐分文件放置以避免循环依赖。第 1 步初始化 tRPC 并创建路由器新建server/trpc.ts只做一件事——初始化后端并导出可复用的助手import { initTRPC } from trpc/server; const t initTRPC.create(); export const router t.router; export const publicProcedure t.procedure;然后在server/appRouter.ts中创建主路由appRouter并导出它的类型——这一行就是类型安全的灵魂export type AppRouter typeof appRouter;第 2 步定义 Query 与 Mutation 两类接口tRPC 借鉴了 GraphQL 的概念把接口分为两类类型底层 HTTP适用场景query()GET只读操作查数据mutation()POST有副作用的操作增删改给路由添加三个典型接口含 zod 输入校验import { z } from zod; export const appRouter router({ userList: publicProcedure.query(async () users), userById: publicProcedure .input(z.string()) .query(async ({ input }) db.findById(input)), userCreate: publicProcedure .input(z.object({ name: z.string() })) .mutation(async ({ input }) db.create(input)), });.input()支持 zod、yup、valibot 等任意校验库非法输入会在进入业务逻辑前被拦截。第 3 步启动 API 服务3 行代码tRPC 内置了丰富的服务器适配器最简场景用 standalone 适配器即可import { createHTTPServer } from trpc/server/adapters/standalone; const server createHTTPServer({ router: appRouter }); server.listen(3000);运行后API 就跑在http://localhost:3000上了。完整后端代码可对照最小示例 examples/minimal/src/server/index.ts其中还演示了可迭代流式接口。第 4 步客户端调用享受端到端类型安全客户端只类型导入服务端的AppRouterimport type会在构建时被擦除不会把任何服务端代码带进浏览器import { createTRPCClient, httpBatchLink } from trpc/client; import type { AppRouter } from ./appRouter; const trpc createTRPCClientAppRouter({ links: [httpBatchLink({ url: http://localhost:3000 })], }); const user await trpc.userById.query(1); // 类型自动推断 ✅ const created await trpc.userCreate.mutate({ name: Katt });此时的 IDE 体验是“真香”时刻✨ 输入trpc.后自动补全所有接口 悬停即可看到每个参数的推断类型️ 拼错方法名、传错参数类型编译期直接报错 在客户端方法上Cmd/Ctrl 点击可直接跳转到服务端定义完整客户端代码见 examples/minimal/src/client/index.ts。最小示例项目结构可直接克隆学习仓库自带一个“最小可运行示例”文件极少、注释清晰最适合初学者逐行阅读要求 Node 18examples/minimal/ ├── src/ │ ├── server/ │ │ ├── trpc.ts # tRPC 初始化 │ │ ├── index.ts # 路由定义 HTTP 服务 │ │ └── db.ts # 模拟数据库 │ ├── client/ │ │ └── index.ts # 类型安全客户端 │ └── shared/ │ └── transformer.ts └── README.md克隆仓库后即可体验git clone https://gitcode.com/GitHub_Trending/tr/trpc cd examples/minimal npm i npm run dev官方建议边跑边改代码——随便改一个字段名立刻就能看到前后端同步报红的类型检查效果这是理解 tRPC 最快的方式。下一步从最小示例走向真实项目完成最小示例后可以按你的技术栈选择进阶路径方向推荐入口说明React 前端packages/tanstack-react-query/官方推荐的 TanStack React Query 集成Next.js 全栈examples/next-minimal-starter/单端点 页面的极简 Next.js 示例服务端适配器packages/server/src/adapters/Express、Fastify、Lambda、Edge 等完整示例集examples/30 个覆盖主流场景的示例应用更详细的分步讲解可阅读官方快速入门文档 www/docs/main/quickstart.mdx。小结‍♂️ tRPC 让你用纯 TypeScript 构建类型安全 API无 schema、无代码生成 只需安装trpc/servertrpc/client两个核心包 四步走通初始化 → 定义 query/mutation → 启动服务 → 客户端类型安全调用 客户端通过import type AppRouter获得全量自动补全与编译期检查10 分钟你的第一个类型安全 API 已经上线。Move fast and break nothing ‍♀️【免费下载链接】trpc‍♀️ Move Fast and Break Nothing. End-to-end typesafe APIs made easy.项目地址: https://gitcode.com/GitHub_Trending/tr/trpc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考