凌晨两点的接口联调室

"接口返回的user对象里怎么没有nickname字段？"前端同事的消息弹出来时，我正在改第三版接口文档。屏幕上的Swagger页面还停留在两小时前的版本，而后端代码里，这个字段已经被我删掉重命名为username。会议室里，测试同学翻着接口测试用例，第17条还标着"待确认"——上周改的分页参数格式，文档忘了同步。

这是我们团队用RESTful API开发时的常态：后端改接口、前端踩坑、测试质疑，三方可怜的下班时间都耗在"接口文档→代码实现→联调反馈"的恶性循环里。直到三个月前，我们用tRPC重构了所有接口，世界突然安静了——现在后端改完接口，前端IDE立刻报错；类型不匹配的问题在编译时就能发现；那个被我们吐槽了无数次的"接口文档群"，已经半个月没人说话了。

从"猜接口"到"类型共享"：tRPC如何撕裂全栈次元壁

传统RESTful API的开发链路像一场"信息接力赛"：后端定义接口（如GET /api/users/:id），然后写文档（说明返回{id: string, name: string}），前端根据文档写请求代码（axios.get<User>('/api/users/1')），最后在运行时才发现"哦？原来后端把name改成了username"。

tRPC用TypeScript的类型系统把这场接力赛变成了"实时同步"。它的核心逻辑很简单：前后端共享一份类型定义文件，后端定义接口时声明输入输出类型，前端调用时直接继承这些类型，TypeScript编译器会自动检查所有调用是否匹配。

tRPC与RESTful API架构对比图

（左侧为tRPC架构：服务端定义getUser接口时声明输入为string、输出为{id: string, name: string}，类型通过AppRouter自动同步到客户端；右侧为REST架构：服务端需手动维护Swagger文档，客户端通过any类型接收数据，类型错误只能在运行时发现）

比如在我们的用户服务里，后端用tRPC定义接口只需三行代码：

// typescript
// 服务端 router.ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
const t = initTRPC.create();
export const appRouter = t.router({
getUser: t.procedure
.input(z.string()) // 输入必须是字符串
.query(({ input }) => ({
id: input,
name: 'Alice' // 输出固定包含id和name
})),
});
export type AppRouter = typeof appRouter; // 导出类型供前端使用

前端调用时，直接导入AppRouter类型，TypeScript会自动提示接口名称、参数格式和返回字段：

// typescript
// 客户端 api.ts
import { createTRPCProxyClient } from '@trpc/client';
import type { AppRouter } from './server/router';
const client = createTRPCProxyClient<AppRouter>({ url: '/api/trpc' });
//  输入不是字符串会报错，返回没有name字段也会报错
const user = await client.getUser.query('123');
console.log(user.name); // 自动提示：name是string类型

这种"类型即文档"的模式，让我们彻底告别了接口文档——后端改接口时，只要修改input或返回值类型，前端IDE立刻标红错误位置，连"文档同步"这个步骤都消失了。

从"三天联调"到"分钟级适配"：我们的tRPC迁移实战

去年底重构用户中心服务时，我们第一次尝试tRPC。这个服务有12个接口，涉及用户登录、信息修改、权限校验等，之前用REST开发时，光接口文档就写了5页，联调时还因为"性别字段后端返回number（1/2）、前端期待string（'男'/'女'）"吵了一下午。

迁移第一步：定义共享类型

我们把所有接口的输入输出类型用Zod校验库定义（tRPC支持Zod/Yup等），比如用户登录接口：

// typescript
// 服务端 procedures/auth.ts
export const authProcedure = t.procedure
.input(z.object({
username: z.string().min(3),
password: z.string().min(6),
// 新增验证码字段时，前端调用处会自动提示缺少参数
captcha: z.string().length(4)
}))
.mutation(async ({ input }) => {
// 业务逻辑...
return { token: 'xxx', user: { id: '1', name: 'Alice' } };
});

迁移第二步：处理非JSON数据

之前用REST上传头像时，后端要单独写FormData解析逻辑，前端要手动设置Content-Type。tRPC v11支持非JSON内容类型后，直接定义二进制输入：

// typescript
// 服务端 procedures/upload.ts
import { octetInputParser } from '@trpc/server/http';
export const uploadAvatar = t.procedure
.input(octetInputParser) // 接收二进制流
.mutation(async ({ input }) => {
const file = await input.arrayBuffer(); // 直接处理文件
// 上传逻辑...
});

迁移效果：

o 接口适配时间：从平均3天缩短到20分钟（改完后端类型，前端自动适配）

o 联调bug数：从12个/服务降到2个/服务（全是业务逻辑错误，无类型问题）

o 文档维护时间：从每周4小时降到0（类型定义即文档，IDE自动提示）

性能碾压REST？实测数据告诉你真相

我们在4核8G云服务器上做了压测：用相同的业务逻辑（查询用户列表，返回10条数据），分别跑tRPC（Express适配器）和REST（Express），结果如下：

（数据来源：基于plow工具的30秒单核压测，业务逻辑为查询数据库返回用户列表）

腾讯文档团队的案例更夸张：他们用tRPC重构推荐系统后，服务监控接入时间从3天缩短到2小时，流量控制规则更新从小时级降到秒级，双十一期间靠tRPC的过载保护插件扛住了3倍峰值流量。

不是银弹，但这3类项目一定要试试tRPC

经过半年实践，我们发现tRPC不是所有场景都适用，但这几类项目用它简直如虎添翼：

1. TypeScript全栈项目

前后端都用TS时，tRPC的类型共享优势发挥到极致。我们的管理后台用Next.js+Node.js开发，现在新增接口只需写服务端逻辑，前端直接调用，连"复制接口URL"的时间都省了。

2. 实时交互应用

tRPC支持WebSocket，配合TanStack Query v5的Suspense功能，实现实时数据更新很简单。比如我们的IM模块，用tRPC的subscription接口推送消息，延迟比REST+ polling降低60%。

3. 微服务内部通信

之前微服务间调用靠REST，每次都要查文档、转JSON。现在用tRPC，服务A定义接口，服务B直接调用，类型不匹配在编译时就拦截，跨服务联调效率提升70%。

写在最后：当"接口文档"从开发流程中消失

上个月团队复盘时，产品经理突然问："最近怎么没见你们吵接口文档了？"我们才意识到，tRPC不仅是个技术工具，更重构了我们的协作方式——后端不再是"接口提供者"，而是"函数编写者"，前端不再是"接口调用者"，而是"函数使用者"，就像在同一个项目里写代码。

现在GitHub上tRPC已经有35k+星标，700k+周下载量，322家公司在用（包括Jobot Consulting、Orbit等）。如果你受够了接口文档的折磨，不妨试试tRPC——可能你会发现，开发原来可以这么顺畅。