t3code 这个名字最早是我在内部项目里顺手起的代号后来整条业务线都按这套路子在写代码。说得直接一点它不是一个现成的开源框架而是一套关于“怎么把代码写稳”的工作流类型先行、测试并行、可追踪性贯穿始终。这三件事单独拎出来团队里没人反对但真正落地的时候问题一大堆类型定义和接口文档脱节测试覆盖率看着还行但关键链路一个没罩住日志倒是打了不少线上出问题还是要靠人肉翻半天。t3code 想做的事就是把这三件“重要但不紧急”的事通过模板、脚本和流水线强制固化下来不依赖个人的自觉性。这篇文章不聊虚的直接从项目设计思路拆起到每一步的实操配置、参数取舍、踩过的坑最后附上排查实录。无论你是正在搭新工程的技术负责人还是想给自己项目建立规范的个人开发者里面大部分内容都能直接抄作业。1. 内容整体设计与思路拆解1.1 为什么是“类型、测试、可追踪”这三件事选这三个维度不是拍脑袋决定的。我统计过我们团队过去一年线上故障的归因排名前三的分别是接口字段对不上导致运行时才报错、改动老代码后回归漏测、以及日志信息不足导致故障定位耗时过长。这三个问题恰好可以被三种手段分别抑制静态类型系统能在编译期拦截接口字段错位测试能在发版前兜住回归风险结构化的可追踪数据能在故障发生时快速缩小排查范围。t3code 的第一条设计原则就是不让这三件事互相孤立。类型定义直接作为接口契约的单一数据源测试用例从类型派生出的 mock 数据来构造场景埋点字段复用同一套类型声明。这样类型系统就不再只是“少写 bug”的工具它变成了整个工程质量体系的锚点。1.2 与常规工程模板的核心差异市面上有不少开源的 monorepo 模板、脚手架通常做的事是帮你把目录建好、依赖装好、lint 配好。t3code 的思路不太一样它更看重“约束的时机”。对比维度常规模板t3code类型约束tsconfig 开 strict靠人自觉遵守schema 驱动自动生成类型接口改动不更新 schema 直接编译失败测试约束提供测试框架示例强制为每个业务模块生成测试骨架覆盖率未达阈值阻断合并可追踪性建议打日志统一封装 track 函数日志结构、脱敏规则、采样策略全部内置约束生效点代码评审时靠人看提交前钩子 CI 流水线自动拦截这个差异的本质是把“约定”变成“配置”。人总会疲劳、会漏看但是机器不会。凡是能自动化拦截的问题就不要留到评审阶段用嘴去吵。2. 核心细节解析与实操要点2.1 类型先行的具体落地方式类型先行不是简单地把 TypeScript 的 strict 模式打开而是要让“类型”成为系统里最权威的契约文档。我建议的顺序是先定义数据 schema再让类型从 schema 里自动推导最后让接口层和存储层都消费这同一份类型。这一步我用的工具是 Zod。原因很直接Zod 既能在运行时校验数据又能通过z.infer推导出 TypeScript 类型。一份 schema 同时服务两个场景省掉了“手写一套类型、再写一套校验”的重复劳动。// user.schema.ts import { z } from zod; export const UserSchema z.object({ id: z.string().uuid(), name: z.string().min(1).max(50), email: z.string().email(), role: z.enum([admin, editor, viewer]), createdAt: z.date(), }); export type User z.infertypeof UserSchema;所有接口的入参、出参都从这套 schema 里派生。如果产品要加一个字段改 schema然后tsc会告诉你哪个接口、哪个组件还没适配。注意Zod 的版本升级有时会带来 infer 类型细节的变化建议把 zod 版本锁死至少在业务核心库里不要追最新。tsconfig 里除了strict: true我强烈建议额外开启两个选项。配置项作用代价noUncheckedIndexedAccess访问数组或索引类型时结果类型自动带上undefined逼着你处理越界刚开始会报很多错exactOptionalPropertyTypes可选属性不允许显式赋undefined消除“有值和没有值”的语义混淆这两个配置刚开的时候老代码会红一片我当时花了大概一天时间消化。但修完之后运行时“Cannot read properties of undefined”这类报错肉眼可见地减少。2.2 测试并行的策略选择测试最怕的不是写不完而是写了之后没人维护、跑得又慢最后大家选择性地不看测试结果。t3code 在测试维度上制定了两条硬规矩分层明确、快慢分离。分层明确指的是单元测试、组件测试、端到端测试的责任边界不能混。单元测试只管纯函数和工具方法组件测试用 Testing Library 模拟用户交互端到端测试只覆盖关键业务流程主链路。快慢分离则是为了开发体验。所有单测和组件测试加起来必须在 2 分钟内跑完跑在提交前端到端测试放在 CI 的夜间流水线不阻塞本地提交。这样既保证了反馈速度又不会让开发者为漫长的 E2E 等待而焦虑。2.3 可追踪性的统一入口日志这件事最怕的就是每个开发按自己的风格打。有人打中文有人打英文有人把敏感信息打全有人连字段名都懒得起。t3code 的做法是封装唯一的track函数所有日志和埋点必须走这一个入口。// track.ts import { v4 as uuid } from uuid; interface TrackEvent { event: string; [key: string]: unknown; } export function track(event: string, data: Recordstring, unknown {}) { const safeData maskSensitiveFields(data); console.log( JSON.stringify({ ts: new Date().toISOString(), traceId: getTraceId(), event, data: safeData, }) ); } function maskSensitiveFields(data: Recordstring, unknown) { const DENY_LIST [password, token, secret, idCard]; const masked { ...data }; for (const key of Object.keys(masked)) { if (DENY_LIST.some((k) key.toLowerCase().includes(k))) { masked[key] ***; } } return masked; }这个封装的价值在于它把“怎么打日志”从一个开放问题变成了选择填空题。后端的 traceId 从请求中间件里取前端的 traceId 在入口处生成一次前后端通过这个 ID 串联整条链路。3. 实操过程与核心环节实现3.1 工程目录结构的搭建一个标准 t3code 项目我一般建议采用 pnpm workspace 的 monorepo 结构这样类型、规则、公共工具都能跨包复用。apps/ web/ # 前端应用 api/ # 后端服务 packages/ schema/ # zod schema 与类型定义 track/ # 统一日志埋点封装 config/ # 共享的 tsconfig / eslint 配置 test-utils/ # 测试工具和 mock 工厂packages/schema 是整个仓库的契约中心apps 下的两个应用都只能依赖它导出的类型不允许直接定义跨端共享的接口类型。这个约束通过 eslint 规则no-restricted-imports来强制。// eslint.config.js export default [ { rules: { no-restricted-imports: [ error, { patterns: [ { group: [../../common/*], message: 请从 packages/schema 中引入共享类型, }, ], }, ], }, }, ];3.2 提交前钩子的配置实践提交前钩子我用的是 husky lint-staged但比大多数模板多配了一步在 commit 前自动对本次改动的 schema 做一次编译校验。# .husky/pre-commit pnpm exec lint-staged pnpm exec tsc --noEmit -p tsconfig.json pnpm exec vitest run --changed这里面vitest run --changed是很有用的一个参数它只跑本次变更涉及的文件相关联的测试。我在刚开始推广 t3code 时最大的阻力就是“测试太慢”自从改成增量运行之后提交前检查基本能控制在 30 秒内团队接受度立刻上来了。3.3 CI 流水线的关键节点配置CI 流水线我分成三个阶段校验、测试、构建部署。stages: - validate - test - build validate_job: stage: validate script: - pnpm install --frozen-lockfile - pnpm lint - pnpm tsc --noEmit test_job: stage: test script: - pnpm vitest run --coverage coverage: /All files[^|]*\|[^|]*\s([\d\.])/ rules: - if: $CI_PIPELINE_SOURCE merge_request_event build_job: stage: build script: - pnpm build这里有一个我在实际运行里总结出来的小经验流水线里的测试阶段只跑单测和组件测试E2E 单独开一条定时流水线在夜间跑。原因很简单E2E 对测试环境稳定性要求很高任意外部服务抖动都会误报放在夜间排障压力小得多。3.4 覆盖率阈值的设定逻辑覆盖率阈值不是拍脑袋定的我参考了团队过往 bug 分布核心业务模块的变更频率和缺陷密度明显高于普通工具模块。所以 t3code 对覆盖率不做一刀切。// vitest.config.ts export default { coverage: { provider: v8, include: [apps/**/src/**/*.{ts,tsx}], exclude: [**/*.test.ts, **/*.d.ts], thresholds: { // 老模块逐步放宽新模块卡紧 apps/api/src/modules/common/**: { lines: 60, functions: 50, }, apps/api/src/modules/checkout/**: { lines: 85, functions: 80, }, }, }, };跑了一段时间之后我发现把覆盖率配成“按目录区分”是最灵活、也最容易被团队接受的方案。核心交易链路卡 85% 以上冷门工具函数放低到 50%既能守住重点又不搞形式主义。4. 常见问题与排查技巧实录4.1 schema 改了但类型没生效这是最常遇到的问题。代码看着没问题tsc也不报错但新字段就是没有类型提示。排查顺序确认packages/schema是否已经重新构建。pnpm workspace 里如果用了dist输出依赖方消费的是产物而不是源码必须保证构建脚本执行了。确认 tsconfig 里的paths映射没有指向旧的构建目录。重启一下 TS Server。这个听上去很蠢但在 monorepo 里真能解决很多“离奇”问题尤其是在 VSCode 里改了某个依赖包的类型定义之后。4.2 覆盖率报告和本地不一致我遇到过几次 CI 上显示覆盖率达标但本地跑出来不达标的情况。原因通常是暂存区里还有未提交的测试文件或者是 vitest 的include配置没把新加的测试目录纳进去。这类问题我给的统一建议是本地执行命令前先git stash未跟踪文件跑完再恢复确保本地环境和 CI 看到的文件集合一致。4.3 日志里有敏感字段漏网maskSensitiveFields函数里的关键词匹配挡不住“把邮箱作为 key”这种情况。有一次排查线上问题时发现邮箱被完整打进了日志就是因为同事把字段名写成了user_email关键词列表里的email确实能匹配这个名字打了个***。但如果是嵌套对象里的非标准命名就有漏出去的风险。后来我们把脱敏策略从关键词黑名单改成了“白名单模式”默认所有字段都视为敏感只有显式声明为可公开的字段才允许输出。安全系数高了很多代价是刚开始使用 track 时得多写几个白名单。现象可能原因解决办法字段没有类型提示workspace 包没重新构建执行 packages/schema 的 build 脚本覆盖率达标但提交失败CI 与本地执行文件集合不一致临时保存未提交文件后重新执行日志出现敏感信息关键词黑名单没覆盖到的字段名切换为白名单脱敏策略测试运行时间过长单测和 E2E 混在同一流水线按分层拆分不同时段的流水线提交前检查经常被跳过钩子脚本执行失败被人为绕过把检查逻辑同步挪到 CI 强制环节4.4 开发阶段临时绕过类型约束业务催得紧的时候一定会有同事问能不能先as any顶一下后面再补类型我的态度是可以用但必须留下痕迹并且不能出现在核心业务模块里。我们的 eslint 配置里有一条规则核心业务目录下禁用as any普通工具目录下允许但要求注释说明原因。这等于在类型安全和交付速度之间留了一个有管理的缓冲地带而不是要么绝对禁止导致大家满天飞的ts-ignore要么彻底放开。// eslint.config.js { rules: { typescript-eslint/no-explicit-any: [ error, { fixToUnknown: false }, ], }, overrides: [ { files: [apps/web/src/modules/checkout/**], rules: { typescript-eslint/no-explicit-any: error }, }, { files: [apps/web/src/modules/common/**], rules: { typescript-eslint/no-explicit-any: off }, }, ], }5. 团队推广过程中的真实心得最后分享一点我在团队里推广这套东西的体会这可能是比技术本身更关键的环节。先从最容易见效的模块切入。t3code 刚搭建完成的时候我没有直接要求全团队迁移而是选了一个正在从零开发的新业务模块按照完整流程来跑。因为老代码的历史包袱太重完全改造的成本极高容易引发抵触情绪。新模块跑通之后大家看到了类型生成带来的开发速度和少 debug 的甜头后续推广阻力小了很多。保证文档和模板同时更新。团队最反感的就是“规则说一套模板是另一套”。我每次调整 eslint 规则或者 tsconfig 配置都会同步更新仓库里的 README 和模板仓库花不了十分钟但能避免大量“为什么我照着文档做还是报错”的低效提问。定期回看约束的合理性。t3code 跑了半年之后我们做了一次规则清理发现有两三条 lint 规则带来的噪音远大于价值。不要觉得规则定下来就不能改收敛的、被团队认可的规则才能持续发挥约束力天天产生误报的规则只会让人学会“忽略报错”反而伤害了整个体系的公信力。根据我个人经验这类工程化改造能不能成功七分在机制设计三分在技术选型。t3code 最核心的价值是把三类最常见的工程质量问题用一种统一、自动化的方式例常化处理。新同学进项目不需要先啃一堆规范文档只要按模板走交出来的代码自然满足基本要求。这种“低门槛高下限”的效果才是它真正让人觉得值的地方。
