1. 项目概述先弄明白 t3code 到底在干什么t3code 是我在梳理一个横跨两个团队、五千多个文件的订单中台项目时随手起的代号。当时手里的代码库已经乱了整整三个迭代没人说得清哪些模块是核心业务、哪些是试验性功能、哪些早就没人调用。我试过直接重构结果拆到一半发现有个“工具函数”被十几个文件依赖谁也不敢动我也试过让团队成员各自整理自己负责的模块结果整理完反而比以前更乱。折腾到最后我沉淀下来的就是 t3code 这套三步走的工作流Tag打标签、Trim裁剪、Transfer转移。它不是框架不是工具库代码里找不到任何 t3code 相关的依赖它本质上是一套“代码收纳术”。解决的核心问题也很朴素代码不是写出来的是长出来的长着长着就分不清哪根枝干什么用了。t3code 要做的就是先看清这棵树长成了什么样再修剪掉枯枝最后把果子按位置归好让后来的人能站在树底下抬头就知道哪个枝头该摘哪个果。这套方法解决的是我在项目里频繁踩到的三个痛点一是需求交接时说不清楚模块边界新同事光熟悉代码就要两周二是想重构却不敢下手因为改一行代码会牵出一堆隐式依赖三是 AI 辅助编程越来越普遍但给 AI 描述“帮我改这块逻辑”时自己也说不清“这块”到底是哪块。适合用它的人群包括正在维护老项目但不知道从哪下手的开发者、准备把混乱模块拆分成微服务的团队、需要给新同学建立代码地图的技术负责人以及想让 AI 更听话地改代码的人。下面我把这套方法的细节、实操过程和踩过的坑一次讲清楚。1.1 名字怎么来的三个 T 各指什么t3code 的 t3 不是某个版本号而是三个 T 开头的英文单词组合Tag、Trim、Transfer。这三个词对应代码整理中三个完全不同性质的动作我刻意把它们压缩到一个代号里方便团队内部沟通时快速对齐。阶段核心动作要解决的问题主要产出物Tag给代码块打职责标签这段代码到底在干什么属于业务规则还是数据访问注释标记、依赖草图、模块地图Trim裁剪冗余与死代码哪些代码可以删哪些逻辑重复了精简后的函数、删除清单Transfer将代码转移到正确位置这段代码应该住在哪个模块、哪一层文件目录调整、依赖方向修正Tag 阶段只动眼睛不动刀任务是“读明白”Trim 阶段开始动刀任务是“删干净”Transfer 阶段动筋骨任务是“搬到位”。三个阶段风险递增收益也递增。后面还会详细展开每一步的操作细节这里先记住一个原则顺序不能乱。1.2 这套方法适合什么场景不适合什么场景明确边界很重要t3code 不是万能药。我在实际使用中总结了一套判断标准如果你手头的代码符合下面任意一条t3code 能帮上大忙。模块之间经常出现复制粘贴的相似逻辑但没人确定能不能合并某个函数动辄一两百行if 嵌套四五层注释比代码还多你想给某个模块做重构但一查调用链发现根本理不清有多少地方依赖它团队新成员入职后对代码结构完全没有头绪只能靠老同事口口相传给 AI 发需求时描述不清“项目的现有结构”导致生成的代码风格和现有工程完全脱节反过来这些场景就不太适合用 t3code一次性跑完就删的脚本、纯探索性原型、没有测试覆盖且马上要上线的紧急修复。原因很简单t3code 的第一步 Tag 需要花时间读代码如果这段代码生命周期只有几个小时投入产出比太低紧急修复时先动刀风险太大。记住这一点能帮你省下很多不必要的纠结。2. 整体设计与思路拆解为什么必须是 Tag、Trim、Transfer很多人在听到 t3code 的三步走之后第一反应都是“这不就是重构吗老生常谈了”。说实话我第一次整理这套方法时也是这么想的但真正执行了几轮之后我才发现t3code 的重点不是“怎么重构”而是“重构前必须按什么顺序做哪些准备”。顺序本身就是最大的设计这就是它和其他重构手法的根本区别。2.1 顺序本身就是最大的设计为什么不能先删再搬我先用一个生活里的例子解释顺序问题。假设你要收拾一间堆满旧物的房间房间里有些东西要扔有些要搬到另一个房间还有些要重新归位。如果进屋直接开始扔大概率会把要搬走的东西一起扔掉如果直接开始搬屋里就会又多出一堆本来已经不需要的杂物。正确做法一定是先站在门口把每个角落看一遍心里有张清单再动手扔最后重新布置。t3code 的三个阶段就是对照这个流程设计的。先做 Tag是因为它零风险你只是读代码、标注代码、记录依赖关系不改任何行为。这一步的主要目标是建立“代码地图”搞清楚每一段代码在系统里扮演什么角色。拿到地图之后再做 Trim你删除代码时就知道哪些是真正的枯枝哪些是虽然难看但还挂在大树主干上的关节。跳过 Tag 直接 Trim 的后果我吃过不少次亏看某个函数觉得变量多余删掉之后一路报错追根溯源才发现那个变量被一个不起眼的闭包引用着。Trim 之后再 Transfer也是强逻辑关系。包含大量死代码、重复逻辑的模块直接搬到新位置等于把垃圾和家具一起搬进新家只会让新结构从诞生那天就开始腐烂。而且 Transfer 阶段最容易引发循环依赖和隐性依赖断裂如果代码里还留着大量没删干净的历史包袱排查起来会雪上加霜。所以我的经验是宁可前两个阶段多花时间也绝不让脏代码转移到新容器里。2.2 三个阶段各自的边界、风险和验收标准每个阶段怎么算结束需要有明确验收标准否则团队执行时会变成“你觉得好了我觉得还差得远”。我整理过一张对照表一直贴在我们项目文档里这里也分享出来。阶段输入条件主要风险验收标准Tag一段待整理的代码模块标注人自身理解有误导致后续方向错误每个函数都能用一句话说明职责依赖关系图画完且能讲给同事听Trim带完整职责标注的代码模块误删运行所需的逻辑破坏行为功能测试全部通过删除的代码都能在 git 历史里找到Transfer已精简并确认职责的模块模块循环依赖、调用链断裂、配置遗漏新目录结构清晰编译构建通过集成测试通过依赖方向无环每个阶段的边界一旦确立就不要来回横跳。比如 Tag 阶段发现某个函数显然要删手痒顺手删了那就等于同时做了两个阶段的事一旦出问题很难定位是哪一步引入的 bug。我给自己定的规矩是Tag 阶段只允许加注释、画图连变量名都尽量不改。2.3 它不是替代重构而是重构前的“地图绘制与火力侦察”经典的重构书里讲过很多具体手法提取函数、搬移函数、拆分模块、以查询取代派生变量等等。t3code 并不排斥这些手法反而是它们的前置步骤。打个比方重构手法是外科手术的刀法t3code 则是手术前的影像检查和术前方案。在实践中尤其是在老项目里最大的障碍往往不是不知道怎么提取函数而是不知道哪些函数能安全提取、提取之后放哪。t3code 通过 Tag 阶段把代码的职责边界画清楚通过 Trim 阶段把干扰项去掉到了 Transfer 阶段你可以直接用教科书里的经典重构手法来完成搬家试错成本会大幅下降。另外还有个容易被忽略的点t3code 里的“代码”不限于编程语言写的文件也适用于配置、数据库脚本、文档里的接口规范甚至 CI 流程里的步骤。因为这套方法的内核是“认知整理”跟具体语言和载体无关。后面我会单独讲它的扩展用法。3. 实操过程用 t3code 整理一段订单处理函数理论说再多不如直接拿一段真实代码走一遍流程。下面这个例子是我从一个内部项目中脱敏后简化出来的它集中了我见过的大部分“脏代码病”。3.1 从一段“典型脏代码”开始又臭又长又不敢动这是重构前的代码一个订单处理函数。注意看它的结构数据访问、业务规则、副作用、日志埋点全塞在一个函数里甚至连优惠券的使用状态都在计算阶段顺手改了这其实给后面埋了一个大雷。// order-handler.js async function handleOrder(order, user) { // 1. 获取商品信息 const products []; for (const item of order.items) { const product await db.findProductById(item.productId); products.push(product); } // 2. 校验库存 for (let i 0; i products.length; i) { const product products[i]; const item order.items[i]; if (product.stock item.count) { throw new Error(库存不足); } } // 3. 计算优惠 let discount 0; if (order.couponId) { const coupon await db.findCouponById(order.couponId); discount coupon.amount; // 这里顺带更新了coupon使用状态其实应该放到支付完成之后再做的 await db.markCouponUsed(order.couponId); } // 4. 抵扣用户余额 let finalPrice computeTotalPrice(order.items, products, discount); if (user.wallet finalPrice) { throw new Error(余额不足); } user.wallet - finalPrice; await db.updateUserWallet(user.id, user.wallet); // 5. 扣减库存 for (const item of order.items) { await db.decreaseStock(item.productId, item.count); } // 6. 保存订单 const orderDoc { userId: user.id, items: order.items, totalPrice: finalPrice, discount, status: paid, createTime: Date.now() }; const saved await db.createOrder(orderDoc); // 7. 发通知 await sendSms(user.phone, 下单成功); // 8. 写日志 埋点 logger.info(order created, { orderId: saved.id }); track(order_created, { userId: user.id, price: finalPrice }); return saved; }这段代码存在的问题很多但最致命的是职责没有边界如果产品经理说“下单时改成不发短信只在用户手动触发时发送”你根本找不到一个清晰的扩展点如果运营说“优惠券状态需要在支付回调里再更新”你又得在多个地方同步改。我曾见过类似代码流转到第三个维护者手里时已经没人敢碰了因为每个看似独立的部分都耦合着别的状态。3.2 第一遍 Tag不着急删先把“身份标”贴明白Tag 阶段我的做法是打开编辑器把函数从头到尾读一遍在每一段逻辑开头加注释标明这段的职责类型。注意只加注释和画图不碰代码。// order-handler.js async function handleOrder(order, user) { // [数据访问] 按订单项批量查询商品 // [业务规则] 校验每个订单项的库存是否充足 // [业务规则] 查找优惠券并计算折扣金额 // [副作用] 把优惠券标记为已使用 // [业务规则] 计算最终支付金额 // [业务规则] 校验余额是否充足 // [数据访问] 扣减用户余额 // [数据访问] 扣减库存 // [数据访问] 创建订单 // [副作用] 发送短信通知 // [副作用] 记录日志与埋点 }打完标签之后整个函数的职责分布一眼就能看清。数据访问和业务规则交织在一起还有两个副作用混在中间。我还会顺手画一张粗糙的依赖草图handleOrder 依赖 db、sendSms、logger、track其中 db 又散落在四个不同的访问点上。这张图不需要画得多精美自己看得懂就行。Tag 阶段有三个细节非常值得注意。第一不要过度追求“每行都打标签”粒度控制到“一段连续同职逻辑”即可否则注释会淹没代码第二尽量使用统一的标签词表比如[数据访问]、[业务规则]、[副作用]、[表现层]这样后续整理和检索都方便第三如果发现自己给某段代码打不出单一职责标签说明它应该被拆开把这个可疑点记录下来这就是后面 Trim 和 Transfer 的主要依据。3.3 第二遍 Trim敢删、真删、删干净标签打完之后我根据职责标注和依赖草图开始做减法。这个例子里可以动刀的地方不少。先从最明显的入手。第一处是user.wallet - finalPrice这行它修改了内存中的 user 对象但后续保存订单用的是db.updateUserWallet和user.id这个减法赋值其实没有任何持久化意义属于逻辑误导删掉。第二处是第 2 步库存校验时明明可以直接通过订单项关联商品没必要先把整个 products 数组查出来再配对索引这里可以改成一次性查询并组装成 Map代码会更短。第三处是几个重复的 try-catch 结构原始代码里每个 db 调用外面都包了一层几乎一样的异常处理可以直接收敛到统一的数据访问层。还有那个把优惠券标记为已使用的逻辑虽然在计算阶段执行本身不对但既然后面 Transfer 时它会挪走这里先不删注释标记为“待迁移”。Trim 之后函数的骨架微缩成了下面这样注意我只是列出了结构还没正式移动代码位置// order-handler.js (Trim 后结构示意) async function handleOrder(order, user) { const products await getProductsWithMap(order.items); assertStockEnough(products, order.items); const { discount, finalPrice } await calcFinalPrice(order, products); await payByWallet(user.id, finalPrice); await decreaseStock(order.items); const saved await createOrder(order, finalPrice, discount); await notify(saved); await logAndTrack(saved, user, finalPrice); }Trim 阶段最需要警惕的就是“舍不得删”。我刚带团队做这个练习时有人指着自己写的注释说“这段解释很重要删了以后看不懂了”。我的回应很简单代码的作用是解释行为如果代码本身足够清晰注释就是噪音如果代码不清晰注释只会让你误以为自己理解了。真正的意图应该通过函数名、变量名和测试用例来表达而不是靠注释。做完这一步一定要跑一遍现有测试用例确认行为没变。3.4 第三遍 Transfer让代码回到它该待的位置Trim 之后才轮到真正的搬家。我的拆分思路基本是数据访问搬到 repository业务规则搬到 service副作用搬到独立的 notification 或 event 模块日志埋点放到一个共享的横切位置。方向上参考的是分层架构和领域驱动设计的边界思想但在落地时我不会为了“纯粹”而过度设计够用就行。src/ domain/order/ order.service.js // 订单主流程、库存校验、价格计算 order.repository.js // 查商品、扣库存、创建订单、更新余额 order.entity.js // 订单实体和状态枚举 domain/coupon/ coupon.repository.js // 查找优惠券 infra/sms/ sms-notification.js // 发短信的封装 shared/ logger.js // 日志封装 tracker.js // 埋点封装搬完之后新的调用链非常直观order.service依赖order.repository和coupon.repository这两个 repository 不依赖任何 servicesms-notification和logger、tracker都是基础设施直接被 service 层调用但反过来不成立。这就是 Transfer 阶段要追求的核心结果依赖方向始终从业务层指向基础设施层而不是两边互相指。搬家结束之后不能默认万事大吉。我建议按这三步做验证先编译看有没有遗漏的引用再跑单元测试和集测重点看数据库状态、短信发送这类外部依赖有没有被重复调用最后看一遍 git diff确认没有不该出现的格式变动。做完这些之后这段代码就可以放心交给任何人维护了新同事看目录就能猜个八九不离十。4. 常见问题与排查技巧实录说实话t3code 这套方法理论上并不复杂真正难的是实际操作中各种“看着对但做起来不对劲”的局面。下面这些问题是我们在推行过程中真实遇到过的我把解决思路和排查技巧一并记录下来。4.1 打标签时发现函数“什么都干”拆不动怎么办这是我在 Tag 阶段最常碰到的问题一个函数里既有数据处理又有 UI 渲染还有状态变更标签根本打不到一个点上。这种情况我发现硬拆反而不容易落地比较稳的路线是先按“数据访问、业务规则、副作用”这三层拆出候选函数不为追求完美只求每个候选函数能起一个准确的名字。举个例子一个函数内部有查询订单列表、过滤已支付订单、渲染表格三件事那就先拆成queryPaidOrders和renderOrderTable两个函数把调用关系理顺。拆完可能还会发现有些变量在两个函数间传递略显啰嗦但不要急着优化参数结构等跑通之后再在 Transfer 阶段做变量收拢。最怕的是在 Tag 阶段就开始改函数签名一旦改到一半失去耐心很容易把整个模块搞得更乱。4.2 Trim 时手抖删了不该删的代码怎么办这个问题听起来很基础但在实际操作中相当容易发生尤其是当代码里存在动态调用、反射、全局替换的时候。我经历过一次事故清理某个工具函数时我用 IDE 的全局搜索确认没有外部引用就直接删了结果上线后用户反馈某个页面白屏追查半天才发现是另一个模块通过字符串拼接的方式动态引用了这个函数。后来我给自己定了一条硬规矩做 Trim 之前所有候选删除代码必须先用相对独立的提交保存至少保证每个阶段有一个可回滚点。如果发现删错了直接用 git 找回而不是靠记忆手写补回去。另外删除逻辑多但范围分散时建议先git stash暂存工作区跑一遍完整测试再提交可以最大程度避免多删漏删。4.3 Transfer 之后出现循环依赖怎么排查循环依赖是我在 Transfer 阶段遇到最多的坑几乎所有模块搬家都会碰到一两回。表现往往是项目启动时模块初始化报错或者某些文件在导入阶段出现 undefined。排查起来不要漫无目的地在代码里找我推荐先画一张模块依赖表列出每个模块 import 了谁、被谁 import。有环的情况下依赖表里一定能找出一条闭合回路。找到环之后处理办法通常是两个一个是把双方共同依赖的常量、枚举、类型定义抽到一个更底层的公共模块打破直接互引另一个是把其中一个方向的引用从编译期依赖改为注入式依赖让模块在运行时才拿到对方的能力。在项目早期发现循环依赖越早越好等模块体积大了再拆成本会成倍上升。4.4 团队成员不配合“先打标签”怎么办这个问题与其说是技术问题不如说是节奏问题。直接跟团队说“以后每段代码都要先打标签再改”基本等于没说不仅枯燥而且难以坚持。我后来用的方式是把它简化到 Code Review 的流程里每个 PR 必须回答三个问题改了什么、为什么这么改、放在这个位置是否合适。当团队习惯了用这套逻辑表达时Tag 带来的思考密度其实已经融进去了。另外我还发现一个比较有效的方法是控制单次 PR 的范围禁止一个 PR 里同时出现“删代码 搬文件 加新功能”这三类变更。我甚至会在 PR 模板里加一个“本次变更属于 t3code 的哪个阶段”的选项Tag 的话就只允许出现注释与文档变化Trim 就只允许出现删除与简化Transfer 就只允许出现移动与调整目录。这样分工清晰责任也清晰出了问题能精确回溯到阶段。问题通用处理思路我的经验备注拆不动先按职责拆候选函数允许暂时不完美把可疑点写进待办下一阶段再处理删错代码先用 git 保存可回滚点再做删除提交不要相信记忆用版本工具找回循环依赖画依赖表找环抽公共模块或注入解决越早发现越好别拖到模块膨胀团队不配合把方法论揉进评审流程与 PR 模板每个 PR 只做单一阶段便于沉淀习惯5. 扩展应用t3code 不止能收拾代码这套三步法我用了几年之后发现它其实已经变成了我的通用思维习惯。很多和代码无关的工作也能套上 Tag、Trim、Transfer 的框架效果还挺不错。5.1 写技术方案和文档时也能用写文档最大的问题是容易“什么都想写最后什么都没写清楚”。我会先用 Tag 把文档当大纲打标签背景、目标、方案选型、技术要点、风险与回滚、执行计划。然后 Trim 阶段负责删掉与主题无关的背景铺陈、复述其他文档的重复内容。最后 Transfer 阶段把核心结论挪到最关键的位置让读者扫一眼标题和首段就能理解重点。以前我写方案喜欢从项目起源讲起五页纸里三页都是铺垫现在砍掉一半内容之后评审效率反而高了很多。5.2 整理个人知识库和笔记知识管理上的应用更直接。我在收集资料时先用 Tag 给内容贴上主题标签比如“Go 并发模型”“接口设计规范”“数据库索引”然后定时做 Trim 把收藏里不再有价值的内容清掉把重复主题的笔记合并。最后 Transfer 阶段把整理后的内容归档到个人知识库的对应板块形成可检索的卡片。很多人收藏一百篇干货却一篇都不看就是因为前两步没做知识堆积太多导致打开笔记软件就头晕。5.3 和 AI 辅助编程配合的用法这个扩展是我最近用得最频繁的。现在大家都会让 AI 生成代码但很多人反馈生成的代码风格和项目格格不入或者 AI 会擅自改动无关逻辑。我按 t3code 的方式调整了 prompt 结构准确率高了不少。给 AI 的 prompt 可以拆成三段先 Tag描述项目目录结构、技术栈、现有代码风格给出具体文件路径和约定再 Trim明确告诉它“只改这个函数 / 只动某个目录其他文件不要碰”最后 Transfer指定输出位置比如“把新代码写到src/domain/order/下不要新增全局变量”。这其实就是把人的认知整理逻辑复制给 AI让它先看懂上下文再做精准修改。我自己体会最深的一点是t3code 最难的一步永远是 Tag因为它需要你诚实面对自己的代码——敢承认有些模块你已经不太懂、有些地方写了几年也不知道为什么存在才是整理的开始。前几次执行这套流程时我总想跳过 Tag 直接开改觉得“我已经够熟了”结果每次都会在两个小时之后回到起点重新画图。后来我干脆把 Tag 当成一种冥想式的动作戴上耳机逐行读代码不急着删除、不急着重构反而让许多隐蔽问题自行暴露了出来。如果你也想在混乱的老项目里找到一点安全感可以从今天开始挑一个最让你头疼的函数只做 Tag不做别的。
