Thêm WaitAndRetryAsync quanh mọi lời gọi HTTP là cách phổ biến nhất để làm hệ thống yếu đi: ba instance cùng retry, upstream vốn đã quá tải, nhận thêm gấp ba lưu lượng. Polly 8 không phải thư viện “thêm retry” — nó là cách khai báo một pipeline chống chịu có thứ tự, có ngân sách thời gian, và có trạng thái ngắt mạch dùng chung.
Mục lục
Cập nhật 2026
- Polly 8.9 dùng
ResiliencePipelinevàResiliencePipelineBuilder. APIPolicy.Handle<T>().WaitAndRetryAsync()của Polly 7 đã bị thay thế hoàn toàn. Polly.Extensions.HttpvàAddPolicyHandlerlà tích hợp của thời Polly 7. Với Polly 8 trên ASP.NET Core, dùngMicrosoft.Extensions.Http.Resilience10.11 vớiAddResilienceHandler/AddStandardResilienceHandler.AddStandardResilienceHandlerđã gói sẵn thứ tự chuẩn: total timeout → retry → circuit breaker → attempt timeout, kèm logging và metrics.- Hedging là strategy có sẵn trong Polly 8, không cần thư viện phụ.
Mental model: pipeline, không phải danh sách policy
Một pipeline là một chuỗi strategy lồng nhau. Request đi từ ngoài vào trong, lỗi nổi từ trong ra ngoài. Strategy thêm trước nằm ngoài cùng. Vì vậy thứ tự khai báo chính là thứ tự ngữ nghĩa:
Request
└─ Total timeout (30s cho toàn bộ, gồm mọi lần retry)
└─ Retry (3 lần, exponential + jitter)
└─ Circuit breaker (mở khi tỉ lệ lỗi > 50%)
└─ Attempt timeout (10s cho một lần gọi)
└─ HttpClient.SendAsync
Đảo hai tầng là đổi hoàn toàn hành vi. Timeout đặt ngoài retry nghĩa là toàn bộ 3 lần thử phải xong trong 30 giây. Timeout đặt trong retry nghĩa là mỗi lần thử có 10 giây riêng. Cả hai đều hợp lý — nhưng bạn phải chọn có ý thức, không copy ngẫu nhiên.
Pipeline tự dựng cho một dependency
// File: Catalog/ResilienceRegistration.cs
using System.Net;
using Polly;
using Polly.CircuitBreaker;
using Polly.Retry;
using Polly.Timeout;
public static class ResilienceRegistration
{
public static IServiceCollection AddCatalogResilience(this IServiceCollection services)
{
services.AddSingleton(sp =>
{
var logger = sp.GetRequiredService<ILogger<ResiliencePipeline<HttpResponseMessage>>>();
return new ResiliencePipelineBuilder<HttpResponseMessage>()
// 1. Tổng ngân sách thời gian cho cả pipeline.
.AddTimeout(new TimeoutStrategyOptions
{
Timeout = TimeSpan.FromSeconds(30),
OnTimeout = args =>
{
logger.LogWarning("Pipeline timeout sau {Seconds}s",
args.Timeout.TotalSeconds);
return default;
},
})
// 2. Retry chỉ cho lỗi transient.
.AddRetry(new RetryStrategyOptions<HttpResponseMessage>
{
ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
.Handle<HttpRequestException>()
.Handle<TimeoutRejectedException>()
.HandleResult(r => (int)r.StatusCode >= 500),
MaxRetryAttempts = 3,
Delay = TimeSpan.FromMilliseconds(200),
BackoffType = DelayBackoffType.Exponential,
UseJitter = true,
OnRetry = args =>
{
logger.LogWarning(
"Retry {Attempt} sau {Delay}ms: {Reason}",
args.AttemptNumber,
args.RetryDelay.TotalMilliseconds,
args.Outcome.Exception?.Message
?? args.Outcome.Result?.StatusCode.ToString());
return default;
},
})
// 3. Ngắt mạch theo tỉ lệ lỗi trong cửa sổ thời gian.
.AddCircuitBreaker(new CircuitBreakerStrategyOptions<HttpResponseMessage>
{
ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
.Handle<HttpRequestException>()
.HandleResult(r => (int)r.StatusCode >= 500),
FailureRatio = 0.5,
MinimumThroughput = 10,
SamplingDuration = TimeSpan.FromSeconds(30),
BreakDuration = TimeSpan.FromSeconds(15),
OnOpened = args =>
{
logger.LogError("Circuit mở trong {Seconds}s",
args.BreakDuration.TotalSeconds);
return default;
},
})
// 4. Timeout cho từng lần gọi.
.AddTimeout(new TimeoutStrategyOptions { Timeout = TimeSpan.FromSeconds(10) })
.Build();
});
return services;
}
}
Ba chi tiết quyết định chất lượng pipeline này. Circuit breaker là singleton — nó giữ trạng thái qua các request; tạo mới mỗi request thì nó không bao giờ mở. ShouldHandle của retry không được chứa BrokenCircuitException, nếu không retry sẽ đánh vào mạch đang mở. Và MinimumThroughput phải đủ lớn để một vài lỗi ngẫu nhiên không mở mạch; với 10 request/30 giây, tỉ lệ 50% nghĩa là 5 lỗi.
Service dùng pipeline đã đăng ký:
// File: Catalog/CatalogClient.cs
public sealed class CatalogClient(
IHttpClientFactory factory,
ResiliencePipeline<HttpResponseMessage> pipeline)
{
public async Task<string> GetAsync(string path, CancellationToken ct)
{
using var client = factory.CreateClient("catalog");
var response = await pipeline.ExecuteAsync(
async token => await client.GetAsync(path, token), ct);
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsStringAsync(ct);
}
}
ExecuteAsync nhận delegate có CancellationToken và truyền token đó xuống tận HttpClient. Đây là điều kiện để timeout hoạt động thật: nếu code bên trong bỏ qua token, timeout chỉ bỏ được kết quả chứ không hủy I/O.
Cách nhanh nhất: standard handler
Nếu bạn không có yêu cầu đặc biệt, đừng tự dựng pipeline. AddStandardResilienceHandler đã có sẵn cấu hình hợp lý và thứ tự đúng, kèm logging và metrics.
// File: Program.cs
builder.Services.AddHttpClient<CatalogClient>(client =>
{
client.BaseAddress = new Uri("https://catalog.internal/");
})
.AddStandardResilienceHandler(options =>
{
options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(30);
options.AttemptTimeout.Timeout = TimeSpan.FromSeconds(10);
options.Retry.MaxRetryAttempts = 3;
options.Retry.Delay = TimeSpan.FromMilliseconds(200);
options.Retry.BackoffType = DelayBackoffType.Exponential;
options.Retry.UseJitter = true;
options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(30);
});
Mặc định của handler là: total 30 giây, attempt 10 giây, 3 lần retry exponential có jitter, circuit breaker mở sau khi tỉ lệ lỗi vượt ngưỡng. Thư viện kiểm tra quan hệ giữa AttemptTimeout và SamplingDuration lúc khởi động, nên cấu hình sai sẽ nổ ngay khi app start chứ không đợi tới lúc có traffic.
Khi cần kiểm soát thêm (ví dụ chỉ retry GET), dùng AddResilienceHandler với builder thay vì standard handler. Đó cũng là nơi bạn thêm strategy riêng mà không phải viết lại toàn bộ pipeline.
Chỉ retry thao tác idempotent
| Method | Retry? |
|---|---|
| GET, HEAD | An toàn. Không có side effect, retry là mặc định nên làm. |
| PUT, DELETE | Theo spec là idempotent, nhưng chỉ retry nếu server của bạn thật sự idempotent. DELETE trả 404 ở lần hai vẫn là kết quả đúng. |
| POST | Không retry, trừ khi có Idempotency-Key và server dedupe theo key. Retry POST tạo đơn = hai đơn hàng. |
| PATCH | Không mặc định. PATCH có thể là “increment” và retry sẽ cộng hai lần. |
Đây là lý do standard handler nguy hiểm với POST: nó retry mọi lỗi 5xx, không quan tâm method. Nếu API của bạn có POST tạo giao dịch, hãy dùng pipeline riêng chỉ retry GET/HEAD, hoặc thêm header idempotency và dedupe ở server.
Retry storm và những thứ làm nó tệ hơn
Ba yếu tố biến retry thành khuếch đại sự cố: không jitter, không giới hạn, và retry lồng nhau. Không jitter thì mọi client cùng retry ở cùng millisecond, tạo đỉnh tải đúng lúc upstream yếu nhất. Không giới hạn thì một sự cố 10 giây biến thành hàng trăm request treo. Retry lồng nhau — Polly ở service, thêm retry ở gateway, thêm retry ở client — nghĩa là 3 × 3 × 3 = 27 lần gọi cho một request thất bại.
Quy tắc: chỉ một tầng được retry, và tầng đó là tầng gần dependency nhất. Tầng trên chỉ nên timeout và ngắt mạch. Nếu bạn không kiểm soát được tầng trên (API gateway bên thứ ba), hãy tắt retry ở client của mình.
Khi server trả 429 hoặc Retry-After, đừng áp backoff cứng. Tôn trọng header đó: nếu server nói chờ 5 giây, retry sau 200ms chỉ làm bạn bị chặn tiếp. Với dependency có rate limit, rate limiter ở phía client hữu ích hơn retry.
Timeout: ba tầng, ba ý nghĩa
HttpClient.Timeoutlà giới hạn cho một lần gọi; hết giờ nó némTaskCanceledException, không phảiTimeoutRejectedException. Đặt nó lớn hơnAttemptTimeoutđể Polly kịp can thiệp.AttemptTimeoutlà ngân sách cho một lần thử, đặt bên trong retry.TotalRequestTimeoutlà ngân sách cho cả pipeline; nếu request của người dùng có SLA 2 giây, đặt total timeout dưới 2 giây, đừng để 30 giây rồi trả lỗi muộn.
Timeout không hủy được code không tôn trọng CancellationToken. Polly 8 dùng timeout lạc quan: nó hủy token, không kill thread. Nếu dependency là một API legacy bỏ qua token, request vẫn chạy nền dù pipeline đã báo timeout.
Hedging: khi latency quan trọng hơn chi phí
// File: Search/SearchResilience.cs (excerpt)
.AddHedging(new HedgingStrategyOptions<HttpResponseMessage>
{
MaxHedgedAttempts = 2,
Delay = TimeSpan.FromMilliseconds(50),
ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
.Handle<HttpRequestException>()
.HandleResult(r => (int)r.StatusCode >= 500),
})
Hedging gửi thêm request song song nếu request đầu chậm, lấy kết quả nào về trước. Nó giảm tail latency hiệu quả với read path, nhưng nhân đôi tải lên dependency. Chỉ dùng cho GET idempotent, chỉ khi bạn đã đo được vấn đề tail latency, và luôn kèm circuit breaker — nếu không, hedging biến một dependency chậm thành dependency bị DDoS từ chính bạn.
Telemetry: biết mạch đang mở hay đóng
AddStandardResilienceHandler tự đăng ký logging và metrics qua System.Diagnostics.Metrics; bạn xem được số lần retry, số lần mạch mở, thời gian pipeline. Với pipeline tự dựng, trách nhiệm thuộc về bạn: log trong OnRetry, OnOpened, OnTimeout và đếm bằng counter riêng.
Đừng log mỗi lần retry ở mức Information trong hệ thống có traffic cao — nó tạo ra hàng triệu dòng vô ích. Log Warning có cấu trúc, kèm dependency name, attempt number và lý do; bài Serilog ở phần đọc tiếp chỉ cách đặt log đúng. Metric quan trọng nhất là tỉ lệ request phải retry, không phải số lần retry tuyệt đối.
Khi nào không nên retry
- 4xx ngoài 408/429. 400, 401, 403, 404, 409, 422 là lỗi logic hoặc quyền; retry chỉ tốn thời gian và có thể khóa tài khoản.
- Thao tác không idempotent. POST tạo giao dịch, PATCH cộng dồn, publish message.
- Dependency đang sập. Đó là việc của circuit breaker và fallback, không phải retry.
- Đã commit transaction hoặc đã gửi message. Retry ở tầng ngoài sẽ lặp side effect; cần idempotency key ở tầng nghiệp vụ.
- Streaming hoặc download lớn. Retry khởi động lại từ đầu và làm hỏng trải nghiệm người dùng.
- Ngân sách latency đã cạn. Nếu request đã dùng 1.5/2 giây SLA, thêm 3 lần retry chỉ biến lỗi nhanh thành lỗi chậm.
Anti-pattern
- Tạo pipeline trong mỗi request. Circuit breaker mất trạng thái, cache nội bộ mất, chi phí dựng lặp lại. Pipeline phải là singleton hoặc do DI quản lý.
Handle<Exception>(). Retry cảNullReferenceExceptionvàInvalidOperationExceptionlà che giấu bug, không phải chống chịu.- MaxRetryAttempts quá cao. 10 lần với backoff exponential là hơn 3 phút treo cho một request. 3 là đủ cho hầu hết API.
- Retry mà không có timeout. Retry không giới hạn thời gian là treo vô hạn có kiểm soát.
- Bỏ qua
EnsureSuccessStatusCode. Pipeline trả về response 500 mà code không kiểm tra thì retry vô nghĩa. - Trộn Polly 7 và 8.
PolicyvàResiliencePipelinekhông chia sẻ trạng thái; hai cơ chế trong một service là bug chờ xảy ra.
2027
Polly 8.9 là bản ổn định trong chuỗi 8.x; .NET 11 (GA tháng 11/2026) không đổi API Polly. Hướng đang đi là chuẩn hóa resilience ở tầng HTTP client và service discovery (Aspire, Dapr), nghĩa là nhiều app sẽ dùng standard handler thay vì tự viết pipeline. Xem thêm .NET Aspire và Dapr cho ứng dụng cloud-native.
Checklist
- Xác định dependency nào thật sự cần chống chịu — không phải mọi
HttpClient. - Dùng
AddStandardResilienceHandlertrước; chỉ dựng pipeline riêng khi cần lọc method hoặc thêm hedging. - Pipeline và circuit breaker là singleton; kiểm tra bằng test DI scope.
- Retry chỉ trên GET/HEAD/PUT/DELETE đã được xác nhận idempotent; POST cần idempotency key.
- Bật jitter, đặt
MaxRetryAttempts = 3, và đặt total timeout theo SLA của người dùng. - Log Warning có cấu trúc cho mỗi lần retry; metric theo dõi tỉ lệ request phải retry.



