Mud.HttpUtils.Abstractions 2.0.0-preview3

Mud.HttpUtils.Abstractions

概述

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

零外部 NuGet 依赖，仅引用 .NET BCL（System.* 命名空间），最大化兼容性和最小化依赖传递。

目标框架

• netstandard2.0

包含内容

HTTP 客户端接口

IEnhancedHttpClient 是 IBaseHttpClient、IJsonHttpClient、IXmlHttpClient、IEncryptableHttpClient 的组合接口，提供完整的 HTTP 客户端能力。新增 WithBaseAddress 方法支持运行时动态切换基地址，BaseAddress 属性获取当前基地址。IFormContent 用于 multipart/form-data 场景，支持通过 IProgress<long> 报告上传进度。

HTTP 拦截器与缓存接口

IHttpResponseCache 是缓存抽象，默认实现为 MemoryHttpResponseCache（基于 IMemoryCache）。可替换为 Redis 等分布式缓存实现。

加密接口

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

安全认证接口

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

日志脱敏接口

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

令牌管理接口

TokenManagerBase 使用 SemaphoreSlim 实现并发安全的令牌刷新，避免多线程同时触发刷新。UserTokenManagerBase 为每个用户维护独立的锁和缓存，并支持过期清理。ITokenRefreshBackgroundService 支持后台定时刷新令牌，避免请求时令牌过期导致的延迟。

令牌管理配置模型

TokenRefreshBackgroundOptions 控制后台刷新服务的行为，UserTokenCacheOptions 控制用户令牌缓存容量和清理策略。

应用上下文接口

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

数据模型与枚举

TokenInjectionMode 新增 ApiKey 和 HmacSignature 两种认证模式。ApiKey 模式通过 IApiKeyProvider 获取密钥注入到请求头；HmacSignature 模式通过 IHmacSignatureProvider 计算请求签名后注入到请求头。

安装

<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 或 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) — 独立接口
IFormContent (ToHttpContent, ToHttpContentAsync) — 表单内容，支持上传进度

IHttpRequestInterceptor (OnRequestAsync) — 请求拦截器
IHttpResponseInterceptor (OnResponseAsync) — 响应拦截器
IHttpResponseCache (TryGet, Set, Remove) — 响应缓存契约

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 (并发安全刷新基类)
│   └── UserTokenManagerBase (用户级并发安全刷新基类)

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)
TokenTypes (常量: TenantAccessToken, UserAccessToken, Bearer, Basic)
Response<T> (StatusCode, Content, RawContent, ErrorContent, ResponseHeaders, IsSuccessStatusCode, GetContentOrThrow)
ApiException (StatusCode, ErrorContent)
AesEncryptionOptions (Key, IV, Validate)
TokenRefreshBackgroundOptions (Enabled, RefreshIntervalSeconds, InitialDelaySeconds, MaxRetryAttempts)
UserTokenCacheOptions (MaxCacheSize, CleanupIntervalSeconds, RefreshAheadSeconds)

设计原则

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