1. 为什么我给项目取名叫 caveman一次对重型工程的刻意逆反先交代背景。上个月我把一个内部用了半年的小工具整理成开源项目顺手起了个别名 caveman。结果社区里不少人问我这名字是不是暗示代码很原始、很粗暴其实恰恰相反。我想表达的东西是在一个依赖遍地开花、脚手架动辄几十个文件的环境里我选择像穴居人一样只靠一块石头就把火生起来。caveman不是野蛮是回归本质。这个念头来自一次非常具体的痛点。当时我在维护一个业务脚本它只有不到两百行真实逻辑但为了符合团队标准工程结构硬生生被拆成了十几个模块目录、三份配置文件、两套抽象接口。每次改一个字段名要全局搜索七八处引用。更离谱的是为了跑这个脚本新同事需要先搭建一整套 CI 流程来安装依赖。我当时的内心OS是这个工具本身应该像一个长矛那么简单——拿起来就能用而不是像一辆需要热车十分钟的坦克。于是我做了一个实验把单文件 零第三方依赖 命令本身即文档作为硬性约束重写这个工具并把它命名为 caveman。本文就是这次实验的完整复盘包括设计取舍、具体实现、踩坑记录和最后的反思。如果你是那种经常写小工具、小脚本、内部自动化程序的开发者这篇文章应该能给你一些完全不同的组织和交付思路。要提前说明的是caveman 不是一个激进宣言要求所有项目都必须单文件。它更像是一种针对规模还没到、复杂度先膨胀这类情况的纠偏手段。判断标准很简单当你的项目主逻辑在 500 行以内且不需要团队协作并行开发时单文件带来的心智负担要远远小于它节省的导航成本。逾越这个边界单文件就会变成灾难这一点我在第五部分会详细聊。2. 单文件不是把代码堆在一起先定四条硬性约定很多人听说单文件第一反应就是把原来散落的代码全部黏到一个 .py 文件里。这么干基本必翻车因为面向multifile 大脑写的横向依赖全部挤在一起很快就变成三千米长的意大利面。我在做 caveman 时最先做的是给自己定规矩一共四条每条都直接对应前几个月踩过的坑。第一条文件内仍要保持清晰的段落分区。我自己的顺序固定为模块级 docstring第一眼就要让人知道这命令是干嘛的→ 配置常量区 → 辅助函数区 → 核心逻辑区 → main 入口。代码按这个顺序从上到下排列禁止穿插。相当于单文件里自己画出了虚拟目录任何人在编辑器里上下滚动两分钟内就能定位到要找的东西。第二条只允许标准库且必须在 docstring 里列出来。caveman 全部依赖只有 argparse、json、logging、pathlib 四个标准库模块。这条约束看起来简单执行起来相当反人性——有时候明明写三行 pip install 就能用一个现成库搞定的事被迫自己写二十行。但是反过来想这让 caveman 在任何一台有 Python 3.8 的机器上都能直接跑不需要 venv、不需要 requirements.txt、不需要一遍遍修依赖冲突。对内部工具来说能跑比优雅重要得多。第三条函数数量不设上限但单函数必须短。我给自己定的规矩是单个函数尽量别超过 30 行辅助函数可以很多但每个函数只做一件事。这样做的原因是单文件本身就缺少跳转成本如果函数又臭又长阅读体验会立刻崩塌函数短小而命名清晰的话即使文件有一千行读起来依然像在读目录。实测下来caveman 核心文件 600 多行七十多个函数还没有人抱怨过难看懂。第四条显式优于隐式所有的魔法都要写成配置。单文件工具最常见的毛病是逻辑里到处都是硬编码路径和神秘数字。我要求所有可变的东西全部集中到文件顶部的 CONFIG 字典函数里不允许出现任何裸字符串字面量除了日志信息。这也让后来增加功能时拥有很大的自由度多数改动只需要动配置区核心逻辑几乎碰都不碰。你可能会问为什么不定文件行数上限我反而觉得行数不是关键分区和函数边界才是。一个被精心组织过的 1200 行单文件容易理解程度远高于一个被硬拆出来的 5 文件项目。反过来一个只有 300 行却毫无分层逻辑的单文件一样会让人想砸电脑。3. 核心实现的三个支点argparse、日志系统和异常出口定好规则后真正动手实现 caveman 就顺畅多了。这一节我把最核心的三个技术支点分别讲透它们几乎是所有单文件命令行工具的地基。3.1 参数解析帮助文本就是第一份用户文档在单文件哲学里cli 的帮助文本不是一个可有可无的说明它本身就是产品说明书。我用 argparse 来实现参数解析但绝对不只是注册几个参数那么随意。每个参数我都写了详细的 help 字符串包括含义、默认值、取值范围、示例。读者在命令行敲caveman --help看到的内容就是一页排版良好的操作手册。参数命名上有一些小规矩短的别名只给最高频的选项比如-i给 input-o给 output低频选项只用完整长名避免把帮助信息刷成一个字母组成的乱码。位置参数永远放在最前面可选参数统一排在后面。布尔开关我尽量使用store_true而不是接受字符串减少用户输入错误的可能。这里有一个很多人忽略的细节argparse 的--version参数实现方式。不要用actionversion配合一个单独的全局变量我习惯把版本号常量翻译成 f-string然后由versionf%(prog)s {VERSION}去引用。这样版本只在文件顶部出现一次发新版本时只需要改一个地方。3.2 日志系统从静默到 verbose 至少要留三级单文件工具的调试体验天然比 IDE 调试差因为大家通常直接把它当作黑盒命令来执行。为此我设计了一套足够简单但有效的日志分层。默认级别是WARNING也就是只有出问题才在终端打印-v参数把级别降到INFO打印流程性信息比如正在读取配置文件处理到第 N 条记录;-vv再降到DEBUG打印每个函数的进出和关键变量的值。具体实现只需要三行logging.basicConfig(levelLOGGING_MAP[args.verbosity], format%(levelname)s | %(message)s)LOGGING_MAP是一个字典{0: logging.WARNING, 1: logging.INFO, 2: logging.DEBUG}。args.verbosity 用actioncount统计 -v 出现了几次。这套设计让 caveman 平时像哑巴一样安静出问题时又能立刻变成话痨节省了大量排查时间。日志这件事我要多唠叨一句单文件工具最容易忽视的地方就是日志格式化。很多小工具用print往标准输出打调试信息其实很危险。print输出的结果如果混入正常输出会让下游管道解析崩溃。我的规矩是正常业务结果走sys.stdout所有过程信息一律走logging也就是stderr。这样即使开了-vvmystdout里依然是干净的结构化数据。3.3 异常出口永远不打印裸 Traceback命令行工具是最容易被丢到 cron 或者 CI 里无人值守运行的。如果它失败时给出一张大红 Traceback使用者根本看不懂。caveman 里我定义了一个统一入口函数run()整个主流程包在 try / except 里def run() - int: try: return _main() except CavemanError as exc: logging.error(exc.message) return exc.exit_code except KeyboardInterrupt: logging.warning(用户中断正在退出) return 130 except Exception as exc: logging.exception(未预期错误: %s, exc) return 1观察一下针对业务错误我定义了CavemanError调用方可以主动抛错并把对应的退出码传递出去。比如配置缺失的退出码是 2文件不存在的退出码是 3。这就让外部脚本可以根据退出码精确判断失败原因而不是一律归为出错了。同时logging.exception会把 Traceback 完整记入日志而不是终端既保留了排查线索又保持了终端视觉干净。这一步直接把工具的专业感拉高了一个档次。说实话市面上有太多开源小工具连这一点都没做到导致每次失败都像在给用户做科技展示。4. 实战打磨从原型到顺手我迭代了三个版本规则定了地基也打好了现在聊 caveman 的本体功能。这个工具的实际用途是批量处理二维表格数据读取 CSV、按规则清洗字段、生成 JSON 输出。就是那种数据工程师每周都要干好几遍的体力活。初版我用半天时间写出来能用但真正让它变得好用多花了整整两个晚上。下面是我迭代过程中觉得最值得分享的内容。4.1 输入校验把错误挡在第一道闸门第一个版本对输入文件的存在性判断只做了一次Path.exists()。结果大部分报错发生在功能执行到一半、读到数据中间才发现列名不对。这个体验很糟糕——用户等了三秒钟最后看到一句KeyError: name。我随即增加了一个validate_input阶段在主流程启动后、正式处理数据前一次性做四件事检查路径是否存在、检查是否为文件、用csv.Sniffer检测分隔符、读取表头并校验必需列是否齐全。任何一项不通过立刻抛出带明确指引的CavemanError比如缺少必需列name实际列id,age,address。这一步让工具的失败从运行期随机爆炸变成了启动期可控拒绝。对命令行用户来说这四样检查做下来就一个词安心。4.2 进度反馈写给看不到尽头的等待者当处理量从几百行涨到几十万行时用户最大的焦虑是不知道还要等多久。这个项目最开始的版本在跑大批量任务时终端一片空白我一度以为它死掉了。后来我给主循环加了一个节制的进度报告机制不是用 tqdm 那种第三方进度条库标准库限制摆在那而是自己实现一个。逻辑其实很简单每处理 N 行N 根据总量动态计算总量十万行就每 1000 行报一次总量一千行就每 20 行报一次往 stderr 打一行已处理 52000 / 100000进度 52%。报告间隔尽量保持在 3 到 5 秒一次既不刷屏又让人明确知道它在动。同时在 DEBUG 级别下每一批处理完还会记录耗时中位数这让我在调优性能时不用额外插桩直接看日志就能定位瓶颈是在 IO、还是在某个正则匹配上。4.3 测试策略单文件不等于不测试项目结构再简单也不能变成没有测试的理由。caveman 的测试是我刻意为之的例外——它允许额外开一个测试文件。我用标准库unittest写了一个测试集重点覆盖三类场景正常数据转换、缺失字段触发正确错误、重复运行结果幂等。这里我特别说了测试文件是例外因为测试代码在生产工具的语境里属于开发辅助设施和发布的工具本体是两套生命周期。分开存放反而清晰。这个取舍也是我想强调的一点极简不是禁欲该有的质量保障不能省省的应该是无关紧要的骨架和抽象。跑测试的命令也很朴素python -m unittest没有 pytest 插件和覆盖率报告的加持但足够守住主要功能的回归底线。后来有一次我调整了日期格式化的默认行为测试立刻抓住了三个用例的失败避免了一个很尴尬的线上事故。5. 单文件工具的边界哪些情况千万别照抄这套思路诚实地说caveman 的哲学不是万能的。随着我把它推广到团队另一个项目很快就撞上了边墙我不得不认真划定适不适合单文件的判断标准。不适合单文件的第一种情况会被两个及以上的人同时高频改动。单文件是单点修改的天然瓶颈两个人同时编辑同一个文件冲突几乎不可避免。哪怕加了再好的段落分区git diff 也会变得十分吓人。如果团队规模超过两个人且开发节奏不同步还是老老实实拆模块吧。第二种情况核心逻辑超过一千行而且模块之间有明显的复用需求。这时候把功能拆成 package不仅是为了可读性更重要的是让单元测试能分别针对不同模块做隔离验证。单文件写法在核心文件过大之后测试也会被迫变得粗粒度回归保护能力会明显下降。第三种情况需要对外提供 API 而不是 CLI 命令。一个工具如果目标受众是直接 import 的开发者单文件的模块划分和私有性设计就会非常别扭。API 的目录结构、公开接口的显式标记、类型声明的归属这些都会跟文件内虚拟目录的约定互相打架。我现在的结论是CLI 工具适合单文件库项目不建议。还有一种很微妙的场景我也碰到过项目本身足够简单但客户或团队有强制规范比如要求每个目录下必须有__init__.py、必须有单独生存周期文档、必须有依赖锁定文件。这类组织层面的约束通常在个人小工具里不存在一旦进入跨部门交付单文件方案反而会成为合规审计的障碍。这时候不要硬拗合规优先。我在内部试过把 caveman 的思路推广到一个中等规模的数据调度模块结果三十天后主动放弃了。原因是我低估了多服务复用同一批公共函数的复杂度几十个函数挤在一个文件里每个调用方都从同一个命名空间取东西改一个函数签名要反复核对全部上层调用。那个阶段让我深刻意识到单文件的适用范围是工具不是平台。工具是你在需要时拿起的石头平台是要住很久的房子。6. 命名 caveman 之后我学到的最有价值的一件事说回标题本身。项目叫 caveman 本来只是个代号可这个名字真的反过来影响了设计决策。团队里有人开玩笑说既然你叫穴居人是不是应该再原始一点结果他真的提交了一个 PR就是把某个 JSON 美化的依赖换成标准库的json.dumps(indent2)理由是我们的口号既然是一块石头生火就别为这点功能引入第三方库。我当场被说服后来还专门把这个原则写进了项目说明能用标准库解决的绝不引依赖能用 20 行实现的功能绝不搞抽象基类。这种被自己的命名绑架的有趣体验让我重新审视了很多开发习惯。我们经常给项目起名之后就忘了名字里包含的期待。caveman 像一个不断检查我行为的守门员——每次我准备加一个花哨依赖、多写一层抽象、或者给项目补一个其实没人看的配置文件时都会先问一句这符合穴居人的气质吗大多数时候答案是不符合于是改动被砍掉。最终的 caveman 产品形态是一个零依赖、600 行、自带完整文档与测试的命令行工具部署方式就是python caveman.py 参数。没有安装流程没有环境依赖在客户的离线服务器上直接拉过去就能跑。这件事让我获得了某种审美上的愉悦——也许恰恰是在一个到处讲微服务、讲容器化、讲复杂度的时代做一个简单到有点返祖的东西反而显得格外清醒。如果你也被各种框架和工程规范压得喘不过气不妨挑一个真正简单的小需求用同样的思路从头造一个单文件工具。相信我你会重新找回写代码就是把想法变成可运行命令的那点快感。这比任何方法论都更值得亲身体验一次。