把临时脚本整理成可重复的小工具

很多团队都会写临时脚本：批量改文件名、导出数据、生成配置、清理日志、检查构建产物。脚本第一次出现时通常只为解决一个具体问题，写得快、跑得通就够了，但它一旦被第二次使用，就已经进入了工程资产的范围。

本文讨论的不是把脚本做成完整平台，而是如何在成本可控的前提下，让一个临时脚本具备可重复执行、可定位问题、可交接维护的基本能力。结论很简单：先固定输入输出边界，再补齐失败处理和运行说明，最后才考虑抽象和扩展。

适用场景包括本地开发辅助脚本、CI 中的小型检查任务、一次性迁移后仍可能复用的数据处理脚本。对于只运行一次且已经归档的脚本，不必过度整理；对于会被多人、定期或自动化环境调用的脚本，则应该尽早收敛成稳定工具。

一、问题背景

临时脚本最常见的问题不是代码写得短，而是执行条件隐藏在作者的记忆里。比如依赖当前目录、默认环境变量、某个未提交的配置文件，或者要求调用者先手动清理输出目录。这些条件没有被记录时，脚本表面上只有几十行，实际维护成本却很高。

本文只讨论小型脚本的工程化处理，不覆盖大型命令行框架、插件系统、任务编排平台等复杂形态。目标是让脚本在保留轻量特征的同时，具备清晰的调用方式和可预期的失败行为。

二、核心思路

先定义边界。脚本应该明确从哪里读取输入、向哪里写入输出、会修改哪些文件、是否允许重复运行。边界越清楚，调用者越容易判断它能否放入自动化流程。

把隐式假设变成显式检查。与其让脚本在中间步骤因为空路径、缺文件或权限不足而失败，不如在开头检查必要条件，并给出明确错误信息。

保持默认行为保守。会删除、覆盖、迁移数据的脚本，应优先支持预览模式或要求显式参数确认。自动化工具最怕含糊的默认动作。

先记录用法，再拆分代码。很多脚本不需要复杂抽象，只需要一段清楚的参数说明、几个函数边界和稳定的退出码。过早拆成多个模块，反而会增加理解成本。

三、落地步骤

第一步，给脚本补一个固定入口。入口只负责解析参数、检查环境和调度主流程，具体处理逻辑放到函数中，避免所有代码堆在全局作用域。

#!/usr/bin/env bash
set -euo pipefail

usage() {
  printf 'Usage: %s --input <dir> --output <dir> [--dry-run]\n' "$0"
}

dry_run=0
input_dir=''
output_dir=''

while [ "$#" -gt 0 ]; do
  case "$1" in
    --input)
      input_dir="${2:-}"
      shift 2
      ;;
    --output)
      output_dir="${2:-}"
      shift 2
      ;;
    --dry-run)
      dry_run=1
      shift
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      usage
      exit 2
      ;;
  esac
done

第二步，集中做前置检查。检查内容至少包括输入路径是否存在、输出路径是否可写、必要命令是否可用、关键参数是否为空。

require_command() {
  if ! command -v "$1" >/dev/null 2>&1; then
    printf 'missing required command: %s\n' "$1" >&2
    exit 1
  fi
}

validate_args() {
  if [ -z "$input_dir" ] || [ -z "$output_dir" ]; then
    usage
    exit 2
  fi

  if [ ! -d "$input_dir" ]; then
    printf 'input directory does not exist: %s\n' "$input_dir" >&2
    exit 1
  fi
}

require_command find
validate_args

第三步，明确输出策略。脚本生成的文件应尽量写入指定目录，不要散落在当前目录或用户主目录。需要覆盖时，先判断目标是否存在，并在日志里写清楚动作。

第四步，增加最小可验证样例。可以在仓库中保留一组小输入，或者在说明文档里提供一条可复制的命令。目标不是做完整测试框架，而是让维护者能快速确认脚本仍然可运行。

./tools/normalize-name.sh \
  --input ./examples/raw \
  --output ./tmp/normalized \
  --dry-run

第五步，将脚本接入自动化前先固定退出码。参数错误返回 2，运行失败返回 1，成功返回 0。这样 CI 或上层任务才能可靠判断结果，而不是解析一段不稳定的文本输出。

四、常见坑

只在本机路径上验证。脚本里写死 /Users/name/project 或 /home/user/tmp，很容易在 CI、容器或其他开发机上失效。

把日志当作接口。调用方如果依赖某一行日志判断成功失败，脚本稍微调整输出就会破坏流程。成功失败应该通过退出码或结构化产物表达。

忽略重复执行。很多脚本第一次运行成功，第二次因为输出目录已存在、临时文件残留或数据已部分迁移而失败。需要明确脚本是幂等、可覆盖，还是只能运行一次。

默认执行高风险操作。清理、覆盖、迁移类脚本如果默认直接生效，调用者很难在不读源码的情况下评估风险。更稳妥的方式是默认预览，或要求传入 --apply。

缺少失败现场。脚本失败后只输出 error，维护者无法知道处理到哪个文件、哪个步骤、哪个外部命令。至少应输出当前处理对象和失败原因。

五、检查清单

• 文件名、参数名和输出目录能表达脚本用途
• 脚本开头启用了必要的失败控制或异常处理
• 所有必需参数都有校验，错误信息能定位问题
• 依赖的外部命令、环境变量或配置文件已显式检查
• 高风险操作支持预览模式或显式确认参数
• 输出文件集中写入指定目录，避免污染调用者当前目录
• 重复执行的行为已经定义并验证
• 成功、参数错误、运行失败使用稳定退出码
• README、注释或帮助信息中包含最小运行示例
• 接入 CI 前已用小样例跑过一次完整流程

六、小结

临时脚本是否值得整理，关键不在于行数，而在于它是否会再次被使用、是否会影响共享流程、是否需要别人接手。只要答案中有一个是肯定的，就应该至少补齐输入输出、前置检查、失败信息和运行示例。

把脚本整理成小工具不需要一次完成。先让它可重复运行，再让它可诊断，最后再考虑复用和抽象，这个顺序通常更符合实际维护成本。