Mud.HttpUtils.Client 2.0.0

Mud.HttpUtils.Client

概述

Mud.HttpUtils.Client 是 Mud.HttpUtils 的客户端实现层，提供 IEnhancedHttpClient 的默认实现、加密提供程序、令牌管理器基类、应用上下文、安全认证、日志脱敏、缓存等核心功能。

目标框架

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

包含内容

HTTP 客户端实现

基地址动态切换

EnhancedHttpClient 和 HttpClientFactoryEnhancedClient 均实现了 WithBaseAddress 方法，支持运行时动态切换基地址：

var userClient = httpClient.WithBaseAddress("https://user-api.example.com");
var orderClient = httpClient.WithBaseAddress("https://order-api.example.com");

// 获取当前基地址
var baseAddress = httpClient.BaseAddress;

WithBaseAddress 创建新的客户端实例，不影响原客户端。新客户端继承原客户端的超时设置和默认请求头。

文件上传进度报告

var content = new ProgressableStreamContent(
    fileContent,
    new Progress<long>(bytesRead => Console.WriteLine($"已上传: {bytesRead} 字节")),
    bufferSize: 8192
);

ProgressableStreamContent 在序列化流时通过 IProgress<long> 报告已发送字节数，适用于大文件上传进度监控。

请求/响应拦截器

拦截器按 Order 属性排序执行，Order 值小的先执行。

响应缓存

// 注册缓存拦截器
services.AddSingleton<IHttpResponseCache, MemoryHttpResponseCache>();
services.AddSingleton<IHttpResponseInterceptor, CacheResponseInterceptor>();

CacheResponseInterceptor 的 Order 为 100，确保在其他拦截器之后执行。MemoryHttpResponseCache 使用 IMemoryCache 作为底层存储，支持绝对过期和滑动过期。

注意：不建议将 Response<T> 返回类型与 [Cache] 特性组合使用。缓存会存储整个 Response<T> 对象（包括 StatusCode 和 ResponseHeaders），可能导致后续请求返回过期的状态码和响应头。源代码生成器会对此组合发出 HTTPCLIENT011 编译警告。

加密提供程序

services.AddMudHttpClient("myApi", encryption =>
{
    encryption.Key = Convert.FromBase64String("your-base64-key");
    // 注意：从 v1.8.0 起 IV 自动随机生成，无需手动设置
}, client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
});

密钥长度支持 AES-128（16 字节）、AES-192（24 字节）、AES-256（32 字节）。AesEncryptionOptions.Validate() 方法在启动时验证密钥的有效性。从 v1.8.0 起，IV 在每次加密时自动随机生成，无需手动设置。

安全认证提供程序

// API Key 认证
services.AddSingleton<IApiKeyProvider, DefaultApiKeyProvider>();

// HMAC 签名认证
services.AddSingleton<IHmacSignatureProvider, DefaultHmacSignatureProvider>();

DefaultApiKeyProvider 从 IConfiguration 的 ApiKey 或 ApiKeys:Default 键读取密钥。DefaultHmacSignatureProvider 使用 HMAC-SHA256 算法对请求内容计算签名，签名结果以 Base64 编码。

日志脱敏

services.AddSingleton<ISensitiveDataMasker, DefaultSensitiveDataMasker>();

// 使用
var masker = serviceProvider.GetRequiredService<ISensitiveDataMasker>();
var masked = masker.Mask("13800138000", SensitiveDataMaskMode.Mask, 3, 4);
// 结果: "138****8000"

var maskedObj = masker.MaskObject(userRequest);
// 自动识别 [SensitiveData] 标记的属性并脱敏

令牌管理

// 自定义令牌管理器
public class MyTokenManager : TokenManagerBase
{
    protected override async Task<CredentialToken> RefreshTokenCoreAsync(CancellationToken ct)
    {
        var response = await FetchTokenAsync(ct);
        return new CredentialToken
        {
            AccessToken = response.AccessToken,
            Expire = response.ExpireTime
        };
    }

    public override Task<string> GetTokenAsync(CancellationToken ct = default)
        => GetOrRefreshTokenAsync(ct);
}

// 注册后台刷新服务（推荐方式）
// AddTokenRefreshBackgroundService 内部自动注册为 IHostedService 和 ITokenRefreshBackgroundService，
// 确保两者解析到同一单例实例，消费方可直接注入 ITokenRefreshBackgroundService。
services.AddTokenRefreshBackgroundService(options =>
{
    options.Enabled = true;
    options.RefreshIntervalSeconds = 3500;
    options.RetryDelaySeconds = 60;
    options.StopOnError = false;
});

TokenManagerBase 使用 SemaphoreSlim(1, 1) 确保同一时刻只有一个线程执行令牌刷新。UserTokenManagerBase 使用 IMemoryCache 管理用户令牌缓存，支持 SizeLimit 限制和自动过期清理。TokenRefreshHostedService 支持配置 RefreshIntervalSeconds（刷新间隔）、RetryDelaySeconds（重试延迟）和 StopOnError（出错时是否停止）。非用户令牌的过期提前量由 TokenManagerBase.ExpireThresholdSeconds 控制（默认 300 秒，引用 TokenManagerBase.DefaultExpireThresholdSeconds 常量）；用户令牌的过期提前量由 UserTokenCacheOptions.ExpireThresholdSeconds 控制（默认同样为 300 秒，引用同一常量），可通过 AddMudHttpUserTokenCacheFromConfiguration 绑定。

DefaultTokenProvider 是 ITokenProvider 的默认实现，通过 IMudAppContext 获取令牌管理器并获取令牌。它不持有 IMudAppContext 引用，而是通过方法参数逐调用接收，以确保生成代码中 UseApp()/UseDefaultApp() 上下文切换的正确性。当 TokenRequest.UserId 非空时，自动使用 IUserTokenManager 获取用户级令牌。

DefaultCurrentUserContext 使用 AsyncLocal 确保用户 ID 在异步上下文中正确传播。适用于非 Web 场景或需要手动设置用户 ID 的场景。在 ASP.NET Core 应用中，建议替换为基于 HttpContext 的实现。每个实例拥有独立的 AsyncLocal 存储，支持多实例并行使用。通过 SetUser(TUser? user) 实例方法设置当前用户对象（TUser 须继承 CurrentUserInfo 且具有无参构造函数），也可通过 SetUserId(string? userId) 方法直接设置用户 ID，UserId 属性从用户对象中自动提取。

内存令牌存储

// 基础内存存储
services.AddSingleton<ITokenStore, MemoryTokenStore>();

// 用户级内存存储
services.AddSingleton<IUserTokenStore, MemoryUserTokenStore>();

// 加密内存存储（需先注册 IEncryptionProvider）
services.AddSingleton<IEncryptionProvider, DefaultAesEncryptionProvider>(/* 配置密钥 */);
services.AddSingleton<IEncryptedTokenStore, MemoryEncryptedTokenStore>();

MemoryTokenStore 基于 ConcurrentDictionary 实现线程安全的令牌管理，支持过期自动清理。MemoryUserTokenStore 为每个用户维护独立的存储空间。MemoryEncryptedTokenStore 在存储前自动加密令牌数据，读取时自动解密，适用于对安全性要求较高的场景。

默认表单内容

var formData = new Dictionary<string, string>
{
    ["username"] = "admin",
    ["password"] = "secret"
};
var formContent = new DefaultFormContent(formData);
var httpContent = formContent.ToHttpContent(); // FormUrlEncodedContent

DefaultFormContent 是 IFormContent 的默认实现，将字典数据转换为 FormUrlEncodedContent。适用于简单的表单提交场景。

OAuth2 配置

OAuth2Options 用于配置 OAuth2 客户端凭证流程的参数，配置节名称为 MudHttpOAuth2。

安全提示：当同时设置 ClientSecret 和 ClientSecretProviderName 时，ClientSecretProviderName 优先生效。建议仅设置其中之一以避免混淆。AddMudHttpOAuth2FromConfiguration 会在启动时自动检测此冲突并记录警告日志。

// 通过代码配置
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：

{
  "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。

// 通过 IConfiguration 绑定
services.AddMudHttpUserTokenCacheFromConfiguration(configuration);

UserTokenManagerBase 支持通过 IOptions<UserTokenCacheOptions> 从 DI 注入缓存配置。子类构造函数可接收 IOptions<UserTokenCacheOptions> 参数，确保通过 AddMudHttpUserTokenCacheFromConfiguration 绑定的配置生效。

令牌恢复配置

TokenRecoveryOptions 用于控制 401 响应时的自动令牌刷新与重试行为，配置节名称为 MudHttpTokenRecovery。

// 通过代码配置
services.Configure<TokenRecoveryOptions>(options =>
{
    options.Enabled = true;
    options.RecoveryMaxRetries = 2;
    options.TokenScheme = "Bearer";
});

// 或通过 IConfiguration 绑定
services.AddMudHttpTokenRecoveryFromConfiguration(configuration);

{
  "MudHttpTokenRecovery": {
    "Enabled": true,
    "RecoveryMaxRetries": 2,
    "TokenScheme": "Bearer"
  }
}

令牌后台刷新配置

TokenRefreshBackgroundOptions 用于配置令牌主动刷新后台服务，配置节名称为 TokenRefreshBackground。

// 通过代码配置
services.AddTokenRefreshBackgroundService(options =>
{
    options.Enabled = true;
    options.RefreshIntervalSeconds = 3500;
    options.RetryDelaySeconds = 60;
    options.StopOnError = false;
});

RefreshIntervalSeconds 和 RetryDelaySeconds 设置为 0 或负数时将抛出 ArgumentOutOfRangeException。

应用上下文

// 多应用管理
services.AddSingleton<IAppManager<FeishuContext>, DefaultAppManager<FeishuContext>>();

// 监听配置变更
var appManager = serviceProvider.GetRequiredService<IAppManager<FeishuContext>>();
appManager.ConfigurationChanged += (sender, args) =>
{
    Console.WriteLine($"应用 {args.AppId} 配置已变更");
};

DefaultAppManager<T> 新增 ConfigurationChanged 事件，支持应用配置热更新通知。IMudAppContext 新增 GetService<T>() 方法，支持从应用上下文中解析 DI 服务。

工具类

HTTP 请求执行器

DefaultHttpRequestExecutor 是生成的 API 实现类与运行时之间的桥梁，负责发送 HTTP 请求、处理响应反序列化、错误状态码异常抛出、拦截器调用等逻辑。

健康检查

// 注册健康检查
services.AddMudHttpHealthChecks();

// 或从 IConfiguration 绑定
services.AddMudHttpHealthChecks(Configuration);

AddMudHttpHealthChecks() 扩展方法注册熔断器和令牌刷新健康检查，可配合 ASP.NET Core Health Checks 中间件使用。

令牌刷新健康检查选项

TokenRefreshHealthCheckOptions 用于配置令牌刷新健康检查的窗口期和阈值，在 appsettings.json 中位于 MudHttpHealthChecks:TokenRefresh 下。

熔断器健康检查选项

CircuitBreakerHealthCheckSettings 用于配置熔断器健康检查，在 appsettings.json 中位于 MudHttpHealthChecks:CircuitBreaker 下。

对应 appsettings.json：

{
  "MudHttpHealthChecks": {
    "TokenRefresh": {
      "WindowSeconds": 300,
      "DegradedThreshold": 0.2,
      "CriticalThreshold": 0.5,
      "MinSampleSize": 5,
      "FailureStatus": "Degraded"
    },
    "CircuitBreaker": {
      "MaxOpenCount": 0,
      "MaxHalfOpenCount": 0,
      "FailureStatus": "Unhealthy"
    }
  }
}

可观测性

TracingDelegatingHandler 作为 DelegatingHandler 注入到 HttpClient 管道中，自动创建分布式追踪 Activity 并记录请求方法、URL、状态码、耗时等信息。配合 Mud.HttpUtils.OpenTelemetry 包可一键导出到 OTLP 收集器。

URL 安全验证

UrlValidator 提供 SSRF（服务端请求伪造）防护，支持以下安全策略：

• 域名白名单：仅允许访问白名单内的域名（含子域名匹配）
• HTTPS 强制：仅允许 HTTPS 协议和标准端口（443）
• 私有 IP 检测：阻止访问 10.x、172.16.x、192.168.x、127.x 等私有地址
• 内网域名检测：阻止访问 .local、.internal、.lan 等内网域名

配置方式一：通过配置文件（推荐）

{
  "MudHttpClients": {
    "AllowedDomains": [ "api.example.com", "cdn.example.com" ],
    "Clients": {
      "Default": {
        "BaseAddress": "https://api.example.com",
        "AllowCustomBaseUrls": false
      },
      "ExternalApi": {
        "BaseAddress": "https://external.api.com",
        "AllowCustomBaseUrls": true
      }
    }
  }
}

AllowCustomBaseUrls 默认为 false，仅允许访问白名单域名。设为 true 时放宽域名限制但仍阻止私有 IP 和内网域名。

配置方式二：通过代码

// 配置白名单
UrlValidator.ConfigureAllowedDomains(["api.example.com", "cdn.example.com"]);

// 运行时增删域名
UrlValidator.AddAllowedDomain("new-api.example.com");
UrlValidator.RemoveAllowedDomain("old-api.example.com");

安装

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

DI 服务注册

AddMudHttpClient — 注册客户端

AddMudHttpClient 同时注册 IHttpClientResolver 为单例服务，支持多命名客户端场景。

AddMudHttpClientsFromConfiguration — 从配置文件注册

从 IConfiguration 自动绑定多个 HTTP 客户端配置，支持全局域名白名单和自定义 URL 策略：

{
  "MudHttpClients": {
    "AllowedDomains": [ "api.example.com", "cdn.example.com" ],
    "DefaultClientName": "Default",
    "Clients": {
      "Default": {
        "BaseAddress": "https://api.example.com",
        "TimeoutSeconds": 30
      },
      "ExternalApi": {
        "BaseAddress": "https://external.api.com",
        "AllowCustomBaseUrls": true
      }
    }
  }
}

services.AddMudHttpClientsFromConfiguration(Configuration);

注册安全认证服务

// API Key 认证
services.AddSingleton<IApiKeyProvider, DefaultApiKeyProvider>();

// HMAC 签名认证
services.AddSingleton<IHmacSignatureProvider, DefaultHmacSignatureProvider>();

注册缓存服务

services.AddMemoryCache();
services.AddSingleton<IHttpResponseCache, MemoryHttpResponseCache>();
services.AddSingleton<IHttpResponseInterceptor, CacheResponseInterceptor>();

注册日志脱敏服务

services.AddSingleton<ISensitiveDataMasker, DefaultSensitiveDataMasker>();

依赖项

设计原则

• 默认实现可替换：所有核心接口均提供默认实现，但可通过 DI 替换为自定义实现
• 线程安全：TokenManagerBase、UserTokenManagerBase、HttpClientResolver 均实现并发安全
• 资源管理：EnhancedHttpClient 实现 IDisposable，正确释放 HttpClient 资源
• 可观测性：所有关键操作均通过 ILogger 记录日志，支持结构化日志
• 性能优先：使用 SemaphoreSlim 替代 lock、使用 IMemoryCache 替代 ConcurrentDictionary、支持大文件上传进度报告