做技术重构这半年我一直在琢磨一件事怎么用一句话告诉组里的新人什么代码算“好代码”。前几天翻团队沉淀的文档看到“t3code”这个代号突然想写点东西聊聊它。它不是一个框架也不是某个开源库而是我们内部对“第三级代码”的统称代码质量从“能跑”到“能改”再到“能演进”分三档t3code 就是最高那一档的约定。以前我们总说“代码乱”“不好维护”但每个人对“乱”的理解都不一样。后来我把这套标准拆成了三条明确的约束组里新同学照着做上手快了不少。这篇就讲讲它到底是什么、怎么落地、以及我踩过的几个坑。1. t3code的整体设计与拆分思路1.1 名字的由来为什么叫 t3codet3code 不是拍脑袋起的名字。它背后对应三个英文字母开头的单词恰好都是 TType类型是否是明确的。变量、函数参数、返回值的类型有没有被说清楚。Trace运行链路是否可追踪。一个请求进来一个任务跑完中间发生了什么能不能从日志或数据里还原出来。Test关键行为是否被测试覆盖。改动一个函数之后能不能通过一条命令确认“原来好的功能没有被改坏”。把这三个词的首字母连起来就是 T3。再加上 code就成了 t3code。这和我以前写的代码完全是两套路子。早些年我追求“代码少”一个函数恨不得塞下所有逻辑类型能不写就不写日志能省就省。表面上看文件很短真出了事故查日志查半天也定位不到根因。后来我把“少写代码”调整为“写容易推理的代码”t3code 就是从那次转变里沉淀出来的。之所以把 Type、Trace、Test 拧成一股绳是因为它们三个其实是互相成就的。类型写清楚了调用方就不需要猜测“这个参数到底是字符串还是数字”出错的概率降低链路日志打完整了线上问题能快速定位到具体分支修 bug 的时间从几小时压缩到十几分钟测试覆盖到位了重构时才敢大胆改内部实现因为回归有兜底。单看任何一条都不稀奇但把它们当作一个整体来要求代码的“可维护性”就变成可以检查、可以打分的东西了。1.2 三档代码等级能跑、能改、能演进我习惯把代码分为三个等级和 t3code 名字里的“3”刚好对应等级名称特征典型表现C1可运行功能跑得通逻辑正确本地功能测试通过但只有写代码的人敢动它C2可维护别人也敢改改了不慌变量命名清晰函数边界明确改动后能快速验证C3可演进新增需求时不需要推翻重来类型约束、链路追踪、测试覆盖三者齐全新功能是“叠加”而不是“重写”t3code 的目标不是停留在 C1而是把人带到 C2再慢慢往 C3 推。说实话很多生产环境的代码长期停留在 C1。功能验证过了交付了上线了但下一次迭代时发现想加一个字段要连带改七个地方想拆一个函数发现它的日志和业务逻辑缠在一起想跑一下测试发现测试依赖外部的真实环境没法在本地稳定通过。这些问题不会在“能跑”阶段暴露全都在“要改”的时候爆发。t3code 想解决的就是这种爆发发生的概率。1.3 它不解决什么问题任何方法都有适用边界t3code 也不是银弹。不适合一次性脚本。如果是临时跑一遍的数据清理、环境排查类型写得太严反而是负担这类场景“能跑”就够了。不适合纯算法实验。还没想清楚方案时快速验证思路比约束风格更重要等思路固定再补类型和测试效率更高。不适合交接前的突击美化。有人会在项目快交接时花一周时间给代码做“表面整容”变量名改顺眼加几个注释。t3code 强调的是日常习惯不是最后一刻的粉饰。靠补出来的规范往往在第一次迭代时就会被打破。明确了这些边界之后再来看 t3code 的三个核心细节就有抓手了。2. t3code三大核心细节解析2.1 T1 Type用类型把“隐式约定”变成“显式约束”类型是最容易被忽略、又最能降低理解成本的东西。我接手过一个模块里面大量使用data这个变量名有时它是字符串有时是对象有时又是数组。调用方靠读代码猜类型猜错了就出 bug。后来我用 TypeScript 重写把整个模块的数据流重新梳理一遍定义出清晰的接口这类问题直接消灭了。举一个最简单的对比。重构前一个查询函数可能是这样的function getOrderDetail(id) { if (!id) return null; const data fetch(/api/order/${id}); if (data data.status success) { return data.result; } return null; }这段代码有三个隐患id到底是字符串还是数字没人知道data的形态不固定前一步是响应包装后一步是业务数据status是魔法值拼错一个字母就会静默走失败分支。用 t3code 的思路改一下interface ApiResponseT { status: success | fail; result: T; } interface OrderDetail { orderId: string; amount: number; createTime: string; } function getOrderDetail(id: string): OrderDetail | null { if (!id.trim()) return null; const response await fetchOrderApi(id); if (response.status ! success) return null; return response.result; }改动点不多但效果很明显id被限定为字符串调用方传数字会直接报编译错误ApiResponseT把响应包装和业务数据分开status只有success | fail两种取值不会再出现拼错字符串的问题。这条约束背后的逻辑是人脑的记忆是有限的。三个月的代码自己都要重新读一遍如果类型信息写在代码里读代码时不需要从几十行之外往回翻找赋值逻辑。类型就是一份“看得到的数据字典”。2.2 T2 Trace让每一次状态变化都有迹可循代码出 bug 不可怕可怕的是不知道它在哪个环节出的问题。t3code 对链路追踪的要求不是“多打日志”而是“在关键节点留下可拼接的痕迹”。我见过一种反面案例所有日志都用console.log(data is , data)没有请求 ID没有时间戳没有函数名出问题之后翻日志等于在沙子里找针。一个可追踪的系统至少要有三个层次请求入口生成唯一标识。无论是 HTTP 请求、消息队列消息还是定时任务每次执行都生成一个 traceId并把它往下游传递。每个关键步骤打印结构化的上下文。包括当前函数名、入参摘要、耗时、结果状态。错误链路上保留原始错误信息。catch到错误后先记录再重新抛出或处理不要吞掉异常。举例来说我习惯这样写日志async function handleRefund(orderId: string, amount: number, traceId: string) { logger.info(refund_start, { traceId, orderId, amount }); try { const result await refundService.apply(orderId, amount); logger.info(refund_success, { traceId, orderId, refundId: result.refundId }); return result; } catch (error) { logger.error(refund_failed, { traceId, orderId, error: error.message }); throw error; } }每一条日志都带 traceId线上排查时按这个 ID 一搜整个调用链就串起来了。哪里开始、哪里结束、哪一步出错一目了然。我还给组里定过一条规矩不允许出现空 catch。以前有人写try { sync(); } catch (e) { // ignore }看起来安全实际上把问题全藏起来了。t3code 要求至少要有一条logger.warn哪怕不加修饰也要把“这里吞了一个错误”这个事实说出来。很多线上事故最初都是从一个空 catch 开始的。2.3 T3 Test为关键行为织一张回归网t3code 里的 Test不是追求行覆盖率 100%而是要求“关键路径必须有测试”。什么算关键路径用户支付成功后的回调流程、库存扣减的并发逻辑、状态机流转、金额计算的分支这些地方一个逻辑错位就是事故。至于工具函数、纯展示组件优先级可以往后放。一份测试设计可以这么组织测试对象关注点测试类型状态机流转每个合法状态迁移是否到达目标状态单元测试金额计算精度、四舍五入、负数与零值单元测试超时与重试第三方调用超时是否走 fallback集成测试异常路径重复请求、幂等处理是否符合预期集成测试另外测试要尽量做到“本地可跑通”。以前我们团队测试依赖测试环境的数据库环境一挂全组没法回归。后来把依赖 mock 掉测试 3 分钟跑完每次提交前都能刷一遍。3. t3code实操过程落地到一个订单模块3.1 起点一份典型的“能跑但难改”代码前阵子重构老订单模块当时我挑了一个典型页面功能很简单根据订单号展示订单详情。原代码长这样function detail(id) { const r request(/api/order/ id) if (r.state 1) { render({ title: r.info.title, price: r.info.price / 100, name: r.info.name || anonymous, }) } else if (r.state 2) { showError(已取消) } else { showError(加载失败) } }问题一目了然state 1、state 2是魔法数字price / 100的换算逻辑埋在渲染函数里name字段为空的默认值处理散落在多个位置。功能是好的但维护文档为零。3.2 重构步骤按 t3code 的节奏来我没有一次性把所有地方改完而是分了六步走第一步确认数据契约。把后端返回的字段画出来整理成一个 TypeScript 接口。订单状态不再是数字而是明确的枚举值。enum OrderStatus { Pending pending, Paid paid, Cancelled cancelled, TimedOut timed_out, } interface OrderDetail { id: string; title: string; priceInFen: number; buyerName?: string; status: OrderStatus; }这里注意到我把金额字段起名为priceInFen单位直接暴露在名字里谁看到都不会再犯“把分当元”的错。这是从一次线上事故换来的教训后面会细说。第二步抽取纯函数。状态判断、金额转换都是纯逻辑不依赖框架把它们抽出来单独测试。function formatPrice(fen: number): string { return (fen / 100).toFixed(2); } function getDisplayName(name?: string): string { return name name.trim() ? name : anonymous; }第三步接日志链路。在获取详情、渲染成功、渲染失败三个节点加上带 traceId 的日志。这一步开始排查问题有了抓手。第四步补测试。先给纯函数加再给页面状态切换的渲染逻辑加。测试跑通之前不进入下一步。第五步替换调用方。把原来页面里的逻辑全部切到新接口删除旧的detail函数不让旧代码和新代码并存。第六步持续集成。把测试命令挂到 CI 流水线每次推代码自动跑一遍不通过就拦住合并。六步做完之后那个页面的代码长成了下面这样class OrderDetailPage { constructor(private api: OrderApi, private logger: Logger) {} async renderDetail(orderId: string): Promisevoid { const traceId generateTraceId(); this.logger.info(render_start, { traceId, orderId }); const order await this.api.getOrderDetail(orderId); if (!order) { this.logger.warn(order_not_found, { traceId, orderId }); this.showError(订单不存在); return; } this.logger.info(render_success, { traceId, orderId, status: order.status, }); this.showDetail({ title: order.title, price: formatPrice(order.priceInFen), name: getDisplayName(order.buyerName), }); } }3.3 落地效果与量化数据这个模块重构完我把改动前后做了一次对比指标重构前重构后文件行数86102状态值表示1、2、3 魔法数字OrderStatus 枚举日志无每次渲染有完整 traceId 链路测试023 个用例新增字段时改动点可能涉及 7 处只需要改接口定义 UI 映射行数没有减少甚至多了 16 行。但这是正常现象类型定义、日志、枚举声明都需要代码量。很多人用“代码行数少”来衡量代码好坏在 t3code 里这反而是一根错误标尺。关注点应该是“下一次改需求时需要动几个地方”。一个月后新需求来了订单列表要显示优惠后的价格。团队里的同事只改了一行映射跑了三分钟测试直接上线了。那一刻我对 t3code 的价值更笃定了一些。4. 常见问题与排查技巧实录4.1 五个高频问题与解法t3code 推行过程中组里几乎每个人都在相同的地方栽过跟头。我把高频问题整理成了一张表问题现象根因解法类型名太抽象读不懂data、res、obj满天飞图省事没认真设计领域概念类型名用业务词汇宁可写长一点日志打太多反而没法查全链路每行都是 info刷屏没有区分级别info 只留关键节点错误用 error详情用 debug测试太脆小改动就跑红改了一个文案测试挂了测试断言了 UI 细节不是行为断言只锁定业务结果不锁定展示样式金额单位混用元/分经常混淆字段名没写明单位字段名带单位或用专门类型标记重构成瘾改动面失控本来只是加字段结果把模块重写了顺手改一切导致风险放大每次改动限定范围不相关代码不动4.2 用简单命令给代码“体检”在没上严格检查工具之前我习惯用几个简单的命令定期扫一遍代码把明显的问题揪出来# 找出代码里的魔法数字3位以上数字字面量 grep -rEn \b[0-9]{3,}\b src --include*.ts --include*.js | grep -v test # 找出空 catch grep -rEn catch\s*\([^)]*\)\s*\{\s*\} src --include*.ts --include*.js # 找出裸 console.log无上下文 grep -rEn console\.log src --include*.ts --include*.js | grep -v traceId这些不能替代类型检查器和 linter但胜在零成本、随时能跑。每周扫一次比自己凭感觉 review 靠谱多了。4.3 推行 t3code 的几个“反直觉”经验第一条不要一开始就要求 100% 达标。如果强迫所有代码立刻满足规范团队会在情绪上反弹。我采取的办法是“新代码必须达标老代码逐步改造”改造时优先挑线上事故最多的模块。第二条测试不能只求绿。有一次我们的 CI 全绿但某个测试断言的是数据库里的旧字段业务代码早就不走了。测试跑过不等于测试有效。我后来会让每个测试简答一个问题“我在保护哪个行为”如果答不上来就删掉它。第三条代码评审时不要揪细节用词。有人把 type 命名为data_info有人命名为orderInfoData没必要统一拘泥于某种风格。只要类型清晰不产生歧义就放行。评审的重点是 T1、T2、T3 三条主线上是否达标而不是纠结下划线风格。5. 把t3code从个人习惯变成团队规范5.1 用一份 PR 清单代替口头要求只靠理念没法约束行为。我后来做了一张 Pull Request 自检清单每次提交代码都对照着过一遍我新增的类型名是否表达业务含义我的函数参数是“看得懂”的还是“猜得着”的这条链路如果出问题我能否靠日志定位到函数我修改的关键逻辑有没有对应测试用例CI 是否跑通本地是否跑得更快这份清单不追求华丽但它把 t3code 从抽象概念变成了可勾选的流程。团队里每个人用同样一把尺子量代码讨论问题时就不再是“你觉得难看”“我觉得还行”这种主观争论了。5.2 与 AI 工具协同最近和 AI 结对编程我发现也可以把 t3code 写成一段 prompt 前缀。给它规定好输出风格效果会稳定很多。比如“请编写函数参数和返回类型使用显式 interface关键步骤打印结构化日志核心逻辑附带单元测试避免魔法数字和空 catch。”AI 写出来的初稿再按 t3code 的清单过一遍能省不少时间。但要注意AI 生成的类型名经常是通用的Result、Detail需要人来改造成业务词汇。工具提供雏形质量判断还是在我们自己手上。5.3 最后一个小技巧用“半年后”视角写代码写代码的时候多问自己一句“半年后的我或同事只看到这一块代码能不能知道它想干什么”这个视角很朴素但它能逼着我在写类型、日志、字段名时多想一层。我见过很多精致的架构最终输给了几个月后无人能懂的命名。t3code 不是什么高深的理论它只是把“替未来的人着想”这件事变成了三条可执行的检查项。坚持下来代码的寿命会明显变长。
