前阵子我把一个半死不活的后台管理系统推翻重写新的代码仓库代号就起了个t3code。说起来挺没新意——直接用了 T3 技术栈的首字母加 code 拼出来的但它确实不是一个花架子而是实实在在帮我解决了项目里类型不统一、接口联调扯皮、样式越写越乱的问题。如果你也在纠结全栈项目从哪下手或者听说了 T3 Stack 但不知道具体怎么组织代码这篇文章应该能让你的弯路少走一些。1. t3code 立项动机为什么我需要一套前后端统一的技术方案1.1 旧项目的三个“老大难”在动工t3code之前我之前维护的项目是典型的前后端分离架构后端 Java Spring Boot前端 Vue 2。说实话这种架构在公司里非常常见但时间一长问题就会浮出水面。第一个大问题是类型不同步。后端接口文档用 Swagger 维护前端再手工写一套api/types.ts。后端字段从userId改成user_id文档可能没更新前端代码却先崩了。开发高峰期几乎每周都要因为字段对不上而在群里扯皮效率很低。第二个问题是接口联调成本高。每加一个页面前端要先写接口定义、再写状态管理、再写类型声明然后等后端联调。中间任何一个环节出错排查链路都很长。第三个问题是项目配置散乱。环境变量散落在各个文件里没有类型校验团队成员随手复制粘贴生产环境偶发缺配置的问题。这三个问题放在一起让我特别渴望一套从数据库到页面端到端类型安全的方案。于是在启动新项目时我花了半天时间对比了 Remix、NestJS 全栈方案和 Next.js 系的全栈整合最后敲定了基于 T3 Stack 搭建t3code。1.2 为什么是 T3 Stack 而不是其他组合T3 Stack 这个名字最早来自 t3.gg 社区核心是 TypeScript、Next.js、Tailwind CSS、tRPC按需加入 Prisma、NextAuth.js。我选择它不是因为“网红项目”光环而是因为它恰好击中了旧项目里我最痛的地方TypeScript 全链路类型从 Prisma Schema 自动生成再到 tRPC 路由的输入输出最后到 React Query 的返回数据全程类型穿透不需要手写中间 DTO。tRPC 解决联调问题前后端共享同一个 API 层路由调用像本地函数一样不需要重复定义接口和请求函数。Tailwind 的样式约束原子化类名天然避免样式文件失控尤其适合我这种不想花太多时间在 CSS 命名上的开发者。当然T3 Stack 不是银弹它更适合中小型项目、内部工具、创业原型。但t3code的目标刚好是这种规模所以选它非常贴切。1.3 目录结构从第一天就规划好边界t3code初始化之后我没有直接开写而是先规划了目录边界。这是整个项目里最值得的东西。我用的是 create-t3-app 的标准结构然后做了一些定制t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ # Next.js App Router │ ├── components/ # 通用 UI 组件 │ ├── server/ # 服务端代码 │ │ ├── api/ # tRPC Router 定义 │ │ ├── auth/ # NextAuth 配置 │ │ ├── db.ts # Prisma Client 单例 │ │ └── trpc.ts # tRPC router 创建逻辑 │ ├── styles/ # 全局样式 │ ├── types/ # 少量手工类型补充 │ └── utils/ # 工具函数 └── .env这里最重要的原则是UI 组件里不允许直接出现prisma相关的调用所有数据请求都走 tRPC Router。这样后端换了、数据库换了前端页面基本不用动。很多项目做到后面代码乱根源就是目录边界从一开始就没守住。2. 初始化与工程配置t3code 的第一步2.1 用 create-t3-app 一键初始化初始化t3code非常简单。我推荐用 pnpm因为 pnpm 对 Next.js 项目依赖安装速度快磁盘占用也小pnpm create t3-applatest t3code命令执行后交互式选择项里我勾选了 Next.js、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth.js。如果你的项目不需要鉴权NextAuth 可以不勾但t3code是做后台管理鉴权是刚需。初始化完成后目录里会看到一个整洁的模板内置了drizzle或prisma的示例环境变量也预留好了。这个脚手架的好处是它把 tRPC 和 Next.js 的胶水代码都生成好了你不用自己去拼接trpc客户端和服务端省掉了最容易出错的环节。2.2 环境变量的类型校验别让 String(undefined) 坑你t3code里所有环境变量都是通过env.mjs里的zod校验的。这一点我非常喜欢。我以前见过太多项目在运行时才暴露环境变量缺失的问题——明明数据库密码没配上却等到第一笔写入才报错。create-t3-app生成的文件长这样import { createEnv } from t3-oss/env-nextjs; import { z } from zod; export const env createEnv({ server: { DATABASE_URL: z.string().url(), NEXTAUTH_SECRET: z.string().min(1), NEXTAUTH_URL: z.string().url(), }, client: { NEXT_PUBLIC_APP_NAME: z.string().min(1), }, runtimeEnv: { DATABASE_URL: process.env.DATABASE_URL, NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET, NEXTAUTH_URL: process.env.NEXTAUTH_URL, NEXT_PUBLIC_APP_NAME: process.env.NEXT_PUBLIC_APP_NAME, }, });这段代码的价值在于一旦.env里缺少字段应用启动阶段就会立刻抛出明确的错误而不是等运行到某个业务逻辑时才变成undefined。在实际使用中我还加了一个.env.example文件团队成员 clone 项目后照着复制一份就能跑起来。提示不要把.env提交到 Git但一定要提交.env.example。这个习惯在t3code的协作过程中帮我们省了很多“环境问题”。2.3 路径别名与严格 TypeScript 配置create-t3-app默认开启了strict模式这很好但还不够。我在 tsconfig.json 里额外开启了noUncheckedIndexedAccess因为这个选项可以强制检查数组和索引访问可能返回undefined的情况能避免开发时漏掉边界判断。同时我把路径别名统一成/*{ compilerOptions: { strict: true, noUncheckedIndexedAccess: true, baseUrl: ., paths: { /*: [./src/*] } } }别小看路径别名。没有统一的别名组件里全是../../../utils/formatDate重构时移动一个文件整个依赖链里的相对路径全得改。统一别名后代码的可读性和可维护性都提升了一个档次。3. 数据库模型与 tRPC Router后端逻辑这样写不会乱3.1 用 Prisma 定义核心数据模型t3code的数据模型很简单但很典型用户、文章、评论。这三张表基本覆盖了大多数业务场景的基础关系。prisma/schema.prisma里我这样定义generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model User { id String id default(cuid()) name String? email String unique createdAt DateTime default(now()) posts Post[] comments Comment[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) comments Comment[] createdAt DateTime default(now()) } model Comment { id String id default(cuid()) content String postId String post Post relation(fields: [postId], references: [id]) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) }这里有一个小经验主键全部用cuid()而不是自增整数。理由是cuid在分布式或未来数据迁移时不容易冲突而且不会暴露业务规模。虽然查询效率略低于 int但在t3code这种规模下完全感知不到差别。定义好模型后执行pnpm prisma migrate dev --name init pnpm prisma generatePrisma 会生成类型安全的 Client后面在 tRPC Router 里调用时返回的数据结构天然带类型。3.2 tRPC Router 按业务域拆分而不是按文件类型很多人用 tRPC 会把所有路由写到一个大文件里这样在线业务少时还好一旦模块多了就乱。t3code里我采用按业务域拆分的方式每个业务域一个 Router最后统一合并。src/server/api/routers/post.ts示例import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .query(({ ctx }) { return ctx.db.post.findMany({ include: { author: true }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1), })) .mutation(({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });protectedProcedure是我在trpc.ts里定义的一个受保护过程用于校验用户是否登录。业务代码里不用重复写 session 判断权限逻辑集中在中间件里维护成本很低。合并路由的代码import { createTRPCRouter } from ../trpc; import { postRouter } from ./post; import { commentRouter } from ./comment; import { userRouter } from ./user; export const appRouter createTRPCRouter({ post: postRouter, comment: commentRouter, user: userRouter, }); export type AppRouter typeof appRouter;这样前端调用api.post.list.useQuery()类型自然就是Post[]连loading、error状态都一并返回不用自己封装请求层。3.3 中间件与权限校验把鉴权逻辑收敛到一处权限校验是后台系统绕不开的事。t3code里我在src/server/api/trpc.ts定义了两个核心 procedureexport const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session || !ctx.session.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });刚开始我会觉得这种写法脱裤子放屁反正每个接口不都查一下登录状态吗但后来发现把权限收敛到中间件里比如后面要要改成“管理员可操作”或“普通用户仅读”直接改中间件判定即可业务 Router 完全不受影响。这就是 tRPC 的中间件模式比在每个 mutation 里写一堆 if else 干净得多。4. 前端数据流从 React Query 到页面渲染4.1 createT3SSR让首屏数据不闪烁t3code用的是 Next.js App Router但数据请求依然通过 tRPC React Query 来处理。为了首屏渲染时能拿到数据而不是先看到 loadingcreate-t3-app默认提供的createT3SSRHelpers很管用。一个列表页的完整示例// app/posts/page.tsx import { api } from ~/utils/api; import { createTRPCContext } from ~/server/api/trpc; import { createServerSideHelpers } from trpc/react-query/server; import { appRouter } from ~/server/api/root; import SuperJSON from superjson; export default async function PostsPage() { const helpers createServerSideHelpers({ router: appRouter, ctx: await createTRPCContext(), transformer: SuperJSON, }); await helpers.post.list.prefetch(); return PostList /; }而在PostList客户端组件里直接api.post.list.useQuery()读取缓存即可。React Query 会自动用服务端预取的数据填充不会闪 loading。这种“服务端预取 客户端渲染”的模式让t3code的页面既对 SEO 友好又保持了客户端交互的流畅度。4.2 mutation 后如何让缓存自动刷新最容易踩的坑是新增数据后列表不刷新必须手动刷新页面。t3code里我用 tRPC 的utils来让相关查询失效const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, });这段代码的意思是当post.create成功之后自动让post.list的缓存失效并重新拉取数据。比手动setQueryData更新缓存更简单且更可靠。有人说invalidate会多一次请求但在内部系统里一次列表查询成本很低换来的是数据一致性完全值得。4.3 服务端状态与客户端状态的边界在t3code开发过程中我给自己定了一个规则凡是来自数据库的状态一律交给 React Query凡是表单输入状态一律交给 react-hook-form全局 UI 状态才用 zustand。一开始大家会忍不住把所有状态放 useState比如当前选中的 tab、筛选条件、列表数据……结果组件一多状态同步很容易乱。后来我强制规定只有组件内部自己消费、不共享的 UI 状态才允许用 useState。其余要么走 URL 参数要么走 React Query。这个规则看着简单实际执行下来代码 review 时轻松了很多。5. Tailwind 样式体系在 t3code 里长得好看的实用方案5.1 原子类的复用与组件抽象Tailwind 用久了最烦的不是写 class而是同一个按钮要复制 8 遍同样的 class。t3code里的解法是用cn()工具加上基础组件封装。例如components/ui/button.tsximport { cn } from ~/utils/cn; type ButtonProps React.ButtonHTMLAttributesHTMLButtonElement { variant?: primary | ghost | danger; }; export function Button({ variant primary, className, ...props }: ButtonProps) { const variants { primary: bg-blue-600 text-white hover:bg-blue-700, ghost: bg-transparent text-gray-600 hover:bg-gray-100, danger: bg-red-600 text-white hover:bg-red-700, }; return button className{cn(rounded-lg px-4 py-2 transition, variants[variant], className)} {...props} /; }cn可以是简单的手写函数也可以直接用clsxtailwind-merge处理 class 覆盖问题。有了这层封装业务代码里的按钮样式就统一了后面想换主题色只需要改这一个文件的 class。5.2 主题定制与深色模式t3code默认是浅色主题但我们后台需要支持深色模式。Tailwind 配置里我用darkMode: class而不是media这样可以让用户手动切换。切换方案很简单给html元素加darkclass然后用 Next.js 的next-themes管理状态。在tailwind.config.ts中定制品牌色import type { Config } from tailwindcss; export default { darkMode: class, content: [./src/**/*.{ts,tsx}], theme: { extend: { colors: { brand: { 500: #4F46E5, 600: #4338CA, }, }, }, }, } satisfies Config;这样你就可以在组件里使用bg-brand-600 text-white而不是纠结是蓝还是紫。自定义品牌色在团队协作中特别有意义它让设计语言有了名称而不是“那个按钮蓝”。5.3 响应式布局踩过的坑Tailwind 的响应式断点是移动优先默认是先写移动端样式再写sm:、md:、lg:覆盖。我在t3code里做侧边栏时踩了一个坑只写了md:flex没写基础的flex导致移动端样式和桌面端样式错乱。实际上一个安全的写法是div classNameflex flex-col md:flex-row aside classNamew-full md:w-64菜单/aside main classNameflex-1内容/main /div如果希望侧边栏在移动端默认收起则可以用hidden md:flex。响应式不复杂但需要养成“移动优先”的习惯否则你会花很多时间去覆盖样式。6. 部署上线与后续迭代6.1 构建与部署方案对比t3code的部署方案我试过两种Vercel 和一台 2C4G 的云服务器。如果你的团队懒省事直接选 Vercel。它和 Next.js 的集成非常顺滑连接 Git 仓库后自动构建环境变量填好就行。t3code早期我就在 Vercel 上跑一条命令部署特别适合快速验证业务。后来因为客户要求数据必须存储在国内服务器我改成了自建服务器 PM2 Docker。自建服务器需要自己处理 Prisma 的迁移、Node 版本管理、进程守护等问题复杂度高了不少。如果团队没有运维经验不建议一上来就自建。部署前务必执行一次生产构建:pnpm build如果项目里有 tRPC、Prisma 的编译问题这一步会暴露出来。create-t3-app默认的构建脚本会先执行prisma generate所以只要你的 Node 环境没问题构建不会出太大岔子。6.2 错误监控不能省后台系统最怕用户说“页面报错了”却看不到任何日志。我把t3code接入了 Sentry前端和后端都监听。tRPC 抛出的TRPCError会被 Sentry 自动捕获并带上前后端完整的调用链。哪个路由、哪个输入、哪个数据库查询出错一目了然。我还做了一个小技巧在protectedProcedure中间件里加上一个meta字段把当前用户 ID 附加到错误事件上。这样排查问题时能快速定位“是不是某个特定用户的数据有问题”。6.3 给新人的三点建议t3code从搭建到上线一共花了两周多。回头来看有几点经验可能对你有帮助不要为了“类型安全”死磕极致。tRPC 的类型安全已经覆盖了大部分场景个别无法用类型表达的地方用zod的手动校验兜底就行不要花大量时间写泛型体操。目录边界比技术栈更重要。哪怕你不用 tRPC只要你把业务代码、服务端代码、UI 代码的边界划线清楚维护度都不会差。一定要引入错误监控。后台系统的崩溃反馈往往是滞后的没有人会主动告诉你“刚才白屏了”。日志服务和错误监控是投产的第一优先级不是最后一个。最后再分享一点个人体会t3code这个名字本身没什么深意但它代表的是一套“全栈类型安全 三件套技术栈”的落地实践。技术选型从来不是越新越好而是越贴合项目规模越稳妥。如果你正着手一个中小体量的全栈项目可以试试按这个思路组织代码至少在类型、接口、样式这三个层面你不会再像以前那样在低价值的扯皮上浪费时间。
前阵子我把一个半死不活的后台管理系统推翻重写新的代码仓库代号就起了个t3code。说起来挺没新意——直接用了 T3 技术栈的首字母加 code 拼出来的但它确实不是一个花架子而是实实在在帮我解决了项目里类型不统一、接口联调扯皮、样式越写越乱的问题。如果你也在纠结全栈项目从哪下手或者听说了 T3 Stack 但不知道具体怎么组织代码这篇文章应该能让你的弯路少走一些。1. t3code 立项动机为什么我需要一套前后端统一的技术方案1.1 旧项目的三个“老大难”在动工t3code之前我之前维护的项目是典型的前后端分离架构后端 Java Spring Boot前端 Vue 2。说实话这种架构在公司里非常常见但时间一长问题就会浮出水面。第一个大问题是类型不同步。后端接口文档用 Swagger 维护前端再手工写一套api/types.ts。后端字段从userId改成user_id文档可能没更新前端代码却先崩了。开发高峰期几乎每周都要因为字段对不上而在群里扯皮效率很低。第二个问题是接口联调成本高。每加一个页面前端要先写接口定义、再写状态管理、再写类型声明然后等后端联调。中间任何一个环节出错排查链路都很长。第三个问题是项目配置散乱。环境变量散落在各个文件里没有类型校验团队成员随手复制粘贴生产环境偶发缺配置的问题。这三个问题放在一起让我特别渴望一套从数据库到页面端到端类型安全的方案。于是在启动新项目时我花了半天时间对比了 Remix、NestJS 全栈方案和 Next.js 系的全栈整合最后敲定了基于 T3 Stack 搭建t3code。1.2 为什么是 T3 Stack 而不是其他组合T3 Stack 这个名字最早来自 t3.gg 社区核心是 TypeScript、Next.js、Tailwind CSS、tRPC按需加入 Prisma、NextAuth.js。我选择它不是因为“网红项目”光环而是因为它恰好击中了旧项目里我最痛的地方TypeScript 全链路类型从 Prisma Schema 自动生成再到 tRPC 路由的输入输出最后到 React Query 的返回数据全程类型穿透不需要手写中间 DTO。tRPC 解决联调问题前后端共享同一个 API 层路由调用像本地函数一样不需要重复定义接口和请求函数。Tailwind 的样式约束原子化类名天然避免样式文件失控尤其适合我这种不想花太多时间在 CSS 命名上的开发者。当然T3 Stack 不是银弹它更适合中小型项目、内部工具、创业原型。但t3code的目标刚好是这种规模所以选它非常贴切。1.3 目录结构从第一天就规划好边界t3code初始化之后我没有直接开写而是先规划了目录边界。这是整个项目里最值得的东西。我用的是 create-t3-app 的标准结构然后做了一些定制t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ # Next.js App Router │ ├── components/ # 通用 UI 组件 │ ├── server/ # 服务端代码 │ │ ├── api/ # tRPC Router 定义 │ │ ├── auth/ # NextAuth 配置 │ │ ├── db.ts # Prisma Client 单例 │ │ └── trpc.ts # tRPC router 创建逻辑 │ ├── styles/ # 全局样式 │ ├── types/ # 少量手工类型补充 │ └── utils/ # 工具函数 └── .env这里最重要的原则是UI 组件里不允许直接出现prisma相关的调用所有数据请求都走 tRPC Router。这样后端换了、数据库换了前端页面基本不用动。很多项目做到后面代码乱根源就是目录边界从一开始就没守住。2. 初始化与工程配置t3code 的第一步2.1 用 create-t3-app 一键初始化初始化t3code非常简单。我推荐用 pnpm因为 pnpm 对 Next.js 项目依赖安装速度快磁盘占用也小pnpm create t3-applatest t3code命令执行后交互式选择项里我勾选了 Next.js、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth.js。如果你的项目不需要鉴权NextAuth 可以不勾但t3code是做后台管理鉴权是刚需。初始化完成后目录里会看到一个整洁的模板内置了drizzle或prisma的示例环境变量也预留好了。这个脚手架的好处是它把 tRPC 和 Next.js 的胶水代码都生成好了你不用自己去拼接trpc客户端和服务端省掉了最容易出错的环节。2.2 环境变量的类型校验别让 String(undefined) 坑你t3code里所有环境变量都是通过env.mjs里的zod校验的。这一点我非常喜欢。我以前见过太多项目在运行时才暴露环境变量缺失的问题——明明数据库密码没配上却等到第一笔写入才报错。create-t3-app生成的文件长这样import { createEnv } from t3-oss/env-nextjs; import { z } from zod; export const env createEnv({ server: { DATABASE_URL: z.string().url(), NEXTAUTH_SECRET: z.string().min(1), NEXTAUTH_URL: z.string().url(), }, client: { NEXT_PUBLIC_APP_NAME: z.string().min(1), }, runtimeEnv: { DATABASE_URL: process.env.DATABASE_URL, NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET, NEXTAUTH_URL: process.env.NEXTAUTH_URL, NEXT_PUBLIC_APP_NAME: process.env.NEXT_PUBLIC_APP_NAME, }, });这段代码的价值在于一旦.env里缺少字段应用启动阶段就会立刻抛出明确的错误而不是等运行到某个业务逻辑时才变成undefined。在实际使用中我还加了一个.env.example文件团队成员 clone 项目后照着复制一份就能跑起来。提示不要把.env提交到 Git但一定要提交.env.example。这个习惯在t3code的协作过程中帮我们省了很多“环境问题”。2.3 路径别名与严格 TypeScript 配置create-t3-app默认开启了strict模式这很好但还不够。我在 tsconfig.json 里额外开启了noUncheckedIndexedAccess因为这个选项可以强制检查数组和索引访问可能返回undefined的情况能避免开发时漏掉边界判断。同时我把路径别名统一成/*{ compilerOptions: { strict: true, noUncheckedIndexedAccess: true, baseUrl: ., paths: { /*: [./src/*] } } }别小看路径别名。没有统一的别名组件里全是../../../utils/formatDate重构时移动一个文件整个依赖链里的相对路径全得改。统一别名后代码的可读性和可维护性都提升了一个档次。3. 数据库模型与 tRPC Router后端逻辑这样写不会乱3.1 用 Prisma 定义核心数据模型t3code的数据模型很简单但很典型用户、文章、评论。这三张表基本覆盖了大多数业务场景的基础关系。prisma/schema.prisma里我这样定义generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model User { id String id default(cuid()) name String? email String unique createdAt DateTime default(now()) posts Post[] comments Comment[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) comments Comment[] createdAt DateTime default(now()) } model Comment { id String id default(cuid()) content String postId String post Post relation(fields: [postId], references: [id]) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) }这里有一个小经验主键全部用cuid()而不是自增整数。理由是cuid在分布式或未来数据迁移时不容易冲突而且不会暴露业务规模。虽然查询效率略低于 int但在t3code这种规模下完全感知不到差别。定义好模型后执行pnpm prisma migrate dev --name init pnpm prisma generatePrisma 会生成类型安全的 Client后面在 tRPC Router 里调用时返回的数据结构天然带类型。3.2 tRPC Router 按业务域拆分而不是按文件类型很多人用 tRPC 会把所有路由写到一个大文件里这样在线业务少时还好一旦模块多了就乱。t3code里我采用按业务域拆分的方式每个业务域一个 Router最后统一合并。src/server/api/routers/post.ts示例import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .query(({ ctx }) { return ctx.db.post.findMany({ include: { author: true }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1), })) .mutation(({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });protectedProcedure是我在trpc.ts里定义的一个受保护过程用于校验用户是否登录。业务代码里不用重复写 session 判断权限逻辑集中在中间件里维护成本很低。合并路由的代码import { createTRPCRouter } from ../trpc; import { postRouter } from ./post; import { commentRouter } from ./comment; import { userRouter } from ./user; export const appRouter createTRPCRouter({ post: postRouter, comment: commentRouter, user: userRouter, }); export type AppRouter typeof appRouter;这样前端调用api.post.list.useQuery()类型自然就是Post[]连loading、error状态都一并返回不用自己封装请求层。3.3 中间件与权限校验把鉴权逻辑收敛到一处权限校验是后台系统绕不开的事。t3code里我在src/server/api/trpc.ts定义了两个核心 procedureexport const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session || !ctx.session.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });刚开始我会觉得这种写法脱裤子放屁反正每个接口不都查一下登录状态吗但后来发现把权限收敛到中间件里比如后面要要改成“管理员可操作”或“普通用户仅读”直接改中间件判定即可业务 Router 完全不受影响。这就是 tRPC 的中间件模式比在每个 mutation 里写一堆 if else 干净得多。4. 前端数据流从 React Query 到页面渲染4.1 createT3SSR让首屏数据不闪烁t3code用的是 Next.js App Router但数据请求依然通过 tRPC React Query 来处理。为了首屏渲染时能拿到数据而不是先看到 loadingcreate-t3-app默认提供的createT3SSRHelpers很管用。一个列表页的完整示例// app/posts/page.tsx import { api } from ~/utils/api; import { createTRPCContext } from ~/server/api/trpc; import { createServerSideHelpers } from trpc/react-query/server; import { appRouter } from ~/server/api/root; import SuperJSON from superjson; export default async function PostsPage() { const helpers createServerSideHelpers({ router: appRouter, ctx: await createTRPCContext(), transformer: SuperJSON, }); await helpers.post.list.prefetch(); return PostList /; }而在PostList客户端组件里直接api.post.list.useQuery()读取缓存即可。React Query 会自动用服务端预取的数据填充不会闪 loading。这种“服务端预取 客户端渲染”的模式让t3code的页面既对 SEO 友好又保持了客户端交互的流畅度。4.2 mutation 后如何让缓存自动刷新最容易踩的坑是新增数据后列表不刷新必须手动刷新页面。t3code里我用 tRPC 的utils来让相关查询失效const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, });这段代码的意思是当post.create成功之后自动让post.list的缓存失效并重新拉取数据。比手动setQueryData更新缓存更简单且更可靠。有人说invalidate会多一次请求但在内部系统里一次列表查询成本很低换来的是数据一致性完全值得。4.3 服务端状态与客户端状态的边界在t3code开发过程中我给自己定了一个规则凡是来自数据库的状态一律交给 React Query凡是表单输入状态一律交给 react-hook-form全局 UI 状态才用 zustand。一开始大家会忍不住把所有状态放 useState比如当前选中的 tab、筛选条件、列表数据……结果组件一多状态同步很容易乱。后来我强制规定只有组件内部自己消费、不共享的 UI 状态才允许用 useState。其余要么走 URL 参数要么走 React Query。这个规则看着简单实际执行下来代码 review 时轻松了很多。5. Tailwind 样式体系在 t3code 里长得好看的实用方案5.1 原子类的复用与组件抽象Tailwind 用久了最烦的不是写 class而是同一个按钮要复制 8 遍同样的 class。t3code里的解法是用cn()工具加上基础组件封装。例如components/ui/button.tsximport { cn } from ~/utils/cn; type ButtonProps React.ButtonHTMLAttributesHTMLButtonElement { variant?: primary | ghost | danger; }; export function Button({ variant primary, className, ...props }: ButtonProps) { const variants { primary: bg-blue-600 text-white hover:bg-blue-700, ghost: bg-transparent text-gray-600 hover:bg-gray-100, danger: bg-red-600 text-white hover:bg-red-700, }; return button className{cn(rounded-lg px-4 py-2 transition, variants[variant], className)} {...props} /; }cn可以是简单的手写函数也可以直接用clsxtailwind-merge处理 class 覆盖问题。有了这层封装业务代码里的按钮样式就统一了后面想换主题色只需要改这一个文件的 class。5.2 主题定制与深色模式t3code默认是浅色主题但我们后台需要支持深色模式。Tailwind 配置里我用darkMode: class而不是media这样可以让用户手动切换。切换方案很简单给html元素加darkclass然后用 Next.js 的next-themes管理状态。在tailwind.config.ts中定制品牌色import type { Config } from tailwindcss; export default { darkMode: class, content: [./src/**/*.{ts,tsx}], theme: { extend: { colors: { brand: { 500: #4F46E5, 600: #4338CA, }, }, }, }, } satisfies Config;这样你就可以在组件里使用bg-brand-600 text-white而不是纠结是蓝还是紫。自定义品牌色在团队协作中特别有意义它让设计语言有了名称而不是“那个按钮蓝”。5.3 响应式布局踩过的坑Tailwind 的响应式断点是移动优先默认是先写移动端样式再写sm:、md:、lg:覆盖。我在t3code里做侧边栏时踩了一个坑只写了md:flex没写基础的flex导致移动端样式和桌面端样式错乱。实际上一个安全的写法是div classNameflex flex-col md:flex-row aside classNamew-full md:w-64菜单/aside main classNameflex-1内容/main /div如果希望侧边栏在移动端默认收起则可以用hidden md:flex。响应式不复杂但需要养成“移动优先”的习惯否则你会花很多时间去覆盖样式。6. 部署上线与后续迭代6.1 构建与部署方案对比t3code的部署方案我试过两种Vercel 和一台 2C4G 的云服务器。如果你的团队懒省事直接选 Vercel。它和 Next.js 的集成非常顺滑连接 Git 仓库后自动构建环境变量填好就行。t3code早期我就在 Vercel 上跑一条命令部署特别适合快速验证业务。后来因为客户要求数据必须存储在国内服务器我改成了自建服务器 PM2 Docker。自建服务器需要自己处理 Prisma 的迁移、Node 版本管理、进程守护等问题复杂度高了不少。如果团队没有运维经验不建议一上来就自建。部署前务必执行一次生产构建:pnpm build如果项目里有 tRPC、Prisma 的编译问题这一步会暴露出来。create-t3-app默认的构建脚本会先执行prisma generate所以只要你的 Node 环境没问题构建不会出太大岔子。6.2 错误监控不能省后台系统最怕用户说“页面报错了”却看不到任何日志。我把t3code接入了 Sentry前端和后端都监听。tRPC 抛出的TRPCError会被 Sentry 自动捕获并带上前后端完整的调用链。哪个路由、哪个输入、哪个数据库查询出错一目了然。我还做了一个小技巧在protectedProcedure中间件里加上一个meta字段把当前用户 ID 附加到错误事件上。这样排查问题时能快速定位“是不是某个特定用户的数据有问题”。6.3 给新人的三点建议t3code从搭建到上线一共花了两周多。回头来看有几点经验可能对你有帮助不要为了“类型安全”死磕极致。tRPC 的类型安全已经覆盖了大部分场景个别无法用类型表达的地方用zod的手动校验兜底就行不要花大量时间写泛型体操。目录边界比技术栈更重要。哪怕你不用 tRPC只要你把业务代码、服务端代码、UI 代码的边界划线清楚维护度都不会差。一定要引入错误监控。后台系统的崩溃反馈往往是滞后的没有人会主动告诉你“刚才白屏了”。日志服务和错误监控是投产的第一优先级不是最后一个。最后再分享一点个人体会t3code这个名字本身没什么深意但它代表的是一套“全栈类型安全 三件套技术栈”的落地实践。技术选型从来不是越新越好而是越贴合项目规模越稳妥。如果你正着手一个中小体量的全栈项目可以试试按这个思路组织代码至少在类型、接口、样式这三个层面你不会再像以前那样在低价值的扯皮上浪费时间。
