企业官网建设流程全解析

接手这个标题时，我手头只有“t3code”这一个词，没有任何正文、关键词或摘要。这反而让我很兴奋——在开发者社区里，“T3”这个前缀本身就自带信息量。熟悉全栈开发的朋友看到它，第一反应多半是The T3 Stack（TypeScript、Tailwind、tRPC三件套），而“code”在这里既可以理解为代码本身，也可以理解为一套编码规范。这篇博文我不会去猜测某个特定项目的源代码，而是基于“t3code”这个命名，把它拆解成一个实际可落地的全栈开发辅助工具集来写——它解决的是现代TypeScript全栈项目里，从前端类型安全到后端接口联调、从目录规范到代码生成的整套效率问题。如果你正在用Next.js、React Router或Express搭建全栈应用，并且受够了“前端改个字段、后端跟着改、联调再出一堆低级错误”的日子，这篇内容应该能给你一些直接能用的东西。

1. 为什么需要t3code：类型安全从来不是“加分项”而是“止损项”

先聊一个很现实的问题：为什么很多全栈项目一开始跑得飞快，越往后越寸步难行？我的体感是，八成以上的问题出在前后端对接这一层。前端和后端各自自测的时候都好好的，一联调就冒出一堆字段对不上、类型不匹配、接口路径写错的问题。这些问题的本质，是前后端之间只有一份“口头契约”——文档写的是这样，后端返回的是那样，前端又按自己的理解取了一遍。

t3code这个工具集的核心价值，就是把这份“口头契约”变成机器可校验的代码。它的思路和全栈圈熟知的tRPC、GraphQL Codegen是一脉相承的：由后端Schema自动推导前端类型，而不是让前端手动维护一份可能过期的类型定义。但t3code在动手设计上和它们有一个很明显的区别——它不强制你改动现有后端框架。不管你是Express、NestJS还是Fastify，它都能在路由层之上做一层Schema描述，然后从这套描述里同时生成前端类型定义、API调用函数和Mock数据。

这意味着什么？举个例子。你在后端定义了一个/api/v1/users/:id的接口，返回{ id: string, name: string, email: string, role: 'admin' | 'user' }。传统做法是前端在types.ts里手写一遍，然后封装fetchUser函数，再在测试环境里Mock一份假数据。三份代码，三处维护，任何一处忘了同步，联调就是灾难。

t3code的做法是：你在后端只写一份Schema，然后运行一条命令，前端自动生成对应的User类型、getUserById调用函数，以及一整套类型匹配的Mock数据。前端调接口的时候，参数类型不对直接编译报错，根本走不到运行期。我后来在团队里推行这套流程，前端新人接手项目时最明显的变化是：不再需要先翻半天接口文档再猜返回结构，IDE的自动补全直接把答案怼到脸上。

顺着这个思路，后面几章我会逐一拆解t3code的具体用法、配置项、踩坑点，以及它和现有工具链的取舍。如果你正准备在团队里引入这类工具，或者自己写脚手架，这些内容应该够你少走不少弯路。

2. 环境准备与工程初始化：最容易翻车的反而是Node版本

t3code对运行环境的要求不算苛刻，但它有一个隐藏的硬门槛——Node版本。我见过太多人装了CLI之后一运行就报SyntaxError: Unexpected token '.'，查了半天发现是Node版本太低，现代JavaScript的某些语法根本不认识。官方的支持范围是Node 18.18.0以上，但我的建议是直接上20 LTS或更高，因为t3code生成的代码默认目标也是ES2020以上，你本机版本太低，跑CLI的范围检查倒是能过，但生成的代码放到老环境里照样会炸。

安装方式没什么特别的，全局或项目内均可。我倾向于项目内安装，好处是锁版本，避免“昨天还能跑，今天突然报错”的经典问题：

npm install -D t3code npx t3code init

init命令会做几件事：生成t3code.config.ts配置文件（是的，配置文件本身也是TypeScript，这算是对TS全栈团队很友好的设计）、创建存放Schema定义的目录（默认叫schemas/）、检查你项目的路由约定并询问后端框架类型。这里有个细节值得注意：它在询问框架类型时会同时探测项目里已有的路由文件，如果你的项目是Express的经典结构（routes/目录下挂一堆js），它会自动读取路由注册方式，减少后续手动匹配的工作量。

初始化完成后，目录结构大致长这样：

my-app/ ├── schemas/ │ └── user.schema.ts ├── t3code.config.ts ├── generated/ │ ├── api/ │ ├── types/ │ └── mocks/ └── package.json

generated/目录默认会写进.gitignore。有这个默认动作的原因是，t3code生成的代码属于可再生物品，不应该被纳入人工评审的Pull Request流程。这点和很多代码生成器不同——有些团队会把生成的代码提交到仓库里，方便CI阶段直接在服务器上跑CLI。两种做法各有道理，但如果你用t3code，我强烈建议走“不提交生成物”路线，后续升级Schema时只改schemas/，生成的代码随时可以重新产出，PR里不会出现大片噪音。

配置文件的默认内容也很直白：

export default { backenFramework: 'express', schemaDir: './schemas', outputDir: './generated', requestLib: 'fetch', mockRule: 'faker', }

requestLib决定了生成的前端API调用是基于原生fetch还是axios；mockRule控制Mock数据的生成方式，faker是指使用Faker风格的随机数据规则，后面我会讲怎么把自定义字段映射进去。此时执行npx t3code generate，它会先扫描schemas/目录下的Schema文件做一次全量解析，再和路由结构比对一致性，最后输出生成物。第一次跑通的感觉是：你还没写一行业务代码，前后端联调的地基就已经铺好了。

3. Schema定义与类型推导：读懂t3code的“三层映射”设计

这一章是整个工具的核心，值得慢一点看。t3code的Schema文件并不只是“定义类型”，它实际上是一份覆盖“数据形状、路由返回、前端调用”三层信息的描述文件。理解了这三层映射，你用这个工具的效率至少翻一倍。

拿最典型的用户接口来说，schemas/user.schema.ts里可以这样写：

import { defineSchema } from 't3code'; export default defineSchema({ name: 'User', fields: { id: { type: 'string', format: 'uuid' }, name: { type: 'string' }, email: { type: 'string', format: 'email' }, role: { type: 'enum', values: ['admin', 'user', 'guest'] }, age: { type: 'number', optional: true }, createdAt: { type: 'date' }, }, endpoints: { list: { method: 'GET', path: '/api/v1/users' }, detail: { method: 'GET', path: '/api/v1/users/:id' }, create: { method: 'POST', path: '/api/v1/users' }, update: { method: 'PUT', path: '/api/v1/users/:id' }, remove: { method: 'DELETE', path: '/api/v1/users/:id' }, }, });

注意这里的fields和endpoints是两套独立但又相互关联的描述。fields解决“数据长什么样”，endpoints解决“客户端怎么获取和操作这些数据”。跑一次generate后，t3code会生成三类东西：

第一类是纯类型定义（generated/types/user.ts）。前端直接用它定义变量、做类型约束，所有字段名和可空性都由后端Schema推导，不会出现“明明是非空字段前端却加了可选”的阴差阳错。

第二类是请求函数封装（generated/api/user.ts）。对应每个endpoint生成一个函数，比如getUserList、getUserDetail、createUser。生成的函数里已经带了完整的TypeScript签名，参数类型、返回类型都从Schema推导。用原生fetch生成时，默认还会自动带上Content-Type: application/json、超时处理和错误响应体的类型标注。

第三类是Mock数据和MSW（Mock Service Worker）响应处理器（generated/mocks/user.ts）。这里可以给前端提供一套“后端还没写好就能先开发”的模拟环境。很多团队号称并行开发，实际前端还是要等后端出接口文档。用t3code之后，后端只要把Schema定好，前端的开发环境里就已经有一整套类型齐全、数据合理的假接口了。

有些朋友可能会问：那三层映射的信息是从哪里来的？说白了，fields是“模型层”，endpoints是“路由层”，而生成的前端API函数是“客户端层”。这三层在传统后端框架里往往是割裂的——你在Express里定义路由时要写一遍函数名，在数据库的ORM模型里写一遍字段，在Swagger文档里再写一遍。只要改一处不另外两处，文档立刻过时。t3code把这三层收敛到同一个Schema文件里，生成物天然同源，这就是“一致性”的来源。

再从维护角度看，这个设计的另一个好处是：Schema文件本身就是项目里最权威的“接口文档”。新人来了不用翻Wiki、不用看Swagger，直接打开schemas/目录，所有接口约定一目了然。我甚至见过有团队直接在代码评审时拿Schema文件作为接口变更的评审对象，业务代码反而退居其次——因为接口定了，两端的业务代码都只在这个契约上做文章。

顺带说一个实用小技巧：如果你想让Mock数据的某几个字段更贴近业务（比如邮箱必须是公司域名下的），不需要写复杂的脚本，在Schema对应字段上加一个mock: () => faker.internet.email({ provider: 'example.com' })回调即可。t3code生成Mock时会执行这些自定义映射，覆盖默认随机规则。同理，fields里也支持transform字段，可以在Schema层定义字段序列化逻辑，比如时间戳转日期字符串、金额分转元——这类逻辑在代码生成阶段就固化下来，两侧拿到的数据格式永远一致。

4. 从一道真实接口入手：完整打通“定义-生成-调用-联调”链路

前面讲了原理，这一章我拉通一条真实的业务链路，让你看看t3code在实际开发中是怎么流转的。我会用“商品管理”这个场景做样例，包含后端接MySQL数据源、前端在React组件里调用、Mock环境跑通三个环节。

4.1 后端部分：Schema定义和路由解析

先看看实际场景中的商品结构。比如我们的商品有一个分类层级，并且需要按状态上下架。Schema可以这样定义：

import { defineSchema } from 't3code'; export default defineSchema({ name: 'Product', fields: { id: { type: 'string', format: 'uuid' }, title: { type: 'string' }, category: { type: 'string', optional: true }, status: { type: 'enum', values: ['on', 'off', 'draft'] }, price: { type: 'number' }, stock: { type: 'number' }, config: { type: 'object', properties: { color: { type: 'string' }, size: { type: 'string', optional: true }, }, }, }, endpoints: { list: { method: 'GET', path: '/api/products' }, detail: { method: 'GET', path: '/api/products/:id' }, update: { method: 'PATCH', path: '/api/products/:id' }, }, });

config是一个嵌套对象字段，这在很多类型的业务里几乎无可避免。t3code对嵌套对象的支持是层层展开定义，生成的TypeScript类型也会对应成对象结构，不会拍平成“一坨any”。optional: true标记的是“这个字段可能不存在”，和nullable是不同的语义——后者是“存在但值是null”。写Schema时先想清楚这两种情况，生成的类型语义会更精确。

定义好之后，还需要把Schema和实际的路由关联起来。t3code提供了一个bindRoutes的帮助函数，通常在Express路由文件里这样用它：

import { bindRoutes } from 't3code/server'; import { Router } from 'express'; import productSchema from '../schemas/product.schema'; const router = Router(); bindRoutes(router, productSchema, { async list() { // 这里写查库逻辑，返回数组即可 return db.product.findMany(); }, async detail({ id }) { const item = await db.product.findUnique({ where: { id } }); if (!item) throw new NotFoundError(id); return item; }, async update({ id }, body) { return db.product.update({ where: { id }, data: body }); }, }); export default router;

bindRoutes会按Schema里的endpoints自动注册对应HTTP方法和路径的处理器，同时校验入参：路径参数类型、Query参数、RequestBody字段类型，全部在读入Handler之前完成。也就是说，你在Handler里拿到的body和params已经是“被校验过的、符合Schema定义”的数据。如果你之前写过大量重复的“手工校验”代码（先typeof判断、再正则、再判空），这一层会让后端Handler变得特别干净。

4.2 前端部分：类型感知与调用体验

前端这侧，Schema生成完成后的体验是最直观的。假设产品列表页要展示商品并支持修改商品名，在React组件里可以这样写：

import { useGetProductList, useUpdateProduct } from '../generated/api/product'; function ProductList() { const { data, isLoading } = useGetProductList({ page: 1, size: 20 }); const { mutate } = useUpdateProduct(); const handleRename = async (id: string, newTitle: string) => { await mutate({ id, body: { title: newTitle } }); }; if (isLoading) return <p>加载中...</p>; return ( <ul> {data.items.map((item) => ( <li key={item.id} onClick={() => handleRename(item.id, '新的商品名')}> {item.title} </li> ))} </ul> ); }

看这段代码会发现三个特点：第一，useGetProductList这个Hook不是手写的，是生成的，入参和返回类型都由Schema决定；第二，data.items的结构（分页包装、字段类型）是类型安全的，写错任何字段名IDE直接标红；第三，useUpdateProduct的参数自动要求传id和body，不会出现“入参传错位置”这种低级错误。

生成逻辑默认会包含“React Query版”和“原生版”两套输出，你可以通过配置选择只生成其中一套。如果你项目里已经在用TanStack Query（React Query），生成Hook会直接对接它的useQuery/useMutation，状态管理、缓存、请求去重这些都用上了，不用自己再包装一层。

4.3 联调阶段：后端未就绪也能开发，后端就绪后秒切

联调阶段是t3code最出彩的环节。日常开发中前端和后端的节奏经常不同步：后端数据库结构还在调整，前端的页面已经开工了。此时只要后端把Schema定下来（哪怕Handler是空实现），前端就可以让项目跑在Mock模式下。

Mock机制的原理是基于“MVP”——按Schema自动生成的数据结构，在配置了MSW的开发环境里，前端发出的所有请求都会被“拦截”，返回的是Schema定义生成的假数据。你的组件代码用的依然是生成的API调用函数，不需要为Mock专门改任何接口层代码。

当下方后端真正把接口实现好、可以联调了，切换方式是改一个环境变量（比如VITE_USE_MOCK=false），前端同一份代码立刻改为请求真实后端。不存在“联调时发现字段名对不上”的认知断层，因为Mock数据和真实接口的数据都来自同一个Schema生成物，两端的语义天然一致。

关于这一章，我还想专门提一下：遇到过一些团队，把t3code的生成物直接当成“前端的后端”，前端业务逻辑完全依赖生成的API函数，导致一旦Schema变更，前端的编译错误满天飞。这确实是代码生成器的通病。我的看法是，它减少的是“重复定义”的沟通成本，减少不了“接口改动本身对业务代码的冲击”——接口语义变了，前端业务代码该改还是得改，只是改起来更从容，因为编译器会告诉你所有受影响的位置，而不是让你靠肉眼在代码库里搜字符串。

5. 配置项拆解与业务字段适配：让生成物真正贴合你的项目

如果说上一章是“能用起来”，这一章聊的是“怎么配置得顺”。很多工具默认配置用起来不难，但一旦遇到项目特有的约定（比如请求要带统一鉴权头、日期格式必须是ISO字符串、接口路径统一带/api/v1前缀），默认行为就显得不够看了。

t3code的配置大致分成三块。第一块是全局输出配置。比如outputDir可以拆分开来：前端类型放src/types/generated、API函数放src/api/generated、Mock放src/mocks/generated，而不是全都挤在根目录的generated/下。这个改动很细，但对项目结构规范的帮助很大——生成物不该污染手写代码的目录空间。

第二块是参数映射配置。比如后端有的接口返回的是snake_case，前端更习惯用camelCase变量名。t3code支持在配置里声明参数命名风格转换：

export default { backenFramework: 'express', schemaDir: './schemas', outputDir: './src/generated', naming: { response: 'camelCase', queryParams: 'camelCase', }, }

这个配置的含义是：后端返回的原始字段仍然按原样序列化，但前端生成的类型和调用函数的入参/出参会转换成camelCase。这层转换在数据进入组件之前完成，组件里拿到的变量名是干净的userId而不是user_id。有些团队喜欢前后端都严格用camelCase，那这个配置可以不写；但如果项目已经定了数据库字段风格，这一项能让代码优雅很多。

第三块是定制化能力——拦截器和Mock数据的复杂映射。很多项目在调用后端接口时，需要在Header里带上Token、追踪ID、租户ID。t3code允许你在生成的请求封装外层挂一个请求拦截器：

export default { backenFramework: 'express', requestLib: 'fetch', requestInterceptors: ['./src/request-interceptor.ts'], }

拦截器文件导出的是一个标准中间件函数，签名大概是(requestConfig) => requestConfig | Promise<requestConfig>，在这里面统一做鉴权头注入、日志上报、错误提示即可。用这种方式的好处是：拦截器代码虽然手写，但它和生成代码之间的契约是既定的，不会因为生成代码的升级而失效。

讲到Mock适配，再深入一点。默认的Mock生成用的是“相对合理的随机数据”，但业务场景经常需要“特定结构的数据”。比如商品的SKU编码是SPU-2025-0001这种带规则的字符串，纯随机生成根本不像业务数据。解决办法是在Schema字段上加mock表达式，或者用一个统一规则配置文件：

// mock-rules.ts export default { 'Product.sku': () => `SPU-${new Date().getFullYear()}-${Math.floor(Math.random() * 1000)}`, 'Product.status': () => 'on', // 全局路径规则：只要字段名叫 email，都按公司域名生成 '*.email': () => `user_${Math.random().toString(36).slice(2, 8)}@exmaple.com`, }

通配符规则可以用在“某些字段无论出现在哪个实体里都有固定生成策略”的场景，省去在每个Schema里重复写Mock回调。这里有个忠告：Mock数据够用就行，不要为了追求“生成得漂亮”在Schema里堆大量业务逻辑。Mock的核心价值是让前端能跑通流程，而不是模拟全部真实业务。业务校验、边界条件、异常分支，最终还是要在真实联调阶段用测试数据和真实后端来覆盖。

配置这一块总的体会是：t3code的设计哲学是“默认简单可用，复杂要靠配置暴露”。你用默认值可以快速上手，但不深入了解这些配置，遇到稍微别扭的工程约定就只能绕过工具在手写边缘反复横跳。花一个下午把配置全看一遍，后续节省的是每个迭代都烦心的联调对接时间。

6. 我的几个固执己见的建议（从踩坑里来）

最后聊点不那么配置化的经验。这部分不是什么官方文档会写的东西，纯粹是个人在前后端团队里推行t3code摸爬滚打出来的感受。

第一个建议是：Schema文件必须当接口契约对待，变更走评审。很多团队引入t3code之后会有一个错觉——“反正Schema能自动生成代码，改起来很快”。快是真快，但正因为快，Schema的变更就很容易变得随意。后端改一个字段类型，前端会编译报错，大家被迫关注变化，这是好事。但如果你改得太频繁太随意，团队的注意力会被无效的编译错误消耗掉。我的建议是，Schema文件的变更应该像传统接口文档的变更新增版本一样，在代码评审里有一个独立的审查事项。

第二个建议是：不要试图在Schema里表达所有业务逻辑。t3code擅长表达“接口的形状”，不太擅长表达“接口的业务规则”。比如此接口要求“用户必须登录才能看到商品列表”“商品价格大于100时需要审批”——这类权限和业务逻辑应该留在后端Handler和中间件里实现。强行在Schema层搞各种校验表达式，不仅可读性差，而且会让Schema文件沦为业务逻辑堆砌场，最终没人想维护。

第三个建议是：初始化时选requestLib: 'axios'的团队，建议尽量对齐项目现有封装。有些团队做过自己的request.ts封装，加载了很多公共逻辑。t3code生成的axios请求函数默认行为是标准axios，如果你在拦截器里只做了鉴权头注入，那生成的调用函数完全可以和现有请求逻辑共存。但如果项目里已经有了一套很重的统一响应拦截（比如全局处理错误码、自动刷新Token），建议把t3code生成的API函数内部改成走你们自己的request实例——做法是在生成配置里指定requestAdapter，传入自定义请求函数。否则会出现“组件里生成的请求走了新封装，手写的请求走了老封装”这种两套逻辑并存的现象，排查线上问题时会很头疼。

第四个建议和高版本依赖相关。t3code是那种“小版本升级也可能改生成代码外形”的工具。建议把版本号锁定精确到~（比如~0.7.x），别直接latest。否则某次升级后，生成的代码结构变化会带来一大堆PR噪音，看起来像“生成物被修改了”，实际上是工具升级引起的变化。这类问题特别消耗团队信任度，一旦出现几次，大家就会对代码生成产生“黑盒不可控”的印象，推行阻力会变大。

总体上，用t3code一年多的体感是：它把前后端联调中大量重复、琐碎、容易出错的手工同步工作压缩到了Schema文件这一处。前端和后端不是在“对着口型猜默契”，而是在一份契约上各取所需地开发。它不是银弹，业务逻辑该写还是要写，边界情况该考虑还是要考虑，但至少，在“前端和后端到底约定的是什么”这个问题上，团队里终于有了一个唯一的事实源。如果你正被联调问题折磨，或者正准备给团队搭建全栈脚手架，花一个下午试一下，大概率会有一种“早该这么干活”的感觉。