Mud.HttpUtils.Abstractions 2.0.1

Mud.HttpUtils.Abstractions

概述

Mud.HttpUtils.Abstractions 是 Mud.HttpUtils 的抽象接口层，提供 HTTP 客户端、加密、令牌管理、应用上下文、安全认证、日志脱敏、缓存等纯接口定义与基础抽象类。

最小外部 NuGet 依赖 — netstandard2.0 目标仅依赖 Microsoft.Bcl.AsyncInterfaces（提供 IAsyncEnumerable 等异步支持），net6.0+ 目标零外部依赖。

目标框架

• netstandard2.0（兼容 .NET Framework、.NET Core、Xamarin、Unity 等）
• net6.0
• net8.0
• net10.0

包含内容

HTTP 客户端接口

IEnhancedHttpClient 是 IBaseHttpClient、IJsonHttpClient、IXmlHttpClient、IEncryptableHttpClient 的组合接口，提供完整的 HTTP 客户端能力。新增 WithBaseAddress 方法支持运行时动态切换基地址，BaseAddress 属性获取当前基地址。IFormContent 用于 multipart/form-data 场景，支持通过 IProgress<long> 报告上传进度。IEnhancedHttpClientFactory 用于按名称创建或获取缓存的 IEnhancedHttpClient 实例，在 .NET 8+ 上通过 Keyed Service 解析。

HTTP 拦截器与缓存接口

IHttpResponseCache 是缓存抽象，默认实现为 MemoryHttpResponseCache（基于 IMemoryCache）。可替换为 Redis 等分布式缓存实现。ICacheResponseInterceptor 继承 IHttpResponseInterceptor，在响应阶段检查缓存并存储响应。IResiliencePolicyResolver 用于解析弹性策略，默认实现为 PollyResiliencePolicyProvider（位于 Mud.HttpUtils.Resilience 包）。

HTTP 请求执行器接口

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

可观测性接口与静态源

可观测性静态源（含上述类型）位于 Mud.HttpUtils.Observability 命名空间（非根命名空间），放在 Abstractions 项目中以便 TokenManagerBase、EnhancedHttpClient、PollyResiliencePolicyProvider 共用。配合 Mud.HttpUtils.OpenTelemetry 包可一键开启 Tracing + Metrics 导出。

加密接口

AesEncryptionOptions 支持通过配置文件绑定（配置节名称：MudHttpAesEncryption），密钥长度支持 AES-128（16 字节）、AES-192（24 字节）、AES-256（32 字节）。

通过 AddMudHttpAesEncryptionFromConfiguration 扩展方法（位于 Mud.HttpUtils.Client 包）从 IConfiguration 一键注册：

builder.Services.AddMudHttpAesEncryptionFromConfiguration(builder.Configuration);

appsettings.json 示例：

{
  "MudHttpAesEncryption": {
    "Key": "base64-encoded-16/24/32-byte-key"
  }
}

注意：Key 必须为 Base64 编码的 16/24/32 字节密钥。注册时会在首次解析 IEncryptionProvider 时校验密钥长度。

安全认证接口

IApiKeyProvider 用于 API Key 认证模式（TokenInjectionMode.ApiKey），默认实现从 IConfiguration 读取密钥。IHmacSignatureProvider 用于 HMAC 签名认证模式（TokenInjectionMode.HmacSignature），默认实现使用 HMAC-SHA256 算法。ISecretProvider 用于从安全存储（如 Vault）获取敏感配置。

日志脱敏接口

ISensitiveDataMasker 配合 SensitiveDataAttribute 使用，自动识别和脱敏标记了 [SensitiveData] 的属性。

令牌管理接口

ITokenProvider 是 Token 获取逻辑的统一抽象层，将 Token 的查找、获取、刷新逻辑从代码生成的类中剥离到运行时服务。默认实现为 DefaultTokenProvider，通过 IMudAppContext 获取令牌管理器。ICurrentUserContext 用于在生成的 API 实现类中获取当前用户 ID，替代原有的 CurrentUserId 公共属性，解决并发场景下的线程安全问题。TokenManagerBase 使用 SemaphoreSlim 实现并发安全的令牌刷新，避免多线程同时触发刷新。UserTokenManagerBase（位于 Mud.HttpUtils.Client 包）为每个用户维护独立的锁和缓存，并支持过期清理。ITokenRefreshBackgroundService 支持后台定时刷新令牌，避免请求时令牌过期导致的延迟。

令牌管理配置模型

TokenRefreshBackgroundOptions 控制后台刷新服务的行为，UserTokenCacheOptions（位于 Mud.HttpUtils.Client 包）控制用户令牌缓存容量和清理策略。TokenRecoveryContext 由生成代码自动附加到 HTTP 请求属性中，TokenRecoveryDelegatingHandler（位于 Mud.HttpUtils.Client 包）在 401 恢复时读取此上下文以确定令牌注入方式。

应用上下文接口

IMudAppContext 新增 GetService<T>() 方法，支持从应用上下文中解析已注册的 DI 服务（如 IApiKeyProvider、IHmacSignatureProvider 等）。IAppManager<T> 新增 ConfigurationChanged 事件，支持应用配置热更新通知。

数据模型与枚举

TokenInjectionMode 新增 ApiKey、HmacSignature、BasicAuth 和 Cookie 四种认证模式。ApiKey 模式通过 IApiKeyProvider 获取密钥注入到请求头；HmacSignature 模式通过 IHmacSignatureProvider 计算请求签名后注入到请求头；BasicAuth 模式将凭据编码为 Base64 注入到 Authorization 头；Cookie 模式将令牌注入到请求 Cookie 中。

安装

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

使用场景

1. 仅需接口定义

当你只需要接口进行编程（例如定义库的合同、编写 Mock 测试），不需要引入重型依赖时：

public class OrderService
{
    private readonly IEnhancedHttpClient _httpClient;

    public OrderService(IEnhancedHttpClient httpClient)
    {
        _httpClient = httpClient;
    }
}

2. 自定义 HTTP 客户端实现

当你需要实现自己的 HTTP 客户端，而不使用 Mud.HttpUtils.Client 提供的默认实现时：

public class CustomHttpClient : IEnhancedHttpClient
{
    // 实现 IBaseHttpClient, IJsonHttpClient, IXmlHttpClient, IEncryptableHttpClient
    // 实现 WithBaseAddress 和 BaseAddress
}

3. 自定义加密提供程序

当你需要实现自定义加密逻辑（如使用非 AES 算法或接入 KMS）时：

public class KmsEncryptionProvider : IEncryptionProvider
{
    public string Encrypt(string plainText) { /* 调用 KMS 加密 */ }
    public string Decrypt(string cipherText) { /* 调用 KMS 解密 */ }
}

4. 自定义令牌持久化存储

当你需要将令牌持久化到分布式缓存或数据库时：

public class RedisTokenStore : ITokenStore
{
    public Task<string?> GetAccessTokenAsync(string tokenType, CancellationToken ct = default) { /* 从 Redis 读取 */ }
    public Task SetAccessTokenAsync(string tokenType, string accessToken, long expiresInSeconds, CancellationToken ct = default) { /* 写入 Redis */ }
}

public class DatabaseUserTokenStore : IUserTokenStore
{
    // 按用户标识隔离的令牌存储实现
}

5. 继承令牌管理器基类

当你需要实现自定义令牌管理器时，可继承 TokenManagerBase，获得并发安全的刷新能力（如需用户级缓存管理，可继承位于 Mud.HttpUtils.Client 包的 UserTokenManagerBase）：

public class MyTokenManager : TokenManagerBase
{
    protected override async Task<CredentialToken> RefreshTokenCoreAsync(CancellationToken ct)
    {
        var response = await CallTokenEndpointAsync(ct);
        return new CredentialToken
        {
            AccessToken = response.AccessToken,
            Expire = response.ExpireTime
        };
    }

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

6. 自定义安全认证提供器

当你需要实现 API Key 或 HMAC 签名认证时：

// 自定义 API Key 提供器
public class VaultApiKeyProvider : IApiKeyProvider
{
    public async Task<string> GetApiKeyAsync(string? keyName = null, CancellationToken ct = default)
    {
        // 从 Vault 或其他密钥管理系统获取 API Key
    }
}

// 自定义 HMAC 签名提供器
public class CustomHmacProvider : IHmacSignatureProvider
{
    public async Task<string> GenerateSignatureAsync(HttpRequestMessage request, string secretKey, CancellationToken ct = default)
    {
        // 自定义签名算法（如 HMAC-SHA512）
    }

    public async Task<bool> VerifySignatureAsync(HttpRequestMessage request, string signature, string secretKey, CancellationToken ct = default)
    {
        var expected = await GenerateSignatureAsync(request, secretKey, ct);
        return string.Equals(signature, expected, StringComparison.Ordinal);
    }
}

7. 自定义响应缓存

当你需要将缓存替换为分布式实现时：

public class RedisHttpResponseCache : IHttpResponseCache
{
    public bool TryGet<T>(string key, out T? value) { /* 从 Redis 读取 */ }
    public void Set<T>(string key, T value, TimeSpan expiration) { /* 写入 Redis */ }
    public void Remove(string key) { /* 从 Redis 删除 */ }
}

8. 多命名客户端解析

在多 API 客户端场景下，通过 IHttpClientResolver 按名称获取客户端：

public class MultiApiService
{
    private readonly IHttpClientResolver _resolver;

    public MultiApiService(IHttpClientResolver resolver)
    {
        _resolver = resolver;
    }

    public async Task CallApiAsync(string apiName)
    {
        if (_resolver.TryGetClient(apiName, out var client))
        {
            await client.GetAsync<User>("/users/1");
        }
    }
}

9. 构建其他扩展包

当你需要基于这些接口构建扩展包（如 Mud.HttpUtils.Resilience），需要将接口作为公共 API 的一部分时。

接口继承关系

IBaseHttpClient (SendAsync, SendRawAsync, SendStreamAsync, DownloadAsync, DownloadLargeAsync)
├── IJsonHttpClient (GetAsync, PostAsJsonAsync, PutAsJsonAsync, DeleteAsJsonAsync, PatchAsJsonAsync)
├── IXmlHttpClient (SendXmlAsync, PostAsXmlAsync, PutAsXmlAsync, GetXmlAsync)
└── IEnhancedHttpClient (继承 IBaseHttpClient, IJsonHttpClient, IXmlHttpClient, IEncryptableHttpClient)
    ├── WithBaseAddress(string/Uri) — 动态切换基地址
    └── BaseAddress — 获取当前基地址

IEncryptableHttpClient (EncryptContent, DecryptContent) — IEnhancedHttpClient 已继承
IHttpClientResolver (GetClient, TryGetClient) — 独立接口
IEnhancedHttpClientFactory (CreateClient, RemoveClient) — 增强客户端工厂
IFormContent (ToHttpContent, ToHttpContentAsync) — 表单内容，支持上传进度

IHttpRequestExecutor (SendAndDeserializeAsync) — HTTP 请求执行器
ExecutionDescriptor — 执行描述符（拦截器、缓存、Token 恢复）
ResponseDescriptor — 响应描述符（反序列化类型、错误处理）

IHttpRequestInterceptor (OnRequestAsync) — 请求拦截器
IHttpResponseInterceptor (OnResponseAsync) — 响应拦截器
ICacheResponseInterceptor — 缓存响应拦截器
IHttpResponseCache (TryGet, Set, Remove) — 响应缓存契约
IResiliencePolicyResolver — 弹性策略解析器接口

MudHttpActivitySource — 分布式追踪源（ActivitySource）
MudHttpMeter — 指标源（Meter）
MudHttpDiagnosticListener — 诊断监听器
TokenRefreshStatsCollector — 令牌刷新统计收集器

IEncryptionProvider (Encrypt, Decrypt) — 加密提供器
IApiKeyProvider (GetApiKeyAsync) — API Key 提供器
IHmacSignatureProvider (GenerateSignatureAsync, VerifySignatureAsync) — HMAC 签名提供器
ISecretProvider (GetSecretAsync) — 安全密钥提供器

ISensitiveDataMasker (Mask, MaskObject) — 敏感数据脱敏器
SensitiveDataMaskMode (Hide, Mask, TypeOnly) — 脱敏模式

ITokenManager (GetTokenAsync, GetOrRefreshTokenAsync)
├── IUserTokenManager (GetTokenAsync(userId), GetOrRefreshTokenAsync(userId), ...)
├── TokenManagerBase (并发安全刷新基类)
│   └── OAuth2TokenManagerBase (OAuth2 标准流程基类)
│   └── [UserTokenManagerBase — 用户级并发安全刷新基类，位于 Mud.HttpUtils.Client]

ICurrentUserContext (UserId) — 当前用户上下文（推荐，线程安全）
ITokenProvider (GetTokenAsync) — Token 提供器（统一封装 Token 获取逻辑）
TokenRequest (TokenManagerKey, UserId, Scopes) — Token 请求参数

ITokenStore (GetAccessTokenAsync, SetAccessTokenAsync, ...)
└── IUserTokenStore (按用户标识隔离的令牌存储)

ITokenRefreshBackgroundService (StartAsync, StopAsync, RefreshAllAsync)

IMudAppContext (HttpClient, GetTokenManager, GetService<T>)
├── IAppContextSwitcher (CurrentContext, SwitchToAsync)
└── IAppManager<T> (GetWebApi, GetDefaultWebApi, RegisterApp, RemoveApp, ConfigurationChanged)

TokenInjectionMode (Header, Query, Path, ApiKey, HmacSignature, BasicAuth, Cookie)
TokenTypes (常量: TenantAccessToken, UserAccessToken, Bearer, Basic)
Response<T> (StatusCode, Content, RawContent, ErrorContent, ResponseHeaders, IsSuccessStatusCode, GetContentOrThrow)
ApiException (StatusCode, ErrorContent)
AesEncryptionOptions (Key, Validate) — IV 已废弃，v1.8.0 起自动随机生成
TokenRefreshBackgroundOptions (Enabled, RefreshIntervalSeconds, RetryDelaySeconds, StopOnError)
[UserTokenCacheOptions — 位于 Mud.HttpUtils.Client]

设计原则

• 最小外部依赖：netstandard2.0 目标仅依赖 Microsoft.Bcl.AsyncInterfaces（提供 IAsyncEnumerable 等异步支持），net6.0+ 目标零外部依赖
• 最大化兼容性：支持 netstandard2.0、net6.0、net8.0、net10.0，可在 .NET Framework、.NET Core、.NET 5+、Xamarin、Unity 等环境中使用
• 接口稳定性：接口定义变化频率低，适合作为稳定的依赖基础
• 组合优于继承：IEnhancedHttpClient 采用组合标记接口设计，实现者可按需实现部分接口
• 并发安全：TokenManagerBase 提供内置的并发令牌刷新控制（UserTokenManagerBase 位于 Mud.HttpUtils.Client 包）
• 可扩展性：通过 IEncryptionProvider、ITokenStore、IHttpClientResolver、IEnhancedHttpClientFactory、IApiKeyProvider、IHmacSignatureProvider、ISensitiveDataMasker、IHttpResponseCache、IResiliencePolicyResolver 等接口支持自定义实现
• 安全认证：内置 API Key 和 HMAC 签名认证模式，通过 TokenInjectionMode 枚举统一管理