Polly for C# (.NET): 完整指南与示例

什么是 Polly，为什么需要它？

Polly 是一个强大且灵活的 .NET (C#, F#, VB.NET) 库，用于处理临时故障并提高应用程序的容错能力。它实现了多种弹性模式，例如重试 (Retry)、断路器 (Circuit Breaker)、超时 (Timeout)、隔离 (Bulkhead Isolation) 和缓存 (Cache)。

在当今微服务架构和云计算的世界中，应用程序不断与外部资源交互：数据库、Web 服务、API。这些交互可能不可靠——网络错误、服务暂时不可用、请求超限。Polly 允许您优雅地处理这些情况，而无需编写冗长的 try-catch 代码块。

主要使用场景：

\n
• Retry (重试)： 在临时错误时自动重试操作。
\n
• Circuit Breaker (断路器)： 如果服务持续报错，则停止调用尝试，让其有时间恢复。
\n
• Timeout (超时)： 限制操作的执行时间。
\n
• Bulkhead (隔离)： 限制并发操作的数量，防止一个“坏”操作阻塞整个线程池。
\n
• Cache (缓存)： 缓存成功操作的结果。
\n
• Fallback (备用方案)： 在失败时执行替代操作。
\n

安装 Polly

Polly 通过 NuGet（.NET 的包管理器）分发。可以通过以下几种方式安装：

通过 Package Manager Console (Visual Studio)

Install-Package Polly

通过 .NET CLI

dotnet add package Polly

通过 PackageReference (在 .csproj 文件中)

<PackageReference Include="Polly" Version="8.2.0" />

安装后，在代码中添加 using 指令：

using Polly;\nusing Polly.Retry;\nusing Polly.CircuitBreaker;\nusing Polly.Timeout;\nusing Polly.Bulkhead;\nusing Polly.Caching;\nusing Polly.Fallback;\nusing Polly.Wrap;

快速入门与代码示例

考虑一个最简单的示例：我们有一个调用外部 API 的方法，如果发生异常，我们希望重试 3 次。

using System;\nusing System.Net.Http;\nusing System.Threading.Tasks;\nusing Polly;\nusing Polly.Retry;\n\npublic class ApiClient\n{\n    private readonly HttpClient _httpClient;\n    private readonly AsyncRetryPolicy _retryPolicy;\n\n    public ApiClient()\n    {\n        _httpClient = new HttpClient();\n        \n        // 创建重试策略\n        _retryPolicy = Policy\n            .Handle<HttpRequestException>() // 处理哪些异常\n            .Or<TimeoutException>()          // 或超时\n            .WaitAndRetryAsync(\n                3,                           // 重试次数\n                retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)), // 指数退避延迟\n                onRetry: (exception, timeSpan, retryCount, context) =>\n                {\n                    Console.WriteLine($"第 {retryCount} 次尝试失败。{timeSpan.Seconds} 秒后重试。错误：{exception.Message}");\n                }\n            );\n    }\n\n    public async Task<string> GetDataAsync(string url)\n    {\n        // 使用策略执行请求\n        return await _retryPolicy.ExecuteAsync(async () =>\n        {\n            var response = await _httpClient.GetAsync(url);\n            response.EnsureSuccessStatusCode();\n            return await response.Content.ReadAsStringAsync();\n        });\n    }\n}\n\n// 使用\npublic class Program\n{\n    public stat