企业官网建设流程全解析

1. 从“t3code”这个代号说起：它到底指什么

第一次看到“t3code”这个词，很多人会一头雾水。它不像“React”“Vue”那样有明确的官方文档，也不像“Docker”“K8s”那样在运维圈人尽皆知。它更像是一个在特定圈子里流传的代号、一个项目内部使用的简称，或者某个技术方案的缩写。我最初接触到这个词，是在和一些做前端架构的朋友聊天时，有人提到“我们内部把那一套模板加代码生成的方案叫 t3code”。后来陆续在几个技术社区里也看到类似说法，才意识到它并不是某个单一工具，而是一类做法的统称。

那 t3code 到底指什么？结合我自己的实践和跟同行交流的结果，它大概率指向这样一类东西：以 TypeScript 为底座，围绕“模板 + 类型安全 + 代码生成”构建的一套开发范式或脚手架体系。这里的“t3”可以理解为 TypeScript 的三次方，也可以理解为某个项目内部第三代模板方案的代号，而“code”则强调它最终产出的是可运行的代码，而不是配置文件或文档。换句话说，t3code 的核心价值在于：让你用一套约定好的模板和类型定义，自动生成前后端都能直接用的代码，减少手写重复逻辑的时间。

为什么这类东西会流行起来？因为现在一个稍微像样的项目，前端要写类型定义、API 请求封装、表单校验，后端要写 DTO、实体类、数据库映射，两边还要保持字段一致。一旦接口改了，前后端不同步就是家常便饭。t3code 这类方案就是冲着这个痛点去的：用一份源头定义，生成多端代码。它适合那些已经有一定工程化基础、团队里有人懂 TypeScript 和代码生成原理的开发者。如果你只是写个小 demo，或者团队里没人愿意维护生成脚本，那强行上这套东西反而会增加负担。

我见过不少人一听到“代码生成”就兴奋，觉得能省掉大量体力活。但实际用下来，t3code 这类方案能不能跑通，关键不在于生成器本身有多强，而在于你有没有把“源头定义”这件事想清楚。源头定义可以是 JSON Schema、OpenAPI 文档、Protobuf，也可以是一份手写的 TypeScript 类型文件。选哪种，直接决定了后续生成链路的复杂度和可维护性。下面我就按自己踩过的坑，把这条链路拆开来讲。

2. 源头定义选型：为什么我最终放弃了手写类型文件

2.1 三种常见源头定义的对比

在 t3code 的实践里，源头定义是整个体系的基石。我先后试过三种方式：手写 TypeScript 类型文件、维护 OpenAPI 文档、以及用 JSON Schema 做中间层。每种方式都有它的适用场景，但坑也各不相同。

我最初选的是手写 TS 类型文件，因为觉得“反正都是 TypeScript，直接写类型多方便”。结果不到两个月就出问题了：后端加了一个字段，前端类型文件忘了改，联调时接口返回多了一个字段，前端直接报错。更麻烦的是，我想根据类型自动生成 API 请求函数，但手写的类型文件里没有路由信息，生成器根本不知道哪个类型对应哪个接口。后来我转向 OpenAPI，但手写 YAML 的体验实在太差，一个嵌套三层的对象能写上百行，改一次错一次。

最终我选择了 JSON Schema 作为中间层。具体做法是：后端用装饰器或注解从实体类自动导出 JSON Schema，前端再基于这份 Schema 生成 TypeScript 类型和请求函数。这样源头只有一个，而且 Schema 本身可以被校验，字段类型、必填项、枚举值都写得清清楚楚。虽然写 Schema 比写 TS 类型啰嗦，但它是中立的，不绑定任何语言，后续想生成 Python 客户端或者 Go 服务端都可以。

2.2 源头定义里必须写清楚的几个字段

不管你选哪种方式，有几个字段是必须写清楚的，否则生成出来的代码一定会有问题。第一个是字段的可选性。很多人只写类型不写是否必填，生成出来的 TS 类型全是可选的，前端用的时候到处都要判空。第二个是枚举值。如果某个字段只能是几个固定值，一定要在源头定义里列出来，生成器才能生成联合类型或枚举。第三个是字段的格式化信息。比如日期时间格式、字符串长度限制、数字范围，这些信息如果不在源头定义里，生成出来的表单校验就得手写。

我吃过一次亏：一个金额字段，源头定义里只写了number，生成出来的前端表单允许输入负数，后端也没做校验，结果测试时发现有人填了-100，直接导致对账逻辑出错。后来我在 Schema 里加了minimum: 0，生成器自动在表单校验里加上了最小值限制，问题才解决。所以源头定义不是“有个类型就行”，而是要把业务约束也写进去。

2.3 版本管理与变更流程

源头定义一旦成为多端代码的生成依据，它的变更就不能随便来了。我建议把源头定义文件单独放在一个仓库里，或者至少放在一个独立的目录下，用 Git 做版本管理。每次修改都要走 Pull Request，并且 CI 里要跑一遍生成流程，确保生成的代码能编译通过。如果生成出来的代码有冲突，说明源头定义的变更影响了下游，必须人工介入。

我们团队现在的做法是：源头定义仓库的每次合并都会触发一个流水线，自动生成前端类型、后端 DTO、API 客户端，并分别提交到对应的业务仓库里。业务仓库的开发者只需要拉取最新代码，不需要自己跑生成脚本。这样既保证了同步，又避免了每个人本地生成结果不一致的问题。

3. 生成器怎么写：从模板引擎选型到自定义逻辑注入

3.1 模板引擎的选型逻辑

生成器的核心是模板引擎。我试过 Handlebars、EJS、Mustache 和 TypeScript 自带的模板字符串。Handlebars 的逻辑控制比较弱，写复杂条件时很别扭；EJS 可以直接写 JavaScript，灵活但容易把业务逻辑混进模板里；Mustache 更简单，但连个像样的循环嵌套都写得很痛苦。最后我选了TypeScript 模板字符串 + 自定义函数的方案。原因很简单：生成器本身就是用 TypeScript 写的，模板里需要的数据处理逻辑可以直接用 TS 函数，不需要额外学一套模板语法。

举个例子，生成一个 API 请求函数时，我需要根据字段是否可选来决定参数签名。用模板字符串可以这样写：

function generateApiFunction(schema: JsonSchema): string { const params = schema.properties.map(p => { const optional = p.required ? '' : '?'; return `${p.name}${optional}: ${mapType(p.type)}`; }).join(', '); return ` export async function ${schema.name}(params: { ${params} }) { return request('${schema.path}', { method: '${schema.method}', data: params, }); } `; }

这种写法虽然看起来不如模板文件优雅，但调试起来非常直接，断点一打就能看到每一步生成的内容。而且类型提示完整，写错了编译器会告诉你。

3.2 自定义逻辑注入的三种方式

生成器不可能覆盖所有场景，总有一些特殊逻辑需要人工干预。我总结了三种注入方式，按推荐程度排序。

第一种是在源头定义里加扩展字段。比如某个接口需要特殊的请求头，可以在 Schema 里加一个x-custom-headers字段，生成器读到这个字段就自动加上。这种方式最干净，因为所有信息都在源头定义里，生成器只是解释执行。

第二种是在生成器里加钩子函数。比如生成完一个文件后，允许调用一个postProcess函数，对生成结果做字符串替换或追加内容。这种方式适合处理一些全局性的调整，比如统一添加文件头注释、修改导入路径。

第三种是生成后手动修改。这是最不推荐的方式，因为下次重新生成时手动修改会被覆盖。如果实在需要，可以把手动修改的部分单独放在一个文件里，生成器只负责生成基础部分，然后通过继承或组合的方式引入手动逻辑。

我现在的做法是：能通过扩展字段解决的，绝不写钩子；能用钩子解决的，绝不动生成结果。这样保证了生成流程的可重复性，任何人拿到源头定义和生成器，跑出来的结果都是一样的。

3.3 生成结果的目录结构与命名规范

生成出来的代码放在哪里，命名怎么定，这件事看起来小，但直接影响后续的维护体验。我见过有人把所有生成的文件都放在一个generated目录下，结果目录里几百个文件，找起来非常痛苦。我的建议是按业务模块分目录，每个模块下再按类型分。

比如：

src/ generated/ user/ types.ts api.ts validators.ts order/ types.ts api.ts validators.ts

命名上，我习惯用types.ts放类型定义，api.ts放请求函数，validators.ts放校验逻辑。这样不管打开哪个模块，文件名都是一致的，找东西很快。另外，生成的文件头部一定要加注释，标明“此文件由 t3code 自动生成，请勿手动修改”，避免不知情的人直接改生成结果。

4. 类型安全链路：从源头定义到运行时校验的完整闭环

4.1 编译时类型检查的边界

t3code 这类方案最大的卖点就是类型安全，但很多人对“类型安全”的理解有偏差。TypeScript 的类型检查只发生在编译时，运行时拿到的 JSON 数据并不受类型系统保护。也就是说，即使你从源头定义生成了完美的 TS 类型，如果后端返回的数据结构和定义不一致，前端照样会在运行时出错。

我遇到过好几次这样的情况：源头定义里某个字段是string，但后端实际返回了null，前端代码里直接调用了.toLowerCase()，页面就白了。后来我在生成器里加了一层运行时校验，用 Zod 或 io-ts 这类库，根据源头定义生成校验函数，在 API 响应返回后先校验再使用。这样虽然多了一步，但能把运行时错误提前暴露出来，而不是等到用户点击某个按钮才崩。

4.2 运行时校验的生成策略

运行时校验函数的生成，关键在于把 JSON Schema 的约束完整翻译成校验库的 DSL。比如 JSON Schema 里的minLength、maxLength、pattern、minimum、maximum，都要对应到校验库的规则里。我用的方案是写一个转换器，把 JSON Schema 的每个字段映射成 Zod 的 schema。

function jsonSchemaToZod(schema: JsonSchema): string { switch (schema.type) { case 'string': let zod = 'z.string()'; if (schema.minLength) zod += `.min(${schema.minLength})`; if (schema.maxLength) zod += `.max(${schema.maxLength})`; if (schema.pattern) zod += `.regex(/${schema.pattern}/)`; return zod; case 'number': let zodNum = 'z.number()'; if (schema.minimum !== undefined) zodNum += `.min(${schema.minimum})`; if (schema.maximum !== undefined) zodNum += `.max(${schema.maximum})`; return zodNum; // ... 其他类型 } }

这样生成的校验函数和类型定义是一一对应的，改了源头定义，两边都会更新。实测下来，这套机制能拦住大部分前后端不一致的问题，尤其是字段类型和必填项的变化。

4.3 错误信息的可读性处理

运行时校验报错时，默认的错误信息往往很机械，比如“Expected string, received null”。这种信息给开发看还行，但如果直接展示给用户，体验就很差。我的做法是在生成校验函数时，把字段的中文名称也带进去。源头定义里加一个title或description字段，生成器把它作为错误信息的一部分。

比如：

z.string({ required_error: '用户名不能为空' }) .min(3, '用户名至少3个字符')

这样用户看到的提示就是“用户名至少3个字符”，而不是“String must contain at least 3 character(s)”。这个细节看起来小，但能省掉很多前端手动写提示文案的时间。

5. 实际落地时最容易被忽略的三个坑

5.1 循环依赖与生成顺序问题

当源头定义里的类型互相引用时，生成器很容易陷入循环依赖。比如 A 类型引用了 B，B 又引用了 A，生成出来的 TS 文件里就会出现import循环，导致运行时某个类型是undefined。我一开始没注意这个问题，直到某个页面在开发环境正常，打包后却报“Cannot read property of undefined”，排查了半天才发现是循环引用。

解决办法有两个：一是生成时做拓扑排序，把没有依赖的类型先生成，有依赖的后生成；二是对于确实需要互相引用的类型，用 TypeScript 的import type语法，这样编译后不会产生实际的模块引用。我现在的生成器里加了一个依赖分析步骤，遇到循环引用会直接报错，提醒我去源头定义里调整结构。

5.2 生成文件的 Git 冲突处理

生成的文件要不要提交到 Git？这个问题我纠结了很久。提交的话，每次重新生成都会产生大量 diff，合并分支时冲突不断；不提交的话，新克隆仓库的人必须记得跑生成脚本，否则代码编译不过。我最后的方案是：生成文件提交到 Git，但在.gitattributes里标记为linguist-generated，并且在 CI 里加一个检查，确保生成文件和源头定义是同步的。如果不同步，CI 直接失败，提示开发者先跑生成脚本。

另外，生成文件的 diff 尽量保持稳定。比如字段顺序按字母排序，不要每次生成都变。这样即使有冲突，也容易看出是哪个字段变了。

5.3 团队协作中的认知对齐

技术方案再好，如果团队里有人不按规矩来，照样会出问题。我见过有人在生成的文件里直接改代码，结果下次生成被覆盖，跑来问我“为什么我的修改没了”。也见过有人绕过生成器，手写了一套 API 请求，导致同一个接口有两套调用方式。

我的经验是：在项目初期就把规矩定死，并且用工具强制约束。比如在生成文件的头部加注释，在 CI 里加检查，在代码评审时重点关注有没有人手动改生成文件。另外，定期给团队做分享，讲清楚 t3code 的链路和原理，让大家理解为什么不能手动改。认知对齐这件事，花再多时间都值得。

6. 从 t3code 延伸出去：这套思路还能用在哪里

t3code 本质上是一种“定义一次，多处生成”的工程化思路。这套思路不局限于 TypeScript，也不局限于前后端代码生成。我在实际工作中把它延伸到了几个其他场景，效果也不错。

第一个场景是数据库迁移脚本生成。把数据库表结构定义成 JSON Schema，然后生成 SQL 迁移文件、ORM 实体类、以及数据校验规则。这样改表结构时只需要改一处，所有相关代码自动更新。

第二个场景是文档生成。源头定义里已经包含了字段名称、类型、描述，直接生成 Markdown 格式的 API 文档，比手写文档省事得多，而且不会和代码脱节。

第三个场景是测试数据生成。根据源头定义里的类型和约束，自动生成符合要求的测试数据。比如字符串字段生成随机字符串，数字字段生成范围内的随机数，枚举字段随机选一个值。这样写单元测试时就不用一个个手动构造数据了。

这套思路的核心在于：找到那个“唯一真相来源”，然后围绕它构建自动化的生成链路。t3code 只是这个思路在 TypeScript 全栈场景下的一个具体实现。如果你正在维护一个多端项目，手写重复代码让你痛苦不堪，不妨试试这个方向。但记住，源头定义的设计比生成器本身更重要，想清楚再动手，能省掉后面很多返工。