ASP.NET Core 外部依赖调用治理实战：HttpClientFactory、Polly 与幂等边界

硅基喵2026-03-18 18:16

订单服务最容易出现的稳定性问题，不是业务代码写错，而是下游支付、库存、短信网关一抖，整个接口成功率跟着雪崩。看起来只是一次超时，实际上会引发重试风暴、线程池占满、数据库回写积压。

今天我们讨论一个问题：如何把外部依赖调用链路收敛到可控、可观测、可恢复的状态。

1. 问题背景：服务没挂，为什么成功率先掉

线上经常出现这种现象：

  • API 进程还活着，CPU 占用也不高，可能只有40%（举个例子，非真实数据）。
  • 请求延迟从 200ms 拉到 6s。
  • 失败率增多。

这类故障通常不是单点问题，大概就是遇到下面这些因素了：

  1. HttpClient 使用方式不当。
  2. 超时和重试没有预算控制，单次请求被放大成多次慢调用。
  3. 对写操作直接重试却没有幂等约束，最终引发重复扣款或重复下单。

对于有多年经验的开发者来说，这不是 API 会不会调的问题，而是如何在高并发场景下把失败控制在局部，不让故障扩散到整条链路。

2. 原理解析：连接、超时、重试和幂等为什么必须一起设计

2.1 连接管理决定了你能扛多久

每次请求都新建 HttpClient，会导致连接池无法稳定复用，遇到峰值时容易把端口和连接资源打爆。更隐蔽的问题是连接存活太久导致 DNS 变更不生效，流量继续打到旧节点。

IHttpClientFactory 的价值不是语法糖，而是把连接池生命周期交给 SocketsHttpHandler 管理。常见配置里至少要有：

  • PooledConnectionLifetime：定期轮换连接，避免长期粘住旧地址。
  • MaxConnectionsPerServer：控制单机并发上限，避免瞬时过载。

2.2 超时预算必须先于重试策略

很多团队会先配"重试 3 次"，但没配总预算。结果是每次重试都等满超时，最后一个请求占用十几秒。

更稳妥的做法是分两层：

  • 每次尝试超时（per-try timeout）：避免单次卡死。
  • 整体调用超时（overall timeout）：限制整次业务调用的总耗时。

在 Resilience Pipeline 里，这两层要通过策略顺序明确表达：

  • outer timeout 放在 retry 外层，控制整次调用预算。
  • inner timeout 放在 retry 内层，控制单次 attempt。

先定预算，再谈重试次数，否则重试是放大器，不是保护器。

2.3 遵循行业共识，重试只能处理瞬时故障，不能处理业务冲突

可重试的典型对象是：网络抖动、连接中断、429、部分 5xx。不可重试的是：参数错误、鉴权失败、业务规则冲突。

如果把所有非 200 都重试，会把本来可快速失败的请求拖成长尾，最终压垮线程池和连接池。

2.4 写操作重试前必须定义幂等边界

对 POST/PUT 这类有副作用的请求，重试不是默认安全动作。支付创建、库存扣减、优惠券核销这类写操作，必须先定义幂等键和幂等存储，再启用自动重试。

简单说：

  • 没有幂等键，重试可能制造重复业务。
  • 有幂等键但没有唯一约束，仍然可能并发写穿。

3. 示例代码：从无边界调用到可恢复的稳定调用

3.1 问题写法：每次 new HttpClient + 无条件重试

bash 复制代码 
public sealed class PaymentGatewayCaller
{
    public async Task<string> CreatePaymentAsync(PaymentRequest request, CancellationToken ct)
    {
        using var client = new HttpClient();
        client.Timeout = TimeSpan.FromSeconds(30);

        for (var attempt = 0; attempt < 3; attempt++)
        {
            var response = await client.PostAsJsonAsync(
                "https://payment.example.com/api/payments",
                request,
                ct);

            if (response.IsSuccessStatusCode)
            {
                return await response.Content.ReadAsStringAsync(ct);
            }
        }

        throw new InvalidOperationException("payment call failed after retries");
    }
}

这个写法的问题很集中：

  • 连接管理不可控。
  • 所有失败都重试。
  • 写操作没有幂等键。
  • 30 秒超时会在重试后放大为更长长尾。

3.2 优化写法：Typed Client + Resilience Pipeline

先安装包：

bash 复制代码 
dotnet add package Microsoft.Extensions.Http.Resilience

然后在 Program.cs 里集中配置客户端和韧性策略：

bash 复制代码 
using System.Net;
using Microsoft.Extensions.Http.Resilience;
using Polly;
using Polly.Retry;
using Polly.Timeout;

builder.Services
    .AddHttpClient<PaymentGatewayClient>(client =>
    {
        client.BaseAddress = new Uri("http://localhost:5001/");
        client.DefaultRequestHeaders.UserAgent.ParseAdd("order-service/1.0");
    })
    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
    {
        // 设置 DNS 重新解析间隔时间和对下游单个服务的最大并发
        PooledConnectionLifetime = TimeSpan.FromMinutes(5),
        MaxConnectionsPerServer = 200
    })
    .AddResilienceHandler("payment-pipeline", static pipeline =>
    {
        // Outer timeout: 限制一次完整调用（包含重试）的总预算
        pipeline.AddTimeout(TimeSpan.FromSeconds(6));

        pipeline.AddRetry(new HttpRetryStrategyOptions
        {
            MaxRetryAttempts = 3,
            BackoffType = DelayBackoffType.Exponential,
            Delay = TimeSpan.FromMilliseconds(200),
            UseJitter = true,
            ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
                .Handle<HttpRequestException>()
                //.Handle<TimeoutRejectedException>()
                .HandleResult(response =>
                    response.StatusCode == HttpStatusCode.RequestTimeout ||
                    response.StatusCode == HttpStatusCode.TooManyRequests ||
                    (int)response.StatusCode >= 500)
        });

        // Inner timeout: 限制单次 attempt
        pipeline.AddTimeout(TimeSpan.FromSeconds(2));

        pipeline.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions
        {
            FailureRatio = 0.5,
            SamplingDuration = TimeSpan.FromSeconds(30),
            // 示例值，需结合实际 QPS 调整；阈值过高会导致低流量服务不触发评估
            MinimumThroughput = 8,
            BreakDuration = TimeSpan.FromSeconds(15)
        });
    });

MinimumThroughput 没有通用固定值。低流量服务如果 30 秒内都达不到阈值，熔断器就不会触发。上线前建议按真实 QPS 压测后再定值。

另外，pipeline 超时会抛 TimeoutRejectedException，而不是 OperationCanceledException。调用方如果要区分"主动取消"和"超时熔断"，需要分别处理两种异常。

bash 复制代码 
try
{
    var result = await _paymentGatewayClient.CreatePaymentAsync(request, idempotencyKey, ct);
    return Results.Ok(result);
}
catch (TimeoutRejectedException)
{
    return Results.StatusCode(StatusCodes.Status504GatewayTimeout);
}
catch (OperationCanceledException) when (ct.IsCancellationRequested)
{
    return Results.StatusCode(StatusCodes.Status499ClientClosedRequest);
}

调用端补充幂等键校验和请求头注入：

bash 复制代码 
using System.Net.Http.Json;
using System.Text.RegularExpressions;

public sealed class PaymentGatewayClient
{
    private readonly HttpClient _httpClient;
    private static readonly Regex IdempotencyKeyPattern =
        new("^[A-Za-z0-9_-]{16,64}$", RegexOptions.Compiled);

    public PaymentGatewayClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<PaymentGatewayResponse> CreatePaymentAsync(
        PaymentGatewayRequest request,
        string idempotencyKey,
        CancellationToken ct)
    {
        if (string.IsNullOrWhiteSpace(idempotencyKey) ||
            !IdempotencyKeyPattern.IsMatch(idempotencyKey))
        {
            throw new ArgumentException("idempotency key is invalid", nameof(idempotencyKey));
        }

        using var message = new HttpRequestMessage(HttpMethod.Post, "api/payments")
        {
            Content = JsonContent.Create(request)
        };

        message.Headers.Add("Idempotency-Key", idempotencyKey);

        using var response = await _httpClient.SendAsync(
            message,
            HttpCompletionOption.ResponseHeadersRead,
            ct);

        response.EnsureSuccessStatusCode();
        var payload = await response.Content.ReadFromJsonAsync<PaymentGatewayResponse>(cancellationToken: ct);

        if (payload is null)
        {
            throw new InvalidOperationException("gateway response is empty");
        }

        return payload;
    }
}

3.3 幂等落地

理想情况下，幂等性确实应该在被调用方里做。网关自己维护幂等记录，调用方只需要带着 Idempotency-Key 重试，网关保证同一个 key 只处理一次，调用方不需要关心细节。下面是被调用方一个最小可用的幂等方案，调用方视角的幂等设计，我懒得做了。。。

bash 复制代码 
app.MapPost("/api/payments", async (HttpRequest request) =>
{
    var idempotencyKey = request.Headers["Idempotency-Key"].FirstOrDefault();

    if (string.IsNullOrWhiteSpace(idempotencyKey))
    {
        return Results.BadRequest(new { error = "Idempotency-Key header is required" });
    }

    Console.WriteLine($"[FakeGateway] key={idempotencyKey} behavior={behavior}");

    // 幂等检查：已有结果直接返回，不再执行业务逻辑
    if (idempotencyStore.TryGetValue(idempotencyKey, out var cached))
    {
        Console.WriteLine($"[FakeGateway] key={idempotencyKey} → returning cached result");
        return Results.Ok(cached);
    }

    // 模拟行为
    switch (behavior)
    {
        case "timeout":
            await Task.Delay(TimeSpan.FromSeconds(30));
            break;
        case "error500":
            return Results.StatusCode(500);
        case "toomany":
            return Results.StatusCode(429);
    }

    var result = new
    {
        paymentId = Guid.NewGuid().ToString("N"),
        status = "created",
        idempotencyKey
    };

    // 存入幂等记录，后续相同 key 直接命中缓存
    idempotencyStore[idempotencyKey] = result;

    return Results.Ok(result);
});

4. 总结

外部依赖调用治理不是"加个重试"这么简单，它本质上是连接管理、预算控制、失败隔离和幂等边界的组合设计。对高并发系统来说，稳定性提升往往来自这些基础动作，而不是复杂框架。先把预算和幂等做扎实，再去做精细调参，系统抗抖能力会稳定很多。

相关推荐
带娃的IT创业者1 天前
Weclaw 请求路由实战：一个 request_id 如何在 800 个并发连接中精准找到目标浏览器？
python·websocket·fastapi·架构设计·实时通信·openclaw·weclaw
墨10242 天前
当 AI 助手开始管理多个项目：如何把“继续某项目”变成可联动机制
人工智能·ai·项目管理·架构设计·工程实践·openclaw
大傻^3 天前
钱的教育架构师思维：从现金流到资产负债表的系统工程
微服务·架构设计·系统思维·财务自由·技术债管理
递归尽头是星辰4 天前
DDD 认知升级：从单服务战术落地，到分布式中台战略全景
领域驱动设计·架构设计·微服务拆分·ddd 落地实践·ddd 战略战术
arvin_xiaoting5 天前
多 Session 伪装大脑：如何在保持隐私隔离的前提下实现多渠道 AI Agent 的认知一致性
人工智能·向量数据库·架构设计·ai agent·lancedb·openclaw·多渠道通信
硅基喵7 天前
ASP.NET Core 认证鉴权实战：JWT、Policy 与权限边界怎么落地
asp.net core·工程实践
Ray Liang8 天前
一小时手搓轻量级可代替 Qdrant 的向量数据库
人工智能·架构设计·mindx·qrant
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04UV安装并设置国内源05OpenClaw Control UI安全上下文访问配置06小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）07本地部署 OpenClaw + DeepSeek-R1 完全指南08Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services09OpenClaw macOS 完整安装与本地模型配置教程（实战版）10AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南