tRPC for TypeScript: 完整指南与示例

什么是 tRPC 以及为什么需要它？

tRPC (TypeScript Remote Procedure Call) 是一个现代库，用于在客户端和服务器之间创建类型安全的 API。tRPC 的主要特点是它不需要代码生成或类型重复。您只需在服务器上编写函数，客户端即可通过完整的 TypeScript 支持（自动补全、类型检查和 IntelliSense）访问这些函数。

与 REST 或 GraphQL 不同，您需要手动描述模式、端点和类型，而 tRPC 会自动从您的服务器代码中推断类型。这极大地简化了开发并减少了错误数量。

tRPC 的主要优势：

• 完全类型安全 — 类型错误在编译阶段而非运行时被发现
• 无需代码生成 — 无需运行生成器或同步模式
• 最少的样板代码 — 比 REST 或 GraphQL 代码更少
• 自动文档 — 类型即文档
• 简单性 — 像普通函数调用一样工作

tRPC 非常适合基于 TypeScript 的全栈应用（Next.js、Remix、Express、Fastify）以及微服务架构。

安装 tRPC

tRPC 由多个包组成。对于基本使用，您需要：

# 安装服务器和客户端部分npm install @trpc/server @trpc/client

# 安装 React 适配器（如果您使用 React）npm install @trpc/react-query @tanstack/react-query

# 安装 Next.js 适配器npm install @trpc/next @trpc/react-query @tanstack/react-query

# 安装 Zod 用于验证（推荐）npm install zod

如果您使用 yarn 或 pnpm：

yarn add @trpc/server @trpc/clientpnpm add @trpc/server @trpc/client

对于 Python 开发者（如果您在后端使用 Python）：tRPC 是一个 TypeScript 库，但您可以通过 trpc-py（实验性封装）在 Python 中使用它。然而，主要生态系统是 TypeScript。

快速入门与代码示例

让我们创建一个简单的应用：一个包含用户操作过程的服务器和一个调用这些过程的客户端。

1. 服务器 (server.ts)

import { initTRPC } from '@trpc/server';import { z } from 'zod';

// 创建 tRPC 实例const t = initTRPC.create();

// 定义用户类型interface User {  id: number;  name: string;  email: string;}

// 模拟数据库const users: User[] = [  { id: 1, name: 'Alice', email: 'alice@example.com' },  { id: 2, name: 'Bob', email: 'bob@example.com' },];

// 创建包含过程的路由器const appRouter = t.router({  // 获取所有用户的过程  getUsers: t.procedure    .query(() => {      return users;    }),

  // 根据 ID 获取用户的过程  getUserById: t.procedure    .input(z.number())    .query(({ input }) => {      return users.find(user => user.id === input) || null;    }),

  // 创建用户的过程  createUser: t.procedure    .input(z.object({      name: z.string().min(1),      email: z.string().email(),    }))    .mutation(({ input }) => {      const newUser: User = {        id: users.length + 1,        name: input.name,        email: input.email,      };      users.push(newUser);      return newUser;    }),});

// 导出路由器类型供客户端使用export type AppRouter = typeof appRouter;

2. 客户端 (client.ts)

import { createTRPCClient, httpBatchLink } from '@trpc/client';import type { AppRouter } from './server';

// 创建客户端const client