feat: 发布v1.8.0版本，完成多项功能优化与配置重构

此版本包含大量 breaking change 与功能改进：
1.  AES加密IV自动随机生成，移除手动配置要求，更新所有文档与示例
2.  重构令牌管理相关配置：移除RefreshBeforeExpirySeconds，统一使用ExpireThresholdSeconds
3.  优化熔断选项校验逻辑，支持高级失败率熔断模式
4.  添加OAuth2配置冲突检查与批量导出OpenTelemetry支持
5.  新增多项配置绑定扩展方法与单元测试
6.  更新所有相关文档与示例代码

Author: shiliu

Mud.HttpUtils.Abstractions/README.md

@@ -69,7 +69,7 @@ Mud.HttpUtils.Abstractions 是 Mud.HttpUtils 的抽象接口层，提供 HTTP 
 | 类型                   | 说明                                                            |
 | ---------------------- | --------------------------------------------------------------- |
 | `IEncryptionProvider`  | 加密提供程序接口，定义 `Encrypt` 和 `Decrypt` 方法              |
-| `AesEncryptionOptions` | AES 加密配置选项，包含 `Key`、`IV` 属性和 `Validate()` 验证方法 |
+| `AesEncryptionOptions` | AES 加密配置选项，包含 `Key` 属性和 `Validate()` 验证方法（`IV` 已废弃，v1.8.0 起自动随机生成） |
 
 > `AesEncryptionOptions` 支持通过配置文件绑定（配置节名称：`MudHttpAesEncryption`），密钥长度支持 AES-128（16 字节）、AES-192（24 字节）、AES-256（32 字节）。
 
@@ -115,7 +115,7 @@ Mud.HttpUtils.Abstractions 是 Mud.HttpUtils 的抽象接口层，提供 HTTP 
 | 类型                            | 说明                                                                                               |
 | ------------------------------- | -------------------------------------------------------------------------------------------------- |
 | `TokenRequest`                  | Token 请求参数，封装获取令牌所需的全部信息（`TokenManagerKey`、`UserId`、`Scopes`）                |
-| `TokenRefreshBackgroundOptions` | 令牌后台刷新配置（`Enabled`、`RefreshIntervalSeconds`、`RefreshBeforeExpirySeconds`、`RetryDelaySeconds`、`StopOnError`） |
+| `TokenRefreshBackgroundOptions` | 令牌后台刷新配置（`Enabled`、`RefreshIntervalSeconds`、`RetryDelaySeconds`、`StopOnError`） |
 | `TokenRecoveryOptions`          | 令牌恢复配置（`Enabled`、`RecoveryMaxRetries`、`TokenScheme`），控制 401 响应时的自动刷新与重试     |
 | `TokenRecoveryContext`          | 令牌恢复上下文，携带注入模式信息供 `TokenRecoveryDelegatingHandler` 使用                            |
 | `TokenInjectionMode`            | 令牌注入模式枚举（`Header`、`Query`、`Path`、`ApiKey`、`HmacSignature`、`BasicAuth`、`Cookie`）    |
@@ -370,8 +370,8 @@ TokenInjectionMode (Header, Query, Path, ApiKey, HmacSignature, BasicAuth, Cooki
 TokenTypes (常量: TenantAccessToken, UserAccessToken, Bearer, Basic)
 Response<T> (StatusCode, Content, RawContent, ErrorContent, ResponseHeaders, IsSuccessStatusCode, GetContentOrThrow)
 ApiException (StatusCode, ErrorContent)
-AesEncryptionOptions (Key, IV, Validate)
-TokenRefreshBackgroundOptions (Enabled, RefreshIntervalSeconds, RefreshBeforeExpirySeconds, RetryDelaySeconds, StopOnError)
+AesEncryptionOptions (Key, Validate) — IV 已废弃，v1.8.0 起自动随机生成
+TokenRefreshBackgroundOptions (Enabled, RefreshIntervalSeconds, RetryDelaySeconds, StopOnError)
 [UserTokenCacheOptions — 位于 Mud.HttpUtils.Client]
 ```
 

Mud.HttpUtils.Abstractions/TokenManager/TokenManagerBase.cs

@@ -46,10 +46,15 @@ public abstract class TokenManagerBase : ITokenManager, IDisposable
     protected virtual int RefreshRetryDelayMilliseconds => 1000;
 
     /// <summary>
-    /// 获取令牌过期提前量（秒），默认 300 秒（5 分钟）。
+    /// 令牌过期提前量的默认值（秒），与 <see cref="UserTokenCacheOptions.DefaultExpireThresholdSeconds"/> 保持一致。
+    /// </summary>
+    protected const int DefaultExpireThresholdSeconds = 300;
+
+    /// <summary>
+    /// 获取令牌过期提前量（秒），默认 <see cref="DefaultExpireThresholdSeconds"/>（300 秒 = 5 分钟）。
     /// 令牌在此时间内即将过期时将触发自动刷新。
     /// </summary>
-    protected virtual int ExpireThresholdSeconds => 300;
+    protected virtual int ExpireThresholdSeconds => DefaultExpireThresholdSeconds;
 
     /// <summary>
     /// 指示此令牌管理器是否支持后台主动刷新。默认为 <c>true</c>。

Mud.HttpUtils.Abstractions/TokenManager/TokenRefreshBackgroundOptions.cs

@@ -28,12 +28,6 @@ public class TokenRefreshBackgroundOptions
     /// </summary>
     public int RefreshIntervalSeconds { get; set; } = 300;
 
-    /// <summary>
-    /// 令牌过期前提前刷新时间（秒），默认 600 秒（10 分钟）。
-    /// 此值用于配合后台服务判断令牌是否即将过期，当前由 TokenManagerBase.ExpireThresholdSeconds 控制。
-    /// </summary>
-    public int RefreshBeforeExpirySeconds { get; set; } = 600;
-
     /// <summary>
     /// 刷新失败后重试延迟（秒），默认 60 秒（1 分钟）。
     /// </summary>

Mud.HttpUtils.Client/README.md

@@ -89,14 +89,14 @@ services.AddSingleton<IHttpResponseInterceptor, CacheResponseInterceptor>();
 services.AddMudHttpClient("myApi", encryption =>
 {
     encryption.Key = Convert.FromBase64String("your-base64-key");
-    encryption.IV = Convert.FromBase64String("your-base64-iv");
+    // 注意：从 v1.8.0 起 IV 自动随机生成，无需手动设置
 }, client =>
 {
     client.BaseAddress = new Uri("https://api.example.com");
 });
 ```
 
-> 密钥长度支持 AES-128（16 字节）、AES-192（24 字节）、AES-256（32 字节）。`AesEncryptionOptions.Validate()` 方法在启动时验证密钥和 IV 的有效性。
+> 密钥长度支持 AES-128（16 字节）、AES-192（24 字节）、AES-256（32 字节）。`AesEncryptionOptions.Validate()` 方法在启动时验证密钥的有效性。从 v1.8.0 起，IV 在每次加密时自动随机生成，无需手动设置。
 
 ### 安全认证提供程序
 
@@ -178,7 +178,7 @@ services.AddTokenRefreshBackgroundService(options =>
 });
 ```
 
-> `TokenManagerBase` 使用 `SemaphoreSlim(1, 1)` 确保同一时刻只有一个线程执行令牌刷新。`UserTokenManagerBase` 使用 `IMemoryCache` 管理用户令牌缓存，支持 `MaxCacheSize` 限制和自动过期清理。`TokenRefreshHostedService` 支持配置 `RefreshIntervalSeconds`（刷新间隔）、`RefreshBeforeExpirySeconds`（过期前提前刷新时间）、`RetryDelaySeconds`（重试延迟）和 `StopOnError`（出错时是否停止）。
+> `TokenManagerBase` 使用 `SemaphoreSlim(1, 1)` 确保同一时刻只有一个线程执行令牌刷新。`UserTokenManagerBase` 使用 `IMemoryCache` 管理用户令牌缓存，支持 `SizeLimit` 限制和自动过期清理。`TokenRefreshHostedService` 支持配置 `RefreshIntervalSeconds`（刷新间隔）、`RetryDelaySeconds`（重试延迟）和 `StopOnError`（出错时是否停止）。令牌过期提前量由 `TokenManagerBase.ExpireThresholdSeconds` 控制（默认 300 秒）。
 
 > `DefaultTokenProvider` 是 `ITokenProvider` 的默认实现，通过 `IMudAppContext` 获取令牌管理器并获取令牌。它不持有 `IMudAppContext` 引用，而是通过方法参数逐调用接收，以确保生成代码中 `UseApp()`/`UseDefaultApp()` 上下文切换的正确性。当 `TokenRequest.UserId` 非空时，自动使用 `IUserTokenManager` 获取用户级令牌。
 
@@ -214,6 +214,39 @@ var httpContent = formContent.ToHttpContent(); // FormUrlEncodedContent
 
 > `DefaultFormContent` 是 `IFormContent` 的默认实现，将字典数据转换为 `FormUrlEncodedContent`。适用于简单的表单提交场景。
 
+### 令牌恢复配置
+
+`TokenRecoveryOptions` 用于控制 401 响应时的自动令牌刷新与重试行为，配置节名称为 `MudHttpTokenRecovery`。
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `Enabled` | `bool` | `true` | 是否启用令牌恢复机制 |
+| `RecoveryMaxRetries` | `int` | `1` | 令牌恢复的最大重试次数 |
+| `TokenScheme` | `string` | `"Bearer"` | 令牌的认证方案 |
+
+```csharp
+// 通过代码配置
+services.Configure<TokenRecoveryOptions>(options =>
+{
+    options.Enabled = true;
+    options.RecoveryMaxRetries = 2;
+    options.TokenScheme = "Bearer";
+});
+
+// 或通过 IConfiguration 绑定
+services.AddMudHttpTokenRecoveryFromConfiguration(configuration);
+```
+
+```json
+{
+  "MudHttpTokenRecovery": {
+    "Enabled": true,
+    "RecoveryMaxRetries": 2,
+    "TokenScheme": "Bearer"
+  }
+}
+```
+
 ### 应用上下文
 
 | 类                     | 说明                                        |

Mud.HttpUtils.Client/ServiceCollectionExtensions.cs

@@ -654,4 +654,70 @@ public static IServiceCollection AddMudHttpClientsFromConfiguration(
 
         return services;
     }
+
+    /// <summary>
+    /// 从 IConfiguration 绑定 OAuth2 令牌管理器配置。
+    /// </summary>
+    /// <param name="services">服务集合。</param>
+    /// <param name="configuration">配置实例。</param>
+    /// <param name="sectionPath">配置节点路径，默认 <see cref="OAuth2Options.SectionName"/>。</param>
+    /// <returns>服务集合（链式调用）。</returns>
+    /// <exception cref="ArgumentNullException">参数为 null 时抛出。</exception>
+    public static IServiceCollection AddMudHttpOAuth2FromConfiguration(
+        this IServiceCollection services,
+        IConfiguration configuration,
+        string sectionPath = OAuth2Options.SectionName)
+    {
+        if (services == null)
+            throw new ArgumentNullException(nameof(services));
+        if (configuration == null)
+            throw new ArgumentNullException(nameof(configuration));
+
+        services.Configure<OAuth2Options>(configuration.GetSection(sectionPath));
+        return services;
+    }
+
+    /// <summary>
+    /// 从 IConfiguration 绑定令牌恢复配置。
+    /// </summary>
+    /// <param name="services">服务集合。</param>
+    /// <param name="configuration">配置实例。</param>
+    /// <param name="sectionPath">配置节点路径，默认 <see cref="TokenRecoveryOptions.SectionName"/>。</param>
+    /// <returns>服务集合（链式调用）。</returns>
+    /// <exception cref="ArgumentNullException">参数为 null 时抛出。</exception>
+    public static IServiceCollection AddMudHttpTokenRecoveryFromConfiguration(
+        this IServiceCollection services,
+        IConfiguration configuration,
+        string sectionPath = TokenRecoveryOptions.SectionName)
+    {
+        if (services == null)
+            throw new ArgumentNullException(nameof(services));
+        if (configuration == null)
+            throw new ArgumentNullException(nameof(configuration));
+
+        services.Configure<TokenRecoveryOptions>(configuration.GetSection(sectionPath));
+        return services;
+    }
+
+    /// <summary>
+    /// 从 IConfiguration 绑定用户令牌缓存配置。
+    /// </summary>
+    /// <param name="services">服务集合。</param>
+    /// <param name="configuration">配置实例。</param>
+    /// <param name="sectionPath">配置节点路径，默认 <c>"MudHttpUserTokenCache"</c>。</param>
+    /// <returns>服务集合（链式调用）。</returns>
+    /// <exception cref="ArgumentNullException">参数为 null 时抛出。</exception>
+    public static IServiceCollection AddMudHttpUserTokenCacheFromConfiguration(
+        this IServiceCollection services,
+        IConfiguration configuration,
+        string sectionPath = "MudHttpUserTokenCache")
+    {
+        if (services == null)
+            throw new ArgumentNullException(nameof(services));
+        if (configuration == null)
+            throw new ArgumentNullException(nameof(configuration));
+
+        services.Configure<UserTokenCacheOptions>(configuration.GetSection(sectionPath));
+        return services;
+    }
 }

Mud.HttpUtils.Client/TokenManager/OAuth2Options.cs

@@ -31,9 +31,24 @@ public class OAuth2Options
     /// 客户端密钥的安全提供程序名称。
     /// 当设置此值时，将通过 <see cref="ISecretProvider"/> 从安全存储中获取 ClientSecret，
     /// 而非使用明文配置的 <see cref="ClientSecret"/>。
+    /// <para>注意：当同时设置 <see cref="ClientSecret"/> 和 <see cref="ClientSecretProviderName"/> 时，
+    /// <see cref="ClientSecretProviderName"/> 优先生效。建议仅设置其中之一以避免混淆。</para>
     /// </summary>
     public string? ClientSecretProviderName { get; set; }
 
+    /// <summary>
+    /// 校验配置是否存在互斥冲突：当同时设置 <see cref="ClientSecret"/> 和 <see cref="ClientSecretProviderName"/> 时返回警告消息。
+    /// </summary>
+    /// <returns>警告消息；如果无冲突则返回 null。</returns>
+    internal string? GetConflictWarning()
+    {
+        if (!string.IsNullOrEmpty(ClientSecret) && !string.IsNullOrEmpty(ClientSecretProviderName))
+        {
+            return $"OAuth2Options: ClientSecret 和 ClientSecretProviderName 同时设置，ClientSecretProviderName 将优先生效。建议仅保留一个以避免混淆。";
+        }
+        return null;
+    }
+
     /// <summary>
     /// 令牌端点。
     /// </summary>

Mud.HttpUtils.Client/TokenManager/UserTokenCacheOptions.cs

@@ -13,32 +13,57 @@ namespace Mud.HttpUtils;
 public class UserTokenCacheOptions
 {
     /// <summary>
-    /// 缓存容量限制（用户数量），默认 10000。
+    /// 默认缓存容量限制（用户数量）。
+    /// </summary>
+    public const int DefaultSizeLimit = 10000;
+
+    /// <summary>
+    /// 默认令牌过期提前量（秒）。
+    /// </summary>
+    public const int DefaultExpireThresholdSeconds = 300;
+
+    /// <summary>
+    /// 默认缓存清理间隔（秒）。
+    /// </summary>
+    public const int DefaultCleanupIntervalSeconds = 300;
+
+    /// <summary>
+    /// 默认滑动过期时间（秒）。
+    /// </summary>
+    public const int DefaultSlidingExpirationSeconds = 3600;
+
+    /// <summary>
+    /// 默认缓存压缩百分比。
+    /// </summary>
+    public const double DefaultCompactionPercentage = 0.2;
+
+    /// <summary>
+    /// 缓存容量限制（用户数量），默认 <see cref="DefaultSizeLimit"/>（10000）。
     /// 当缓存数量超过此值时，将自动淘汰过期令牌和最久未访问的令牌。
     /// </summary>
-    public int SizeLimit { get; set; } = 10000;
+    public int SizeLimit { get; set; } = DefaultSizeLimit;
 
     /// <summary>
-    /// 用户令牌过期提前量（秒），默认 300 秒（5 分钟）。
+    /// 用户令牌过期提前量（秒），默认 <see cref="DefaultExpireThresholdSeconds"/>（300 秒 = 5 分钟）。
     /// 令牌在此时间内即将过期时将触发自动刷新。
     /// </summary>
-    public int ExpireThresholdSeconds { get; set; } = 300;
+    public int ExpireThresholdSeconds { get; set; } = DefaultExpireThresholdSeconds;
 
     /// <summary>
-    /// 缓存清理间隔（秒），默认 300 秒（5 分钟）。
+    /// 缓存清理间隔（秒），默认 <see cref="DefaultCleanupIntervalSeconds"/>（300 秒 = 5 分钟）。
     /// 定期清理过期的用户令牌缓存和对应的锁资源。
     /// </summary>
-    public int CleanupIntervalSeconds { get; set; } = 300;
+    public int CleanupIntervalSeconds { get; set; } = DefaultCleanupIntervalSeconds;
 
     /// <summary>
-    /// 滑动过期时间（秒），默认 3600 秒（1 小时）。
+    /// 滑动过期时间（秒），默认 <see cref="DefaultSlidingExpirationSeconds"/>（3600 秒 = 1 小时）。
     /// 如果在此时间内未访问缓存条目，该条目将被自动移除。
     /// </summary>
-    public int SlidingExpirationSeconds { get; set; } = 3600;
+    public int SlidingExpirationSeconds { get; set; } = DefaultSlidingExpirationSeconds;
 
     /// <summary>
-    /// 缓存压缩百分比，默认 0.2（20%）。
+    /// 缓存压缩百分比，默认 <see cref="DefaultCompactionPercentage"/>（0.2 = 20%）。
     /// 当缓存达到容量限制时，将按此比例压缩（移除）条目。
     /// </summary>
-    public double CompactionPercentage { get; set; } = 0.2;
+    public double CompactionPercentage { get; set; } = DefaultCompactionPercentage;
 }

Mud.HttpUtils.OpenTelemetry/MudHttpOpenTelemetryExtensions.cs

@@ -71,6 +71,9 @@ public static OpenTelemetryBuilder AddMudHttpOpenTelemetry(
                     new KeyValuePair<string, object>("deployment.environment", options.DeploymentEnvironment)
                 }));
 
+        // 批量导出配置：通过 DI 注册 BatchExportProcessorOptions，对所有 Provider 生效
+        ConfigureBatchExportOptions(services, options);
+
         if (options.EnableTracing)
         {
             builder.WithTracing(tp =>
@@ -127,6 +130,25 @@ public static OpenTelemetryBuilder AddMudHttpOpenTelemetry(
         return builder;
     }
 
+    /// <summary>
+    /// 通过 DI 注册批量导出处理器选项，使 <see cref="MudHttpOpenTelemetryOptions.ExportBatchSize"/>
+    /// 和 <see cref="MudHttpOpenTelemetryOptions.ExportIntervalMilliseconds"/> 生效。
+    /// </summary>
+    private static void ConfigureBatchExportOptions(IServiceCollection services, MudHttpOpenTelemetryOptions options)
+    {
+        // 批量导出配置：仅当值 > 0 时生效，null 使用 SDK 默认值
+        if (options.ExportBatchSize.HasValue && options.ExportBatchSize.Value > 0)
+        {
+            services.Configure<BatchExportProcessorOptions<Activity>>(b =>
+                b.MaxQueueSize = options.ExportBatchSize.Value);
+        }
+        if (options.ExportIntervalMilliseconds.HasValue && options.ExportIntervalMilliseconds.Value > 0)
+        {
+            services.Configure<BatchExportProcessorOptions<Activity>>(b =>
+                b.ExporterTimeoutMilliseconds = options.ExportIntervalMilliseconds.Value);
+        }
+    }
+
     private static void ConfigureOtlpExporter(TracerProviderBuilder builder, MudHttpOpenTelemetryOptions options)
     {
         if (options.OtlpEndpoint is null) return;

Mud.HttpUtils.Resilience/Options/CircuitBreakerOptions.cs

@@ -33,7 +33,16 @@ public class CircuitBreakerOptions
     public int FailureThreshold
     {
         get => _failureThreshold;
-        set => _failureThreshold = value > 0 ? value : throw new ArgumentOutOfRangeException(nameof(FailureThreshold), "故障阈值必须大于 0。");
+        set
+        {
+            if (value <= 0)
+                throw new ArgumentOutOfRangeException(nameof(FailureThreshold), "故障阈值必须大于 0。");
+            // 当使用高级熔断模式（SamplingDurationSeconds > 0）时，FailureThreshold 表示失败率百分比，范围为 1-100
+            if (_samplingDurationSeconds > 0 && value > 100)
+                throw new ArgumentOutOfRangeException(nameof(FailureThreshold),
+                    "当 SamplingDurationSeconds 大于 0 时，FailureThreshold 表示失败率百分比，取值范围为 1-100。");
+            _failureThreshold = value;
+        }
     }
 
     /// <summary>
@@ -57,7 +66,16 @@ public int BreakDurationSeconds
     public int SamplingDurationSeconds
     {
         get => _samplingDurationSeconds;
-        set => _samplingDurationSeconds = value >= 0 ? value : throw new ArgumentOutOfRangeException(nameof(SamplingDurationSeconds), "采样窗口时间不能为负数。");
+        set
+        {
+            if (value < 0)
+                throw new ArgumentOutOfRangeException(nameof(SamplingDurationSeconds), "采样窗口时间不能为负数。");
+            // 当切换到高级熔断模式时，校验 FailureThreshold 是否在百分比范围内
+            if (value > 0 && _failureThreshold > 100)
+                throw new ArgumentOutOfRangeException(nameof(SamplingDurationSeconds),
+                    $"当 SamplingDurationSeconds 大于 0 时，FailureThreshold 表示失败率百分比，当前值为 {_failureThreshold}，超出范围 1-100。");
+            _samplingDurationSeconds = value;
+        }
     }
 
     /// <summary>

Mud.HttpUtils.Resilience/README.md

@@ -83,7 +83,7 @@ services.AddMudHttpUtils("myApi", "https://api.example.com", options =>
 | `MaxRetryAttempts` | `int` | `3` | 最大重试次数 |
 | `DelayMilliseconds` | `int` | `1000` | 基础延迟时间（毫秒） |
 | `UseExponentialBackoff` | `bool` | `true` | 是否使用指数退避 |
-| `RetryStatusCodes` | `int[]` | `[408, 429, 500, 502, 503, 504]` | 触发重试的 HTTP 状态码 |
+| `RetryStatusCodes` | `int[]?` | `null`（运行时回退到 `[408, 429, 500, 502, 503, 504]`） | 触发重试的 HTTP 状态码 |
 | `OnRetry` | `Func<Exception?, int, TimeSpan, Task>?` | `null` | 重试回调函数 |
 
 ### TimeoutOptions