工具脚本入门：写好一个可复用的小工具

工具脚本的价值在于把重复动作固定下来，但很多脚本写完只用一次就废弃，原因往往不是功能不对，而是设计时没考虑复用。下面这套方法围绕“能不能被别人接手使用”展开。

一、先判断该不该写成脚本
不是所有重复劳动都值得脚本化。判断标准有三条：动作是否高频、步骤是否稳定、输入是否可枚举。高频且步骤固定的任务最适合；步骤每次都要人工判断的，脚本只能做辅助；输入来源不固定的，先规范输入再考虑自动化。另外要评估风险：涉及删除、覆盖、批量修改的操作，脚本必须带确认或试运行模式，否则一次误操作代价很高。明确边界之后，再决定脚本是只做一步，还是串起整条流程。

二、参数与输入输出的约定
好脚本的接口应当一眼看懂。参数设计遵循几条：必填参数放前面，可选参数给默认值，危险操作单独开关，路径类参数支持相对与绝对两种写法。输入尽量从标准输入或文件读取，避免把数据写死在代码里。输出要分两类：给人看的结果摘要，给程序用的结构化结果。摘要简短说明做了什么、影响多少条、是否成功；结构化结果便于后续串联。退出状态要能区分成功、参数错误、执行失败，这样在流程里调用时才能判断下一步。

三、出错处理与可观测性
脚本最常见的失败不是逻辑错，而是环境不对：路径不存在、权限不足、依赖缺失、编码不一致。所以开头先做前置检查，把可能的环境问题挡在业务逻辑之前。执行过程中每一步都输出简短进度，失败时给出具体位置和原因，而不是只抛一句通用错误。对批量操作，记录每条的处理结果，失败的单独汇总，方便重跑。重跑要幂等：同一输入执行多次结果一致，已经处理过的跳过。做不到幂等时，至少提供断点续跑的参数。

四、验收与交付
写完不等于可用。验收清单包括：空输入、异常输入、超大输入各跑一次；路径含空格与中文时是否正常；权限不足时提示是否清楚；中断后再执行是否安全；输出结果是否可直接被下游使用。交付时附一段简短说明：用途、依赖、参数含义、示例命令、已知限制。示例命令比长篇文档更有用。把脚本放在固定目录并统一命名，长期积累下来就是一套顺手的小工具箱。

五、常见误区
把业务规则硬编码进脚本，规则一变就要改代码；把日志和结果混在一起输出，导致无法自动解析；缺少试运行模式，第一次执行就是正式执行；错误处理只写一句捕获全部异常，掩盖了真实原因；脚本之间互相调用却没有约定退出状态。避开这些，脚本的寿命会明显变长。最后提醒一点：脚本能力越强，越要限制它的作用范围，默认只处理明确指定的目标，不要提供“全量处理”的默认行为。