提起“t3code”这个名字其实最初只是我本地一个随手建的项目文件夹。我当时的想法很简单干了这么多年开发机器上堆了几百个项目代码散落在各种仓库、压缩包和历史分支里每次想找一段以前写过的逻辑都得翻半天想复用一段工具函数又怕改过之后不兼容想给团队分享点经验又得解释半天背景。后来我下了狠心用了三周时间把那些沉淀下来的代码做了系统梳理形成了一个我自己称之为“三层代码体系”的资产库——这就是 t3code 的由来。这套东西不是框架也不是平台更没有多先进的技术含量。它是一套把长期积累的代码重新组织、过滤、注释、归档的工程实践。核心就答一个问题怎么让代码在你需要的时候能以正确的形态出现在你面前。对于接私活、维护老系统、或者长期在同一个技术栈里工作的人来说这套方法能实打实地节省大量找代码、改代码、解释代码的时间。这篇文章我会把 t3code 的定位思路、筛选标准、落地步骤和踩坑记录完整展开希望能给同样有“代码资产整理”需求的你一点参考。1. 内容整体设计与思路拆解1.1 为什么是“三层”而不是按项目分类最开始我没想过分层就是用 tag 或者目录按业务领域分订单、支付、权限、消息推送……分了大概三十个目录结果用了不到一周就乱了。原因很好理解业务分类是动态的。今天在电商项目里写过的东西明天可能用在内容管理系统上今天放在“支付”目录里的一个签名算法后天可能服务于一个生成活动海报的接口签名。按业务分本质上还是在用项目的思维方式看待代码并没有跳出“项目仓库”的束缚。于是我把思路改了不再问“这段代码是什么业务的”只问“这段代码离了当前这个项目能不能活”以及“我下次需要它时是希望拿来就用还是要再动一两处才能用”。按这两个问题我把所有值得沉淀的代码分成了三层。第一层叫“运行层”特征是强依赖业务环境和外部系统离开当前项目就跑不起来。典型的比如一个电商下单接口的完整实现涉及定价规则、库存扣减和消息队列环境里还挂着用户体系。这种代码再漂亮也不适合进入资产库最多留一个文档链接指向原仓库。第二层叫“维护层”特征是已经和具体业务剥离但不算完全独立可能要注入一些配置项或依赖外部基础组件比如一个封装了数据库读写和缓存更新的工具模块换一个项目时只要改配置就能用。第三层叫“复用层”是与业务完全无关、不依赖团队内部基础设施的纯逻辑。像是加密签名、数据类型转换、时间区间计算、树结构遍历这类函数丢到任何环境里只要基础语言运行时在就能复制过去直接跑。1.2 三层体系要解决的核心痛点我梳理旧代码库时发现表面上最大的问题是“找不到”深层其实是“不敢用”。很多代码在旧仓库里跑得好好的但拉到新项目里要么依赖一个早就不存在的内部包要么用了过时的 API要么藏着一个看着不知道初始作者的隐式配置。若是有个中间状态把它们重新加工变成可持续维护、且坑都被填平的内容复用才成为可能而不是一种赌博。t3code 的设计目标就是让三层里的每一层都有明确的加工标准和出路。运行层的代码只做“登记”写清楚它在哪个仓库、哪个版本、因为什么业务存在将来项目重构或下线时知道哪些代码可以被安全删除。维护层的代码要做“适配”统一输入输出格式屏蔽旧项目的特殊上下文让新项目真正可以“配置后用”。复用层的代码要做“打磨”单测、注释、边界条件都补齐用起来不需要再读一遍实现细节只看函数签名就能明白。这三层对人的要求也不同。运行层基本是自动化的盘点花的是体力维护层是中间状态也是价值最高但最耗精力的部分复用层则是靠长期积累每两个月往里面放入三五个函数一年下来就相当可观。很多团队没有自己的内部库或者内部库建得过于宽松收了一堆只有原作者能看懂的“私货”最后沦为代码坟场。t3code 希望通过这种从源头过滤的方式避免那条老路。2. 核心细节解析与实操要点2.1 质量准入门槛三层各自的“准入红线”既然要给代码分层就绕不开一个问题哪些代码值得沉淀哪些代码直接放弃。我在梳理 t3code 时定了几条红线凡是触碰任意一条就不进入资产库。第一条红线是关键逻辑没有注释说明背景。要注意我说的注释不是写“这个变量是价格”而是写清楚“为什么这里要除以 100因为双精度浮点在金额计算上有精度风险”。必须有“背景型注释”不讨论“是什么”只解释“为什么”。复活旧代码时最困难的就是还原当时的心理状态注释就是记录这种状态的地方。第二条红线是存在隐藏状态。一个函数如果依赖函数外部的全局变量、环境变量或者某个静态同步块那它就不适合进复用层甚至连维护层都要谨慎。隐藏状态意味着不确定性你在这边测试是通的复制到那边就炸了。除非做完整的显式化改造否则宁可放弃这段代码。第三条红线是依赖不明。第三方依赖要明确到能锁版本公司内部依赖要明确到能锁仓库和版本系统层面的依赖比如 Linux 下的某个命令也要写明。老项目里最常见的坑就是一个工具类依赖了曾经存在于另一套服务里的一个 HTTP 接口代码本身没问题但环境变了以后接口不存在了。所有依赖都得写在文件头部的描述里这是 t3code 的硬要求。2.2 命名、结构与注释的统一约定三层体系如果只是逻辑分层没有统一的命名和结构约束用不了半年又会变成一个新的无序仓库。所以我在 t3code 里定了一套比较轻量但强制的约定。目录命名上第一层以“业务域 项目代号”命名表明这段代码来自哪套系统、归属哪个业务第二层以功能域命名比如 “cache”“mq-client”“excel-utils”第三层全部收进一个名为 “pure” 的目录里面只放不依赖任何项目上下文的函数。文件命名要求看一眼就知道“层”和“能力”。前缀p_表示 pure 层a_表示适配层对应维护层r_表示运行层的登记卡片。例如一个时间区间计算的工具函数命名为p_time_range_util.go。一开始觉得前缀丑但用了两周就觉得真香——全局搜“time_range”时完全可以靠前缀判断哪个是能直接复用的版本哪个还要再适配。注释上同样分了三个等级。纯函数的注释像一个迷你文档描述用途、参数、返回值、边界行为、示例、依赖。适配层函数除了基础注释还要多一个“适配说明”块记录原始代码来自哪里、当前参数对应了旧系统哪个概念。运行层则不写代码注释只生成登记卡片说明代码的位置和生命周期状态。2.3 工具链的选择Git 仓库加脚本不用重武器有些团队做代码资产沉淀第一反应就是搞一套制品库上系统、配权限、写文档平台最后发现弹药已经耗尽了。t3code 从头到尾没有用一个重型工具核心就是 Git 仓库加几个 Python 脚本外加 Markdown 索引文件。为什么这样选因为工具链越重参与维护的心理门槛越高。一个人跑到服务器上手动上传一个组件和直接在本地仓库里扔一个文件 push 上去完全不是一个动作成本。代码资产库需要的是“顺手”不顺手的东西最后一定会被放弃。t3code 的 Git 仓库只有三种提交频率最高的操作新增文件、更新文件、修改索引。用到 CI 的地方很少只在索引一致性检查上跑一下判断是不是有人把文件放错层级。索引文件是 t3code 的“门面”。我的索引不需要多豪华只需要包含五列文件路径、层级标记、功能描述、依赖列表、最后维护时间。用脚本生成 Markdown 表格提交到仓库根目录。打开就能看到全貌不用到目录里逐个翻。这也间接形成了质量反馈一段时间没有新的 p_ 文件或 a_ 文件加入就说明沉淀的动作停滞了该给自己提个醒。3. 实操过程与核心环节实现3.1 从零搭建目录结构、分支策略与开发习惯第一步是初始化仓库。我的 t3code 仓库结构很简单三类顶层目录runtime_cards/放登记卡片、adapt/放维护层的适配组件、pure/放复用层函数。scripts/放着索引生成脚本。因为没有什么复杂的发布流程所以日常开发直接采用单主干策略所有改动都提到主分支上只配合粗粒度的提交规范新增用add: p_xxx更新用update: a_xxx删除用remove: r_xxx。这样过一个月看提交历史可以大致了解资产增长的趋势。纯函数的入库流程我建议严格走四步第一步写函数和注释第二步写针对边界条件的单测第三步按脚本跑一趟规范检查第四步更新索引文件。前三步好理解第四步很多人会忽略但索引就是资产的账本不做这一步等于进了货没登记。实际的开发体验是当你在写一个通用函数时先想想它是不是已经在 t3code 里有过类似实现。如果是就直接复制出来改然后对比新旧差异把差异作为函数的第二个版本放回去而不是直接在原文件上改。这能防一个经典问题为了满足当前项目需求把一个通用函数写死成专用函数destroy了未来真正的可复用性。3.2 存量代码的迁移从老仓库挖掘和复活的完整流程对存量代码动手之前我的第一个忠告是不要试图迁移你舍不得删的全部代码只挑“最近一年里被反复复制或改动超过三次”的部分。复制粘贴三次是明确的信号灯表示这个逻辑值得有自己的家。t3code 的迁移流程分五步第一步在运行时库里搜索候选代码搜的时候不是搜文件名而是搜关键行为。比如我需要一段计算税率的逻辑就在所有老仓库里搜“rate”和“tax”这类关键词。第二步是判依赖。把候选文件复制到一个隔离目录试着编译或运行看它引用了哪些不属于标准库和明确第三方库的东西。凡是要改代码才能跑起来的引用都记为“适配点”。第三步是写适配层版本。所有适配点都通过参数方式暴露出来不要用全局替换的方式绕过去。比如原来代码里直接读环境变量env.get(USER_REGION)适配后改成func Calculate(region string, amount int) Result由调用方显式提供区域信息。第四步是补测试至少覆盖三个成功路径和三个异常路径异常路径尤其要测输入为 null、空数组、非法数值、超出范围值等等。第五步才是提交并写索引。我花时间最长的是第二步和第三步。一次从老系统里挖了一个价格优惠分摊工具逻辑十几行隐藏依赖却有一大堆数据库里的一个商家配置表、一个“活动类型字典”、还有一个上游定义的币种枚举。这种代码在运行层活着毫无问题但如果想放进适配层就要花费很多心思去理清每个依赖背后对应的业务概念。最终我只挑了其中“优惠金额按行项权重分摊”这一小段进 pure 层其余保持运行层的登记卡片状态。这事让我想通了拆迁式迁移没有意义很多时候做切片比做整体搬运更实际。3.3 日常工作流让代码资产库始终活着整理代码资产最怕的就是“一次性运动”搞完发布一个“重大更新”通告然后半年没人再碰。t3code 的日常维护必须融入开发习惯里不然又是一个静态仓库。我的做法是给自己定了一个“半小时规则”接到一个新的开发任务后不急着写代码先花半小时翻阅 t3code 索引看看是否有可复用的逻辑。如果发现一个函数需要稍微加工才能满足需求当场在适配层新建一个版本而不是就地修改原函数。这样既保证了原版本的稳定性又让新需求获得了自己的适配实体。这个习惯的收益不是一次性的它会越来越明显因为每次查找或适配都在给索引增加新的记录让后续检索更快。团队协作时我用的是每周定一个小目标的方式每周至少提交一个 a_ 层适配组件或者一个 p_ 层函数。代码量不重要重要的是保持对“复用可能”的敏感。有没有一段逻辑在不同需求里反复出现有没有一个函数虽然现在只有几行但牵涉复杂判断流程这些候选如果放掉下一周它又会消失在生产代码的海洋里。需要特别强调的是“从业务代码里抽出通用函数”这个动作的本身就是一次机会成本很小的重构但它带来的收益会随着代码资产的积累而复利式放大。4. 常见问题与排查技巧实录4.1 “逻辑不是很通用”和“现在还用不到”的取舍判断一段代码是不是值得进入资产库最常见的问题是“老觉得自己这个功能不够通用”。我在 t3code 项目里处理这个问题的方式很简单先收录再逐渐删除。除了极其明显的垃圾代码之外先给一段代码一个临时席位给它标记为“探索期的通用代码”用两次以上就转正用不到就定期清理。这和写业务代码的直觉是反着的但资产运营的逻辑本来就不同。业务代码讲究短小、聚焦资产库讲究覆盖、可查找。唯一要小心的是不能因为“先收录”就把垃圾当宝贝所以探索期的纯函数必须在一开始就具备基本注释和至少一个测试用例不然它连被评估的资格都没有。我经历过一个典型失败当时从项目里抽出一个“时区转换组件”以为自己是在沉淀通用能力结果后来发现这个组件只有项目里那个调度系统在用时区表的更新逻辑和业务耦合得很深。在项目重构时我花了一晚上把所有引用剥离出去发现真正通用的部分只有“基于 IANA 时区名称做字符串解析”一个十分钟能写完的工具函数。那次之后我学会了“先把真正小颗粒的纯函数挖出来再考虑包成一个组件”——颗粒度是从小往大积累的而不是从大往小切割。4.2 依赖与版本问题的排查老代码为什么跑不起来了t3code 里最容易出问题的不是纯函数层而是适配层。跑不起来的首要元凶是“隐式依赖”。排查时我一般按顺序查三步第一步是有没有读环境变量或者全局配置第二步是有没有调用不在参数列表里的内部服务 API第三步是有没有依赖某个不明确的系统命令比如假设所有服务器都是 CentOS 并直接调 Yum。这三步里环境变量的最隐晦。偏门写法很多比如早年一些老代码喜欢读取 “server.port” 这种通用的键名如果新项目和旧项目的配置语义不同很容易造成静态变量被悄悄初始化成一个错误值。t3code 对进入适配层的代码有一项硬检查所有环境变量读取必须封装成显式的 Configuration 结构体由调用方注入禁止代码内部直接读全局键。版本管理上纯函数层的版本策略最省心因为纯函数几乎不引入第三方依赖。适配层就要注意锁版本了。我的防线是两层文件头注释里写清楚依赖的版本区间例如 “dep: com.example:common-utils2.1 3.0”索引表格里增加一个 “危险依赖” 列标记哪些适配组件有过版本兼容事故。很多维护者会在升级第三方库时漏掉这些老组件结果线上直接触发隐蔽回归。有了这个标记升级前至少可以提前知道风险面。4.3 团队执行时的阻力怎么让大家愿意贡献代码企业团队里推广这种代码资产库时最典型的阻力是“多一事不如少一事”——写代码本来就是输出价值凭什么还要额外整理这个问题没有技术解只能靠降低门槛和提供反馈。我把 t3code 的团队提交方式设计得比写周报还简单只需要把新文件放到对应目录推一个分支提一个 Pull Request索引由脚本自动生成不需要人工维护。越少依赖人去做重复劳动执行阻力越小。除此之外我觉得更真实、也在实际上更有效的推力是“找到一位愿意先贡献的第一个用户”。如果有一个影响力不小的核心开发愿意带头把自己的工具函数沉淀进来其他人看到实际效果后才会有动力。我在团队里干的就是这个角色“我先把最常用的十个函数放进 pure 层并写好单测之后再有人看到他也会觉得这是大家共有的资产值得补充。”这种自发的社区氛围一旦建立质量红线才容易真正被执行而不是靠行政命令。4.4 检索技巧让沉淀的代码真正能被找到最后再分享一个检索层面的实际问题。“我明明整理过这段代码但要用的时候搜不到”往往是检索词和命名词不一致导致的。我给自己定过一个规矩也是 t3code 的全体实践写函数注释时至少留下一组“行为词”和一组“业务词”。行为词描述这段代码是做什么的例如“检查端口是否被占用”业务词描述它可能来自哪个业务背景例如“部署脚本”。活生生的例子早期我使用 “url-shortener” 作为关键词来搜索一个短链生成的函数怎么都搜不到后来发现它被命名为p_token_to_id.go。文件名和搜索词的差距太大了。所以我现在每次往仓库里放代码时会强迫自己在注释里加一行keywords: short-link, token, url-shortener方便未来搜索。这是一个极小的动作但它是所有沉淀工作能否发挥价值的关键。5. 关于维护节奏与个人体会t3code 运行到现在我最真实的体会是整理代码资产这件事不需要贵重的工具也不需要提前规划宏伟蓝图它更像是一个“长期习惯 轻量规则”的组合。不会一次性见效也不会被某个老板察觉但每次当你找到一段自己半年前写的函数、确认它可以直接复用、跑完测试一次通过的时候那种确定性带来的满足感特别值。后来我接一些外部项目时很多公共模块都能从 t3code 里直接找出来改改参数就能上那种感觉就像一个积攒多年的工具箱终于做到了随手可取。如果你也在处理几百个旧项目不妨从今晚开始随便挑一个你觉得还算顺眼的工具函数给它放进一个叫 t3code 的文件夹里——一个月后你大概率会感谢那个简单的开始。