自动化的失败路径：幂等、超时与回滚该在脚本里怎么落

写一段自动化脚本之前，先回答一个问题：同一段脚本原样再跑一次，会改变什么？这个问题比"能省多少时间"更能决定工具能否长期用下去。本文只给通用判断框架和检查项，不涉及具体产品的版本、价格或性能；本次没有可核验的联网材料，凡涉及具体接口是否支持去重、限流阈值多少这类事实，都需以对应官方文档为准（待核实）。

先问重放，再问收益#

效率工具的收益是可累加的，故障成本往往不是。一次重复提交、重复扣费或重复通知，可能抵掉很多天省下的时间。这是基于常见工程经验的推断，不是实测结论；但从风险结构上看，它决定了脚本该写成什么样。

幂等的三种常见做法#

幂等（idempotent）指同一请求执行一次与执行多次，对系统状态的最终影响相同。

• 天然幂等：纯读取，或"整条覆盖写入"语义的接口。是否真的覆盖而非追加，需按接口文档核实。
• 键控去重：客户端生成请求标识或业务唯一键，服务端保存已处理记录并拒绝重复。前提是服务端支持，不能只在客户端假设。
• 状态守卫：只有处于某个状态的记录才允许推进到下一状态，重复调用会被状态检查挡下。这层守卫最好放在自己的数据里，不完全依赖外部接口。

超时与重试：区分"没发生"和"不知道有没有发生"#

连接阶段失败，通常可以判定请求没发出去；而等待响应超时属于未知状态——对方可能已经处理完了。对未知状态直接重试，就是重复副作用的来源。可落地的做法：

• 给每个网络调用设置显式超时，不用默认值兜底。
• 只对可判定安全的失败做自动重试；未知状态转人工核对或走查询接口确认后再决定。
• 重试次数设上限，配合退避与随机抖动，避免把自己的请求叠成对方的一次流量峰值。具体退避参数与接口限流上限待核实。
• 超过上限就停止并告警，不做无限重试。

日志要能回答三个问题#

输入是什么（脱敏后的标识，不要写入密钥或完整个人数据）；失败停在哪一步；重放需要什么。建议每条记录带运行标识、步骤名、结果分类（成功／失败／未知）和耗时字段。耗时在未测量前不要写成任何固定数值。

# 未执行示例：仅展示结构，不保证可直接运行
# 环境：Python 3.x（具体版本未核实）；依赖接口自身支持幂等键
import uuid
from dataclasses import dataclass

@dataclass
class StepResult:
    run_id: str
    step: str
    status: str      # "ok" / "failed" / "unknown"

def classify(exc) -> str:
    # 需按实际 SDK 的异常类型细分；此处为占位逻辑
    return "unknown"

def run_step(fn, run_id: str):
    try:
        fn()
        return StepResult(run_id, fn.__name__, "ok")
    except Exception as exc:
        return StepResult(run_id, fn.__name__, classify(exc))

把"停"当成一项功能#

• 干跑模式：先输出"将要做什么"的清单，人工确认后再执行写操作。
• 分批与上限：批量任务按固定条数切分，任一批失败即暂停，避免一次跑完全部。
• 开关：留一个能立刻停掉任务的入口，并写清谁来关、关了之后状态停在哪。
• 回滚脚本：和正向脚本一起写、一起评审。事后补写的回滚，通常缺少必要字段。

不适合自动化的情形#

一次性操作、规则仍在频繁变动、以及失败代价不可逆又缺少补偿手段的动作（例如对外发送通知、涉及资金的写操作），通常更适合"人执行＋清单核对"。这类场景写脚本的维护成本高于收益，判断依据是重放代价，不是技术难度。

回到开头那个问题：自动化脚本的价值不在跑得快，而在失败后可预测、可重放、可停止。做不到这三点，先别扩大它的执行范围。