命令行工具:项目复盘与经验提炼

说实话,做命令行工具这件事,我们团队前前后后踩了不少坑。今天想和您聊聊我们最近一个 CLI 项目的复盘过程,尤其是技术债务怎么还、敏捷开发怎么落地。如果您也在维护内部工具链,或者正被一堆"能用但不敢动"的脚本拖累,那这篇文章就是写给您看的。

痛点:能跑的命令行,为什么成了烫手山芋?

您是不是也遇到过这种情况?一个命令行工具,最初只是为了解决某个临时需求,三五十行代码,跑得挺欢。结果半年后,它变成了团队里谁都离不开的"基础设施",但谁也不敢改。加个参数要改三个文件,修个 bug 得手动测试一整天。

我们就有一个这样的工具,内部叫它 deploy-cli。刚写出来时,它只负责把构建产物推到测试环境。后来需求像滚雪球一样:支持多环境、加回滚、接通知、做权限校验……代码从 200 行涨到 3000 多行,全部塞在一个 main.go 里。坦白讲,那时候每次发版前,负责这个工具的同事都要深吸一口气。

这就是典型的技术债务。它不是"坏代码",而是"当时合理、现在拖后腿"的决策累积。命令行工具尤其容易这样,因为它的入口简单,大家总觉得"加点逻辑没关系",结果越加越乱。

复盘第一步:把"能跑"变成"能测"

我们做的第一件事,不是重写,而是补测试。听起来很枯燥对吧?但这是还债的必经之路。命令行工具的测试有个天然优势:输入输出明确。您给它一组参数和标准输入,它就该返回确定的退出码和输出。

就拿 deploy-cli 来说,我们花了三天时间,把核心的五个子命令——部署、回滚、状态查询、日志拉取、权限校验——全部用表驱动测试覆盖了。每个用例就是一行数据:参数、环境变量、期望输出。刚开始覆盖率只有 40%,但已经能拦住大部分回归问题。

这里有个小技巧:把副作用隔离出去。命令行工具经常要调 API、写文件、发消息。我们在测试里把这些都 mock 掉,只验证"工具本身的行为"。这样一来,测试跑得飞快,一次全量也就 200 毫秒。敏捷开发讲究快速反馈,如果测试要跑五分钟,没人愿意频繁跑。

技术债务处理:边拆边搬,不停机

有了测试网,我们就敢动刀了。但重写风险太大,我们选了"绞杀者模式"——新逻辑走新路径,旧逻辑逐步废弃。

举个例子,原来的参数解析是一坨 if-else,我们把它换成了 cobra 框架。但不是一次性替换,而是先让新旧两套解析器并存。新命令走 cobra,旧命令走老逻辑,中间加一层适配。每迁移一个子命令,就删掉对应的旧代码。整个过程持续了四个迭代,每个迭代结束时工具都是可用的。

这里的关键是控制爆炸半径。敏捷开发不是"快就行",而是"小步快跑,每步可回退"。我们给每个迁移的子命令都加了特性开关,线上出问题一键切回旧逻辑。说实话,这个开关救过我们两次。

还有一点:把技术债务可视化。我们在项目看板上专门开了一列"债务项",每个债务卡片都写清楚:影响范围、还债成本、不还的风险。这样产品经理也能看懂,排期时不会觉得我们在"瞎折腾"。

敏捷实践:让命令行工具也拥有"用户故事"

您可能会想,命令行工具给内部人用的,需要那么正式吗?我们的经验是:越内部的工具,越要讲用户故事。因为内部用户不会像外部用户那样写工单,他们只会说"那个命令又挂了"。

我们把每个子命令都写成用户故事。比如:"作为后端工程师,我希望用一条命令把当前分支部署到预发环境,以便快速验证联调。" 然后围绕这个故事定义验收标准:命令名称、参数格式、成功输出、失败提示、退出码。

这样做的好处是,迭代评审时大家有据可依。以前我们说"优化了部署命令",现在说"完成了'一键部署预发'故事,参数从 6 个减到 2 个,平均耗时从 45 秒降到 12 秒"。数据具体了,团队成就感也强了。

另外,我们坚持每两周做一次 CLI 体验走查。就是让一个不常使用该工具的同事,照着文档跑一遍核心流程。您猜怎么着?每次都能发现几个"反人类"的设计。比如错误提示只写"参数错误",不告诉用户哪个参数错了。这种问题测试测不出来,只有真人用才会暴露。

总结:还债不是目的,持续交付才是

复盘下来,我们最大的体会是:命令行工具的技术债务,本质上是反馈回路太长造成的。写的时候爽,改的时候痛。要打破这个循环,就得把测试、迁移、用户故事这三件事串起来。

现在我们的 deploy-cli 代码量从 3000 行降到 1800 行,核心逻辑全部有测试覆盖,新增一个子命令从两天缩短到两小时。更重要的是,团队不再害怕改这个工具了。

如果您手上也有类似的"祖传命令行",我建议您从今天开始做一件事:挑一个最常用的子命令,给它补上三个测试用例。不用多,三个就行。然后您会发现,当您下次想改它的时候,心里有底了。技术债务不会自己消失,但我们可以让它变得可控。您说呢?