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 客户端接口

接口	说明	核心方法
`IBaseHttpClient`	基础 HTTP 操作	`SendAsync<TResult>`, `SendRawAsync`, `SendStreamAsync`, `DownloadAsync`, `DownloadLargeAsync`
`IJsonHttpClient`	JSON 操作	`GetAsync<TResult>`, `PostAsJsonAsync<TResult>`, `PutAsJsonAsync<TResult>`, `DeleteAsJsonAsync<TResult>`, `DeleteAsJsonAsync<TRequest, TResult>`, `PatchAsJsonAsync<TResult>`
`IXmlHttpClient`	XML 操作	`SendXmlAsync<TResult>`, `PostAsXmlAsync<TResult>`, `PutAsXmlAsync<TResult>`, `GetXmlAsync<TResult>`
`IEncryptableHttpClient`	加密操作	`EncryptContent`, `DecryptContent`
`IEnhancedHttpClient`	增强组合接口	继承 `IBaseHttpClient`、`IJsonHttpClient`、`IXmlHttpClient`、`IEncryptableHttpClient`，支持 `WithBaseAddress` 动态切换基地址
`IHttpClientResolver`	命名客户端解析	`GetClient`, `TryGetClient`
`IEnhancedHttpClientFactory`	增强客户端工厂	`CreateClient`, `RemoveClient`
`IFormContent`	表单内容接口	`ToHttpContent`, `ToHttpContentAsync`（支持上传进度报告）

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

HTTP 内容序列化器接口

类型	说明
`IHttpContentSerializer`	HTTP 内容序列化器抽象，统一封装请求体序列化、响应反序列化、NDJSON 流式解析、加密内容序列化等全部 JSON 操作，不再直接调用 `JsonSerializer`
`IQueryParameter`	AOT 兼容查询参数接口，配合 `QueryParameterBuilder` 在编译期构建 URL 查询字符串，避免运行时反射
`QueryParameterBuilder`	查询参数构建器，提供流式 API 构建 URL 查询字符串

IHttpContentSerializer 是 Mud.HttpUtils 序列化的统一入口。所有 JSON 序列化/反序列化（请求体、响应、加密内容、NDJSON 逐行解析等）均通过此抽象进行，默认实现 SystemTextJsonContentSerializer（位于 Mud.HttpUtils.Client）行为等价于直接调用 JsonSerializer，保证向后兼容。消费方可注入自定义实现以切换序列化引擎（如 Newtonsoft.Json / XML）。IHttpContentSerializer 是 Native AOT 友好的关键设计：AOT 路径下由源生成器在编译期提供字段名映射，绕过 GetFieldNameForProperty 的反射读取。

HTTP 拦截器与缓存接口

接口	说明
`IHttpRequestInterceptor`	请求拦截器，在请求发送前执行自定义逻辑
`IHttpResponseInterceptor`	响应拦截器，在响应接收后执行自定义逻辑
`ICacheResponseInterceptor`	缓存响应拦截器，配合 `CacheAttribute` 实现响应缓存
`IHttpResponseCache`	响应缓存契约，提供 `TryGet`、`Set`、`Remove` 方法
`IResiliencePolicyResolver`	弹性策略解析器，支持自定义策略实现
`IAppResiliencePolicyResolver`	按应用（App）解析弹性策略的工厂接口（`ResolveResolver(string)`）

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

HTTP 请求执行器接口

接口	说明
`IHttpRequestExecutor`	HTTP 请求执行器，统一处理响应反序列化、错误处理和执行模式编排。由源生成器生成的代码调用。
`ExecutionDescriptor`	执行描述符，封装请求执行所需的元数据（拦截器、缓存、Token 恢复等）
`ResponseDescriptor`	响应描述符，封装响应处理方式（反序列化类型、错误处理、允许任意状态码等）

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

可观测性接口与静态源

类型	说明
`MudHttpActivitySource`	分布式追踪源（ActivitySource），W3C TraceContext 兼容，无监听器时零开销
`MudHttpMeter`	指标源（Meter），提供 HTTP 请求计数、耗时、缓存命中、令牌刷新等指标
`MudHttpDiagnosticListener`	诊断监听器，将 HTTP 事件转发到 `DiagnosticListener`
`MudHttpDiagnosticNames`	诊断事件名称常量
`TokenRefreshStatsCollector`	令牌刷新统计收集器，记录刷新次数和耗时
`CircuitBreakerStateObserver`	熔断器状态观察器（`SetState`/`RemoveState`/`CurrentStates`），配合熔断可观测性
`CircuitBreakerState`	熔断器状态枚举（`Closed` / `HalfOpen` / `Open`）
诊断负载类型（`*DiagnosticPayload`）	`Mud.HttpUtils.Observability` 命名空间下：`CircuitBreakerDiagnosticPayload`、`TokenRefreshDiagnosticPayload`、`CacheDiagnosticPayload`、`DownloadDiagnosticPayload`、`DownloadErrorDiagnosticPayload`

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

加密接口

类型	说明
`IEncryptionProvider`	加密提供程序接口，定义 `Encrypt` 和 `Decrypt` 方法
`AesEncryptionOptions`	AES 加密配置选项，包含 `Key` 属性、`RequireCrossRuntimePortable` 属性和 `Validate()` 验证方法（`IV` 已移除（CFG-27），v1.8.0 起自动随机生成）

AesEncryptionOptions 支持通过配置文件绑定（配置节名称：MudHttpAesEncryption），密钥长度支持 AES-128（16 字节）、AES-192（24 字节）、AES-256（32 字节）。
DefaultAesEncryptionProvider 始终使用认证加密，密文首字节为信封版本前缀，解密仅按该前缀分派（与配置无关）：
版本布局产出条件可在哪些目标框架解密
0x02 [0x02][nonce(12)][tag(16)][密文]（AesGcm） net8.0/net10.0 且 AesGcm.IsSupported 且 RequireCrossRuntimePortable=false（默认）仅 net8.0+
0x03 [0x03][IV(16)][MAC(32)][密文]（CBC + HMAC-SHA256，Encrypt-then-MAC）其余运行时；或 RequireCrossRuntimePortable=true 全部（ns2.0/net6/net8/net10）
版本字节 0x00（保留哨兵）与 0x01（v1 裸 CBC，路径已移除）永不复用；0x04~0xFF 预留给未来扩展。若密文需跨进程传输到低版本目标框架的服务，请在加密侧设置 RequireCrossRuntimePortable = true。
通过 AddMudHttpAesEncryptionFromConfiguration 扩展方法（位于 Mud.HttpUtils.Client 包）从 IConfiguration 一键注册：
csharp
builder.Services.AddMudHttpAesEncryptionFromConfiguration(builder.Configuration);
1
appsettings.json 示例：
json
{
  "MudHttpAesEncryption": {
    "Key": "base64-encoded-16/24/32-byte-key"
  }
}
1
2
3
4
5
注意：Key 必须为 Base64 编码的 16/24/32 字节密钥。注册时会在首次解析 IEncryptionProvider 时校验密钥长度。

版本	布局	产出条件	可在哪些目标框架解密
`0x02`	`[0x02][nonce(12)][tag(16)][密文]`（AesGcm）	net8.0/net10.0 且 `AesGcm.IsSupported` 且 `RequireCrossRuntimePortable=false`（默认）	仅 net8.0+
`0x03`	`[0x03][IV(16)][MAC(32)][密文]`（CBC + HMAC-SHA256，Encrypt-then-MAC）	其余运行时；或 `RequireCrossRuntimePortable=true`	全部（ns2.0/net6/net8/net10）

安全认证接口

接口	说明
`IApiKeyProvider`	API Key 提供器，通过 `GetApiKeyAsync` 获取 API 密钥
`IHmacSignatureProvider`	HMAC 签名提供器，提供 `GenerateSignatureAsync` 和 `VerifySignatureAsync` 方法
`ISecretProvider`	安全密钥提供器，通过 `GetSecretAsync` 从安全存储获取敏感配置

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

日志脱敏接口

类型	说明
`ISensitiveDataMasker`	敏感数据脱敏器，提供 `Mask` 和 `MaskObject` 方法
`SensitiveDataMaskMode`	脱敏模式枚举（`Hide` — 完全隐藏、`Mask` — 部分遮盖、`TypeOnly` — 仅显示类型）

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

令牌管理接口

接口 / 类	说明
`ITokenManager`	通用令牌管理，提供 `GetTokenAsync`、`GetOrRefreshTokenAsync` 方法，继承 `IDisposable`（推荐 DI 生命周期：Singleton）
`IUserTokenManager`	用户令牌管理，继承 `ITokenManager`，提供用户级令牌获取与刷新（推荐 DI 生命周期：Singleton）
`ICurrentUserId`	当前用户标识，提供 `GetCurrentUserIdAsync` 方法
`ICurrentUserContext`	当前用户上下文，提供 `UserId` 属性，用于线程安全的用户 ID 传播（推荐替代 `ICurrentUserId`）
`ITokenProvider`	Token 提供器，统一封装 Token 查找、获取、刷新逻辑，根据 `TokenRequest` 获取令牌
`ITokenStore`	令牌持久化存储契约，支持分布式缓存或数据库持久化，提供 `GetTokenTypesAsync`、`ClearAsync` 批量操作
`IUserTokenStore`	用户级令牌持久化存储契约，继承 `ITokenStore`，按用户标识隔离
`IEncryptedTokenStore`	加密令牌持久化存储契约，继承 `ITokenStore`，提供自动加密/解密能力
`ITokenRefreshBackgroundService`	令牌后台刷新服务契约，提供 `StartAsync`、`StopAsync` 和 `RefreshAllAsync` 方法
`ITokenManagerRegistry`	令牌管理器注册表契约（SR-M6）：按 `TokenRecoveryContext.TokenManagerKey` 解析管理器实例，供 401 恢复执行器按键路由；未知键返回 null（由调用方回退）
`TokenManagerBase`	令牌管理器抽象基类，提供并发安全的令牌刷新实现，支持绝对过期保护（`MaxCacheLifetimeSeconds`）。TMX-04：刷新失败后 5s 负缓存窗口（`protected virtual int NegativeCacheSeconds => 5`，覆写为 0 可关闭）。TMX-07：`GetTokenAsync(scopes)` 默认走 scope 感知路径，不支持 scope 的派生类应覆写并抛 `NotSupportedException`
`OAuth2TokenManagerBase`	OAuth2 标准流程抽象基类，继承 `TokenManagerBase`，内置 Authorization Code / Client Credentials / ROPC / Refresh Token 流程
`TokenTypes`	令牌类型常量类，提供标准化的令牌类型标识符
`ITokenCache<T>`	令牌缓存契约（TryGet、Set、TryRemove、Count、Keys、Clear、Compact），`TokenManagerBase` 的核心依赖
`ConcurrentDictionaryTokenCache<T>`	`ITokenCache<T>` 默认实现，基于 `ConcurrentDictionary`
`TokenResult`	只读令牌结果结构（AccessToken、ExpireTime、Scope、IsExpiringSoon 等）
`CurrentUserInfo`	当前用户基本信息基类（`UserId`），`UserTokenInfo` 继承自此类型

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

令牌管理配置模型

类型	说明
`TokenRequest`	Token 请求参数，封装获取令牌所需的全部信息（`TokenManagerKey`、`UserId`、`Scopes`）
`TokenRefreshBackgroundOptions`	令牌后台刷新配置（`Enabled`、`RefreshIntervalSeconds`、`RetryDelaySeconds`、`StopOnError`、`MaxConsecutiveFailures`）
`TokenRecoveryOptions`	令牌恢复配置（`Enabled`、`RecoveryMaxRetries`、`TokenScheme`、`RefreshTimeoutSeconds`、`MaxCachedRequestBodyBytes`、`RefreshDedupWindowSeconds`），控制 401 响应时的自动刷新与重试
`TokenRecoveryContext`	令牌恢复上下文，携带注入模式信息供 `TokenRecoveryDelegatingHandler` 使用（`UserId` 必须来自受信上下文，恢复执行器校验与 `ICurrentUserContext` 的一致性；`TokenManagerKey` 经 `ITokenManagerRegistry` 路由）
`TokenInjectionMode`	令牌注入模式枚举（`Header`、`Query`、`Path`、`ApiKey`、`HmacSignature`、`BasicAuth`、`Cookie`）
`UserTokenInfo`	用户令牌信息模型
`CredentialToken`	凭证令牌模型
`TokenIntrospectionResult`	令牌内省结果模型
`TokenRefreshFailedEventArgs`	令牌刷新失败事件参数

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

应用上下文接口

接口	说明
`IMudAppContext`	应用上下文，封装 `IEnhancedHttpClient`、Token 管理器和 `GetService<T>` 服务解析
`IAppContextSwitcher`	多应用切换，提供 `CurrentContext` 属性和 `SwitchToAsync` 方法
`IAppContextHolder`	应用上下文持有器，提供 `Current` 属性（只读 + `SwitchTo` 方法运行时切换）和 `BeginScope(IMudAppContext)` 方法（如 `AsyncLocalAppContextSwitcher`）
`IAsyncInitializable`	异步初始化接口，`RegisterAppAsync` 等场景用于延迟初始化应用上下文
`IAppManager<T>`	多应用管理器，提供按 AppKey 获取上下文、注册/移除应用、配置变更通知、默认应用切换的能力
`IAppAccessAuthorizer`	应用切换授权器，多租户场景下判定当前调用主体是否有权切换到指定应用

IMudAppContext 新增 GetService<T>() 方法，支持从应用上下文中解析已注册的 DI 服务（如 IApiKeyProvider、IHmacSignatureProvider 等）。IAppManager<T> 新增 ConfigurationChanged 事件，支持应用配置热更新通知。
注册约定：IAppManager<IMudAppContext> 不由库自动注册（宿主需显式注册 DefaultAppManager<IMudAppContext> 或自定义实现）。IAppContextHolder 由 AddMudHttpAppContextHolder() 或配置入口 AddMudHttpClientsFromConfiguration 自动补齐。
IAppAccessAuthorizer 为必注册项（MT-02 / BC-18）：生成代码的 UseApp(appKey) / BeginScope(appKey) / UseAppScope(appKey) 在未注册授权器时直接抛 InvalidOperationException（默认拒绝，取代此前的静默放行——后者允许调用方凭请求参数中的 appKey 切换到任意租户应用并读取其令牌）。多租户宿主请注册业务授权器；单应用 / 完全受信 / 迁移过渡场景请显式注册 AllowAllAppAccessAuthorizer 以表明放行意图。可用 AddMudHttpAppManagementStartupValidation() 把该检查前移到启动期（MudHttpAppManagementOptions.RequireAppAccessAuthorizer = true 时缺失即阻断启动）。
上下文归还约束（MT-19）：UseApp(appKey) / SwitchTo(...) 是无作用域切换，不会自动归还上下文。长生命周期宿主（后台服务、单例编排、IAsyncEnumerable 未逐段开作用域等）应优先使用 UseAppScope(appKey) / BeginScope(appKey) / UseDefaultAppScope() 并配合 using，否则后续请求可能串到错误的应用并读取到该应用的令牌。
IAppContextHolder.BeginScope 归属约束：返回的 IDisposable 必须在其创建的异步流程内释放。跨执行上下文释放（例如在别的 Task.Run 中释放）不会被识别为本作用域的还原点，以免覆盖其它流程的合法上下文写入。
IAppContextHolder.Current 写入约束：Current 属性的 setter 为 init，仅允许在对象初始化阶段设置。运行时切换应用上下文请使用 SwitchTo 方法或 BeginScope 方法。

数据模型与枚举

类型	说明
`SerializeType`	序列化类型枚举（`Json` / `Xml`）
`TokenInjectionMode`	Token 注入模式枚举（`Header` / `Query` / `Path` / `ApiKey` / `HmacSignature` / `BasicAuth` / `Cookie`）
`IQueryParameter`	AOT 兼容查询参数接口
`QueryParameterBuilder`	查询参数构建器，提供流式 API 构建 URL 查询字符串
`Response<T>`	HTTP 响应包装类型，同时提供响应内容和元数据（StatusCode、ResponseHeaders、ErrorContent）
`ApiException`	API 异常类，封装 HTTP 错误状态码和错误内容

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

安装

xml

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

使用场景

1. 仅需接口定义

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

csharp

public class OrderService
{
    private readonly IEnhancedHttpClient _httpClient;

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

2. 自定义 HTTP 客户端实现

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

csharp

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

3. 自定义加密提供程序

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

csharp

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

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

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

csharp

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）：

csharp

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 签名认证时：

csharp

// 自定义 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. 自定义响应缓存

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

csharp

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 按名称获取客户端：

csharp

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) — 表单内容，支持上传进度

IHttpContentSerializer (ToHttpContent / FromHttpContentAsync / Serialize / Deserialize / GetFieldNameForProperty)
IQueryParameter / QueryParameterBuilder — AOT 兼容查询参数构建

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

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

MudHttpActivitySource — 分布式追踪源（ActivitySource）
MudHttpMeter — 指标源（Meter）
MudHttpDiagnosticListener — 诊断监听器
TokenRefreshStatsCollector — 令牌刷新统计收集器
CircuitBreakerStateObserver / CircuitBreakerState — 熔断器状态可观测性

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。锁非重入（TMX-15-4/B12）：RefreshUserTokenAsync 中禁止回调 GetOrRefreshTokenAsync/GetTokenAsync，否则死锁]
└── ITokenManagerRegistry — 401 恢复按键路由

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

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

ITokenRefreshBackgroundService (StartAsync, StopAsync, RefreshAllAsync)

IMudAppContext (HttpClient, GetTokenManager, GetService<T>)
├── IAppContextSwitcher (CurrentContext, SwitchToAsync)
├── IAppContextHolder (Current, BeginScope)
└── IAppManager<T> (GetWebApi, GetDefaultWebApi, RegisterApp, RemoveApp, ConfigurationChanged)
IAppAccessAuthorizer — 应用切换授权器（多租户必注册）

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, RequireCrossRuntimePortable, Validate) — IV 已移除（CFG-27），v1.8.0 起自动随机生成；始终认证加密
TokenRefreshBackgroundOptions (Enabled, RefreshIntervalSeconds, RetryDelaySeconds, StopOnError)
[UserTokenCacheOptions — 位于 Mud.HttpUtils.Client]

Native AOT 支持

Mud.HttpUtils 全面支持 .NET Native AOT 编译，核心设计目标是编译期确定 JSON 元数据、运行期零反射兜底：

序列化抽象 IHttpContentSerializer：所有 JSON 操作经统一抽象进行，AOT 路径下由源生成器在编译期提供字段名映射，避免运行时反射。
AOT 兼容查询参数：IQueryParameter / QueryParameterBuilder 在编译期构建 URL 查询字符串。
JSON 源生成上下文：消费方通过 [HttpJsonSerializable]（见 Mud.HttpUtils.Attributes）标注实体/DTO，并用 JsonContextScaffolder 脚手架（Mud.HttpUtils.JsonContextScaffolder 工具）自动生成 JsonSerializerContext，或手动注册到 JsonSerializerContext 后通过 AddMudHttpClientJsonContext（.NET 8+）接入合并。
编译期诊断：源生成器会发出 AOT001–AOT007 系列诊断（部分可由 Mud.HttpUtils.CodeFixes 代码修复器一键修复），在 CI 严格模式（-p:AotStrictMode=true）下升级为 Error，强制消费方构建必须接入 Context，避免 AOT 下漏元数据导致运行时失败。

详细工作流与脚手架用法参见 JsonContext 脚手架与源代码生成器的「AOT JSON 序列化诊断」章节。

设计原则

最小外部依赖：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 签名、Basic 与 Cookie 认证模式，通过 TokenInjectionMode 枚举统一管理

Mud.HttpUtils.Abstractions ​

概述 ​

目标框架 ​

包含内容 ​

HTTP 客户端接口 ​

HTTP 内容序列化器接口 ​

HTTP 拦截器与缓存接口 ​

HTTP 请求执行器接口 ​

可观测性接口与静态源 ​

加密接口 ​

安全认证接口 ​

日志脱敏接口 ​

令牌管理接口 ​

令牌管理配置模型 ​

应用上下文接口 ​

数据模型与枚举 ​

安装 ​

使用场景 ​

1. 仅需接口定义 ​

2. 自定义 HTTP 客户端实现 ​

3. 自定义加密提供程序 ​

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

5. 继承令牌管理器基类 ​

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

7. 自定义响应缓存 ​

8. 多命名客户端解析 ​

9. 构建其他扩展包 ​

接口继承关系 ​

Native AOT 支持 ​

设计原则 ​

Mud.HttpUtils.Abstractions

概述

目标框架

包含内容

HTTP 客户端接口

HTTP 内容序列化器接口

HTTP 拦截器与缓存接口

HTTP 请求执行器接口

可观测性接口与静态源

加密接口

安全认证接口

日志脱敏接口

令牌管理接口

令牌管理配置模型

应用上下文接口

数据模型与枚举

安装

使用场景

1. 仅需接口定义

2. 自定义 HTTP 客户端实现

3. 自定义加密提供程序

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

5. 继承令牌管理器基类

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

7. 自定义响应缓存

8. 多命名客户端解析

9. 构建其他扩展包

接口继承关系

Native AOT 支持

设计原则