自动化脚本从能跑到敢用：失败分层、幂等与上线前自检

开发者效率工具的讨论常停在“选哪个工具”，但脚本进入日常流程之后，真正决定维护成本的是失败时的表现：能不能被发现，能不能安全重跑，能不能一键停掉。如果这三件事没有答案，那么它更适合留在本地手动执行，而不是挂进定时任务。

一、先给失败分层，别让退出码承担全部语义#

进程退出码只能表达“程序有没有正常结束”，不能表达“事情有没有办成”。实践中至少要区分三类结果：

• 执行失败：网络不可达、权限不足、依赖缺失，任务根本没跑起来。
• 业务失败：请求返回了，但响应体里带错误码，例如参数不合法。
• 部分成功：批量处理 100 条，成功 97 条，失败 3 条。

第三类最容易被写成退出码 0。一旦这样处理，调度系统认为一切正常，失败的那 3 条就再也没人看。建议给“部分成功”单独编码，并在日志里带上失败条数与失败标识列表；是否告警由调用方决定，但信息必须留出来。

二、幂等：重跑之前先问“会不会重复写入”#

幂等（idempotency）指同一操作执行多次与执行一次的结果一致。它不是“代码能跑两遍不报错”，而是“跑两遍之后数据状态相同”。常见手段有三种：

• 自然键去重：用业务上唯一的键判断是否已处理过。
• 写前查：先查目标状态，再决定新增还是更新。
• 只追加不改写：把变更写成事件记录，汇总交给下游计算。

不能幂等的步骤，就不要交给自动重试。发通知、扣额度、触发下游流水线这类有外部副作用的动作，宁可停下来等人确认。

三、超时、重试与限额：重试要有限定原则#

重试不是“失败就再来一次”，需要三条约束同时成立：对象可重试、操作幂等、次数与总时长有上限。超时、限流响应、服务端临时错误通常可以重试；参数错误、鉴权失败重试多少次都是同样结果，只会放大调用量。

退避策略建议用指数退避加随机抖动，并设置总时长上限——否则一次故障会占满执行窗口，把下一次调度也挤掉。涉及外部接口的配额、限速与计费规则，应以官方文档为准；本文没有联网核验，也不提供具体数值。若脚本通过 API.PLUS 这类接口平台调用外部服务，端点、配额与定价同样待核实，不要在代码里写死猜测值。

四、让失败可见：run_id、日志字段与 dry-run#

可观测性不必从监控系统开始，先把每次运行记录成一条可检索的记录就够了。建议至少包含：run_id、开始与结束时间、输入摘要（不含密钥）、结果分类、失败条数、失败标识。run_id 的价值在于把一次运行产生的所有日志串起来，排查时不用靠时间戳猜。

另一个低成本手段是 dry-run：默认只打印“将要做什么”，确认无误后再加参数真正执行。对批量改写类脚本，这一步能挡掉大部分误操作。

# 未执行示例：仅示意结构，不是可运行代码，也未在本机运行
# 适用环境：Python 3.x 语法层面，实际项目需替换为真实的调用与存储实现

def run_job(items, dry_run=True):
    run_id = new_run_id()                 # 占位实现
    failed = []
    for item in items:
        if dry_run:
            log(run_id, "would_process", item.key)
            continue
        if already_done(item.key):        # 幂等判据：自然键去重
            continue
        try:
            process(item, timeout=10)     # 超时必须有
        except Retryable as e:            # 仅可重试错误进入重试
            failed.append((item.key, str(e)))
        except Exception as e:            # 不可重试：记录并继续
            failed.append((item.key, str(e)))
    log(run_id, "done", ok=len(items) - len(failed), failed=len(failed))
    return 1 if failed else 0             # 部分成功用非 0 表达

上面的片段刻意省略了重试循环与退避实现，只表达分类与记录的位置。它没有被执行，也不构成可直接使用的模板。

五、上线前自检清单#

1. 退出码能否区分执行失败、业务失败与部分成功？
2. 每个写操作是否有幂等判据？不能幂等的步骤是否已改为人工确认？
3. 是否设置了请求超时、最大重试次数与总时长上限？
4. 失败信息是否带 run_id 与失败标识，能否事后定位到具体条目？
5. 是否有 dry-run 开关，默认关闭真实写入？
6. 是否有一键停用方式（注释定时任务不算，要能在不改代码的情况下停）？
7. 密钥是否只存在于服务端环境变量，未进入日志与仓库？

边界：这些做法管不到的地方#

判断标准是重跑代价，而不是脚本长短。只在本地运行、结果可逆、失败重跑无副作用的一次性脚本，做到退出码清晰、日志能看懂即可，不必套用完整清单。反过来，只要涉及写外部系统、批量数据或额度变动，就应按上面的顺序补课。

本文未联网核验，也没有可核验的实测记录；涉及具体工具版本、价格、配额与性能的部分均未展开，需要时请以对应官方文档为准。真正可迁移的结论只有一条：把自动化脚本当作需要运维的对象来设计失败路径，它才值得被放进日常流程。