C#常用类库-详解Polly

C#常用类库-详解Polly

在分布式系统、微服务及网络请求开发中，故障（网络抖动、第三方接口超时、数据库连接中断、服务降级）是常态。传统try-catch仅能被动捕获异常，无法实现故障恢复与系统保护，而Polly作为.NET生态最成熟的弹性治理库，以声明式语法封装了重试、熔断、超时等核心策略，让应用具备自我修复、抗雪崩能力，是C#开发者保障系统稳定性的必备工具。

本文摒弃冗余理论，聚焦"实用、深度、简练"，从核心价值、基础策略、进阶组合到实战落地，全方位解析Polly，帮你快速掌握其精髓，解决实际开发中的故障处理痛点。

一、核心定位：Polly解决什么问题？

Polly的核心是"策略化故障处理"，区别于简单的异常捕获，它能主动干预执行流程，解决传统开发的3大核心痛点：

• 避免级联故障：下游服务故障时，防止请求堆积拖垮上游服务，杜绝系统雪崩。

• 实现故障自愈：针对临时性故障（如网络抖动），自动重试恢复，无需人工干预。

• 保护系统资源：通过限流、隔离，避免单一故障耗尽线程池、连接池等核心资源。

核心优势：轻量（无冗余依赖）、兼容所有.NET平台（.NET Standard 2.0+）、语法简洁（声明式配置）、可扩展性强（支持自定义策略），无缝集成HttpClient、DI容器。

二、环境搭建：快速引入与核心命名空间

Polly安装简单，按需选择NuGet包，无需复杂配置，开箱即用。

1. 安装NuGet包（核心+常用扩展）

// 核心包（所有基础策略，必装）
dotnet add package Polly

// HttpClient集成包（HTTP请求场景首选，推荐）
dotnet add package Microsoft.Extensions.Http.Polly

// 核心扩展包（补充高级特性，按需安装）
dotnet add package Polly.Extensions.Http

2. 核心命名空间

using Polly;                  // 核心策略
using Polly.CircuitBreaker;   // 熔断策略
using Polly.Fallback;         // 回退策略
using Polly.Retry;            // 重试策略
using Polly.Timeout;          // 超时策略
using Polly.Bulkhead;         // 舱壁（限流）策略
using Polly.Wrap;             // 策略组合

三、核心策略详解（基础必学，简练落地）

Polly提供6大核心策略，覆盖90%日常场景，每个策略聚焦单一故障处理能力，语法统一，重点掌握"触发条件+配置参数+适用场景"。

1. 重试策略（Retry）------ 临时性故障自愈

核心：针对临时故障（网络抖动、接口偶发超时），自动重试，避免单次失败影响业务。

关键配置：重试次数、重试间隔、触发条件（异常/返回值）、重试回调。

// 示例：HTTP请求失败（网络异常/500错误），重试3次，指数退避间隔（1s→2s→4s）
var retryPolicy = Policy<HttpResponseMessage>
    .Handle<HttpRequestException>() // 捕获网络异常
    .OrResult(resp => !resp.IsSuccessStatusCode) // 捕获非成功响应
    .WaitAndRetryAsync(
        retryCount: 3,
        // 指数退避+抖动（避免重试风暴）
        sleepDurationProvider: (attempt, _) => TimeSpan.FromSeconds(Math.Pow(2, attempt)) + TimeSpan.FromMilliseconds(new Random().Next(100, 300)),
        onRetryAsync: (ex, span, attempt, _) => // 重试回调（日志/告警）
        {
            Console.WriteLine($"第{attempt}次重试，间隔{span.TotalSeconds}s，原因：{ex.Exception?.Message ?? ex.Result.StatusCode.ToString()}");
            return Task.CompletedTask;
        });

适用场景：接口偶发超时、数据库连接临时失败、网络波动。

注意：重试操作必须保证幂等性（多次执行结果一致），避免重复创建订单、扣款。

2. 熔断策略（Circuit Breaker）------ 系统雪崩防护

核心：监控故障频率，当故障达到阈值，自动"切断"请求，避免无意义调用拖垮系统，一段时间后试探恢复。

关键配置：故障阈值、熔断时长、状态回调（断开/恢复/半开）。

// 示例：连续5次失败，熔断10秒，期间直接快速失败，10秒后进入半开状态试探
var circuitBreakerPolicy = Policy<HttpResponseMessage>
    .Handle<HttpRequestException>()
    .OrResult(resp => resp.StatusCode == HttpStatusCode.InternalServerError)
    .CircuitBreakerAsync(
        exceptionsAllowedBeforeBreaking: 5, // 故障阈值（连续失败5次）
        durationOfBreak: TimeSpan.FromSeconds(10), // 熔断时长
        onBreak: (ex, span) => Console.WriteLine($"熔断触发，断开{span.TotalSeconds}s"),
        onReset: () => Console.WriteLine($"熔断恢复，服务正常"),
        onHalfOpen: () => Console.WriteLine($"半开状态，试探放行请求"));

状态流转：Closed（正常）→ Open（熔断）→ Half-Open（试探）→ Closed（恢复）/ Open（继续熔断）。

适用场景：下游服务宕机、大面积故障，防止级联雪崩。

3. 回退策略（Fallback）------ 故障兜底

核心：当所有策略（重试、熔断）都失败时，提供降级逻辑或默认返回值，保证业务不中断、用户体验不降级。

// 示例：所有策略失败后，返回降级提示（友好响应）
var fallbackPolicy = Policy<HttpResponseMessage>
    .Handle<Exception>() // 捕获所有异常（含熔断、超时、重试失败）
    .OrResult(resp => !resp.IsSuccessStatusCode)
    .FallbackAsync(
        fallbackValue: new HttpResponseMessage(HttpStatusCode.ServiceUnavailable)
        {
            Content = new StringContent("服务繁忙，请稍后重试")
        },
        onFallbackAsync: (ex, _) => // 降级回调（日志/告警）
        {
            Console.WriteLine($"触发降级：{ex.Exception?.Message ?? ex.Result.StatusCode.ToString()}");
            return Task.CompletedTask;
        });

适用场景：第三方接口故障、服务降级，如支付接口失败返回"排队中"，库存查询失败返回默认库存。

4. 超时策略（Timeout）------ 防止资源阻塞

核心：强制限制操作执行时间，超时则取消任务，避免线程池、连接池被长期阻塞。

// 示例：操作超过3秒强制取消，避免阻塞
var timeoutPolicy = Policy
    .TimeoutAsync(
        timeout: TimeSpan.FromSeconds(3),
        strategy: TimeoutStrategy.Optimistic, // 配合CancellationToken取消任务（推荐）
        onTimeoutAsync: (_, span, _) =>
        {
            Console.WriteLine($"操作超时，已取消（超时时间：{span.TotalSeconds}s）");
            return Task.CompletedTask;
        });

关键区别：Optimistic（推荐）→ 取消任务；Pessimistic → 仅标记超时，不取消任务（易造成资源泄漏）。

适用场景：第三方接口调用、数据库查询、耗时操作，防止长时间阻塞。

5. 舱壁策略（Bulkhead）------ 资源隔离

核心：限制并发执行数量，隔离故障操作，避免单一业务耗尽所有资源（如线程池）。

// 示例：最大并发2个任务，排队1个，超出则拒绝
var bulkheadPolicy = Policy
    .BulkheadAsync(
        maxParallelization: 2, // 最大并发数
        maxQueuingActions: 1,  // 最大排队数
        onBulkheadRejectedAsync: () =>
        {
            Console.WriteLine("并发已满，任务被拒绝");
            return Task.CompletedTask;
        });

适用场景：高并发接口、第三方接口限流，防止单一业务拖垮整体系统。

6. 策略对比（快速选型）

策略	核心作用	适用场景
Retry	临时故障自愈	网络抖动、偶发超时
Circuit Breaker	防止雪崩	下游服务宕机、大面积故障
Fallback	故障兜底	服务降级、友好提示
Timeout	防止阻塞	耗时操作、第三方接口
Bulkhead	资源隔离	高并发、限流

四、进阶特性：策略组合与实战集成

实际开发中，单一策略无法满足复杂场景，Polly支持策略组合（PolicyWrap），结合DI、HttpClient实现声明式治理，是企业级开发的标准用法。

1. 策略组合（Policy Wrap）------ 故障处理组合拳

核心：按"兜底→重试→熔断→超时"的顺序组合策略，形成完整的故障处理链路（顺序影响执行效果）。

// 1. 构建各子策略（复用前面定义的重试、熔断、回退、超时）
var timeout = Policy.TimeoutAsync(3);
var retry = Policy<HttpResponseMessage>.Handle<Exception>().WaitAndRetryAsync(2, _ => TimeSpan.FromSeconds(1));
var circuitBreaker = Policy<HttpResponseMessage>.Handle<Exception>().CircuitBreakerAsync(3, TimeSpan.FromSeconds(10));
var fallback = Policy<HttpResponseMessage>.Handle<Exception>().FallbackAsync(new HttpResponseMessage(HttpStatusCode.ServiceUnavailable));

// 2. 组合策略：执行顺序 → fallback（兜底）→ retry（重试）→ circuitBreaker（熔断）→ timeout（超时）
var policyWrap = Policy.WrapAsync(fallback, retry, circuitBreaker, timeout);

// 3. 执行组合策略
var response = await policyWrap.ExecuteAsync(async () =>
{
    var client = new HttpClient();
    return await client.GetAsync("https://api.example.com/data");
});

2. ASP.NET Core 集成（HttpClient + DI）

在Web项目中，推荐通过IHttpClientFactory集成Polly，无需手动创建策略，声明式配置，全局生效。

// Program.cs 注册HttpClient并附加Polly策略
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient("ExternalApiClient", client =>
{
    client.BaseAddress = new Uri("https://api.example.com/");
    client.Timeout = TimeSpan.FromSeconds(30);
})
// 附加重试策略
.AddPolicyHandler(Policy<HttpResponseMessage>
    .HandleResult(resp => !resp.IsSuccessStatusCode)
    .WaitAndRetryAsync(2, _ => TimeSpan.FromSeconds(1)))
// 附加熔断策略
.AddPolicyHandler(Policy<HttpResponseMessage>
    .HandleResult(resp => !resp.IsSuccessStatusCode)
    .CircuitBreakerAsync(3, TimeSpan.FromSeconds(10)))
// 附加超时策略
.AddPolicyHandler(Policy.TimeoutAsync(3));

var app = builder.Build();

// 控制器中注入使用
[ApiController]
[Route("api/[controller]")]
public class ExternalApiController : ControllerBase
{
    private readonly IHttpClientFactory _httpClientFactory;

    public ExternalApiController(IHttpClientFactory httpClientFactory)
    {
        _httpClientFactory = httpClientFactory;
    }

    [HttpGet]
    public async Task<IActionResult> GetData()
    {
        var client = _httpClientFactory.CreateClient("ExternalApiClient");
        var response = await client.GetAsync("data");
        return response.IsSuccessStatusCode ? Ok(await response.Content.ReadAsStringAsync()) : StatusCode((int)response.StatusCode);
    }
}

3. 实战场景：微服务调用完整方案

需求：订单服务调用库存服务，需实现"重试→熔断→超时→回退"，保证订单流程不中断。

// 1. 策略工厂（封装可复用策略）
public static class PollyPolicyFactory
{
    public static IAsyncPolicy<HttpResponseMessage> CreateInventoryServicePolicy()
    {
        // 超时：3秒
        var timeout = Policy.TimeoutAsync(3);

        // 重试：2次，指数退避（1s→2s）
        var retry = Policy<HttpResponseMessage>
            .Handle<HttpRequestException>()
            .OrResult(resp => resp.StatusCode is HttpStatusCode.RequestTimeout or HttpStatusCode.InternalServerError)
            .WaitAndRetryAsync(2, attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)));

        // 熔断：连续3次失败，熔断30秒
        var circuitBreaker = Policy<HttpResponseMessage>
            .Handle<HttpRequestException>()
            .OrResult(resp => resp.StatusCode == HttpStatusCode.InternalServerError)
            .CircuitBreakerAsync(3, TimeSpan.FromSeconds(30));

        // 回退：降级返回排队提示
        var fallback = Policy<HttpResponseMessage>
            .Handle<Exception>()
            .OrResult(resp => !resp.IsSuccessStatusCode)
            .FallbackAsync(() => Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
            {
                Content = new StringContent("{\"Success\":false,\"Message\":\"库存服务繁忙，订单已排队\"}")
            }));

        // 组合策略：兜底→重试→熔断→超时
        return Policy.WrapAsync(fallback, retry, circuitBreaker, timeout);
    }
}

// 2. 注册服务
builder.Services.AddHttpClient("InventoryService", client =>
{
    client.BaseAddress = new Uri("http://inventory-service/");
}).AddPolicyHandler(PollyPolicyFactory.CreateInventoryServicePolicy());

五、避坑指南与最佳实践（深度重点）

Polly用法简单，但细节处理不当易引发新问题，以下是企业级开发的避坑要点和最佳实践。

1. 重试策略避坑

• 必须保证幂等性：非幂等操作（创建订单、扣款）不可盲目重试，可结合唯一标识避免重复执行。

• 避免重试风暴：使用指数退避+抖动，合理设置重试次数（建议2-3次），不无限重试。

• 精准触发条件：仅对临时性故障（如网络异常、503）重试，对400（参数错误）、404（资源不存在）不重试。

2. 熔断策略避坑

• 阈值合理设置：exceptionsAllowedBeforeBreaking建议3-5次，避免1次失败就熔断（误杀正常服务）。

• 熔断时长适配：根据下游服务恢复时间调整（30秒-5分钟），过短易频繁试探，过长影响服务恢复。

• 半开状态监控：半开状态仅放行少量请求，避免刚恢复的服务被瞬间压垮。

3. 通用最佳实践

• 日志与监控：所有策略的回调中添加日志（重试、熔断、降级次数），结合Prometheus/Grafana监控，及时发现系统异常。

• 策略复用：通过工厂模式封装策略，避免重复代码，统一维护。

• 结合CancellationToken：超时、重试策略配合CancellationToken，确保任务能被及时取消，避免资源泄漏。

• 环境差异化：开发环境可关闭熔断（便于调试），生产环境严格配置策略参数。

六、总结

Polly的核心价值的是"以策略化方式解决故障处理"，它不是复杂的框架，而是轻量、实用的工具------无需改变原有业务逻辑，仅通过声明式配置，就能让应用具备弹性治理能力。

掌握Polly的关键：理解6大核心策略的适用场景，学会组合策略应对复杂故障，规避幂等性、重试风暴等常见坑。在分布式、微服务架构中，Polly是保障系统稳定性的"第一道防线"，合理运用，能显著降低系统故障带来的损失，提升用户体验。

扩展建议：深入学习Polly的自定义策略、策略监控、与Resilience4j（另一款弹性治理库）的对比，根据项目需求选择合适的方案。