HttpClient و ارتباط با APIهای خارجی

.NET 10 | IHttpClientFactory، Resilience و Timeouts

ارتباط با سرویس خارجی باید Timeout، Cancellation، Serialization، Retry و خطاهای شبکه را کنترل کند. IHttpClientFactory مدیریت Lifetime Handler و پیکربندی Clientهای نام‌دار یا Typed را ساده می‌کند.

این فصل با تمرکز بر قراردادهای قابل اتکا، مرزبندی مسئولیت‌ها و رفتار قابل پیش‌بینی در محیط واقعی تنظیم شده است. مثال‌ها بر پایه ASP.NET Core و .NET 10 نوشته شده‌اند.

1. چارچوب موضوع و مفاهیم اصلی

ارتباط با سرویس خارجی باید Timeout، Cancellation، Serialization، Retry و خطاهای شبکه را کنترل کند. IHttpClientFactory مدیریت Lifetime Handler و پیکربندی Clientهای نام‌دار یا Typed را ساده می‌کند.

واژگان و قراردادهای این بخش باید در سراسر پروژه یکدست بمانند؛ تفاوت میان لایه HTTP، منطق برنامه و زیرساخت زمانی روشن می‌ماند که مسئولیت هر جزء به‌صورت صریح تعریف شود.

2. ساختار پیشنهادی در پروژه

Typed Client با BaseAddress و Headerهای ثابت ثبت می‌شود. Service داخلی تنها Contract آن Client را می‌شناسد و پاسخ خارجی پیش از ورود به Domain به DTO داخلی نگاشت می‌شود.

builder.Services.AddHttpClient<IPaymentGateway, PaymentGateway>(client =>
{
    client.BaseAddress = new Uri("https://payments.example.com/");
    client.Timeout = TimeSpan.FromSeconds(10);
});

3. سناریوی اجرایی

در درخواست ثبت پرداخت، CancellationToken جاری منتقل می‌شود. تنها خطاهای Transient واجد Retry هستند و عملیات غیر Idempotent بدون Idempotency Key کورکورانه تکرار نمی‌شود.

در این سناریو، قرارداد ورودی و خروجی، مسیر شکست و رفتار قابل مشاهده سرویس باید پیش از جزئیات پیاده‌سازی مشخص شود. این رویکرد باعث می‌شود تغییرات بعدی بدون وابستگی پنهان و با امکان تست دقیق انجام شوند.

using var response = await httpClient.PostAsJsonAsync(
    "api/payments",
    request,
    cancellationToken);

if (!response.IsSuccessStatusCode)
    throw new PaymentGatewayException((int)response.StatusCode);

4. اصول طراحی و نگهداری

پیاده‌سازی قابل نگهداری تنها به درست کار کردن در مسیر موفق محدود نیست. مرزهای مسئولیت، قابلیت مشاهده، امنیت، رفتار در خطا و امکان توسعه تدریجی باید هم‌زمان بررسی شوند.

• Timeout صریح برای Dependency خارجی تعریف شود.
• Retry بر اساس Idempotency و نوع خطا تنظیم شود.
• Response خارجی به مدل داخلی مستقیم نشت نکند.
• Telemetry نام Dependency و Duration را ثبت کند.

5. خطاهای رایج و کنترل آن‌ها

بخش مهمی از کیفیت یک API در نحوه جلوگیری از خطاهای تکرارشونده مشخص می‌شود. موارد زیر باید در بازبینی کد و تست‌های قبل از انتشار کنترل شوند.

• new HttpClient در هر Request بدون مدیریت Handler.
• Timeout نامحدود.
• Retry روی 400 یا خطای منطقی ثابت.
• ارسال Secret سرویس خارجی در Log.

6. چک‌لیست نهایی فصل

• Client از IHttpClientFactory ساخته می‌شود.
• Timeout و Cancellation پوشش داده شده‌اند.
• Failure خارجی به خطای داخلی معنی‌دار نگاشت می‌شود.
• Retry تنها برای شرایط مناسب فعال است.

7. جمع‌بندی

مفاهیم این فصل زمانی کامل محسوب می‌شوند که هم مسیر موفق و هم مسیر خطا قابل پیش‌بینی، قابل تست و قابل مشاهده باشند. طراحی نهایی باید با Contract API، امنیت و نیازهای نگهداری پروژه هماهنگ بماند.