Mud.HttpUtils.Resilience 2.0.0

Mud.HttpUtils.Resilience

概述

Mud.HttpUtils.Resilience 是 Mud.HttpUtils 的弹性策略层，基于 Polly 提供重试、超时、熔断策略，通过装饰器模式增强 IEnhancedHttpClient。

目标框架

• netstandard2.0
• net6.0
• net8.0
• net10.0

包含内容

核心类

策略组合顺序

组合策略执行顺序：重试（外层） → 熔断 → 超时（内层）

• 每次请求先经过超时策略限制
• 超时的请求会被熔断器统计
• 重试策略在所有内层策略之外

超时配置说明：HttpClient.Timeout（通过 MudHttpClientOptions.TimeoutSeconds 配置）与 Polly 的 TimeoutOptions.TimeoutSeconds 是两个独立的超时机制。

• HttpClient.Timeout 是 .NET HttpClient 内置的全局超时，作用于整个请求生命周期（包括重试）。
• TimeoutOptions.TimeoutSeconds 是 Polly 的单次请求超时，仅作用于单次尝试（每次重试独立计时）。
• 建议将 HttpClient.Timeout 设置为略大于 Retry.MaxRetryAttempts × TimeoutOptions.TimeoutSeconds + 总重试延迟，避免 HttpClient 超时打断正常的重试流程。
• 启用弹性策略后，如果未显式设置 HttpClient.Timeout，Polly 超时策略将作为主要超时控制。

请求克隆与大小限制

HttpRequestMessageCloner 用于在重试时克隆请求消息（因为 HttpRequestMessage 不可重用）。新增内容大小限制功能：

// 默认最大克隆大小为 10MB
public const long DefaultMaxContentSize = 10 * 1024 * 1024;

// 克隆时检查大小
var cloned = await HttpRequestMessageCloner.CloneAsync(request, maxContentSize: 10 * 1024 * 1024);

当请求体大小超过 MaxCloneContentSize 时，ResilientHttpClient 会自动跳过重试策略，避免克隆大请求体的性能开销。适用于大文件上传等场景。

重试回调机制

RetryOptions 提供 OnRetry 属性，支持在每次重试前执行自定义逻辑：

services.AddMudHttpUtils("myApi", "https://api.example.com", options =>
{
    options.Retry.MaxRetryAttempts = 3;
    options.Retry.OnRetry = async (exception, retryCount, delay) =>
    {
        Console.WriteLine($"第 {retryCount} 次重试，延迟 {delay.TotalMilliseconds}ms，异常: {exception?.Message}");
    };
});

OnRetry 签名为 Func<Exception?, int, TimeSpan, Task>，参数分别为：触发的异常（可能为 null）、重试次数（从 1 开始）、下次重试前的延迟时间。可用于日志记录、指标收集、动态调整重试策略等。

配置选项

ResilienceOptions

RetryOptions

TimeoutOptions

CircuitBreakerOptions

熔断模式说明：

• 当 SamplingDurationSeconds = 0（默认）时，使用简单熔断策略，FailureThreshold 表示连续失败次数
• 当 SamplingDurationSeconds > 0 时，使用高级熔断策略，FailureThreshold 表示采样窗口内的失败率百分比（1-100）

安装

<PackageReference Include="Mud.HttpUtils.Resilience" Version="x.x.x" />

使用方式

代码配置

services.AddMudHttpResilienceDecorator(options =>
{
    // 重试策略
    options.Retry.Enabled = true;
    options.Retry.MaxRetryAttempts = 3;
    options.Retry.DelayMilliseconds = 1000;
    options.Retry.UseExponentialBackoff = true;
    options.Retry.RetryStatusCodes = [408, 429, 500, 502, 503, 504];
    options.Retry.OnRetry = async (ex, retryCount, delay) =>
    {
        logger.LogWarning("HTTP 请求重试 {RetryCount}，延迟 {Delay}ms", retryCount, delay.TotalMilliseconds);
    };

    // 超时策略
    options.Timeout.Enabled = true;
    options.Timeout.TimeoutSeconds = 30;

    // 熔断策略
    options.CircuitBreaker.Enabled = true;
    options.CircuitBreaker.FailureThreshold = 5;
    options.CircuitBreaker.BreakDurationSeconds = 30;

    // 请求克隆大小限制
    options.MaxCloneContentSize = 10 * 1024 * 1024; // 10MB
});

配置文件绑定

services.AddMudHttpResilienceDecorator(configuration, "MudHttpResilience");

对应 appsettings.json：

{
  "MudHttpResilience": {
    "MaxCloneContentSize": 10485760,
    "Retry": {
      "Enabled": true,
      "MaxRetryAttempts": 3,
      "DelayMilliseconds": 1000,
      "UseExponentialBackoff": true,
      "RetryStatusCodes": [408, 429, 500, 502, 503, 504]
    },
    "Timeout": {
      "Enabled": true,
      "TimeoutSeconds": 30
    },
    "CircuitBreaker": {
      "Enabled": true,
      "FailureThreshold": 5,
      "BreakDurationSeconds": 30,
      "SamplingDurationSeconds": 0,
      "MinimumThroughput": 10
    }
  }
}

高级熔断策略（基于采样窗口的失败率模式）：

{
  "CircuitBreaker": {
    "Enabled": true,
    "FailureThreshold": 50,
    "BreakDurationSeconds": 30,
    "SamplingDurationSeconds": 60,
    "MinimumThroughput": 10
  }
}

高级模式下 FailureThreshold = 50 表示采样窗口内失败率达 50% 时触发熔断，至少需要 MinimumThroughput 次请求。

配置校验

ResilienceOptionsValidator 实现了 IValidateOptions<ResilienceOptions>，在选项绑定时自动执行跨选项校验：

• 当 Retry.Enabled 和 Timeout.Enabled 同时为 true 时，校验重试总延迟（含指数退避）是否超过单次超时时间 Timeout.TimeoutSeconds。超出时 IOptions.Validate 返回失败，应用启动抛出异常。
• 当 Retry.Enabled 或 Timeout.Enabled 为 false 时，跳过此校验。

已知限制：此校验器无法检测 HttpClient.Timeout（通过 MudHttpClientOptions.TimeoutSeconds 配置）与 Polly 超时的跨选项冲突。建议用户手动确保 HttpClient.Timeout 略大于 Retry.MaxRetryAttempts × Timeout.TimeoutSeconds + 总重试延迟，避免 HttpClient 超时打断正常的重试流程。详见上方"超时配置说明"。

一站式注册

services.AddMudHttpUtils("myApi", "https://api.example.com", options =>
{
    options.Retry.MaxRetryAttempts = 3;
    options.Timeout.TimeoutSeconds = 30;
    options.MaxCloneContentSize = 5 * 1024 * 1024; // 5MB
});

大文件上传场景

对于大文件上传等场景，建议禁用重试或增大克隆限制：

// 方式一：增大克隆限制
options.MaxCloneContentSize = 100 * 1024 * 1024; // 100MB

// 方式二：禁用重试
options.Retry.Enabled = false;

// 方式三：不限制（不推荐）
options.MaxCloneContentSize = -1;

当请求体大小超过 MaxCloneContentSize 时，ResilientHttpClient 会记录警告日志并跳过重试，直接发送请求。

DI 服务注册方法

注意：AddMudHttpResilienceDecorator 必须在 AddMudHttpClient 之后调用。

依赖项

设计原则

• 装饰器模式：ResilientHttpClient 装饰 IEnhancedHttpClient，不修改原始实现
• 策略组合：通过 Polly PolicyWrap 组合多种策略，执行顺序可控
• 安全重试：通过 HttpRequestMessageCloner 克隆请求消息，确保重试安全
• 性能保护：通过 MaxCloneContentSize 限制克隆大小，避免大请求体的克隆开销
• 可观测性：通过 OnRetry 支持自定义重试回调，便于日志记录和指标收集；内置诊断事件负载（RetryDiagnosticPayload、TimeoutDiagnosticPayload）支持分布式追踪
• 配置灵活：支持代码配置和配置文件绑定