在 .NET 10 中为外部调用配置 Polly v8…

适用于 .NET 10 应用为 HTTP、数据库、消息队列等外部调用配置重试、熔断、超时、降级、限流、对冲与遥测的场景。

适用场景

解决思路

1. 使用 Polly v8 的 ResiliencePipeline 替代 v7 的 Policy；不要使用 PolicyBuilder、Policy.Handle<>()、ISyncPolicy，改用可组合、类型安全且与 IHttpClientFactory 原生集成的 API。
2. HTTP 调用不要手动包装 ExecuteAsync，而是通过 DI 使用 Microsoft.Extensions.Http.Resilience 的 AddResilienceHandler 把 pipeline 加到 HttpClient。
3. 在单个 ResiliencePipeline 中组合策略（retry + circuit breaker + timeout），不要嵌套 try/catch；策略执行顺序为 outer-to-inner，先加入的为最外层。
4. 为每个外部调用设置超时；用 AddTimeout() 作为最内层策略按每次尝试生效，并可选在最外层再加一个总耗时超时。
5. 用 Polly v8 的 Metering 事件和 TelemetryOptions 接入 OpenTelemetry，监控重试率、熔断器状态和超时频率。
6. HTTP 客户端默认使用 AddHttpClient<...>(...).AddStandardResilienceHandler()；它会配置 Retry 3 次、指数退避、jitter，Circuit breaker 30 秒采样窗口内 10% 失败率并熔断 30 秒，每次尝试 10 秒超时，总请求 30 秒超时；仅在需要不同阈值时覆盖。
7. 自定义 HTTP 韧性时使用 AddResilienceHandler("catalog", builder => ...)；按 total timeout > retry > circuit breaker > attempt timeout 顺序配置：最外层 AddTimeout(15s)，然后 AddRetry(HttpRetryStrategyOptions { MaxRetryAttempts=3, BackoffType=Exponential, UseJitter=true, Delay=500ms, ShouldHandle 处理 RequestTimeout/TooManyRequests/ServiceUnavailable 或 HttpRequestException })，然后 AddCircuitBreaker(HttpCircuitBreakerStrategyOptions { FailureRatio=0.5, SamplingDuration=10s, MinimumThroughput=10, BreakDuration=30s })，最内层 AddTimeout(5s)。
8. 命名 handler 可按服务调优；顺序很重要：总超时 > retry > circuit breaker > 单次尝试超时。
9. 非 HTTP 操作用 AddResiliencePipeline("database", builder => ...) 注册命名 pipeline；AddRetry(RetryStrategyOptions { MaxRetryAttempts=3, BackoffType=Exponential, Delay=200ms, ShouldHandle = PredicateBuilder().Handle<TimeoutException>().Handle<InvalidOperationException>(ex => ex.Message.Contains("deadlock", StringComparison.OrdinalIgnoreCase)) }) 后 AddTimeout(10s)。
10. 注入非 HTTP pipeline 时用 [FromKeyedServices("database")] ResiliencePipeline，并调用 pipeline.ExecuteAsync(async token => await db.Orders.FindAsync([id], token), ct)。
11. 需要返回特定类型时使用 ResiliencePipeline<T>，例如 AddResiliencePipeline<string, HttpResponseMessage>("external-api", builder => ...)，加入 AddFallback(FallbackStrategyOptions<HttpResponseMessage> { FallbackAction 返回默认 HttpResponseMessage，ShouldHandle 处理异常或非成功状态码 })、AddRetry(RetryStrategyOptions<HttpResponseMessage> { MaxRetryAttempts=2, Delay=500ms })、AddTimeout(5s)。
12. 用 fallback 在所有重试耗尽后返回默认值，实现优雅降级。
13. 延迟敏感读取用 AddHedging(HttpHedgingStrategyOptions { MaxHedgedAttempts=2, Delay=500ms }) 在延迟后发送并行请求，并配 AddTimeout(3s)；仅在可容忍重复工作时使用。
14. 遥测集成：在 AddResiliencePipeline("monitored", (builder, context) => ...) 中调用 ConfigureTelemetry(new TelemetryOptions { LoggerFactory = context.ServiceProvider.GetRequiredService<ILoggerFactory>() })，再链式 AddRetry、AddCircuitBreaker、AddTimeout。
15. 在 Program.cs 中用 AddOpenTelemetry().WithMetrics(metrics => metrics.AddMeter("Polly")) 捕获 Polly 指标。
16. .NET 内置限流用 AddRateLimiter(options => ...)；算法包括 AddFixedWindowLimiter、AddSlidingWindowLimiter、AddTokenBucketLimiter、AddConcurrencyLimiter。
17. 配置 AddFixedWindowLimiter("fixed", opt => { opt.PermitLimit = 100; opt.Window = TimeSpan.FromSeconds(60); opt.QueueLimit = 0; })。
18. 限流被拒时在 OnRejected 中返回 429 和 ProblemDetails；若 context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfter) 则设置 Retry-After 响应头，并 WriteAsJsonAsync(new ProblemDetails { Title = "Too many requests", Status = 429 }, ct)。
19. 应用限流：app.UseRateLimiter(); app.MapGet("/api/orders", ListOrders).RequireRateLimiting("fixed");。
20. 不要使用 Polly v7 的 Policy.Handle<HttpRequestException>().WaitAndRetryAsync(...) 和 ExecuteAsync 包装；改用 v8 pipeline via DI。
21. 不要在每次调用处手动 try/catch TimeoutRejectedException、BrokenCircuitException 并返回空值；把韧性配置在 HttpClient 层，调用方直接处理响应。
22. 不要在非幂等操作上重试；只对幂等操作重试，或为非幂等操作加幂等键：httpClient.DefaultRequestHeaders.Add("Idempotency-Key", Guid.NewGuid().ToString())，并让 AddRetry 的 ShouldHandle 仅处理 RequestTimeout/ServiceUnavailable。
23. 熔断器必须配合监控：用 OpenTelemetry 捕获 Polly 指标，并对 polly.circuit_breaker.state = Open 设置告警。
24. 决策：HTTP 外部 API 用 AddStandardResilienceHandler() 默认值，仅覆盖特定阈值；HTTP 自定义阈值用 AddResilienceHandler("name", ...)。
25. 决策：数据库/EF Core 用 AddResiliencePipeline("db", ...) 对 deadlock/timeout 重试且不用熔断器；消息队列发布用 AddResiliencePipeline("mq", ...) 配指数退避重试和超时。
26. 决策：延迟敏感读取用 AddHedging(...)；优雅降级用 AddFallback(...) 返回缓存/默认值。
27. 决策：单次尝试时限用最内层 AddTimeout(...)，按操作设 2-10 秒；总操作时限用最外层 AddTimeout(...)，设为所有重试总和加 buffer。
28. 决策：非幂等写入用幂等键重试或不重试快速失败；读密集型微服务用标准 handler + hedging；API 限流用 AddRateLimiter() + RequireRateLimiting()，按端点选择 Fixed、Sliding 或 Token bucket。

适用边界 · 注意事项

• 非幂等写操作且无法提供 Idempotency-Key 时，不要使用重试或对冲，否则可能产生重复订单等副作用。
• 使用 Polly v7 或非 .NET 10 技术栈时，本技能中的 Polly v8 ResiliencePipeline API 不适用。
• 不能容忍重复请求或额外副作用时，不要用 hedging。