把一次性脚本整理成可复跑的工程步骤

很多团队都会积累一批临时脚本：导数据、补配置、批量改文件、清理缓存、生成报表。它们通常从一次问题处理开始，能跑通，但没有边界、没有检查、没有回滚提示。问题不在于脚本短，而在于它已经承担了生产操作，却仍按临时命令的方式维护。

本文讨论的不是如何把所有脚本改造成复杂平台，而是如何把一个已经有价值的脚本整理成可复跑、可审查、可交接的工程步骤。结论是：先明确输入输出和影响范围，再补齐预检查、幂等处理、日志记录和失败退出，让脚本从“某个人会用”变成“按说明就能稳定执行”。

一、问题背景

一次性脚本最容易被低估，因为它看起来没有服务端接口、没有长期运行进程，也不需要复杂架构。但它经常直接接触数据库、文件系统、制品仓库或线上配置，一旦参数写错、目录选错、重复执行，就可能产生难以追踪的副作用。

这类问题值得写，是因为脚本通常处在流程边缘：它不一定进入常规代码评审，不一定有测试，也不一定被监控覆盖。越是边缘工具，越需要用简单明确的工程约束降低风险。

本文限定讨论小型自动化脚本，例如 Shell、Python、Node.js 命令行工具或项目内维护脚本。重点不是语言选择，而是执行前后如何让结果可预测、失败可定位、再次运行不造成额外损害。

二、核心思路

• 把脚本当作一次受控变更，而不是一串命令。脚本需要说明它会读取什么、修改什么、依赖什么环境，以及成功后的状态是什么。
• 优先保证幂等性。理想情况下，脚本重复执行不会重复插入、重复删除或重复追加；如果无法做到幂等，也要显式阻止第二次执行。
• 先检查，再修改。预检查应该覆盖参数、路径、权限、依赖命令、目标资源状态和磁盘空间等基础条件。
• 默认保守执行。涉及删除、覆盖、迁移、批量写入时，提供 dry-run 或确认开关，让执行者先看到影响范围。
• 日志要面向排障。日志不需要铺满每一行代码，但必须记录输入参数、关键分支、变更数量、失败原因和最终结果。
• 退出码要可靠。成功返回 0，失败返回非 0，不要把错误吞掉后继续输出“完成”。

三、落地步骤

第一步，给脚本补一段固定说明，放在文件头部或相邻的 README 中。说明至少包含用途、输入、输出、副作用、示例命令和回滚方式。如果回滚做不到自动化，也要写清楚人工恢复需要哪些材料。

第二步，统一参数入口，避免在脚本正文中散落硬编码路径。简单脚本可以用环境变量和命令行参数，复杂一点的脚本可以读取配置文件，但不建议同时混用太多来源。

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

TARGET_DIR="${1:-}"
DRY_RUN="${DRY_RUN:-1}"

if [[ -z "$TARGET_DIR" ]]; then
  echo "usage: DRY_RUN=1 ./cleanup.sh <target_dir>" >&2
  exit 2
fi

if [[ ! -d "$TARGET_DIR" ]]; then
  echo "target_dir not found: $TARGET_DIR" >&2
  exit 2
fi

第三步，增加预检查函数，把真正修改资源之前必须满足的条件集中放在一起。这样评审时能快速看到脚本的安全边界，执行失败时也能尽早停止。

check_preconditions() {
  command -v find >/dev/null
  command -v sort >/dev/null

  if [[ ! -w "$TARGET_DIR" ]]; then
    echo "target_dir is not writable: $TARGET_DIR" >&2
    exit 2
  fi
}

第四步，先计算变更集合，再执行变更。不要一边遍历一边无提示地修改。先把候选项打印出来，dry-run 模式只展示不写入，正式执行时再逐项处理。

mapfile -t candidates < <(find "$TARGET_DIR" -type f -name "*.tmp" | sort)

echo "candidate_count=${#candidates[@]}"

for file in "${candidates[@]}"; do
  if [[ "$DRY_RUN" == "1" ]]; then
    echo "[dry-run] remove $file"
  else
    rm -- "$file"
    echo "removed $file"
  fi
done

第五步，补充结果摘要。摘要要能回答三个问题：脚本处理了多少对象、实际变更了多少对象、是否有跳过或失败项。对于批量操作，最好把明细输出到日志文件或报告文件，便于复核。

第六步，把常用执行命令固化到项目任务中，例如 npm scripts、Makefile、justfile 或 CI 手动任务。这样可以减少口头传递参数，也方便后续把脚本纳入构建或发布流程。

四、常见坑

• 只在本机验证，没有检查目标环境是否具备相同命令、权限和目录结构。
• 使用相对路径直接删除或覆盖文件，执行目录变化后影响范围失控。
• 把 dry-run 做成单纯打印命令，但正式执行路径和预览路径不是同一套逻辑。
• 捕获异常后继续执行，最后仍然返回成功退出码。
• 日志只写“开始”和“完成”，没有记录处理对象数量和关键参数。
• 默认直接修改真实资源，没有显式的环境标识、确认开关或备份策略。
• 重复执行会追加重复内容，或者再次删除已经被前一次移动的文件。
• 脚本依赖外部状态，却没有把状态版本、输入文件校验和或执行批次记录下来。

五、检查清单

• 脚本用途、输入、输出和副作用已经写清楚。
• 所有路径、环境、账号和目标资源都通过参数或配置传入。
• 修改资源前已经完成参数、权限、依赖命令和目标状态检查。
• 支持 dry-run，且 dry-run 与正式执行共用同一套候选集合计算逻辑。
• 重复执行不会产生重复变更；无法幂等时已经显式阻止重复执行。
• 失败时会返回非 0 退出码，并输出可定位的错误信息。
• 日志包含关键参数、候选数量、实际变更数量和跳过原因。
• 涉及删除、覆盖或迁移时，已经准备备份、恢复步骤或人工回滚说明。
• 常用命令已经固化到项目任务中，避免依赖口头记忆。

六、小结

把一次性脚本整理成可复跑步骤，核心不是增加很多框架，而是补齐执行边界：它处理什么、什么时候可以处理、失败时停在哪里、重复运行会发生什么。只要这些问题有明确答案，脚本的风险就会明显下降。

工程实践里，临时工具经常会变成长期资产。与其等它在关键时刻暴露问题，不如在第一次复用前完成最小工程化：参数化、预检查、dry-run、幂等、日志和退出码。这些约束成本不高，却能让脚本从个人经验变成团队可维护的操作流程。