Polly

Polly 是一个 .NET 弹性和瞬态故障处理库,允许开发人员以流畅和线程安全的方式表达重试、断路器、对冲、超时、速率限制和回退等弹性策略。

通过 www.thepollyproject.org 了解新功能公告、提示和技巧以及其他新闻

[!重要] 此文档描述了新的 Polly v8 API。如果您正在使用 v7 API,请参考之前版本的文档。

NuGet 包

包名	最新版本	说明
`Polly.Core`		核心抽象和内置策略。
`Polly.Extensions`		遥测和依赖注入支持。
`Polly.RateLimiting`		与 `System.Threading.RateLimiting` API 集成。
`Polly.Testing`		Polly 库的测试支持。
`Polly`		此包包含 Polly 库 8 版本之前的旧版 API。

文档

本 README 旨在快速概述一些 Polly 功能 - 包括足够让您开始使用任何弹性策略的内容。要深入了解任何弹性策略以及 Polly 的许多其他方面,请务必查看 pollydocs.org。

快速入门

要使用 Polly,您必须提供一个回调并使用弹性管道执行它。弹性管道是一个或多个弹性策略的组合,如重试、超时和速率限制器。Polly 使用构建器将这些策略集成到管道中。

要开始使用,首先通过运行以下命令将 Polly.Core 包添加到您的项目中:

dotnet add package Polly.Core

您可以使用 ResiliencePipelineBuilder 类创建 ResiliencePipeline,如下所示:

// 创建一个公开各种扩展以添加弹性策略的构建器实例
ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions()) // 使用默认选项添加重试
    .AddTimeout(TimeSpan.FromSeconds(10)) // 添加 10 秒超时
    .Build(); // 构建弹性管道

// 异步执行管道
await pipeline.ExecuteAsync(static async token => { /* 您的自定义逻辑放在这里 */ }, cancellationToken);

依赖注入

如果您更喜欢使用 IServiceCollection 定义弹性管道,您需要安装 Polly.Extensions 包:

dotnet add package Polly.Extensions

然后,您可以使用 AddResiliencePipeline(...) 扩展方法定义弹性管道,如下所示:

var services = new ServiceCollection();

// 使用名称 "my-pipeline" 定义弹性管道
services.AddResiliencePipeline("my-pipeline", builder =>
{
    builder
        .AddRetry(new RetryStrategyOptions())
        .AddTimeout(TimeSpan.FromSeconds(10));
});

// 构建服务提供程序
var serviceProvider = services.BuildServiceProvider();

// 检索动态创建和缓存弹性管道的 ResiliencePipelineProvider
var pipelineProvider = serviceProvider.GetRequiredService<ResiliencePipelineProvider<string>>();

// 使用注册时的名称检索弹性管道
ResiliencePipeline pipeline = pipelineProvider.GetPipeline("my-pipeline");

// 或者,您可以使用键控服务检索弹性管道
pipeline = serviceProvider.GetRequiredKeyedService<ResiliencePipeline>("my-pipeline");

// 执行管道
await pipeline.ExecuteAsync(static async token =>
{
    // 您的自定义逻辑放在这里
});

弹性策略

Polly 提供了多种弹性策略。除了每种策略的综合指南外,wiki 还包括每种策略在弹性工程中扮演角色的概述。

Polly 将弹性策略分为两个主要组:

反应性

这些策略处理通过策略执行的回调抛出的特定异常,或返回的结果。

策略	前提	又称	缓解
重试系列	许多故障是暂时的,可能在短暂延迟后自行纠正。	可能只是暂时的问题	允许配置自动重试。
断路器系列	当系统严重挣扎时,快速失败比让用户/调用者等待更好。保护故障系统免受过载可以帮助其恢复。	如果它造成伤害就停止给系统一个休息	当故障超过某个预配置的阈值时,断开电路(阻塞执行)一段时间。
回退	事情仍会失败 - 计划在发生这种情况时该怎么办。	优雅降级	定义在失败时返回的替代值(或要执行的操作)。
对冲	有时事情可能会很慢,计划在发生这种情况时该怎么办。	对冲你的赌注	当事情变慢时执行并行操作,并等待最快的一个。

主动性

与反应性策略不同,主动性策略不关注处理回调可能抛出或返回的错误。它们可以主动决定取消或拒绝执行回调。

策略	前提	又称	预防
超时	超过某个等待时间,成功结果不太可能。	不要永远等待	保证调用者不会等待超过超时时间。
速率限制器	限制系统处理请求的速率是控制负载的另一种方法。这可以应用于您的系统接受传入调用的方式,和/或您调用下游服务的方式。	慢一点,好吗?	限制执行不超过某个速率。

访问弹性策略文档,了解如何更详细地配置单个弹性策略。

重试

// 使用默认选项重试。
// 有关默认值,请参见 https://www.pollydocs.org/strategies/retry#defaults。
var optionsDefaults = new RetryStrategyOptions();

// 立即重试,无延迟
var optionsNoDelay = new RetryStrategyOptions
{
    Delay = TimeSpan.Zero
};

// 对重试行为进行高级控制,包括尝试次数、
// 重试之间的延迟以及要处理的异常类型。
var optionsComplex = new RetryStrategyOptions
{
    ShouldHandle = new PredicateBuilder().Handle<SomeExceptionType>(),
    BackoffType = DelayBackoffType.Exponential,
    UseJitter = true,  // 为延迟添加随机因素
    MaxRetryAttempts = 4,
    Delay = TimeSpan.FromSeconds(3),
};

// 使用自定义函数生成重试的延迟
var optionsDelayGenerator = new RetryStrategyOptions
{
    MaxRetryAttempts = 2,
    DelayGenerator = static args =>
    {
        var delay = args.AttemptNumber switch
        {
            0 => TimeSpan.Zero,
            1 => TimeSpan.FromSeconds(1),
            _ => TimeSpan.FromSeconds(5)
        };

        // 此示例使用同步延迟生成器,
        // 但 API 也支持异步实现。
        return new ValueTask<TimeSpan?>(delay);
    }
};

// 从结果对象中提取延迟
var optionsExtractDelay = new RetryStrategyOptions<HttpResponseMessage>
{
    DelayGenerator = static args =>
    {
        if (args.Outcome.Result is HttpResponseMessage responseMessage &&
            TryGetDelay(responseMessage, out TimeSpan delay))
        {
            return new ValueTask<TimeSpan?>(delay);
        }

        // 返回 null 意味着重试策略将对此尝试使用其内部延迟。
        return new ValueTask<TimeSpan?>((TimeSpan?)null);
    }
};

// 在执行重试时获取通知
var optionsOnRetry = new RetryStrategyOptions
{
    MaxRetryAttempts = 2,
    OnRetry = static args =>
    {
        Console.WriteLine("OnRetry, Attempt: {0}", args.AttemptNumber);

        // 事件处理程序可以是异步的;这里我们返回一个空的 ValueTask。
        return default;
    }
};

// 要无限重试或直到成功,请使用 int.MaxValue。
var optionsIndefiniteRetry = new RetryStrategyOptions
{
    MaxRetryAttempts = int.MaxValue,
};

// 将带有 RetryStrategyOptions{<TResult>} 实例的重试策略添加到管道
new ResiliencePipelineBuilder().AddRetry(optionsDefaults);
new ResiliencePipelineBuilder<HttpResponseMessage>().AddRetry(optionsExtractDelay);

如果所有重试都失败,重试策略会将最后的异常重新抛出给调用代码。

有关更多详细信息,请访问重试策略文档。

断路器

// 使用默认选项的断路器。
// 有关默认值,请参见 https://www.pollydocs.org/strategies/circuit-breaker#defaults。
var optionsDefaults = new CircuitBreakerStrategyOptions();

// 自定义选项的断路器:
// 如果在任何 10 秒采样时间内,超过 50% 的操作导致处理的异常,
// 且至少处理了 8 个操作,则电路将断开。
var optionsComplex = new CircuitBreakerStrategyOptions
{
    FailureRatio = 0.5,
    Samp
// 如果操作失败则使用动态生成的值。
var optionsFallbackAction = new FallbackStrategyOptions<UserAvatar>
{
    ShouldHandle = new PredicateBuilder<UserAvatar>()
        .Handle<SomeExceptionType>()
        .HandleResult(r => r is null),
    FallbackAction = static args =>
    {
        var avatar = UserAvatar.GetRandomAvatar();
        return Outcome.FromResultAsValueTask(avatar);
    }
};

// 使用默认或动态生成的值，并在触发后备时执行额外操作。
var optionsOnFallback = new FallbackStrategyOptions<UserAvatar>
{
    ShouldHandle = new PredicateBuilder<UserAvatar>()
        .Handle<SomeExceptionType>()
        .HandleResult(r => r is null),
    FallbackAction = static args =>
    {
        var avatar = UserAvatar.GetRandomAvatar();
        return Outcome.FromResultAsValueTask(UserAvatar.Blank);
    },
    OnFallback = static args =>
    {
        // 添加在触发后备时要执行的额外逻辑，比如日志记录。
        return default; // 返回一个空的ValueTask
    }
};

// 将带有FallbackStrategyOptions<TResult>实例的后备策略添加到管道中
new ResiliencePipelineBuilder<UserAvatar>().AddFallback(optionsOnFallback);

更多详情，请访问后备策略文档。

对冲

// 使用默认选项的对冲。
// 查看 https://www.pollydocs.org/strategies/hedging#defaults 了解默认值。
var optionsDefaults = new HedgingStrategyOptions<HttpResponseMessage>();

// 一个自定义的对冲策略，如果执行时间超过1秒，或因异常失败，或返回HTTP 500内部服务器错误，最多重试3次。
var optionsComplex = new HedgingStrategyOptions<HttpResponseMessage>
{
    ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
        .Handle<SomeExceptionType>()
        .HandleResult(response => response.StatusCode == HttpStatusCode.InternalServerError),
    MaxHedgedAttempts = 3,
    Delay = TimeSpan.FromSeconds(1),
    ActionGenerator = static args =>
    {
        Console.WriteLine("准备执行对冲操作。");

        // 返回一个委托函数，用动作上下文调用原始动作。
        // 您也可以选择创建一个全新的动作来执行。
        return () => args.Callback(args.ActionContext);
    }
};

// 订阅对冲事件。
var optionsOnHedging = new HedgingStrategyOptions<HttpResponseMessage>
{
    OnHedging = static args =>
    {
        Console.WriteLine($"OnHedging: 尝试次数 {args.AttemptNumber}");
        return default;
    }
};

// 将带有HedgingStrategyOptions<TResult>实例的对冲策略添加到管道中
new ResiliencePipelineBuilder<HttpResponseMessage>().AddHedging(optionsDefaults);

如果所有对冲尝试都失败，对冲策略将重新抛出原始异常或向调用者返回原始失败结果。

更多详情，请访问对冲策略文档。

超时

超时弹性策略假设您执行的委托支持协作取消。您必须使用接受CancellationToken的Execute/Async(...)重载，且执行的委托必须遵守该CancellationToken。

// 添加具有自定义TimeSpan持续时间的超时
new ResiliencePipelineBuilder().AddTimeout(TimeSpan.FromSeconds(3));

// 使用默认选项的超时。
// 查看 https://www.pollydocs.org/strategies/timeout#defaults 了解默认值。
var optionsDefaults = new TimeoutStrategyOptions();

// 使用自定义超时生成器函数添加超时
var optionsTimeoutGenerator = new TimeoutStrategyOptions
{
    TimeoutGenerator = static args =>
    {
        // 注意：超时生成器支持异步操作
        return new ValueTask<TimeSpan>(TimeSpan.FromSeconds(123));
    }
};

// 添加超时并监听超时事件
var optionsOnTimeout = new TimeoutStrategyOptions
{
    TimeoutGenerator = static args =>
    {
        // 注意：超时生成器支持异步操作
        return new ValueTask<TimeSpan>(TimeSpan.FromSeconds(123));
    },
    OnTimeout = static args =>
    {
        Console.WriteLine($"{args.Context.OperationKey}: 执行在 {args.Timeout.TotalSeconds} 秒后超时。");
        return default;
    }
};

// 将带有TimeoutStrategyOptions实例的超时策略添加到管道中
new ResiliencePipelineBuilder().AddTimeout(optionsDefaults);

超时策略在发生超时时抛出TimeoutRejectedException。

更多详情，请访问超时策略文档。

速率限制器

// 添加具有默认选项的速率限制器。
// 查看 https://www.pollydocs.org/strategies/rate-limiter#defaults 了解默认值。
new ResiliencePipelineBuilder()
    .AddRateLimiter(new RateLimiterStrategyOptions());

// 创建一个速率限制器，允许最多100个并发执行和50的队列。
new ResiliencePipelineBuilder()
    .AddConcurrencyLimiter(100, 50);

// 创建一个速率限制器，每分钟允许100次执行。
new ResiliencePipelineBuilder()
    .AddRateLimiter(new SlidingWindowRateLimiter(
        new SlidingWindowRateLimiterOptions
        {
            PermitLimit = 100,
            Window = TimeSpan.FromMinutes(1)
        }));

如果执行被拒绝，速率限制器策略会抛出RateLimiterRejectedException。

更多详情，请访问速率限制器策略文档。

混沌工程

从版本8.3.0开始，Polly已将混沌工程库Simmy直接集成到其核心中。欲了解更多信息，请参阅专门的混沌工程文档。

下一步

要了解更多关于Polly的信息，请访问pollydocs.org。

示例

示例：本仓库中作为Polly介绍的示例。
Polly-Samples：包含使用Polly各种实现的实际示例。请随时为Polly-Samples仓库做出贡献，以帮助那些初次学习Polly的人，或寻找由我们慷慨的社区提供的高级示例和新颖方法的人。
Microsoft的eShopOnContainers项目：演示.NET微服务架构并使用Polly进行弹性处理的示例项目。

赞助商

感谢以下公司赞助Polly的持续开发。

通过GitHub Sponsors成为赞助商来帮助支持这个项目。

许可证

根据New BSD License的条款许可