refactor: 完成项目多维度优化与功能完善

本次提交包含多项核心改进：
1. 令牌缓存与OAuth2配置优化：新增配置节常量、DI注入构造函数，修复配置绑定逻辑
2. 弹性策略重构：调整配置结构，添加参数校验与跨选项冲突检查，完善文档与测试
3. 健康检查优化：重构配置路径与继承关系
4. OpenTelemetry增强：新增配置绑定支持，扩展可配置项
5. 文档与测试补充：更新各模块README，新增大量单元测试覆盖配置绑定与参数校验

Author: shiliu

Mud.HttpUtils.Client/HttpClient/Observability/HealthChecksServiceCollectionExtensions.cs

@@ -122,21 +122,10 @@ public sealed class MudHttpHealthChecksOptions
 
 /// <summary>
 /// 令牌刷新健康检查配置（含失败状态）。
+/// 继承自 <see cref="TokenRefreshHealthCheckOptions"/>，额外包含 <see cref="FailureStatus"/> 属性。
 /// </summary>
-public sealed class TokenRefreshHealthCheckSettings
+public sealed class TokenRefreshHealthCheckSettings : TokenRefreshHealthCheckOptions
 {
-    /// <summary>统计窗口期（秒），默认 300。</summary>
-    public int WindowSeconds { get; set; } = 300;
-
-    /// <summary>告警阈值（0~1），默认 0.2。</summary>
-    public double DegradedThreshold { get; set; } = 0.2;
-
-    /// <summary>临界阈值（0~1），默认 0.5。</summary>
-    public double CriticalThreshold { get; set; } = 0.5;
-
-    /// <summary>最小样本数，默认 5。</summary>
-    public int MinSampleSize { get; set; } = 5;
-
     /// <summary>失败时返回的健康状态，默认 null（由健康检查内部判定）。</summary>
     public HealthStatus? FailureStatus { get; set; }
 }

Mud.HttpUtils.Client/HttpClient/Observability/TokenRefreshHealthCheckOptions.cs

@@ -8,10 +8,12 @@ namespace Mud.HttpUtils.Observability;
 /// <summary>
 /// 令牌刷新健康检查选项。
 /// </summary>
-public sealed class TokenRefreshHealthCheckOptions
+public class TokenRefreshHealthCheckOptions
 {
-    /// <summary>配置节点路径。</summary>
-    public const string SectionName = "TokenRefreshHealthCheck";
+    /// <summary>
+    /// 配置节点路径。在 <c>appsettings.json</c> 中位于 <c>MudHttpHealthChecks:TokenRefresh</c> 下。
+    /// </summary>
+    public const string SectionName = "MudHttpHealthChecks:TokenRefresh";
 
     /// <summary>
     /// 统计窗口期（秒），默认 300 秒（5 分钟）。

Mud.HttpUtils.Client/README.md

@@ -214,6 +214,72 @@ var httpContent = formContent.ToHttpContent(); // FormUrlEncodedContent
 
 > `DefaultFormContent` 是 `IFormContent` 的默认实现，将字典数据转换为 `FormUrlEncodedContent`。适用于简单的表单提交场景。
 
+### OAuth2 配置
+
+`OAuth2Options` 用于配置 OAuth2 客户端凭证流程的参数，配置节名称为 `MudHttpOAuth2`。
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `ClientId` | `string` | `""` | 客户端 ID |
+| `ClientSecret` | `string` | `""` | 客户端密钥（明文，建议优先使用 `ClientSecretProviderName`） |
+| `ClientSecretProviderName` | `string?` | `null` | 密钥安全提供程序名称，设置后从 `ISecretProvider` 获取密钥 |
+| `TokenEndpoint` | `string` | `""` | 令牌端点 URL |
+| `RevocationEndpoint` | `string` | `""` | 令牌撤销端点 URL |
+| `IntrospectionEndpoint` | `string` | `""` | 令牌内省端点 URL |
+| `RequireHttps` | `bool` | `true` | 是否强制 HTTPS 端点 |
+| `ExpirySafetyMarginSeconds` | `int` | `60` | 令牌过期安全边际（秒），提前刷新以避免使用过期令牌 |
+
+> **安全提示**：当同时设置 `ClientSecret` 和 `ClientSecretProviderName` 时，`ClientSecretProviderName` 优先生效。建议仅设置其中之一以避免混淆。`AddMudHttpOAuth2FromConfiguration` 会在启动时自动检测此冲突并记录警告日志。
+
+```csharp
+// 通过代码配置
+services.Configure<OAuth2Options>(options =>
+{
+    options.ClientId = "my-client";
+    options.ClientSecretProviderName = "vault-provider";
+    options.TokenEndpoint = "https://auth.example.com/token";
+    options.ExpirySafetyMarginSeconds = 90;
+});
+
+// 或通过 IConfiguration 绑定
+services.AddMudHttpOAuth2FromConfiguration(configuration);
+```
+
+对应 `appsettings.json`：
+
+```json
+{
+  "MudHttpOAuth2": {
+    "ClientId": "my-client",
+    "ClientSecretProviderName": "vault-provider",
+    "TokenEndpoint": "https://auth.example.com/token",
+    "RevocationEndpoint": "https://auth.example.com/revoke",
+    "IntrospectionEndpoint": "https://auth.example.com/introspect",
+    "RequireHttps": true,
+    "ExpirySafetyMarginSeconds": 90
+  }
+}
+```
+
+### 用户令牌缓存配置
+
+`UserTokenCacheOptions` 用于配置用户令牌缓存的容量、过期和清理策略，配置节名称为 `MudHttpUserTokenCache`。
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `SizeLimit` | `int` | `10000` | 缓存容量限制（用户数量） |
+| `ExpireThresholdSeconds` | `int` | `300` | 令牌过期提前量（秒），即将过期时触发刷新 |
+| `CleanupIntervalSeconds` | `int` | `300` | 缓存清理间隔（秒） |
+| `SlidingExpirationSeconds` | `int` | `3600` | 滑动过期时间（秒），未访问则自动移除 |
+| `CompactionPercentage` | `double` | `0.2` | 缓存压缩百分比（达容量限制时按此比例淘汰） |
+
+```csharp
+// 通过 IConfiguration 绑定
+services.AddMudHttpUserTokenCacheFromConfiguration(configuration);
+```
+
+> `UserTokenManagerBase` 支持通过 `IOptions<UserTokenCacheOptions>` 从 DI 注入缓存配置。子类构造函数可接收 `IOptions<UserTokenCacheOptions>` 参数，确保通过 `AddMudHttpUserTokenCacheFromConfiguration` 绑定的配置生效。
+
 ### 令牌恢复配置
 
 `TokenRecoveryOptions` 用于控制 401 响应时的自动令牌刷新与重试行为，配置节名称为 `MudHttpTokenRecovery`。

Mud.HttpUtils.Client/ServiceCollectionExtensions.cs

@@ -674,6 +674,9 @@ public static IServiceCollection AddMudHttpOAuth2FromConfiguration(
             throw new ArgumentNullException(nameof(configuration));
 
         services.Configure<OAuth2Options>(configuration.GetSection(sectionPath));
+        // 注册后置配置器，在选项绑定后检查 ClientSecret 与 ClientSecretProviderName 的互斥冲突
+        services.TryAddSingleton<IPostConfigureOptions<OAuth2Options>>(sp =>
+            new OAuth2OptionsPostConfigure(sp.GetService<ILogger<OAuth2OptionsPostConfigure>>()));
         return services;
     }
 
@@ -704,13 +707,13 @@ public static IServiceCollection AddMudHttpTokenRecoveryFromConfiguration(
     /// </summary>
     /// <param name="services">服务集合。</param>
     /// <param name="configuration">配置实例。</param>
-    /// <param name="sectionPath">配置节点路径，默认 <c>"MudHttpUserTokenCache"</c>。</param>
+    /// <param name="sectionPath">配置节点路径，默认 <see cref="UserTokenCacheOptions.SectionName"/>。</param>
     /// <returns>服务集合（链式调用）。</returns>
     /// <exception cref="ArgumentNullException">参数为 null 时抛出。</exception>
     public static IServiceCollection AddMudHttpUserTokenCacheFromConfiguration(
         this IServiceCollection services,
         IConfiguration configuration,
-        string sectionPath = "MudHttpUserTokenCache")
+        string sectionPath = UserTokenCacheOptions.SectionName)
     {
         if (services == null)
             throw new ArgumentNullException(nameof(services));

Mud.HttpUtils.Client/TokenManager/OAuth2OptionsPostConfigure.cs

@@ -0,0 +1,39 @@
+// -----------------------------------------------------------------------
+//  作者：Mud Studio  版权所有 (c) Mud Studio 2026   
+//  Mud.HttpUtils 项目的版权、商标、专利和其他相关权利均受相应法律法规的保护。使用本项目应遵守相关法律法规和许可证的要求。
+//  本项目主要遵循 MIT 许可证进行分发和使用。许可证位于源代码树根目录中的 LICENSE-MIT 文件。
+//  不得利用本项目从事危害国家安全、扰乱社会秩序、侵犯他人合法权益等法律法规禁止的活动！
+// -----------------------------------------------------------------------
+
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+
+namespace Mud.HttpUtils;
+
+/// <summary>
+/// OAuth2 选项的后置配置器，在选项绑定后检查 <see cref="OAuth2Options.ClientSecret"/> 
+/// 与 <see cref="OAuth2Options.ClientSecretProviderName"/> 的互斥冲突并记录警告日志。
+/// </summary>
+internal sealed class OAuth2OptionsPostConfigure : IPostConfigureOptions<OAuth2Options>
+{
+    private readonly ILogger<OAuth2OptionsPostConfigure> _logger;
+
+    public OAuth2OptionsPostConfigure(ILogger<OAuth2OptionsPostConfigure>? logger)
+    {
+        _logger = logger ?? NullLogger<OAuth2OptionsPostConfigure>.Instance;
+    }
+
+    /// <inheritdoc />
+    public void PostConfigure(string? name, OAuth2Options options)
+    {
+        if (options == null)
+            return;
+
+        var warning = options.GetConflictWarning();
+        if (warning != null)
+        {
+            _logger.LogWarning("{Warning}", warning);
+        }
+    }
+}

Mud.HttpUtils.Client/TokenManager/UserTokenCacheOptions.cs

@@ -12,6 +12,11 @@ namespace Mud.HttpUtils;
 /// </summary>
 public class UserTokenCacheOptions
 {
+    /// <summary>
+    /// 配置节的名称。
+    /// </summary>
+    public const string SectionName = "MudHttpUserTokenCache";
+
     /// <summary>
     /// 默认缓存容量限制（用户数量）。
     /// </summary>

Mud.HttpUtils.Client/TokenManager/UserTokenManagerBase.cs

@@ -6,6 +6,7 @@
 // -----------------------------------------------------------------------
 
 using System.Collections.Concurrent;
+using Microsoft.Extensions.Options;
 
 namespace Mud.HttpUtils;
 
@@ -46,6 +47,16 @@ protected UserTokenManagerBase(UserTokenCacheOptions? cacheOptions) : this(null,
     {
     }
 
+    /// <summary>
+    /// 初始化用户令牌管理器基类，从 DI 注入缓存配置选项。
+    /// 使用此构造函数时，<see cref="UserTokenCacheOptions"/> 将从 <see cref="IOptions{TOptions}"/> 获取，
+    /// 确保通过 <c>AddMudHttpUserTokenCacheFromConfiguration</c> 绑定的配置能够生效。
+    /// </summary>
+    /// <param name="cacheOptions">从 DI 注入的缓存配置选项。为 null 时使用默认配置。</param>
+    protected UserTokenManagerBase(IOptions<UserTokenCacheOptions>? cacheOptions) : this(null, cacheOptions?.Value)
+    {
+    }
+
     /// <summary>
     /// 初始化用户令牌管理器基类，使用指定的令牌缓存和缓存配置选项。
     /// </summary>

Mud.HttpUtils.OpenTelemetry/MudHttpOpenTelemetryExtensions.cs

@@ -5,6 +5,7 @@
 //  不得利用本项目从事危害国家安全、扰乱社会秩序、侵犯他人合法权益等法律法规禁止的活动！任何基于本项目开发而产生的一切法律纠纷和责任，我们不承担任何责任！
 // -----------------------------------------------------------------------
 
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using OpenTelemetry;
 using OpenTelemetry.Exporter;
@@ -22,7 +23,7 @@ namespace Mud.HttpUtils.OpenTelemetry;
 /// Mud.HttpUtils OpenTelemetry 适配包的 DI 扩展方法。
 /// </summary>
 /// <remarks>
-/// <para>通过 <see cref="AddMudHttpOpenTelemetry"/> 一键启用 Mud.HttpUtils 的分布式追踪与指标采集，
+/// <para>通过 <see cref="AddMudHttpOpenTelemetry(IServiceCollection, Action{MudHttpOpenTelemetryOptions}?)"/> 一键启用 Mud.HttpUtils 的分布式追踪与指标采集，
 /// 并关联 .NET HttpClient 内置的 <c>System.Net.Http</c> ActivitySource。</para>
 /// <para>默认导出至本地 OTLP gRPC 端点（<c>http://localhost:4317</c>），
 /// 通过 <see cref="MudHttpOpenTelemetryOptions.OtlpEndpoint"/> 自定义。</para>
@@ -31,6 +32,48 @@ namespace Mud.HttpUtils.OpenTelemetry;
 /// </remarks>
 public static class MudHttpOpenTelemetryExtensions
 {
+    /// <summary>
+    /// 一键开启 Mud.HttpUtils 的 OpenTelemetry 追踪与指标采集，从 <see cref="IConfiguration"/> 绑定选项。
+    /// </summary>
+    /// <param name="services">服务集合。</param>
+    /// <param name="configuration">配置实例，用于绑定 <see cref="MudHttpOpenTelemetryOptions"/>。</param>
+    /// <param name="sectionPath">配置节点路径，默认 <c>"MudHttpOpenTelemetry"</c>。</param>
+    /// <param name="configure">可选的附加配置委托，在配置绑定之后执行，可覆盖绑定值。</param>
+    /// <returns>返回 <see cref="OpenTelemetryBuilder"/>，便于调用方继续追加配置。</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="services"/> 或 <paramref name="configuration"/> 为 null。</exception>
+    /// <example>
+    /// appsettings.json：
+    /// <code>
+    /// {
+    ///   "MudHttpOpenTelemetry": {
+    ///     "ServiceName": "my-service",
+    ///     "SamplingRatio": 0.1,
+    ///     "OtlpEndpoint": "http://otel-collector:4317",
+    ///     "EnableLogging": true
+    ///   }
+    /// }
+    /// </code>
+    /// 代码：
+    /// <code>
+    /// builder.Services.AddMudHttpOpenTelemetry(builder.Configuration);
+    /// </code>
+    /// </example>
+    public static OpenTelemetryBuilder AddMudHttpOpenTelemetry(
+        this IServiceCollection services,
+        IConfiguration configuration,
+        string sectionPath = "MudHttpOpenTelemetry",
+        Action<MudHttpOpenTelemetryOptions>? configure = null)
+    {
+        if (services is null) throw new ArgumentNullException(nameof(services));
+        if (configuration is null) throw new ArgumentNullException(nameof(configuration));
+
+        var options = new MudHttpOpenTelemetryOptions();
+        configuration.GetSection(sectionPath).Bind(options);
+        configure?.Invoke(options);
+
+        return AddMudHttpOpenTelemetryCore(services, options);
+    }
+
     /// <summary>
     /// 一键开启 Mud.HttpUtils 的 OpenTelemetry 追踪与指标采集。
     /// </summary>
@@ -62,6 +105,14 @@ public static OpenTelemetryBuilder AddMudHttpOpenTelemetry(
         var options = new MudHttpOpenTelemetryOptions();
         configure?.Invoke(options);
 
+        return AddMudHttpOpenTelemetryCore(services, options);
+    }
+
+    private static OpenTelemetryBuilder AddMudHttpOpenTelemetryCore(
+        IServiceCollection services,
+        MudHttpOpenTelemetryOptions options)
+    {
+
         // 配置 Resource：service.name / service.version / deployment.environment（OTel 规范必需）
         var builder = services.AddOpenTelemetry()
             .ConfigureResource(r => r

Mud.HttpUtils.OpenTelemetry/README.md

@@ -60,13 +60,48 @@ using var provider = services.BuildServiceProvider();
 |------|------|--------|------|
 | `EnableTracing` | `bool` | `true` | 是否启用分布式追踪 |
 | `EnableMetrics` | `bool` | `true` | 是否启用指标采集 |
+| `EnableLogging` | `bool` | `false` | 是否启用 OTLP 日志导出（向后兼容；依赖 .NET 8+ 的 ILogger 集成） |
 | `EnableHttpClientInstrumentation` | `bool` | `true` | 关联 .NET HttpClient 内置 ActivitySource |
 | `EnableAspNetCoreInstrumentation` | `bool` | `true` | 启用 ASP.NET Core 入站请求 Instrumentation（控制台应用无效） |
 | `OtlpEndpoint` | `Uri?` | `http://localhost:4317` | OTLP 导出端点，`null` 表示不配置 OTLP 导出器 |
 | `OtlpExportProtocol` | `OtlpExportProtocol` | `Grpc` | OTLP 导出协议（`Grpc` 或 `HttpProtobuf`） |
 | `UseShortExporterTimeout` | `bool` | `false` | 是否使用 5 秒短超时（开发调试用） |
+| `ServiceName` | `string` | `"Mud.HttpUtils.Application"` | OTel Resource 属性 `service.name` |
+| `ServiceVersion` | `string` | `MudHttpActivitySource.Version` | OTel Resource 属性 `service.version` |
+| `DeploymentEnvironment` | `string` | `"production"` | OTel Resource 属性 `deployment.environment` |
+| `SamplingRatio` | `double` | `1.0` | 采样比率（0.0~1.0），生产环境建议 0.1~0.3 |
+| `ExportBatchSize` | `int?` | `null` | OTLP 批量导出批量大小，`null` 使用 SDK 默认值（512） |
+| `ExportIntervalMilliseconds` | `int?` | `null` | OTLP 批量导出间隔（毫秒），`null` 使用 SDK 默认值（5000ms） |
+| `OtlpHeaders` | `IDictionary<string, string>?` | `null` | 自定义 OTLP Headers（如认证头） |
 | `ConfigureTracing` | `Action<TracerProviderBuilder>?` | `null` | 自定义追踪配置委托，在 Mud 默认配置之后执行 |
 | `ConfigureMetrics` | `Action<MeterProviderBuilder>?` | `null` | 自定义指标配置委托，在 Mud 默认配置之后执行 |
+| `ConfigureLogging` | `Action<LoggerProviderBuilder>?` | `null` | 自定义日志配置委托，在 Mud 默认配置之后执行 |
+
+### 从 IConfiguration 绑定
+
+除代码配置外，还支持从 `appsettings.json` 绑定选项：
+
+```csharp
+builder.Services.AddMudHttpOpenTelemetry(builder.Configuration);
+```
+
+对应 `appsettings.json`：
+
+```json
+{
+  "MudHttpOpenTelemetry": {
+    "ServiceName": "my-service",
+    "SamplingRatio": 0.1,
+    "OtlpEndpoint": "http://otel-collector:4317",
+    "EnableLogging": true,
+    "OtlpHeaders": {
+      "Authorization": "Bearer my-token"
+    }
+  }
+}
+```
+
+> 也可同时使用配置绑定和代码配置：`AddMudHttpOpenTelemetry(builder.Configuration, configure: options => { ... })`，代码配置在配置绑定之后执行，可覆盖绑定值。
 
 ### 高级配置示例