使用 tRPC 构建全栈类型安全的 API #

解决前后端类型脱节痛点：通过 tRPC 实现端到端类型安全，让服务器端的 API 定义直接转化为客户端的类型提示，消除 REST 或 GraphQL 中繁琐的 Schema 维护与代码生成步骤。

为什么需要这个技能 #

在传统的 API 开发中，前后端通信依赖于文档或手动同步的类型定义。即使使用了 TypeScript，客户端在调用接口时仍然需要手动定义 Response 类型，一旦后端字段变更，客户端往往在运行时才会发现崩溃。

tRPC 改变了这一模式。它允许 TypeScript 类型从服务器路由直接流向客户端。这意味着你的每一个 API 调用都拥有完整的自动补全，且在编译时就能验证输入输出的正确性。如果后端修改了字段，前端代码会立即报编译错误，极大地提升了重构效率和开发速度。

适用场景 #

• 使用 TypeScript 构建的全栈应用（如 Next.js, Remix, Express + React）。
• 前后端共用同一个代码仓库（Monorepo）的项目。
• 需要快速迭代且要求极高类型安全性，且不想维护 REST/GraphQL Schema 的场景。
• 需要在 API 层实现复杂的中间件逻辑（如鉴权、限流、租户隔离）。
• 需要集成实时数据流（Subscriptions）的功能。

核心工作流 #

1. 初始化与基础配置：安装 @trpc/server 和 @trpc/client，创建 tRPC 实例并定义全局错误格式化器。
2. 构建上下文（Context）：定义 createTRPCContext。针对 Next.js App Router，需区分 HTTP 请求上下文和纯服务端调用上下文（Server Components）。
3. 实现中间件与权限控制：通过 t.middleware 构建鉴权逻辑，并创建 protectedProcedure 用于保护私有接口。
4. 定义路由与验证：使用 Zod 定义输入 Schema，通过 query（读）和 mutation（写）构建业务逻辑路由。
5. 导出类型并挂载：仅在服务器端导出 AppRouter 类型，在客户端通过 createTRPCReact 注入该类型，实现零 API 描述文件的类型同步。
6. 前端调用与状态管理：结合 TanStack Query（React Query）使用 useQuery 和 useMutation 并在成功后通过 utils.invalidate() 刷新缓存。

下载和安装 #

下载 trpc-fullstack 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要 #

暂无推荐