TypeScript全栈工程化实践：从零搭建t3code代码基座

先说结论：t3code不是某个框架的官方名称，而是我围绕TypeScript全栈开发沉淀出来的一套工程化模板和代码组织方案。从最初只有几个ESLint规则和一堆注释的零散文件，到后面扩展成包含服务端、数据库、客户端、CI检查在内的完整脚手架，我在t3code上迭代了大半年。如果你也在为多项目之间代码风格不统一、前后端类型对不上、每次开新项目都要重复搭环境而头疼，这篇文章值得花十分钟看完，里面有我踩过的坑和可以直接抄走的配置。

1. 项目解读：t3code是什么，为什么非做不可

1.1 三个痛点把项目逼出来的

先说背景。我之前所在的团队同时维护六七个业务系统，技术栈五花八门，有的用Vue2，有的用React，有的还在用jQuery时代的老代码。每次从零开一个新项目，光是把开发环境、代码规范、目录结构、权限校验这些基础设施拉起来，就得耗掉一两天，而且每次拉出来的结果还不一样。等项目的业务代码写多了，问题就更明显：接口定义混乱，后端改了字段类型，前端还在按字符串解析，出了问题只能虾爬式排查。

t3code这个项目本质上就是为解决这些痛点而生的。它不是一个业务系统，而是一套“代码基座”，把TypeScript全栈项目最常见的通用能力提前封装好。我在设计目标里写了三条硬性要求：新项目从初始化到能写第一条业务代码，时间控制在十五分钟内；前后端数据类型必须同一套来源，绝不允许各写各的；所有常规检查一组命令就能跑完，新人不看文档也能上手。

这三条听起来不复杂，但真要做扎实，每个环节都有讲究。比如类型同一套来源，很多人以为只要前端也写TypeScript就完事了，实际上你不把运行时校验、数据库Schema、API路由捆绑在一起，类型还是会慢慢失联。这些后面我会详细展开。

1.2 t3code的定位与设计目标

给这个项目定边界很重要，不然越做越臃肿。我在设计t3code时就明确了两条边界：只做全栈Web应用的基础设施，不做业务组件库；只支持TypeScript单一语言，不搞多语言适配。原因很简单，全栈Web应用的工程化痛点已经够多了，如果再把组件库、设计系统塞进来，模板会变得极其庞大，反而是负担。

在这两条边界下，t3code的核心能力被拆成四块：项目脚手架、代码规范、类型安全链路、自动化检查。项目脚手架负责快速生成一个可运行的全栈项目；代码规范统一了ESLint、Prettier、提交信息三者之间的协作方式；类型安全链路让数据库表、API入参出参、前端调用全部共享一套类型；自动化检查把类型检查、代码检查、测试串成一条流水线。

现在回看，当初把范围砍到这么聚焦是很关键的决定。我没有在t3code里塞状态管理方案，也没有封装统一请求库，因为这些属于业务层或者更上层的取舍，塞进来只会让模板变得教条。t3code只解决那些换了多少项目都一样的脏活累活。

1.3 为什么盯上T3这套技术栈而不是自己造轮子

很多朋友会问，为什么不干脆用官方脚手架？答案是官方脚手架给了你一张白纸，但没教你如何把工程约束固化下来。t3code这个命名的灵感来自T3技术栈的理念：用TypeScript贯穿全栈，用最小组合换取最大类型安全保障。T3强调的是“Typesafe”优先，核心组合是Next.js加TypeScript加tRPC加Tailwind，再加Prisma和Zod做数据与校验。这套组合和我们团队的技术积累最贴合，所以我选择在它的基础上做二次封装，而不是从零发明。

如果让我自己造轮子，最终大概率也会落到这套组合上。因为TypeScript是类型安全的底座；Next.js负责服务端和客户端一体化的托管能力；tRPC让前后端API像调用本地函数一样顺畅；Prisma把数据库表定义变成类型安全的数据模型；Zod做入口校验。这几个东西单独拎出来都很好用，组合在一起之后，它们的化学反应才是t3code最核心的价值。

2. 技术选型与整体架构设计

2.1 核心技术底座：Next.js + TypeScript + tRPC + Tailwind

先聊Next.js。我选它是因为它把服务端组件、路由、API能力都收敛到一个框架里，这让t3code可以同时承担BFF层和页面渲染层。在t3code里，一个业务模块既可以直接调用数据库获取数据，也可以对外暴露tRPC接口给前端调用，这种灵活度在传统的“前端项目加一个独立后端项目”模式下很难做到。

TypeScript不用多说，但我想强调一个很多人容易忽略的点：TypeScript的严格程度要在工程层面彻底打开。我在t3code里设了一套偏严的TypeScript配置，要求所有函数参数都有完整类型，禁止使用any作为逃生舱，回调函数返回值必须写清楚。很多人在项目初期觉得严格模式拖慢速度，但一旦项目超过三万行代码，这些约束会救你的命。

tRPC的引入是整个架构里最重的一个决策。tRPC的核心思路是让客户端和服务端共享类型定义，调用API就像调用本地函数。在t3code里，前端代码可以直接调用后端Router里定义好的查询，入参和返回类型在编辑器中就能自动提示出来。这种体验一旦用上手，你就再也不想回到手写接口文档、手动对齐类型的时代。

Tailwind在这里承担的是样式层。它不是技术难点，但统一了样式写法，避免每个项目都出现一套“自定义CSS变量命名哲学”。我对Tailwind的要求很朴素：配合设计Token使用，核心颜色、字重、间距全部走Token，组件里不写魔法数字。这样就算UI稿换了一套主题，改Token就能全局生效。

2.2 代码组织：目录结构、模块边界与命名约定

t3code的目录结构是花了心思的，它不像很多脚手架那样从pages目录一路铺开，而是按“模块”和“能力”两个维度切分。顶层划分是这样的：app目录放路由和页面，server目录放服务端逻辑，trpc目录放Router定义，db放Prisma相关文件，lib放领域无关的工具函数，styles放全局样式和Token。

具体落地时我还会要求每个业务模块自带router、schema和service三个文件，不允许跨模块随意import。什么意思呢？比如用户模块，它的router只负责接收tRPC请求调用本模块的service，schema只定义用户入参和出参的Zod模型，service里才是数据库操作和业务逻辑。这种做法让每个模块的边界非常清晰，出问题的时候直接进对应目录看就行。

目录结构之外，我还在t3code里硬性规定了命名约定。文件名用小写横杠分隔，比如user-profile.ts而不是userProfile.ts；常量用全部大写下划线分隔；类型和组件用大写驼峰。这些约定看起来琐碎，但它们直接决定了代码检索的效率。我用过一个统一代码搜索工具扫描全仓库，启用了命名规则之后，按文件名搜索的命中率提升了非常多。

2.3 从类型安全到运行时安全：Zod的正确用法

类型系统虽然能约束开发期类型，但运行时进来的数据往往是不可信的，特别是接口请求、环境变量、第三方回调。Zod在t3code里就专门负责补这个缺口。我的做法是：所有tRPC入参定义成Zod Schema，当请求进来时，tRPC中间件先做一次解析和校验，不合法就直接返回错误，保证到达Service层的数据一定是合法的。

很多人以为Zod的作用只是校验几个字段，其实它的能力远不止于此。在t3code里，我从同一个Zod Schema里同时推导出请求类型、数据库某张表的Form创建模型、前端表单的初值类型，这样表单、接口、数据库三者永远共享同一套类型定义。就算后端加了一个必填字段，前端编译期就会被类型报错提醒，而不是上线后接口报错。

运行环境变量的校验也是一个容易被忽略的盲区。t3code里内置了一个env Schema，项目启动时会校验所有环境变量是否存在、格式是否正确，任何一个变量缺失都会直接阻断启动进程，并把缺哪个变量打在控制台里。这个机制我强烈建议每个项目都保留，因为它能帮你在配置环节就发现错误，而不是等到线上请求的时候才爆出一堆看不懂的运行时异常。

3. 从零搭建t3code的完整实操

3.1 初始化脚手架

如果你要复现这套方案，第一步是拿到一个干净的Next.js加TypeScript项目。这一步我不建议纯手工创建，直接用社区最好的初始化工具。使用create-t3-app是最快的路径，它会一次性把Next.js、TypeScript、tRPC、Prisma、Tailwind以及ESLint全部初始化好，而且默认配置就是比较主流的那套。

初始化完成后，我建议立刻做三件事。第一件事是把git仓库初始化好，第一笔提交就留在脚手架刚生成、什么业务代码都没有的这一刻，这张干净快照以后很有用。第二件事是删掉脚手架自带的示例页面和演示数据，这些内容首屏虽然好看，但会干扰你对代码结构的理解。第三件事是跑一次完整的lint、类型检查和构建，确认基线是绿的状态，后面每一步改完再跑，出问题就能立刻定位是哪个环节引入的。

这里有一个我特别想强调的点：t3code的所有配置都应该跟着项目走，而不是跟着个人走。我的意思是，配置文件和依赖锁定文件必须提交到git仓库，不允许以“我这台机器上能跑”为由到处漂移。CI环境、同事的电脑、甚至未来的你，都应该和当前仓库环境保持完全一致。这也是后面自动化检查能稳定跑起来的前提。

3.2 配置代码规范与Git提交检查

代码规范这层，ESLint是绝对的主角。初始化项目自带的ESLint配置是一个很好的基线，但我在t3code里加了一组自定义规则：禁止在组件外声明非必要函数、禁止使用TypeScript非空断言（因为那通常意味着类型设计有漏洞）、强制导入顺序分组等等。这些规则都不是什么花活，而是在实践里真的能减少隐性Bug的约束。

Prettier负责纯粹的格式化，配置很简单，我端口、单引号、缩进都设成了团队约定值。但这里有个关键操作：Prettier和ESLint的分工要搞清楚，Prettier管格式，ESLint管代码质量，两者同时启用时要用eslint-config-prettier关闭ESLint里和格式相关的冲突规则，否则你会在格式化上浪费大量时间。

Git提交检查是t3code里比较有特色的部分。我用Husky挂上了pre-commit钩子，借助lint-staged对暂存区的文件执行ESLint和Prettier检查，只有通过的文件才能被提交。Commitlint负责校验提交信息格式，要求所有提交都写成feat(模块名): 描述这种结构。我还在团队里固定了一条规矩：提交信息里只写发生了什么，不写为什么和怎么做，原因和背景放进PR描述里。

这套机制看起来有点繁琐，但它最大好处是让每一次提交都具备可审查性。你回看git log的时候，一眼就能扫出这个项目做过什么类型的改动、涉及哪个模块。对于一个长期维护的项目来说，这种可阅读的提交记录价值极高，比任何周报都靠谱。

3.3 实现一个完整业务闭环

光有配置还不行，我拿一个具体的例子讲清楚t3code里一个业务闭环长什么样。假设我们要做一个笔记模块，数据表叫Note，包含标题、内容、创建时间三个字段。这个过程我会刻意分成数据库层、接口层、页面层三层来做，每层都依赖类型安全链路串起来。

首先是数据库层。在Prisma的Schema文件里定义Note模型，字段类型要严格按照用途选择，标题用String，内容用String，创建时间用DateTime，索引加在创建时间字段上，为后续列表查询预埋性能优化。定义完成后执行迁移命令，生成迁移文件并把结构同步到数据库。这一步记住，迁移文件同样要提交到git，它是数据库结构的版本历史。

然后是接口层。我先写一个Zod Schema定义创建笔记的入参，标题和内容的长度都要约束，比如标题最长100个字符，内容最长5000个字符。接着在tRPC Router里暴露一个createNote mutation，内部调用Prisma创建记录并返回新记录数据。前端调用这个mutation的时候，编辑器和TypeScript会直接提示出参数结构，完全不需要去翻接口文档。

最后是页面层。我创建一个页面，用表单收集标题和内容，提交时调用刚才那个mutation。这里有个细节，我会在表单校验失败、接口请求失败、创建成功三个场景分别做不同的用户提示，而不是只在控制台打印错误。整体跑下来，从数据库到页面整个链路都是类型贯通的，改一处类型定义，编译期就能暴露所有受影响的位置。这体验一旦习惯，很难回退。

3.4 配置CI自动检查

本地检查做得再好，不落到CI上还是等于零。t3code里把CI配置做成了标准流程，提交代码到主分支就会自动触发三个环节：安装依赖、跑类型检查、跑全量代码检查。这套CI的真正作用不是帮本地开发省时间，而是守住主分支的底线。谁都不允许绕过本地检查把坏代码合进去，这在多人协作里是刚需。

依赖安装这一步有个性能陷阱。直接用npm install会把所有依赖都解析一遍，多人协作时很容易出现锁文件不同步的问题。我在t3code里把依赖安装改成了基于锁文件精确安装的方式，并且在CI缓存了依赖目录，这样大部分命中缓存的情况下，整个构建流程能压缩到三分钟内。

还有一个CI细节是我后来才加的：提交产物的体积阈值。我会在CI里跑一次生产构建，然后检查关键产物的大小，如果单文件比上次超出了某个比例就自动失败提醒。防止有人为了省事把一张大图片当模块Import进来，等上线才发现首页加载慢得离谱。

4. 运行半年踩过的坑和排查实录

4.1 tRPC类型不同步的诡异报错

t3code上线跑了大概两个月，我对这套体系越来越放心的时候，撞上一个很诡异的坑。某天同事在Service层加了一个新查询函数，前端页面跟着调用，编译一会儿后突然报类型错误，提示某个类型别名不存在。我第一反应是代码写错了，但在本地反复检查了半天，代码逻辑完全没问题，重启开发服务器之后错误又消失了。

后来排查才知道，这是tRPC类型导出的缓存机制在作怪。开发环境下类型更新有时会命中热更新的缓存，导致类型定义没完全刷新。解决方案很简单：把tsc的类型检查进程和服务进程一起重启即可。但更彻底的做法是在CI里跑独立的全量类型检查，因为CI是全量冷启动，不会受热更新缓存影响。从那以后，我再也不依赖本地编辑器提示验证类型正确性，一切以CI结果为准。

4.2 Next.js服务端渲染与tRPC权限判断

还有一个让我印象深刻的坑和权限相关。刚开始设计t3code时，我把用户登录信息放在客户端的React Query缓存里，然后在服务端组件里判断用户是否登录。看起来逻辑没错，但实际表现非常奇怪：有时候用户明明登录了，服务端还是渲染成未登录状态，刷新之后又正常了。

原因并不复杂，服务端组件是跑在服务器上的，它根本拿不到浏览器里的React Query缓存，我那些判断逻辑在服务端压根不生效。t3code后来专门设计了一套会话读取方案：把登录态放在HttpOnly的会话Cookie里，服务端组件和tRPC中间件统一从Cookie解析用户信息，而不是依赖客户端状态。这个问题如果不在架构层解决，后面每个涉及登录判断的页面都会踩一遍。

这个坑给我们的教训很实在：在Next.js这种同时存在服务端和客户端执行环境的技术栈里，状态必须区分清楚到底存在哪一侧。所有需要跨环境共享的信息都要走HTTP层面的传递机制，而不是依赖JavaScript内存里的变量。

4.3 数据库迁移在部署时的不一致

数据库迁移是t3code上线阶段最波折的一环。我们有一次发布新版本，代码已经更新到服务器了，数据库结构却没有同步，结果线上接口先是开始报错，然后有用户在页面操作的时候触发了异常提示。那次事故最费时间的不是修复本身，而是找出到底是哪一条迁移记录没执行。

查了半天，发现原因是部署脚本里把迁移和启动混在一个命令里了，迁移命令执行到了中间某一步会询问交互式输入，在无人值守的服务器环境里它就卡住了，后面的步骤全部被阻塞。这个坑非常经典，数据库迁移命令必须在部署流程里独立执行，而且要配置成非交互模式，一旦执行失败就立刻中止部署，绝不允许带着旧的数据库结构去跑新代码。另外，数据库备份在迁移前一定要做，别问我是怎么知道的。

4.4 体积控制与构建性能优化

t3code维护到后期，依赖数量和代码体积开始胀肚子。第一次全量构建的时候，我盯着终端的输出看了好一会儿，光样式文件就快到了3MB，还附带一个巨大的打包警告。这个问题通过两处改动解决：一面在Next.js里开启依赖预打包，把常用的、几乎不改的依赖提前编译成独立包，加快主项目的构建速度；另一面在打包配置里把切分粒度调整得更合理，把体积大的依赖拆成单独模块按需加载。

这里有个我很满意的调整：把大型依赖从打包临界值中排除，让它们走CDN或者服务端的提前加载。迁移之后首屏加载时间掉了约四成，这不是什么高深技巧，但如果你在t3code里不提前做体积约束，等业务膨胀后再想收，成本会翻好几倍。

4.5 常见问题速查表

我把半年里经常被问到的问题整理成了一张速查表，方便现在的团队成员直接查：

这张表不是写出来摆着看的，我把它挂在了团队开发文档最显眼的位置。遇到类似报错的人先查表，能解决就直接解决，解决不了再来找我。事实上，很多“看起来很难”的问题，查分行三分钟就找到了原因。

5. 最后分享几点这段时间的真实体会

整套t3code做下来，我最深的感受是工程化这件事，百分之八十的收益来自百分之二十的关键约束。类型安全链路、代码规范检查、CI自动化，这几根柱子立住了，项目的下限就低不了。至于那些花里胡哨的插件和规则，真的是能删就删，每一条多余规则都在消耗团队的注意力。

如果你也打算搭一套类似的代码基座，我建议你从小处入手，不要一上来就铺开做完整的全家桶。先把类型安全链路打通，把代码规范检查跑起来，再把CI守住，就已经能解决团队里百分之八十的协作问题了。t3code不是终点，代码工程化的路很长，但这套模板帮我换来了非常可观的安定时间，让我有精力去做真正有价值的业务和架构探索。