📚 课程目录第3章幂等性设计原则

3. 幂等性设计原则：为什么它如此重要

先问大家一个问题：你写的升级脚本，跑一次和跑十次，结果一样吗？

如果答案是不确定，那你很可能踩过幂等性的坑。我见过太多运维事故，都是因为脚本不是幂等的——跑一半失败了，重试一次，系统直接崩了。

说白了，幂等性就是：同一个操作，执行任意多次，产生的效果与执行一次完全相同。这不是锦上添花，而是升级脚本的生存底线。

核心定义：对于函数 f，如果 f(f(x)) = f(x)，则 f 是幂等的。在运维脚本中，这意味着重复执行不会产生副作用。

3.1 为什么幂等性如此重要

我在项目中遇到过这样一个案例：某次数据库迁移脚本，执行到一半网络断了。运维同学重启脚本，结果重复插入了 3 万条重复记录。恢复数据花了整整两天。

为什么会这样？因为脚本没有做幂等检查。它只管执行，不管状态。

幂等性重要，主要有三个原因：

网络不可靠——脚本随时可能中断，重试是常态
人工操作会出错——运维手抖点两次，脚本就跑两遍
自动化编排需要——Ansible、SaltStack 等工具默认会重试，非幂等脚本就是定时炸弹

我曾经踩过的坑：写了一个初始化配置的脚本，每次执行都会在 /etc/nginx/conf.d/ 下追加 upstream 配置。结果 CI/CD 跑了 5 次，Nginx 里出现了 5 份相同的 upstream 块，直接导致负载均衡策略错乱。从那以后，我所有脚本的第一行逻辑都是：检查是否已经执行过。

3.2 如何实现幂等：三种核心方法

实现幂等性，我总结了三板斧。你不需要全部用上，但至少得选一种。

3.2.1 检查状态法

这是最常用的方法。执行操作前，先检查目标状态是否已经满足。

#!/bin/bash
# 检查状态法示例：创建用户

# 先检查用户是否存在
if id "appuser" &>/dev/null; then
    echo "[INFO] 用户 appuser 已存在，跳过创建"
else
    useradd -m -s /bin/bash appuser
    echo "[INFO] 用户 appuser 创建成功"
fi

# 检查目录是否存在
if [ -d "/data/app/logs" ]; then
    echo "[INFO] 日志目录已存在，跳过"
else
    mkdir -p /data/app/logs
    echo "[INFO] 日志目录创建成功"
fi

我个人习惯用这种模式写所有配置脚本。你想想看，检查一下状态又不费多少时间，但能避免 90% 的重试问题。

3.2.2 标记文件法

对于复杂操作，状态检查可能太麻烦。这时候可以用标记文件。

#!/bin/bash
# 标记文件法示例：数据库初始化

MARKER_FILE="/var/lib/mysql/.init_done"

if [ -f "$MARKER_FILE" ]; then
    echo "[INFO] 数据库已初始化，跳过"
    exit 0
fi

# 执行初始化操作
mysql -e "CREATE DATABASE IF NOT EXISTS myapp;"
mysql -e "CREATE USER 'app'@'localhost' IDENTIFIED BY 'password';"
mysql -e "GRANT ALL ON myapp.* TO 'app'@'localhost';"

# 创建标记文件
touch "$MARKER_FILE"
echo "[INFO] 数据库初始化完成"

小技巧：标记文件里可以写入执行时间、版本号、校验和等信息。这样不仅能判断是否执行过，还能判断是否需要重新执行。

3.2.3 原子操作法

对于关键操作，要用数据库或文件系统的原子特性来保证。

#!/bin/bash
# 原子操作法示例：使用 Redis SETNX 实现分布式锁

# 尝试获取锁（SETNX 是原子操作）
LOCK_ACQUIRED=$(redis-cli SETNX upgrade_lock "in_progress" 2>/dev/null)

if [ "$LOCK_ACQUIRED" != "1" ]; then
    echo "[ERROR] 升级任务已在执行中，退出"
    exit 1
fi

# 设置锁过期时间，防止死锁
redis-cli EXPIRE upgrade_lock 3600

# 执行升级操作
echo "[INFO] 开始执行升级..."
# ... 升级逻辑 ...

# 释放锁
redis-cli DEL upgrade_lock
echo "[INFO] 升级完成，锁已释放"

嗯，这里要注意：原子操作法通常用于分布式环境，单机脚本用前两种就够了。

3.3 三种方法对比

方法	适用场景	优点	缺点
检查状态法	配置管理、用户创建、目录创建	逻辑清晰，无额外文件	状态检查逻辑可能复杂
标记文件法	数据库初始化、数据导入、复杂流程	实现简单，容易理解	标记文件可能被误删
原子操作法	分布式锁、关键资源操作	强一致性，防并发	依赖外部组件（Redis/数据库）

3.4 幂等性测试方法

写完了脚本，怎么验证它是不是真的幂等？我有一套标准流程。

3.4.1 基础测试：重复执行

最简单的测试：把脚本跑三遍，每次检查结果是否一致。

#!/bin/bash
# 幂等性测试脚本

for i in 1 2 3; do
    echo "=== 第 $i 次执行 ==="
    ./upgrade.sh
    
    # 检查关键状态
    if ! systemctl is-active --quiet myapp; then
        echo "[FAIL] 第 $i 次执行后服务未运行"
        exit 1
    fi
    
    # 检查配置文件是否重复
    CONFIG_COUNT=$(grep -c "upstream backend" /etc/nginx/conf.d/app.conf)
    if [ "$CONFIG_COUNT" -gt 1 ]; then
        echo "[FAIL] 配置文件存在重复内容"
        exit 1
    fi
    
    echo "[PASS] 第 $i 次执行通过"
done

echo "[PASS] 幂等性测试通过"

3.4.2 中断恢复测试

模拟脚本执行到一半被中断，然后重新执行。

#!/bin/bash
# 中断恢复测试

# 在脚本关键位置插入中断点
sed -i '/^# 关键步骤：数据库迁移/a\    exit 1  # 模拟中断' upgrade.sh

# 执行脚本（预期会失败）
./upgrade.sh || true

# 恢复脚本
sed -i '/exit 1  # 模拟中断/d' upgrade.sh

# 重新执行
./upgrade.sh

# 检查数据一致性
mysql -e "SELECT COUNT(*) FROM users;" | grep -q "1000"
if [ $? -eq 0 ]; then
    echo "[PASS] 中断恢复后数据一致"
else
    echo "[FAIL] 中断恢复后数据异常"
fi

我曾经踩过的坑：测试幂等性时只测了正常情况，没测中断恢复。结果生产环境脚本跑到一半磁盘满了，重试后数据全乱了。现在我的测试用例里，中断恢复测试是必选项。

3.4.3 并发测试

对于可能并发执行的脚本，要测试同时跑多个实例的情况。

#!/bin/bash
# 并发测试：同时启动 5 个实例

for i in 1 2 3 4 5; do
    ./upgrade.sh &
done

wait

# 检查最终状态
# 应该只有一个实例成功执行
echo "[INFO] 并发测试完成"

3.5 幂等性设计知识图谱

下面这张图总结了幂等性设计的核心逻辑，你可以把它当作检查清单来用。

3.6 实战建议

最后，分享几个我个人的实战习惯：

脚本开头加幂等检查——就像开车前系安全带，形成条件反射
用函数封装幂等逻辑——写一个 ensure_state() 函数，到处调用
测试用例里包含幂等测试——CI/CD 流程中自动跑，不通过不允许上线
记录执行日志——每次执行都写日志，方便排查问题

我的习惯：所有升级脚本都用一个统一的幂等框架。开头检查状态，中间用标记文件记录进度，结尾验证结果。这样不管脚本多复杂，幂等性都不会丢。

记住：幂等性不是功能，而是质量属性。它不会让脚本跑出新功能，但能让脚本在任何情况下都安全可靠。写脚本时多花 10 分钟做幂等设计，能省下未来 10 小时的故障处理时间。