---
URL: "/zh-CN/blog/2025-08/dotnet_polly.html"
LLMS_URL: "/zh-CN/blog/2025-08/dotnet_polly.md"
lastUpdated: true
commentabled: true
recommended: true
title: ".NET 处理瞬态故障 Polly库 详解"
description: ".NET 处理瞬态故障 Polly库 详解"
date:
pageClass: "blog-page-class"
cover: "/covers/dotnet.svg"
---
---
lastUpdated: true
commentabled: true
recommended: true
title: .NET 处理瞬态故障 Polly库 详解
description: .NET 处理瞬态故障 Polly库 详解
date: 2025-08-04 14:00:00
pageClass: blog-page-class
cover: /covers/dotnet.svg
---
## 简介 ##
`Polly` 是处理 `.NET` 应用中瞬态故障的强大工具，通过提供丰富的弹性策略，帮助开发者构建更健壮、更具弹性的应用程序。合理使用 `Polly` 可以显著提高应用在面对网络波动、服务临时不可用等问题时的稳定性。
## Polly 核心策略详解 ##
`Polly` 提供七种策略应对不同故障场景，均支持流畅 `API` 链式调用
- 重试 (`Retry`)：短暂故障（如网络抖动）
- 熔断 (`Circuit Breaker`)：持续故障避免系统过载
- 超时 (`Timeout`)：防止长时间阻塞
- 隔板隔离 (`Bulkhead`)：限制并发资源消耗
- 回退 (`Fallback`)：失败时提供降级响应
- 缓存 (`Cache`)：高频数据加速访问
- 策略包装 (`PolicyWrap`)：组合多策略应对复杂故障
### 应用场景 ###
- 调用远程服务（`REST API`、微服务）
- 数据库操作
- 文件系统访问
- 任何可能出现暂时性故障的操作
### 示例 - 熔断+重试组合策略 ###
```csharp
var policy = Policy.Wrap(
Policy.Handle()
.CircuitBreaker(5, TimeSpan.FromSeconds(30)),
Policy.Handle()
.WaitAndRetry(3, attempt => TimeSpan.FromSeconds(attempt))
);
policy.Execute(() => CallExternalService());
```
## Polly 基本使用 ##
### 安装 NuGet 包 ###
```shell
dotnet add package Polly
```
### 基本策略使用模式 ###
```csharp
// 创建策略
var policy = Policy
.Handle() // 处理特定异常
.Retry(3); // 重试3次
// 执行受策略保护的操作
await policy.ExecuteAsync(async () =>
{
// 可能会失败的操作（如HTTP请求）
var response = await httpClient.GetAsync("https://api.example.com/data");
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsStringAsync();
});
```
## 核心策略详解 ##
### 重试策略（Retry） ###
```csharp
// 简单重试3次
var retryPolicy = Policy
.Handle()
.Retry(3);
// 带退避算法的重试（指数退避）
var retryWithBackoffPolicy = Policy
.Handle()
.WaitAndRetryAsync(
retryCount: 5,
sleepDurationProvider: retryAttempt =>
TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)), // 2, 4, 8, 16, 32秒
onRetry: (exception, sleepDuration, retryCount, context) =>
{
Console.WriteLine($"重试 {retryCount}: 等待 {sleepDuration.TotalSeconds}s 后重试，异常: {exception.Message}");
});
```
### 断路器策略（Circuit Breaker） ###
```csharp
// 简单断路器：连续3次失败后断开，断开30秒
var circuitBreakerPolicy = Policy
.Handle()
.CircuitBreaker(
exceptionsAllowedBeforeBreaking: 3,
durationOfBreak: TimeSpan.FromSeconds(30),
onBreak: (ex, breakDelay) => Console.WriteLine($"断路器断开: {ex.Message}"),
onReset: () => Console.WriteLine("断路器重置"),
onHalfOpen: () => Console.WriteLine("断路器半开状态")
);
// 高级断路器：基于失败比例（统计窗口内）
var advancedCircuitBreaker = Policy
.Handle()
.AdvancedCircuitBreaker(
failureThreshold: 0.5, // 50%的请求失败
samplingDuration: TimeSpan.FromSeconds(30), // 统计30秒内的请求
minimumThroughput: 10, // 至少10次请求才开始统计
durationOfBreak: TimeSpan.FromSeconds(30)
);
```
### 超时策略（Timeout） ###
```csharp
// 超时策略：操作超过5秒则终止
var timeoutPolicy = Policy
.Timeout(TimeSpan.FromSeconds(5), TimeoutStrategy.Pessimistic);
// 使用悲观超时策略并处理超时异常
try
{
await timeoutPolicy.ExecuteAsync(async () =>
{
// 可能耗时较长的操作
await Task.Delay(10000);
return "操作完成";
});
}
catch (TimeoutRejectedException ex)
{
Console.WriteLine($"操作超时: {ex.Message}");
}
```
### 隔离舱策略（Bulkhead Isolation） ###
```csharp
// 隔离舱：限制并发执行的操作数量
var bulkheadPolicy = Policy
.Bulkhead(
maxParallelization: 10, // 最多10个并发操作
maxQueuingActions: 5, // 最多5个操作排队等待
onBulkheadRejected: context =>
Console.WriteLine("隔离舱已满，请求被拒绝")
);
// 使用隔离舱策略
await bulkheadPolicy.ExecuteAsync(async () =>
{
// 受隔离舱保护的操作
await DoWorkAsync();
});
```
### 降级策略（Fallback） ###
```csharp
// 降级策略：操作失败时提供备选值
var fallbackPolicy = Policy
.Handle()
.FallbackAsync(
fallbackValue: "默认值",
fallbackAction: async ct => // 降级操作
{
return await CacheService.GetLatestDataAsync();
},
onFallbackAsync: ex =>
{
Console.WriteLine($"执行失败，使用降级策略: {ex.Exception.Message}");
return Task.CompletedTask;
}
);
// 使用降级策略
var result = await fallbackPolicy.ExecuteAsync(async () =>
{
// 可能失败的操作
return await GetDataFromServiceAsync();
});
```
### 缓存策略 (Cache) ###
```csharp
// 内存缓存策略
var cachePolicy = Policy.Cache(
new MemoryCacheProvider(myMemoryCache),
TimeSpan.FromMinutes(5)); // TTL=5分钟
// 使用示例
var result = cachePolicy.Execute(context =>
ExpensiveOperation(), new Context("cache_key"));
```
### 策略包装（Policy Wrap） ###
```csharp
var policyWrap = Policy.WrapAsync(fallbackPolicy, retryPolicy, circuitBreakerPolicy, timeoutPolicy);
var result = await policyWrap.ExecuteAsync(ct => _context.Users.FirstOrDefaultAsync(ct), cancellationToken);
```
### 健康检查策略 ###
```csharp
// 定义健康检查策略
var healthPolicy = Policy
.Handle()
.AdvancedCircuitBreaker(...)
.WrapAsync(Policy.TimeoutAsync(TimeSpan.FromSeconds(3)));
// 健康检查端点
app.MapGet("/health", async () =>
{
var healthResult = await healthPolicy.ExecuteAsync(async () =>
{
await db.CheckHealthAsync();
await queue.CheckHealthAsync();
});
return healthResult.IsHealthy ?
Results.Ok() : Results.StatusCode(503);
});
```
## 组合策略 ##
`Polly` 允许将多个策略组合成一个策略链（`Policy Wrap`）：
```csharp
// 组合重试、断路器和超时策略
var policyWrap = Policy.WrapAsync(
circuitBreakerPolicy, // 最外层：断路器
retryWithBackoffPolicy, // 中间层：带退避的重试
timeoutPolicy // 最内层：超时
);
// 使用组合策略执行操作
await policyWrap.ExecuteAsync(async () =>
{
// 受多重策略保护的操作
var response = await httpClient.GetAsync("https://api.example.com/data");
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsStringAsync();
});
```
## 策略上下文（Context） ##
通过 `Context` 可以在策略执行过程中传递自定义数据：
```csharp
// 创建带上下文的策略
var policy = Policy
.Handle()
.RetryAsync(3, (ex, retryCount, context) =>
{
// 从上下文中获取数据
if (context.ContainsKey("RequestId"))
{
Console.WriteLine($"请求 {context["RequestId"]} 重试 {retryCount}: {ex.Message}");
}
});
// 执行策略时传递上下文
await policy.ExecuteAsync(
async context =>
{
// 执行受保护的操作
return await DoWorkAsync();
},
new Context { { "RequestId", Guid.NewGuid().ToString() } }
);
```
## Polly 与 HttpClient 集成 ##
### 使用 Polly 与 HttpClientFactory ###
```csharp
// 注册 HttpClient 并应用 Polly 策略
services.AddHttpClient("ResilientClient")
.AddPolicyHandler(GetRetryPolicy())
.AddPolicyHandler(GetCircuitBreakerPolicy());
// 定义重试策略
private IAsyncPolicy GetRetryPolicy()
{
return HttpPolicyExtensions
.HandleTransientHttpError() // 处理常见HTTP错误（408, 500-599）
.OrResult(msg => msg.StatusCode == System.Net.HttpStatusCode.NotFound)
.WaitAndRetryAsync(
retryCount: 3,
sleepDurationProvider: retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
onRetry: (response, sleepDuration, retryCount, context) =>
{
Console.WriteLine($"HTTP请求失败，重试 {retryCount}: {response.Result?.StatusCode}");
}
);
}
// 定义断路器策略
private IAsyncPolicy GetCircuitBreakerPolicy()
{
return HttpPolicyExtensions
.HandleTransientHttpError()
.CircuitBreakerAsync(
exceptionsAllowedBeforeBreaking: 3,
durationOfBreak: TimeSpan.FromSeconds(30)
);
}
```
### 在控制器中使用 ###
```csharp
public class MyController : ControllerBase
{
private readonly HttpClient _httpClient;
public MyController(IHttpClientFactory clientFactory)
{
_httpClient = clientFactory.CreateClient("ResilientClient");
}
[HttpGet]
public async Task GetData()
{
var response = await _httpClient.GetAsync("https://api.example.com/data");
response.EnsureSuccessStatusCode();
return Ok(await response.Content.ReadAsStringAsync());
}
}
```
## 高级特性 ##
### 策略注册表（Policy Registry） ###
```csharp
// 注册策略到注册表
var policyRegistry = new PolicyRegistry
{
{ "RetryPolicy", Policy.Handle().Retry(3) },
{ "CircuitBreakerPolicy", Policy.Handle().CircuitBreaker(3, TimeSpan.FromSeconds(30)) }
};
// 从注册表获取策略
var retryPolicy = policyRegistry.Get("RetryPolicy");
```
### 自定义策略 ###
```csharp
// 创建自定义策略：记录所有操作
var loggingPolicy = Policy
.Handle()
.ExecuteAndCaptureAsync(async (ctx, cancellationToken) =>
{
Console.WriteLine($"开始执行操作: {ctx.OperationKey}");
try
{
var result = await ctx.CancellationToken.HasValue
? ctx.Action(ctx, ctx.CancellationToken.Value)
: ctx.Action(ctx, CancellationToken.None);
Console.WriteLine($"操作成功: {ctx.OperationKey}");
return result;
}
catch (Exception ex)
{
Console.WriteLine($"操作失败: {ctx.OperationKey}, 异常: {ex.Message}");
throw;
}
});
```
### 分布式断路器 ###
```csharp
// 使用Redis实现分布式断路器
public class RedisCircuitBreaker : AsyncCircuitBreakerPolicy
{
private readonly IDistributedCache _cache;
public RedisCircuitBreaker(IDistributedCache cache)
{
_cache = cache;
}
protected override async Task IsolateCircuitAsync(...)
{
var state = new CircuitState(State.Closed);
await _cache.SetAsync("CircuitState", state);
}
protected override async Task GetCircuitStateAsync()
{
return await _cache.GetAsync("CircuitState");
}
}
```
### 自适应弹性策略 ###
```csharp
// 基于响应时间自动调整超时
var adaptiveTimeout = Policy.TimeoutAsync(() =>
{
var avgResponseTime = Telemetry.GetAvgResponseTime("ServiceA");
return avgResponseTime * 1.5; // 平均响应时间的1.5倍
});
```
### gRPC 弹性处理 ###
```csharp
// gRPC 弹性策略
var grpcPolicy = Policy
.Handle(ex =>
ex.StatusCode == StatusCode.Unavailable ||
ex.StatusCode == StatusCode.DeadlineExceeded)
.WaitAndRetryAsync(3, attempt =>
TimeSpan.FromSeconds(attempt * 2));
// 使用
var client = new Greeter.GreeterClient(channel);
var response = await grpcPolicy.ExecuteAsync(() =>
client.SayHelloAsync(new HelloRequest()).ResponseAsync);
```
## 性能优化策略 ##
### 策略重用与缓存 ###
```csharp
// 策略工厂模式（避免重复创建）
public static class PolicyFactory
{
private static ConcurrentDictionary _policies = new();
public static IAsyncPolicy GetOrCreatePolicy(string key, Func createPolicy)
{
return _policies.GetOrAdd(key, _ => createPolicy());
}
}
// 使用示例
var policy = PolicyFactory.GetOrCreatePolicy("CircuitBreakerPolicy", () =>
Policy.Handle()
.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30));
```
### 上下文传递与监控 ###
```csharp
// 策略上下文配置
var context = new Context
{
{"OperationName", "GetUserData"},
{"RequestId", Guid.NewGuid()}
};
// 策略执行
await policy.ExecuteAsync(async ctx =>
{
var requestId = ctx["RequestId"];
Telemetry.StartTracking(requestId);
// 业务逻辑
}, context);
// 事件钩子
var policyWithEvents = Policy
.Handle()
.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30),
onBreak: (ex, breakDelay, ctx) =>
{
Telemetry.TrackCircuitBreak(ctx["OperationName"].ToString());
},
onReset: ctx =>
{
Telemetry.TrackCircuitReset(ctx["OperationName"].ToString());
});
```
### 错误处理模式 ###
```csharp
try
{
return await _resilientPolicy.ExecuteAsync(BusinessOperation);
}
catch (BrokenCircuitException)
{
// 处理开路状态
return ServiceUnavailable();
}
catch (TimeoutRejectedException)
{
// 处理超时
return GatewayTimeout();
}
catch (BulkheadRejectedException)
{
// 处理限流
return TooManyRequests();
}
catch (Exception ex)
{
// 其他异常
return InternalError(ex);
}
```
### Polly架构黄金法则 ###
```csharp
Policy.WrapAsync(
FallbackPolicy.ForDegradedService(), // 降级保护
TimeoutPolicy.ForSlowServices(), // 超时控制
CircuitBreakerPolicy.ForProtection(), // 短路保护
BulkheadPolicy.ForConcurrency(), // 资源保护
RetryPolicy.ForTransientFaults() // 重试机制
);
```
## 混沌工程与性能优化 ##
V8 版本引入 混沌工程策略，模拟生产环境故障以验证系统韧性
```csharp
builder.AddResilienceHandler("chaos-pipeline", pipelineBuilder => {
pipelineBuilder
.AddRetry(new RetryStrategyOptions { /*...*/ })
.AddChaosFault(0.02, () => new InvalidOperationException("模拟故障")) // 2% 请求注入异常
.AddChaosLatency(0.01, TimeSpan.FromSeconds(5)); // 1% 请求增加 5s 延迟
});
```
- **混沌注入类型**：故障(`Fault`)、错误结果(`Outcome`)、延迟(`Latency`)、自定义行为(`Behavior`)
- **动态控制**：通过 `InjectionRate` 和 `EnabledGenerator` 动态调整注入频率
## 集成应用实践 ##
### 与 HttpClient 深度集成 ###
通过 `Microsoft.Extensions.Http.Polly` 包实现声明式策略配置
```csharp
services.AddHttpClient("ResilientClient")
.AddPolicyHandler(Policy.TimeoutAsync(10))
.AddTransientHttpErrorPolicy(policyBuilder =>
policyBuilder.WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(attempt)));
```
### ASP.NET Core 全局策略注册 ###
```csharp
services.AddSingleton(Policy
.Handle()
.WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(2))
);
services.AddMvc().AddPollyPolicies(); // 配合 AOP 框架如 AspectCore 使用
```
## 高级应用场景 ##
### 电商订单系统熔断设计 ###
- 触发条件：支付服务连续 5 次超时或返回 5xx 错误
- 熔断动作：开启 30 秒熔断，快速返回“服务暂不可用”提示
- 半开状态：熔断结束后首个请求成功则闭合，否则再次熔断
### 金融交易系统隔板隔离 ###
- 资源配置：核心交易线程池（10 线程），报表查询线程池（20 线程）
- 效果：交易高负载时，报表查询不受影响，避免级联故障
## 性能优化 ##
- 策略复用：单例模式管理 `Policy` 对象，避免重复创建
- 异步支持：优先使用 `RetryAsync`、`ExecuteAsync` 异步方法
- 上下文传递：利用 `Context` 对象传递参数，支持动态策略调整
## 混沌工程 ##
混沌工程是通过在生产或类生产环境中故意引入故障（如异常、延迟、假结果），测试系统在异常条件下的行为，以增强系统对不可预测故障的弹性（`Resilience`）。它源自 `Netflix` 的 `Simian Army` 项目（如 `Chaos Monkey`），旨在验证系统是否能承受“混乱”场景。其核心目标是：
- 暴露系统脆弱点：模拟生产环境中的非常规故障（如网络抖动、服务不可用）。
- 检验弹性策略有效性：验证重试、熔断等策略是否能正确处理注入的故障。
- 提升系统韧性：通过可控的混沌实验，增强系统抵御真实故障的能力。
### Polly V8 的优势 ###
- 无缝集成：与 `Polly` 的弹性策略（如重试、断路器）结合，测试弹性机制。
- 灵活配置：支持同步/异步操作，统一 `API`（`ChaosStrategyOptions`）
- 生产环境测试：在生产环境中以可控方式注入故障，无需修改核心代码。
- `telemetry` 支持：通过 `Polly` 的遥测（`Telemetry`）系统记录混沌事件。
### 常见混沌实验类型 ###
- 服务响应超时
- 随机抛出异常
- 模拟网络抖动
- 限制资源（CPU、内存）
### 使用场景 ###
- `HTTP` 请求：测试 `API` 调用在网络延迟或失败时的弹性。
- 数据库操作：模拟 `EF Core` 的 `SqlException` 或 `DbUpdateConcurrencyException`。
- 后台任务：结合 `BackgroundService` 和 `ConcurrentQueue` 测试批量任务的容错。
- `CQRS` 架构：在命令/查询处理程序中注入故障，验证业务逻辑的鲁棒性。
- 微服务：模拟服务间通信失败，测试分布式系统的可靠性。
### 核心混沌策略 ###
Polly V8 提供四类策略，支持细粒度故障模拟：
| 策略类型 | 作用 | 典型场景 | 备注 |
| :-------: | :---------: | :--------: | :----------: |
| 故障注入 (Fault) | 抛出自定义异常 | 模拟服务崩溃、依赖失效 | |
| 结果注入 (Outcome) | 返回错误结果或异常 | 测试客户端对错误响应的处理逻辑 | |
| 延迟注入 (Latency) | 增加处理延迟 | 模拟网络拥塞或资源竞争 | |
| 行为注入 (Behavior) | 执行自定义操作（如重启服务） | 验证系统自愈能力 | |
### 精细化控制参数 ###
| 参数 | 类型 | 默认值 | 作用 |
| :-------: | :---------: | :--------: | :----------: |
| `InjectionRate` | `double (0-1)` | 0.001 | 混沌触发概率（如0.05表示5%的请求受影响） |
| `InjectionRateGenerator` | `Func` | null | 动态生成注入率（支持按请求上下文调整） |
| `EnabledGenerator` | `Func` | null | 动态启用策略（例如仅在测试环境激活） |
### 核心混沌策略 ###
#### Fault（故障注入） ####
注入异常（如 `TimeoutException`），模拟系统错误。
```csharp
var faultOptions = new ChaosFaultStrategyOptions
{
FaultGenerator = new FaultGenerator()
.AddException()
.AddException(() => new InvalidOperationException("Chaos fault")),
InjectionRate = 0.1, // 10% 概率
OnFaultInjected = args =>
{
Console.WriteLine($"Fault injected: {args.Fault.Message}");
return default;
}
};
new ResiliencePipelineBuilder().AddChaosFault(faultOptions);
```
#### Outcome（结果注入） ####
注入假结果或异常，测试应用对不同响应的处理。
```csharp
var outcomeOptions = new ChaosOutcomeStrategyOptions
{
OutcomeGenerator = args => new ValueTask>(new Outcome