T3Code实战：以OpenAPI为唯一契约源，一键生成TypeScript类型、请求与Mock数据

前后端联调的痛干过几年的朋友基本都懂。最折磨人的不是接口报错而是报错以后你跟后端对字段名发现两边都有点道理后端说他 DTO 里就叫createdTime前端代码里写的是createTime接口文档上却写着create_time。同一个字段三个地方三个名字整个下午就这么耗没了。这种问题在团队规模上来之后几乎是日常靠人肉对齐效率低还容易漏。T3Code 就是我们为了解决这类问题在团队内部做出来的一个小工具后来抽成了独立项目。它全称是 Three-Tier Code Generator核心逻辑很单纯拿一份 OpenAPI 3.0 接口描述当唯一输入自动生成前端日常要用的三类代码——类型定义、请求封装和 Mock 数据。这篇文章我会从设计思路、核心细节、落地实操到常见坑位完整拆一遍。适合被接口联调折磨的前端、全栈开发以及正在选型代码生成工具的团队。1. 项目定位与整体思路拆解1.1 为什么需要一个专门的代码生成器先说清楚我们要解决的问题到底是什么。团队里的接口契约正常情况下应该只有一份实际却常常散落成三份后端的 DTO、前端的 interface、写在外置文档里的字段说明。后端加一个字段文档可能记得改前端没人通知等联调时候报错才知道。接口一多这种错位就是无底洞。有人会说这不是有 Swagger 吗有但大多数团队只是把它当成在线文档看一眼没有让它真正驱动代码。开发流程里依然有人工拷贝 schema、手写请求函数的工作。手写请求函数本身不算难但它属于高重复、易出错、又不需要什么创造力的活最适合交给程序去生成。我们当然也评估过现成的开源工具比如 OpenAPI Generator、swagger-codegen。它们功能很全面但正因为太全面落到我们场景里反而不顺手。它们面向的是所有语言、所有框架生成一大坨工程骨架前端项目往往只需要其中很小一部分而且生成的代码风格跟团队手写的代码风格经常冲突想定制一个模板费老半天劲。T3Code 的定位从一开始就是克制的只做三件事类型定义、请求封装、Mock 数据。生成的产物少而精团队消化起来几乎无感。1.2 T3 三层的含义与边界T3Code 里的 T3指的是生成的代码按三个层级拆分这也是整个工具设计上最核心的一条线。第一层是 Types。把 OpenAPI 里的components.schemas和所有请求响应结构映射成 TypeScript 的interface或type。这一层是给编辑器用的让 IDE 能提示字段、检查类型把错误尽量挡在编译期。第二层是 Services。每个operationId生成一个请求方法方法内部负责拼接 URL、处理 query、请求体序列化最终返回一个 Promise类型上挂到对应的 Types。第三层是 Mocks。根据 schema 里的示例值或者字段类型生成一份可用的模拟数据方便前端在后端接口还没就绪时跑业务流程。为什么是这三层而不是更多因为业务代码真正直接依赖的就这三样。有人建议把路由定义、表单校验规则也生成出来我试过结果得不偿失——生成的代码越贴近业务抽象定制需求就越多模板会变得越来越复杂。T3Code 故意保持简单就是把“最容易出错的机械部分”生成好剩下的业务自定义留给开发者自己写。1.3 技术选型背后的思考工具本身是用 Node.js TypeScript 写的。选这个组合没什么悬念前端团队天生熟悉生态也成熟。解析 OpenAPI 文件我们站在了swagger-parser的肩膀上它能把一份 YAML 或者 JSON 描述文件解析成完整的 JavaScript 对象还顺带处理掉大部分$ref引用省去很多自研解析器的麻烦。模板渲染没有引入 handlebars 这类重型模板引擎。T3Code 的产物结构相对稳定变量替换和简单循环就够用所以我自己写了一套轻量的模板函数大概两百行。好处是依赖少、安装快排查问题能一行行看下去。缺点也很明显写复杂模板的时候表达力不如 handlebars但权衡下来可维护性更重要。请求封装层默认依赖一个http适配器不绑定 axios 还是 fetch配置文件里可以指定自己的请求函数路径。为什么要留这个口子因为每个团队的数据请求层都有自己的封装有的统一处理登录态、有的统一做错误统计强行生成一个不兼容的请求层接入成本会很高。2. 核心细节解析与实操要点2.1 一份靠谱的 OpenAPI 描述文件是一切的前提用 T3Code 之前最先要确认的不是工具安装而是你的接口描述文件质量。工具的能力上限取决于输入描述文件的完整度。后端如果给一份字段缺失、参数没标类型的 YAML生成的代码自然也是残缺的。一份最少可用的描述文件长这样openapi: 3.0.3 info: title: user-service version: 1.0.0 paths: /users: get: operationId: getUsers summary: 获取用户列表 parameters: - name: page in: query required: false schema: type: integer responses: 200: description: OK content: application/json: schema: $ref: #/components/schemas/UserList components: schemas: User: type: object required: - id - name properties: id: type: integer name: type: string注意operationId这个字段。T3Code 生成的服务方法名默认就是拿它转成小驼峰格式比如getUsers。如果描述文件里漏写了工具会退化成用 HTTP 方法和路径拼一个方法名比如get_users这个说法有点丑但能用。长远的建议是跟后端约定好所有operationId必须提供并且全局唯一。这是整个工具落地最有效的一个规则。responses部分同样重要。200状态码下的 schema会决定服务方法的返回值类型。团队里常见的问题是只写成功响应不写错误响应。这样生成出来的类型没有错误分支只能靠运行时去兜底。更合理的做法是把常见错误码的基础结构定义成公共组件复用而不是每个接口单独写。2.2 类型映射与命名规则OpenAPI 的基础类型和 TypeScript 不是一一对应的这一步必须在模板里做一层映射。OpenAPI Schema 类型TypeScript 类型备注integernumber不区分 int32/int64numbernumberfloat/double 均映射 numberstringstring不区分 formatbooleanboolean无arrayArrayTT 取 items 映射后的类型object带propertiesinterface字段名字不做改动$ref引用对应类型名需要预先注册所有组件这里有个关键坑字段的必填性。OpenAPI 对象里有required数组只有列在里面的字段才是必填。T3Code 处理时会检查这个数组命中的字段不加?没命中的自动加?。很多团队把 schema 的required写漏了导致生成出来的所有字段都是可选使用时反而发现不了字段缺失的问题。命名规则上我们做了一套保守但统一的转换。schema 组件名保持原样方法名按operationId小驼峰文件名则按模块名拆目录。比如/users/{id}这个路径里的{id}会被解析成id这个路径参数模板里生成的请求方法接受一个对象参数{ id }。路径参数的字段名转换官方规范里没有强制标准所以 T3Code 默认转成 camelCase配置里可以改成 snake_case。2.3 目录与文件名设计生成代码的目录结构直接决定了三个模块之间如何引用、以及在 Git 仓库里怎么管理。我们默认的输出结构是这样src/generated/ types/ user-service/ user.ts services/ user-service/ user-api.ts mocks/ user-service/ user.ts按服务名拆一层目录而不是把所有的接口放一个文件夹里这是从实践里总结出来的经验。多个后端服务并行开发时每个服务对应一个目录互不干扰。如果设计成平铺的单文件几十个接口都塞在同一个 index.ts 里合并冲突几乎无法避免。模板之间的引用关系也要提前想清楚。Types 目录里的user.ts可以独立编译Services 目录里的请求方法会 import 上一层的类型。Mocks 依赖 Types 的字段结构但需要提供一个手动调整的入口——自动生成的 mock 数据只能保证字段完整没法保证业务上合理。比如一个phone字段模板默认生成字符串string这显然不像真实号码这时候需要你在生成的 mock 文件里改一手或者提供一个覆盖模板的钩子。2.4 模板定制什么时候动什么时候别动T3Code 内置的模板已经能满足大部分 Web 项目但每个团队都有自己的代码风格免不了要改。工具支持传一个自定义模板目录里面的文件会覆盖内置模板的同名文件。我的建议是只改两个东西。第一个是请求函数的外层形态。有些团队所有请求都要过自己封装的request模板里就要把http.get替换成request.get甚至替换成axios(config)的形式。第二个是 import 路径风格。比如项目里配置了指向 src 目录模板里的相对路径就得改成别名。除此之外不要过于激进地定制。有人想把每个接口都生成一个带缓存逻辑的钩子函数我理解这种冲动但缓存策略、重试策略属于业务运行时逻辑不同页面需求差异很大硬塞进模板会产生一堆配置开关。生成层保持“无业务逻辑”是你后续维护这个工具最省心的姿势。T3Code 把模板的职责限定在代码排版和基础调用上业务行为留给开发者。3. 实操过程与核心环节实现3.1 安装与初始化先把工具装到全局或者用 npx 直接跑。我更推荐把脚本写进package.json这样团队成员不需要全局安装。npm install -g t3code # 或者 npx t3code initinit会在当前目录生成一个t3code.yaml配置文件内容大致是input: ./openapi.yaml output: ./src/generated services: - user-service requestFile: ./src/http/request.ts typesStyle: interface mock: trueinputOpenAPI 描述文件路径支持 YAML/JSON。output生成产物的根目录。services需要生成的服务模块列表写错会直接跳过。requestFile自定义请求适配器的路径生成的 service 会从这里面导入请求方法。typesStyle基础类型用 interface 还是 type。mock是否生成 mock 目录。配置文件本身很轻。没有引入一串必填项就是为了让团队能在十分钟之内跑通。3.2 写一份带业务味的接口描述光看最小示例不过瘾来一个更贴近实际的。假设我们要生成一个“创建用户”的接口paths: /users: post: operationId: createUser summary: 创建用户 requestBody: required: true content: application/json: schema: $ref: #/components/schemas/CreateUserRequest responses: 200: description: OK content: application/json: schema: $ref: #/components/schemas/User components: schemas: CreateUserRequest: type: object required: - name - email properties: name: type: string example: 张三 email: type: string format: email age: type: integer example: 28注意到CreateUserRequest里name和email在required数组中age不在。这意味着生成的创建用户请求体类型name和email必填age可选。工具还会读取example字段把它写到 Mock 数据里mock 资料的可用性立刻提升不少。3.3 执行生成与产物检查命令行执行t3code generate对着上面的配置和描述文件生成结果大概是这样的。类型定义部分export interface CreateUserRequest { name: string; email: string; age?: number; }服务封装部分import { http } from ../../http/request; import { CreateUserRequest, User } from ../types/user; export class UserApi { createUser(data: CreateUserRequest): PromiseUser { return http.post(/users, data); } }如果后端写文档时operationId用了create_user工具默认也会转成createUser。检查产物时重点看两处字段是否都在、方法返回类型是否和响应 schema 对应。如果不对第一处怀疑永远应该是输入描述文件而不是模板。3.4 接入业务代码与 Mock 切换接入过程比想象中顺滑因为生成的代码就是普通 TypeScript直接 importimport { UserApi } from /generated/services/user-service/user-api; const api new UserApi(); const res await api.createUser({ name: 张三, email: testexample.com });类型推导会跟你项目里手写的代码完全一致不需要做任何桥梁层。这里我强烈建议在生成的services目录里只做导入和导出不要改生成文件本身。上次有个同事为了修一个字段名直接改了user-api.ts下一轮生成就把改动覆盖了查了好久才发现是生成产物被手工修改过。Mock 切换是 T3Code 比较顺手的一个点。工具会生成一个mock目录里面放着模拟数据。运行时的判定逻辑也很简单读环境变量T3CODE_MOCK为true时请求适配器走内存里的 mock 数据否则走真实接口。这样前端在接口还没就绪时不用改业务代码只换环境变量。真正上线时只要确保环境变量不设置生产环境就不会加载任何 mock 文件。接业务代码时有个小教训mock 数据文件不要直接 import 到业务组件里而是让请求适配器在初始化时一次性读取否则你会在多个组件里看到if (mock) return mock...这种分支时间一长到处都是沼泽。4. 常见问题与排查技巧实录4.1 生成的类型和后端 DTO 对不上这是出现频率最高的问题。通常现象是前端拿着生成的 interface 去调接口结果后端返回里多了个字段前端类型里没有。排查方向只有两个后端是不是没有把新字段更新到 OpenAPI 描述文件或者描述文件没有重新提交。这个问题的根子不在 T3Code在契约流程。我试过有效的一个约定是后端接口变更时必须同时提交 OpenAPI 描述文件并且由前端或工具生成后做一次 diff。这个动作应该进 Code Review 检查项而不只是靠口头提醒。4.2$ref嵌套解析异常OpenAPI 里组件互相引用很正常但嵌套层级过深时解析偶尔会出问题。尤其是自引用结构比如一个树形节点的children引用自身。T3Code 目前对循环引用能处理到第一层但深层循环会导致生成的 interface 循环报错。处理办法是手动限制一下递归深度或者在描述文件里把多层嵌套拆成扁平结构不要写成无底递归。团队里最常见的是三层嵌套A 引用 BB 引用 CC 引用 A。这种在代码生成时容易绕晕。我的建议是把最底层的 C 从引用中拆出来单独平铺成id、name这类标量字段有必要再维护一张关联表。这么改虽然牺牲了一点描述的严谨性但生成代码的可读性和稳定性提升很大。4.3 自定义模板渲染结果不对自定义模板时最常踩的坑是修改了线上文件执行生成却看不到变化。要记住T3Code 的模板读取是静态的模板目录是启动时加载一次不是热更新。每次改完模板重启生成进程。另外模板里的变量名和数据的字段名对不上的概率很高我习惯在模板里写调试输出比对当前上下文里的键。这事不高级但排查效率比逐一猜变量名高得多。4.4 Git 合并冲突集中爆发生成产物要不要提交进 Git 仓库两种策略我都试过。提交的好处是前端同事可以立即看到类型变化坏处是每次生成都会产生大量 diffReviewer 压力大不提交的话新克隆仓库的人要自己跑一遍生成命令如果本地缺依赖环境配置问题又会冒出来。我目前的习惯是提交但在项目里加一道约束生成产物禁止手工修改并通过 lint 规则禁止在生成的目录中写业务代码。提交后合并冲突基本不可避免但冲突内容大多只是接口字段变化解决起来比业务合并简单得多。配合 CI 里的一步校验——跑t3code generate --check如果产物与预期不一致直接让流水线失败——从机制上防止“有人改了生成文件”这种情况。下面用一张表把常见问题整理成速查现象可能原因排查与处理生成的 interface 缺字段schema 的 properties 缺失检查描述文件补全 properties可选字段全部变成必填required数组没维护核对required将非必填移出服务方法名不符合预期缺少operationId补全operationId或调整命名规则mock 数据业务上不合理直接信了默认生成的假数据手动覆盖 mock 目录下的产物模板改了没生效模板目录路径错了或未重启确认配置路径重新执行生成生成时找不到请求适配器requestFile路径与实际不符更正requestFile确保导出http4.5 请求适配器对接的细节requestFile这个配置很容易被忽略但它是整个生成代码能够跑通的关键。默认情况下生成的 service 会从相对路径导入http对象而http是你项目里真实的请求模块。团队里每个人的请求模块可能长得不一样有的导出的是实例有的导出的是一个函数集合。T3Code 约定生成的代码只依赖http.get、http.post这类方法所以你的适配器这层需要稍微包一层统一接口。这个约定不复杂但值得在团队文档里单独写清楚请求适配器需要暴露get、post、put、delete方法每个方法签名是(url, data?, config?) PromiseT。只要保证这个形状T3Code 生成的代码就像接到一个标准插头上。5. 价值边界与我的实际体会5.1 什么情况下别用它工具不是银弹。如果项目接口数量很少几十个 CRUD手写请求函数反而更快引入生成器只是给自己增加配置成本。如果后端连一份像样的 OpenAPI 描述文件都维护不出来那首要是治理接口文档而不是急着搞代码生成。T3Code 在接口描述混乱的团队里生成出来的代码只是把混乱原样复刻了一遍不会带来质变。另外如果团队前端技术栈高度不一致有人用 class 风格有人用函数组件加 hooks生成器就会很被动因为一套模板只能满足一种主流风格。这种情况我建议不要强推全局统一生成先集中在核心业务模块试点等风格收敛后再扩大范围。5.2 后续还能怎么扩展说几个我列在 roadmap 上但暂时没动手的方向供有同样需求的朋友参考。第一是支持更多模板预设。很多人问能不能生成 React Query 版本让每个接口直接生成一个 Query 调用。这确实有需求但需要动模板渲染层和类型推导的接口得等到模板插件机制稳定以后再做。第二是增加接口变更 diff 的提示。目前只能靠生成后比对代码希望工具在生成时直接输出新增字段和废弃字段的清单方便前端评估影响范围。第三是支持多输入文件合并。一个团队可能有多个服务多个文件现在只能逐个生成以后想统一入口这个功能会很受欢迎。5.3 踩过几次坑之后的真实感受给还在观望的团队一个建议先把一个模块端到端跑通再决定是全量推行还是局部使用。T3Code 帮我们把接口联调的摩擦降低了不少但真正让局面变好的是流程约定本身——接口描述文件成为契约的唯一源头。生成的代码只是把这个契约用机器的方式固化了下来。工具本身要做到的是尽量不打扰团队已有的开发习惯。它不要求你把代码结构推翻重来也不要求你改变请求框架。生成出来的就是普通的 TypeScript 文件你可以正常 import、正常测试、正常交给 CR。这种“低侵入”的克制反而是它能被大家接受并长期用下来的原因。如果你刚好也在为接口三处不同步头疼不妨拿一个小模块试一下感受应该会很直观。