工具脚本上线前的避坑清单

脚本在本地跑通，只说明它在一条顺利路径上成立。真正决定它能否被反复使用的，是异常输入、重复执行和失败之后的可恢复性。以下检查点适合在把脚本交给他人或挂到定时任务之前逐项确认。

一、输入边界与参数校验
先列出脚本接受的全部输入：命令行参数、环境变量、配置文件、标准输入、被读取的文件。对每一类输入明确三件事——缺省值是什么、非法值如何拒绝、超范围如何提示。常见坑是参数缺省时静默使用危险默认值，例如未指定目标目录就操作当前目录。校验应在任何写操作之前完成，先全部校验再执行，避免执行到一半才发现参数错误。对文件类输入，检查是否存在、是否可读、是否为预期类型；对路径类输入，注意结尾分隔符、相对路径与符号链接带来的歧义。提示信息要指出“哪个参数、期望什么、实际收到什么”，而不是只抛一句通用错误。

二、幂等性与重复执行
问自己一个问题：同一命令连续执行两次，结果是否一致？如果第二次会追加重复数据、重复创建资源、重复发送通知，就说明缺少幂等设计。常见做法包括执行前检查目标状态、使用唯一标识去重、把“已处理”记录在可查询的位置。对批量处理类脚本，要能从中断处继续，而不是每次从头开始；这要求处理进度可持久化，且单条处理具备可重入性。另一个隐蔽问题是并发：两个实例同时运行时，是否会出现互相覆盖。若无法保证串行，至少要有互斥标记，并在获取失败时给出明确退出码。

三、日志、退出码与回滚
日志要能回答三个问题：做了什么、影响了哪些对象、失败在哪一步。避免只打印“开始”“结束”，要在关键分支输出可核对的标识。退出码应区分成功、参数错误、运行失败、部分成功，方便上层调度判断。涉及写操作的脚本，执行前应说明如何回滚：是备份原文件、生成反向操作清单，还是依赖版本快照。没有回滚路径的批量修改，风险远高于收益。建议先在少量样本上试运行，核对输出与预期一致后再扩大范围；试运行模式应真实读取、只跳过写入，而不是走一条与正式路径不同的分支，否则验证没有意义。

四、交付与复查
交付时附上最小使用示例、参数表、已知限制和失败排查顺序。把“不要做什么”写清楚，例如不要在目标目录仍有写入时执行清理。定期复查脚本依赖的外部命令是否仍然存在、输出格式是否变化。工具脚本的可靠性来自边界清晰和失败可见，而不是代码写得多短。