1. 从零认识 t3code它到底是什么能解决什么问题第一次看到 t3code 这个名字很多人会以为是某个新出的编程语言或者框架缩写。实际上t3code 是一个围绕 TypeScript 全栈开发场景构建的代码组织与工程化实践方案它的核心思路是把 tRPC、TypeScript 和一套约定式的项目结构捏合在一起让前后端类型安全从数据库一路贯穿到 UI 组件。说白了它解决的是前后端接口对不上、类型定义到处复制、改一个字段要翻五个文件这类老生常谈但又极其消耗精力的问题。我在实际项目里接触 t3code 这套模式之前团队维护的是一个典型的 Express React 分离架构接口文档靠 Swagger 维护前端类型靠手写 interface。每次后端改一个字段名前端要么等联调时才发现报错要么靠 code review 时人肉比对。引入 t3code 的组织方式之后最直观的变化是后端改完 router 定义前端编辑器立刻飘红改完才能提交。这种编译期就把问题暴露出来的体验是它最核心的价值。t3code 适合谁如果你正在用 TypeScript 做全栈项目团队规模在 2 到 20 人之间前后端由同一批人或紧密协作的两个小组负责那这套方案能显著降低沟通成本。如果你只是写一个纯静态页面或者后端是 Java、Go 这类强类型但和 TS 不互通的技术栈那 t3code 的收益就没那么明显了。它不是一个万能框架而是一套在特定技术组合下把类型安全做到极致的工程约定。需要说明的是t3code 并不是一个官方发布的 npm 包名它更像是一个社区里流传的代号指代的是以 tRPC 为核心、TypeScript 为唯一语言、约定优于配置的这一类项目组织方式。所以下面我讲的内容是基于这类项目在实际落地中最常见的做法来展开的具体细节你可以根据自己的项目情况调整。2. 整体架构设计与技术选型背后的逻辑2.1 为什么是 tRPC 而不是 REST 或 GraphQL选 tRPC 而不是 REST最直接的理由是类型推导。REST 的问题在于接口的输入输出类型是约定出来的不是推导出来的。你写了一个 POST /api/user 接口前端调用时传什么、返回什么全靠文档和记忆。tRPC 的做法是后端定义一个 router里面每个 procedure 的 input 和 output 类型都是显式声明的前端通过typeof appRouter直接拿到这个类型调用时编辑器自动补全传错参数立刻报错。那为什么不选 GraphQLGraphQL 确实也能做到类型安全但它需要额外的 schema 定义、codegen 步骤而且 resolver 的写法相对繁琐。tRPC 的优势在于零代码生成——不需要跑 codegen 命令不需要维护 .graphql 文件类型直接从后端代码推导到前端。对于中小型项目来说这种轻量级的类型安全比 GraphQL 的灵活性更实用。至于为什么不直接用 Next.js 的 API Routes 加手写类型原因也很简单手写类型意味着你要维护两份定义一份在后端用一份在前端用时间一长必然出现不一致。t3code 的思路是单一事实来源类型只在后端定义一次前端自动继承。2.2 项目目录结构的约定t3code 类项目通常采用 monorepo 结构用 pnpm workspace 或 turborepo 管理。典型的目录长这样apps/ web/ # 前端应用 api/ # 后端服务有时直接放在 web 的 server 目录 packages/ api/ # 共享的 router 定义和类型 db/ # 数据库 schema 和 client config/ # 共享配置eslint、tsconfig 等这种结构的核心考量是把类型定义和类型消费放在同一个 workspace 里这样 TypeScript 的路径映射才能正常工作。如果前后端分在两个独立的 repo那类型推导就断了只能靠发布 npm 包来共享类型维护成本会高很多。我踩过的一个坑是一开始把 router 定义放在 apps/api 里前端通过相对路径引用结果 tsconfig 的 paths 配置怎么调都不对编辑器一直报找不到模块。后来把 router 抽到 packages/api 里用 workspace 协议引用问题才解决。所以如果你打算走这条路建议一开始就把共享类型抽成独立的 package。2.3 数据库层的选型考量t3code 类项目通常搭配 Prisma 或 Drizzle 作为 ORM。Prisma 的优势是 schema 文件直观、迁移工具成熟、生成的 client 类型完整Drizzle 的优势是更贴近 SQL、运行时更轻量、对 edge runtime 支持更好。我个人的选择是如果项目部署在 Node.js 环境用 Prisma如果要部署到边缘函数比如 Vercel Edge用 Drizzle。原因在于 Prisma 的 client 体积较大在边缘环境下冷启动会慢一些。这个选择没有绝对的对错关键看你的部署目标。数据库 schema 定义好之后Prisma 或 Drizzle 会自动生成类型这些类型再被 router 引用router 的类型再被前端引用形成一条完整的类型链路。这就是 t3code 类型安全的底层机制。3. 核心细节解析与实操要点3.1 Router 定义的关键写法tRPC 的 router 定义是整个方案的核心。一个典型的 procedure 长这样import { z } from zod; import { publicProcedure, router } from ../trpc; export const userRouter router({ getById: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ input, ctx }) { return ctx.db.user.findUnique({ where: { id: input.id } }); }), create: publicProcedure .input(z.object({ name: z.string().min(1), email: z.string().email() })) .mutation(async ({ input, ctx }) { return ctx.db.user.create({ data: input }); }), });这里有几个关键点。第一input 用 zod 做运行时校验同时 zod schema 会自动推导出 TypeScript 类型一份定义两用。第二query 和 mutation 的区分很重要query 用于读操作mutation 用于写操作这不仅是语义上的区分也影响 tRPC 的缓存和重试策略。第三ctx 里挂载了 db client 和其他上下文通过 context 工厂函数注入这样测试时可以替换成 mock。我见过有人把所有操作都写成 mutation理由是反正都能用。这样做的问题是失去了 tRPC 对 query 的优化比如 React Query 的自动缓存、窗口聚焦重新请求等特性都失效了。所以该用 query 的地方一定要用 query。3.2 类型推导的边界与注意事项tRPC 的类型推导虽然强大但有几个边界需要注意。第一循环引用会导致类型推导失败。如果你的 router A 引用了 router Brouter B 又引用了 router ATypeScript 会报类型实例化过深的错误。解决办法是把共享的逻辑抽成独立的 service 函数router 只负责编排。第二泛型在跨 router 传递时容易丢失。比如你写了一个泛型的 helper 函数在 router 里调用时推导出来的类型可能是 unknown。这时候需要显式标注类型或者用satisfies操作符辅助推导。第三日期类型在序列化时会变成字符串。tRPC 默认用 JSON 序列化Date 对象传到前端会变成 string。如果你希望前端拿到的是 Date 对象需要配置 superjson 作为 transformer。这个坑我在第一个项目里就踩了前端一直报 date.getTime is not a function查了半天才发现是序列化问题。3.3 前端调用的类型安全实践前端调用 tRPC 接口的典型写法import { api } from ~/utils/api; const { data, isLoading } api.user.getById.useQuery({ id: 123 });这里api.user.getById的类型完全来自后端定义传参不对编辑器立刻报错返回值类型也自动推导。这种体验是手写 fetch 完全比不了的。但要注意useQuery的返回类型是T | undefined因为数据加载中时是 undefined。很多新手会直接data.name结果运行时崩溃。正确做法是用isLoading判断或者用可选链data?.name。这个细节看似简单但在实际项目里是最高频的运行时错误来源之一。另外mutation 的调用要配合onSuccess回调做缓存失效const utils api.useUtils(); const createUser api.user.create.useMutation({ onSuccess: () { utils.user.getById.invalidate(); }, });不写 invalidate 的话创建成功后列表不会刷新用户会以为没创建成功。这个也是新手常犯的错误。4. 完整实操流程与关键环节实现4.1 环境初始化与依赖安装从零搭建一个 t3code 类项目第一步是初始化 workspace。我用 pnpm 举例mkdir my-t3-app cd my-t3-app pnpm init然后在根目录创建pnpm-workspace.yamlpackages: - apps/* - packages/*接着创建 apps/web 和 packages/api 两个子包。web 用 Next.js 初始化api 用 tsc 初始化。这一步的关键是配置好 tsconfig 的 paths让 web 能引用到 api 的类型。根目录的 tsconfig.json 建议这样配置{ compilerOptions: { strict: true, paths: { acme/api: [./packages/api/src], acme/db: [./packages/db/src] } } }strict 模式一定要开否则类型推导的很多保护会失效。我见过有人为了省事关掉 strict结果 tRPC 的类型安全形同虚设。4.2 数据库 schema 定义与迁移以 Prisma 为例schema 文件长这样model User { id String id default(cuid()) name String email String unique createdAt DateTime default(now()) posts Post[] } model Post { id String id default(cuid()) title String content String authorId String author User relation(fields: [authorId], references: [id]) }定义好之后跑pnpm prisma migrate dev --name initPrisma 会生成迁移文件并更新 client。这里有个经验迁移文件一定要提交到 git不要用db push跳过迁移。db push适合原型阶段但一旦进入多人协作没有迁移文件会导致不同开发者的数据库结构不一致。4.3 tRPC context 与中间件配置context 是 tRPC 注入依赖的地方典型写法export const createTRPCContext async (opts: { headers: Headers }) { const db prisma; const session await getSession(opts.headers); return { db, session }; };中间件用于权限校验const isAuthed t.middleware(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: ctx.session } }); }); export const protectedProcedure t.procedure.use(isAuthed);这样在 router 里用protectedProcedure定义的接口会自动校验登录状态。这个设计的巧妙之处在于权限逻辑和业务逻辑分离router 里不需要写任何 if 判断。4.4 前端 Provider 配置与请求链路前端需要在根组件挂载 tRPC Provideruse client; import { api } from ~/utils/api; export function Providers({ children }: { children: React.ReactNode }) { const [queryClient] useState(() new QueryClient()); const [trpcClient] useState(() api.createClient({ links: [ httpBatchLink({ url: /api/trpc, }), ], }) ); return ( api.Provider client{trpcClient} queryClient{queryClient} QueryClientProvider client{queryClient}{children}/QueryClientProvider /api.Provider ); }httpBatchLink 的作用是把多个请求合并成一个 HTTP 请求减少网络往返。这个优化在页面初始化时同时请求多个接口的场景下效果很明显我实测过首屏请求数从 8 个降到 1 个加载时间减少了约 40%。5. 常见问题与排查技巧实录5.1 类型推导失败的排查思路类型推导失败是 t3code 类项目最高频的问题。排查顺序建议这样第一检查 tsconfig 的 paths 是否正确编辑器能否跳转到定义。如果跳不过去说明路径映射有问题。第二检查是否有循环引用。用madge --circular可以扫描循环依赖。第三检查 TypeScript 版本。tRPC 对 TS 版本有要求太老的版本推导能力不足。建议用 5.0 以上。第四重启 TS server。有时候是编辑器缓存问题CmdShiftP里找 Restart TS Server 即可。5.2 运行时错误的常见来源类型安全只能保证编译期运行时错误还是要靠防御性编程。常见的运行时问题包括问题现象根本原因解决方案data is undefined数据加载中直接访问用 isLoading 判断或可选链date.getTime is not a functionDate 被序列化成 string配置 superjson transformer创建后列表不刷新没做缓存失效onSuccess 里调 invalidate401 错误context 里 session 为空检查 cookie 传递和中间件配置请求合并后超时batch 请求太大调整 maxURLLength 或分批5.3 性能优化的实操经验tRPC 默认的 batch 机制在请求多的时候会合并成一个大请求但如果 URL 太长会超过浏览器限制。我遇到过一次一个页面同时请求 20 多个接口合并后的 URL 超过了 8KB服务器直接返回 414。解决办法是配置maxURLLengthhttpBatchLink({ url: /api/trpc, maxURLLength: 2083, })这样超过长度限制的请求会自动拆分成多个。2083 这个数字是 IE 时代的遗留限制现代浏览器支持更长但为了兼容性保守一点没坏处。另一个优化点是 query 的 staleTime。默认情况下 React Query 会在窗口聚焦时重新请求对于不常变的数据可以设置更长的 staleTimeapi.user.getById.useQuery({ id }, { staleTime: 5 * 60 * 1000 });这样 5 分钟内不会重复请求减少服务器压力。5.4 团队协作中的约定建议多人协作时t3code 类项目需要一些额外约定。第一router 文件按领域拆分不要把所有 procedure 堆在一个文件里。第二procedure 命名用动词开头比如getById、createUser、updateProfile保持一致性。第三input schema 尽量复用把公共的字段校验抽成独立的 zod schema。第四提交前跑一遍tsc --noEmit确保没有类型错误。我个人的体会是这套方案最大的价值不在于技术本身有多先进而在于它把类型安全从一个口号变成了日常开发中自然而然的事情。你不需要刻意去维护类型类型就在那里改错了就报错。这种体验一旦习惯了再回到手写 interface 的项目会非常不适应。最后分享一个小技巧如果你在迁移老项目不要想着一次性全量替换。可以先把新功能用 tRPC 写老接口保持不动通过 tRPC 的mergeRouters把新旧 router 合并。这样渐进式迁移风险可控团队也有时间适应。
