命令行与文本处理 / 系统课时
加入重试与幂等控制
加入重试与幂等控制
本课把批量巡检中的临时失败变成可恢复任务:只重试网络抖动、超时等可恢复错误,用退避间隔降低持续冲击,并通过持久化任务状态保证同一任务重复执行时不会再次产生副作用。
学习目标
- 区分可重试错误与必须立即失败的错误
- 实现指数退避、状态记录和幂等跳过
- 验证首次执行、重试成功与重复运行三种结果
先划定重试边界
重试不是“出错后再跑一次”,而是只针对短暂且有恢复可能的故障。连接超时、服务暂时不可用、远程主机忙碌通常可以重试;参数错误、权限不足、脚本语法错误和业务校验失败通常应立即终止,否则只会放大负载并掩盖根因。
每次任务都应有稳定的幂等键,例如“任务类型 + 主机名 + 巡检日期”。执行前先读取状态:若已经完成则直接返回;若未完成才进入重试循环。成功后必须先落盘状态,再向上游确认完成,避免进程在两步之间退出后重复产生副作用。
状态与执行流程

这个流程把“是否执行”和“如何恢复”分开:幂等状态决定任务能否进入执行阶段,重试策略只处理单次执行中的临时失败。两者缺一不可;只有重试会重复副作用,只有幂等则无法自动恢复短暂故障。
主示例:退避重试并持久化完成状态
下面脚本使用 JSON 文件保存任务状态。示例操作前两次抛出临时网络错误,第三次成功;同一幂等键再次调用时会直接跳过。生产环境可把状态文件替换为数据库或 Redis,但状态判断顺序不变。
param(
[switch]$ResetDemoState
)
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
$statePath = Join-Path $env:TEMP 'anystack-retry-state.json'
if ($ResetDemoState -and (Test-Path $statePath)) {
Remove-Item $statePath -Force
}
function Read-TaskState {
if (-not (Test-Path $statePath)) {
return @{}
}
Get-Content $statePath -Raw | ConvertFrom-Json -AsHashtable
}
function Write-TaskState {
param([hashtable]$State)
$tempPath = "$statePath.tmp"
$State | ConvertTo-Json -Depth 6 |
Set-Content $tempPath -Encoding utf8
Move-Item $tempPath $statePath -Force
}
function Invoke-IdempotentTask {
param(
[Parameter(Mandatory)]
[string]$Key,
[Parameter(Mandatory)]
[scriptblock]$Operation,
[int]$MaxAttempts = 4,
[int]$BaseDelayMilliseconds = 100
)
$state = Read-TaskState
if ($state.ContainsKey($Key) -and $state[$Key].Status -eq 'Completed') {
Write-Host "SKIP task=$Key status=Completed"
return $state[$Key].Result
}
for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
try {
$result = & $Operation
$state[$Key] = @{
Status = 'Completed'
Attempts = $attempt
Result = $result
UpdatedAt = (Get-Date).ToString('o')
}
Write-TaskState -State $state
Write-Host "SUCCESS task=$Key attempt=$attempt result=$result"
return $result
}
catch {
Write-Host "Attempt $attempt failed: $($_.Exception.Message)"
if ($attempt -eq $MaxAttempts) {
$state[$Key] = @{
Status = 'Failed'
Attempts = $attempt
Error = $_.Exception.Message
UpdatedAt = (Get-Date).ToString('o')
}
Write-TaskState -State $state
throw
}
$delay = $BaseDelayMilliseconds * [math]::Pow(2, $attempt - 1)
Write-Host "Retrying after $([int]$delay) ms"
Start-Sleep -Milliseconds $delay
}
}
}
$script:simulatedCalls = 0
$operation = {
$script:simulatedCalls++
if ($script:simulatedCalls -lt 3) {
throw 'temporary network error'
}
'inventory-saved'
}
Invoke-IdempotentTask -Key 'host-web-01' -Operation $operation | Out-Null
Invoke-IdempotentTask -Key 'host-web-01' -Operation $operation | Out-Null使用 pwsh ./retry-demo.ps1 -ResetDemoState 首次运行,预期输出如下:
Attempt 1 failed: temporary network error
Retrying after 100 ms
Attempt 2 failed: temporary network error
Retrying after 200 ms
SUCCESS task=host-web-01 attempt=3 result=inventory-saved
SKIP task=host-web-01 status=Completed状态文件实际位于 <PATH>/anystack-retry-state.json,其中 <PATH> 会随操作系统临时目录而变化。之后不带 -ResetDemoState 再运行,两个调用都会命中 Completed 并跳过。
验收与生产边界
验收时至少检查三件事:临时错误是否按预期间隔重试,成功后状态是否持久化,以及相同幂等键是否不再执行操作。若任务会调用写接口、创建文件或发送消息,还应让下游同时接受幂等键,避免状态写入前进程崩溃造成重复副作用。
指数退避通常还会加入随机抖动,防止大量任务同时恢复后再次冲击目标服务。对于权限、参数和数据校验错误,应使用错误分类直接失败;不要把所有异常都塞进同一个重试循环。