★ FEATURED ARTICLE 很多年前当我把自己的代码仓库翻了个底朝天却死活找不到上周刚写的一个网络超时重试工具时我就知道必须得做点什么了。那个工具并不复杂大概四五十行但因为它散落在某个临时项目的utils/目录里没有任何注释也没有提交信息它就这么静悄悄地消失了。后来我花了两小时重新写了一遍边写边骂自己。从那以后我开始认真对待一件看起来很虚的事情代码资产管理。我前前后后折腾了好几轮方案从最初的散落文件到统一收进一个巨型仓库再到半途而废的 Wiki 整理计划全部以失败告终。直到我做了第三次系统性重构把整套方法论和落地方案沉淀成了一个代号叫t3code的个人项目局面才算彻底打开。这篇文章就是 t3code 从想法到落地再到日常运转的完整复盘包括为什么这么设计、具体怎么操作、以及我踩过的那些坑。如果你也经常觉得自己写过的代码像不存在一样那这篇东西应该能帮上忙。1. 为什么会有 t3code从能跑就行到找得到、拿起来就用先说清楚 t3code 解决的是什么问题。绝大多数开发者——尤其是像我这种什么都爱折腾的独立开发者——个人代码库的混乱程度和代码量是成正比的。代码少的时候不觉得一旦超过某个临界点问题就暴露了写过的脚本找不回来、不同项目的工具函数重复造轮子、旧项目的环境配置早已随风飘散、想复用某段逻辑得先把整个项目翻一遍。1.1 前两代代码管理的失败经验我最早是散装流代码散落在各个项目里靠grep -r过日子。这套方案的问题是广度和深度不可兼得如果项目之间没有明确的主题关联你根本不知道应该去哪个仓库里翻就算侥幸找到了那段代码往往和业务逻辑缠在一起还是要花时间拆解。后来我改成一锅端把所有代码平铺到一个巨型仓库里按语言分目录python/、go/、javascript/。听起来井井有条但是运行几个月后就失控了。为什么因为按语言分目录这个维度本身就错了——它解决的是归属问题不是检索问题。你写了一个抓取网页标题的脚本是归到python/还是javascript/如果两个版本都写过呢而且语言分类完全没有语义线索一个脚本如果既跟爬虫有关、又涉及定时任务、又要发通知它在仓库里的位置根本无法表达这些信息。1.2 t3code 的核心思路把代码当资产不当草稿第二代方案失败后我冷静下来问了自己一个问题我希望从代码库里获得什么答案不是干干净净的目录结构而是三件事能在几分钟内定位到一段曾经写过的代码能确定它的运行方式能判断它是否可以直接拿来用。可否直接拿来用这个诉求是之前所有方案都没有正面回答过的。散装阶段能找但不可用巨型仓库能用但找不到。于是我设计了 t3code 的三条核心准则可定位任何一段有价值的代码都必须有明确的归属层级和标签。可运行每个代码单元都能被一条命令拉起不需要回忆当时用的什么解释器、依赖了哪个第三方库。可演进代码单元之间不互相锁死升级某一段不会牵连整个仓库。1.3 这套体系适合谁平心而论t3code 不是给团队项目用的它更适合这几类人个人开发者、开源项目的维护者、靠技术接活儿的自由职业者以及那些需要频繁跨语言、跨领域写代码的人。它的核心价值不是让你的仓库变漂亮而是让你的经验不贬值。如果你只写公司项目代码长期由团队统一管理那 t3code 对你的帮助有限。但如果你和我一样手里攒了一堆小工具、爬虫、脚本模板、算法片段并且定期会在新项目里复用它们那我强烈建议你往下看。2. Tier 与 Type 双轴分类t3code 的三维定位法t3code 这个名字里的t3第一重含义是指我做的第三次重构但更准确地说它是指我使用的三级定位法Tier 层 Type 类 Tag 标签。这个三维体系是整套方案的骨架。先把结论摆出来t3code 的每个代码库条目都必须能回答三个问题——成熟度多高Tier、本质是什么Type、涉及哪些主题Tag。这三个答案合在一起就能像经纬度一样在代码宇宙里给一段代码唯一的位置。2.1 Tier 层用成熟度划分而不是用项目划分我把所有代码按成熟度分成三个层用目录前缀区分core/核心资产库。代码经过验证、有测试或至少有清晰的运行说明可以被多个项目稳定复用。biz/业务项目库。有具体背景的完整项目比如接的单子、自己的产品原型、实验性网站。lab/实验室。灵感片段、未完成的尝试、刚写完还没验证思路的草稿。这个分层的好处是它把这段代码写得好不好和这个项目重不重要彻底解耦。很多人在管理代码时的误区是把重要的东西和成熟的东西混为一谈。公司声称的重要项目代码质量可能稀烂随手写的一个小工具反而稳定运行了好几年。我现在的判断标准非常简单能离开项目独立运行的代码才配进core/需要上下文才能看懂的东西留在biz/里还不确定有没有价值的先在lab/里待着。2.2 Type 类按代码性质分而不是按语言分Tier 解决了归属问题接下来要解决的是这东西到底是什么的问题。我定义了五个 TypeType含义例子script一次性或低频的自动化脚本批量重命名文件、数据清洗tool可以被命令行调用的小工具JSON 格式化、端口检测service需要常驻运行的进程通知机器人、定时任务调度lib可以被 import 的代码库重试封装、并发控制doc知识文档/代码片段说明README、技术笔记为什么要按这个维度分因为不同 Type 的代码生命周期和依赖方式完全不同。脚本今天写完明天可能就删了但库会被长期依赖服务的运行环境要求高工具的测试方式又不一样。按 Type 分类后我在规划代码的长期待遇时就有了依据lib和tool我会加测试script只要写好注释就行service我会额外写部署说明。2.3 Tag 标签用 front-matter 做语义检索Tier 和 Type 是粗粒度分类真正实现秒级定位的是靠 Tag。我在每个代码库/代码片段的入口处放一个t3.yaml文件用键值对记录元信息name: url-title-fetcher tier: core type: tool lang: rust tags: - http - html - crawler - cli desc: 从任意 URL 中提取 title 标签内容支持超时、重试、代理。 updated: 2024-05-01这个文件就是这段代码的身份证。搜索的时候我不再搜代码内容而是先搜元信息。比如我想找一个能处理 cookie 的登录脚本直接搜tags: cookie script配合type: script结果精确得多完全不会出现找到一万个包含 login 字符串的无关文件这种尴尬。这套三维定位法的核心思想是**靠结构管理归属靠标签管理语义靠层级管理成熟度。**三件互不相干的事别混在一起办。3. 仓库划分的终局方案双轨制不再纠结一个还是多个解决了单个代码单元的分类问题接下来自然要面对那个所有长期维护代码库的人都绕不开的难题到底应该把所有代码放在一个仓库里还是拆成多个仓库我两种极端都走过也都为自己的极端付出了代价。最终在 t3code 里我采用的是双轨制方案核心资产集中在单一仓库场景项目独立成仓二者通过t3.yaml元信息连接。这个方案不新但我觉得它是最适合个人开发者的折中值得展开讲讲。3.1 纯多仓库为什么不适合个人很多人迷信多仓库觉得模块清晰、互不干扰。但对个人开发者而言多仓库带来的维护成本是实打实增加的每个仓库要单独init、单独写.gitignore、单独处理 issues——虽然个人项目没人提 issue但你还是会为仓库的管理烦心。最要命的是多仓库导致上下文池被切碎了。我曾经有一个仓库只放了一个十行的 Python 函数因为忘了它在哪里隔半年又写了一遍。多仓库对大型团队没问题——因为不同团队对代码的记忆是分开的而个人开发者的记忆是靠全局检索的仓库一多检索的直接成本就变高了。3.2 纯单仓库为什么也让人崩溃单仓库的教训同样深刻。我的第二个方案就是那个巨型仓库按语言分目录所有代码一起跑。崩溃的原因不是代码多而是演进阻力每当我打算升级某个脚本的算法会担心影响同目录下别的脚本每当我打算删掉一段垃圾代码会犹豫会不会有谁依赖它——哪怕这个谁就是我自己。仓库越大做决策越畏首畏尾。更麻烦的是单仓库的构建和搜索时间会随体积线性增长。当rg --stats告诉我扫描全库要半分钟时我知道这条路走死了。3.3 双轨制的实际运作我的双轨制是这样设计的core/对应单一仓库t3core只收集那些脱离业务场景依然有用的代码。它有统一的构建脚本和测试入口。biz/对应多个项目仓库每个项目一仓保持业务完整性。lab/不建仓库只是主仓库的一个异常分支或独立分支方便随时 push 和丢弃。每次从biz/某个项目里发现了可复用的模块就把它抽出来升格到t3core并在原项目里替换为对t3core的引用。这个升格动作就是双轨制的润滑剂——它能防止t3core变成没人更新的死仓库也能避免业务仓库之间的重复造轮子。选择仓库方案时我的决策矩阵是场景合适方案原因代码可以脱离项目直接用单仓库 core便于全局检索代码和业务强绑定独立项目仓库上下文完整灵感、临时尝试、测试草稿不进任何仓库或进 lab 分支随手可删这套方案运行到现在我的t3core保持在几十个模块的规模——这个规模既能保证我记住每个模块的大致功能又不会像几百个模块那样彻底失去控制。4. 一键运行让十年前写的代码也能在当前环境跑起来代码找得到还是第一步找得到却跑不起来比找不到更让人恼火。我在这件事上吃的亏最多有段时间我修复了一个三年前写的 Python 脚本改完发现它依赖的DataFrameAPI 全是老版本用法一跑就被弃用警告刷屏还有一个 Rust 工具当时的编译器和现在的缓存机制完全不同折腾了半天才让它重新出活。为了让跑起来不再是靠回忆和运气t3code 里规定了一条硬性要求每个进入core/的代码单元必须提供一个run.sh或Makefile任务并配一个最简README.md写明运行方式。4.1 统一入口脚本我用的入口脚本模板大概是这样的#!/usr/bin/env bash # 用法: ./run.sh command # command: start | test | build | clean set -euo pipefail COMMAND${1:-start} case $COMMAND in start) # 主入口 python main.py ;; test) pytest tests/ ;; build) # 如果有构建环节例如 Rust/Go 项目 cargo build --release ;; clean) rm -rf dist/ build/ .pytest_cache/ ;; *) echo unknown command: $COMMAND exit 1 ;; esac别小看这个模板。它做了几件事第一它把如何运行这段代码从人的脑子里迁移到了文件系统里——只要你进了目录第一个看到的是run.sh照做就行第二set -euo pipefail强制脚本在出错时立刻退出避免了脚本运行一半输出乱码你还在傻等的尴尬第三锚定了command语义让test、build这些动作在每个模块里都是统一姿势我不用为每个语言单独记一套命令。4.2 环境和依赖怎么办脚本解决了入口解决不了依赖。个人项目最大的环境痛点就是我明明装了这个库怎么跑不起来 这时候有两条路一是把依赖声明进t3.yaml我在里面增加一个deps字段记录用到的关键依赖清单deps: python: - requests2.20 - beautifulsoup4 system: - jq二是对重量级、环境纠缠不清的模块用 Docker 包一层。我给core/里的两个服务型模块配了Dockerfile用一条命令拉起来。不过我要泼盆冷水**不是所有代码都值得 Docker 化尤其是脚本和小工具。**Python 的虚拟环境、Node 的node_modules、Go 的单二进制都比 Docker 更适合解决这类问题。Docker 适合的是那些依赖乱七八糟系统库、多年后还在频繁变化的东西。真正的探索是我在core/里做了一个全局的env脚本负责为每个模块启动独立环境比如# 在任意位置运行: t3enter core/url-title-fetcher t3enter() { local dir$1 local lang lang$(yq .lang $dir/t3.yaml) case $lang in python) (cd $dir python -m venv .venv source .venv/bin/activate exec bash) ;; node) (cd $dir [[ -d node_modules ]] || npm install exec bash) ;; *) exec bash ;; esac }这个脚本的思路是把环境准备变成标准化的动作而不是每个项目自己发明一套。虽然上面只是骨架代码但你已经可以体会到我想要的效果进入任何核心模块先用一条命令把环境搞定再开始改代码。4.3 一次实际演示的收获有一次我为了给一个客户演示历史数据处理流程需要重新跑通一个一年前写的爬虫加清洗管线。按 t3code 的规则我先在core/里定位到爬虫模块跑./run.sh start拉取数据成功然后定位到清洗模块同样一条命令输出落地。全过程包括环境准备、依赖安装、测试跑通合在一起不到八分钟。换作以前我起码得花两个小时在这个模块依赖那个脚本--那个脚本又依赖另一个环境变量的泥潭里。这就是 t3code 在这件事上给我的最大回报代码的可用性不再依赖记忆而依赖一套自动化的运行约定。5. 检索与复用从我记得好像写过到我知道它在哪前面讲了定位和运行接下来讲最日常的诉求——检索。如果面试里被问你做过的最提升效率的工具是什么我多半会提 t3code 里的检索体系。它不酷但极其实用。5.1 三重检索文本、元信息、目录结构各自为政我把检索拆成三个层次使用者按需选择文本全文检索用 ripgrep 取代grep -r。它快而且默认尊重.gitignore不会跑进node_modules和.venv里。元信息检索直接对t3.yaml做结构化查询比如找出所有用 Go 写的工具找出 tags 里含 cron 的所有模块。我维护了一个聚合脚本t3query输出一个 Markdown 索引。目录树检索某些时候连检索都嫌麻烦直接ls一层层找。目录结构本身设计得足够语义化这一招很管用。5.2 t3query 索引脚本这是t3query的核心逻辑伪代码#!/usr/bin/env bash # t3query: 按标签/语言/类型检索代码资产 set -euo pipefail find . -name t3.yaml -print0 | while IFS read -r -d file; do dir$(dirname $file) name$(yq .name $file) tier$(yq .tier $file) type$(yq .type $file) lang$(yq .lang $file) tags$(yq .tags | join(,) $file) echo $tier | $type | $lang | $name | $tags done \ | column -t -s |跑一次大概几秒钟仓库规模不大输出类似core | tool | rust | url-title-fetcher | http,html,crawler,cli core | lib | go | retry-wrapper | retry,timeout,net biz | service | python | cron-notifier | cron,notification曾经有个晚上我要写一个带重试机制的 HTTP 客户端第一反应是我肯定写过类似的东西跑到t3query里搜retry直接把core/retry-wrapper捞出来基于它改了个新版本。整个过程十分钟不到。要是没这套索引我大概已经在搜索引擎里转悠半天了。5.3 快速跳转zoxide 加持检索解决的只是知道在哪真正高频的是怎么快速过去。我用 zoxide 维护一套zi命令把常用目录加入数据库z add ~/dev/t3core z add ~/dev/t3core/retry-wrapper z add ~/dev/biz/project-abc # 之后直接用 z retry配合上编辑器的工作区功能我会把整个t3core作为常驻窗口的前几个 tab。这样以来任何一段常用代码都离我两步之遥——一步检索一步跳转。这些习惯叠加起来的效应非常可观。5.4 复用不是简单的复制粘贴最后想多说一句t3code 的复用从来不是让你把代码复制粘贴到新项目里就拍拍屁股走人。我在每个可从biz/升格到core/的模块上都会做一次通用化手术剥离业务字段、把硬编码变成参数、补充边界情况的测试。这个步骤很费时间但正是这一步决定了你的代码资产到底是可复用的库还是一个更长的草稿。我现在有一个不成文的规定如果一段代码在三个月内被我在两个不同的项目里用到那就值得拿出来做通用化收进core/。否则它就应该停留在它出生的项目里。6. 用 t3code 一年后的得失盘点收益、代价与踩坑清单任何一套体系用久了都会显露出真实的性价比。t3code 运行到现在我得到过实实在在的收益也交过不少学费。趁这个机会我把最关键的教训和体会一股脑倒出来。6.1 让我舍不得放弃的收益首先是效率层面的我现在写新代码的时间被压缩得很紧。需要某个能力时搜查、复用、改参数、提交半小时内完成。以前同样的活可能花掉一下午——主要是耽误在找和让它跑通上。其次是心智负担的减轻当年那个我肯定写过但死活找不到的焦虑感现在几乎消失了。写代码时心里有底因为我知道自己有一个可靠的记忆外部化系统不担心辛辛苦苦攒的东西被遗忘。还有一点是隐性收益t3code 让我的代码库变成了一个可教学的资源库。过去朋友问我某个功能怎么实现我得东拼西凑找例子现在直接甩过去几个core/模块附上索引文件对方自己就能看懂。6.2 这段经历里的代价和让我后悔的取舍代价同样不少。最大的代价是维护时间给每个模块写t3.yaml、跑测试、定期清理lab/这些琐碎工作每周会占掉我大概三到四个小时。有时候项目特别忙整理就拖欠了一旦拖欠超过一个月整理的成本会指数上升——因为记忆已经开始模糊你看着一段代码半天想不起它是干嘛的这正是所有规则失效的开端。第二个代价是过度规范的陷阱。我一开始给t3.yaml设计了十多个字段后来一个个删掉了大部分只保留现在这几个。字段一多写的人我自己就烦烦了就会敷衍敷衍了索引质量就崩。规范的目的是降低摩擦不是制造仪仗队。6.3 避坑清单如果你也想搭这么一套记住这五条命名要用功能词不要用代号。模块叫url-title-fetcher永远比叫alpha好查好记忆。代码模块不是项目你不需要给它取的响亮名字。标签宁缺毋滥。给模块打 8 个 tags 说明你没想清楚它到底是什么。我现在的经验是最多 5 个最少 1 个标准是一个陌生人能不能靠这些标签找到它。绝不把lab/里的东西当生产。实验室代码就是用来实验的别因为它刚好能跑就把它升格到生产环境。升格必须走通用化手术 测试的流程否则你只是把自己的问题交给了未来。定期清理僵尸模块。我每季度做一次 review统计哪些模块在过去 90 天完全没有被访问过。没人访问说明现在它没价值——但也别急着删移进archive/目录让它不干扰主线搜索就足够了。坚持测试哪怕是最小的测试。我的一个最低要求是run.sh test不能为空。哪怕只有一个测试也能在以后修改的时候保护你。连测试都没有的代码说白了你根本不清楚它能跑是不是偶然。6.4 给考虑入手的人一条最简单的起步路径如果你是第一次接触个人代码资产整理这个概念我建议你别一上来就复刻整个 t3code。起步可以从一个最小的循环做起建一个core/目录把你未来 7 天反复要用的那个脚本/工具放进去写一小段README.md说明用法跑通一次从其他项目里调用它的路径。连t3.yaml都可以先不写用注释代替也行。关键是把循环转起来新写的代码优先选择去core/里找找不到再写新的写完立刻放回去。等这个循环发生了三次以上再考虑引入分类、标签、检索这些进阶玩法。一上来就搞庞大体系多半会跟我的第二代方案一样被自己设的规则压垮。做 t3code 这件事对我来说最大的意义不是我的目录好整齐而是我重新相信了一件事代码不在于写得多快而在于写完后能被时间留住。你现在写下的每一行将来都是你最大的一笔财富前提是你有一套让它们能不断被重新发现、重新使用的机制。我选了 t3code 这条路希望这整套实践下来沉淀出的经验也能成为你构建自己那套体系时的一块跳板。
阅读完成 · 觉得有帮助？
