Sage.Http 1.0.0.4

Sage.Http 客户端库

简介

Sage.Http 是一个功能强大的 HTTP 客户端库，封装了 .NET HttpClient，提供了更简洁、更灵活的 API，使 HTTP 请求的发送和处理变得更加简单和高效。该库支持流式 API、多种认证方式和高级弹性功能，帮助开发者构建稳健、高效的网络通信模块。

特性

• 流式 API：链式方法调用，代码更简洁清晰
• 多种认证方式：支持 Bearer Token、Basic Auth、API Key 等认证方式
• 文件上传下载：简化文件上传和下载操作，支持进度报告
• JSON 序列化/反序列化：内置 JSON 处理支持
• 请求重试：自动重试失败的请求，支持指数退避策略
• 熔断器模式：防止系统级联失败
• 超时控制：精确控制请求超时
• 请求进度跟踪：监控上传和下载进度
• 流式数据处理：高效处理大型数据集
• ** 兼容AOT编译** ： 完全兼容AOT编译

安装

dotnet add package Sage.Http

发送请求

基本 GET 请求

// 方式1：使用 HttpRequestManager
var response = await manager.GetAsync("users");
var content = await response.Content.ReadAsStringAsync();

// 方式2：使用流式 API
var response = await manager.CreateRequest(HttpMethod.Get, "users")
    .WithHeader("X-Custom-Header", "value")
    .SendAsync();

// 方式3：直接获取字符串内容
var content = await manager.GetStringAsync("users");

POST 请求

// 发送 JSON 数据
var user = new User { Name = "John", Email = "john@example.com" };
var response = await manager.CreateRequest(HttpMethod.Post, "users")
    .WithJsonContent(user)
    .SendAsync();

// 发送表单数据
var response = await manager.CreateRequest(HttpMethod.Post, "users")
    .WithForm("name", "John")
    .WithForm("email", "john@example.com")
    .SendAsync();

使用选项模式发送请求

// 创建请求选项
var options = new HttpRequestOptions
{
    Method = HttpMethod.Post,
    Uri = "users",
    JsonContent = user,
    Headers = new Dictionary<string, string>
    {
        { "X-Custom-Header", "value" }
    },
    AuthProvider = new BearerTokenAuthProvider("your-token")
};

// 发送请求
var response = await manager.SendAsync(options);

// 或直接获取反序列化的结果
var result = await manager.SendAndGetJsonAsync<UserResponse>(options);

认证

Bearer Token 认证

// 方式1：设置默认认证
manager.SetDefaultAuthentication(new BearerTokenAuthProvider("your-token"));

// 方式2：请求级别认证
var response = await manager.CreateRequest(HttpMethod.Get, "users")
    .WithBearerToken("your-token")
    .SendAsync();

// 方式3：使用扩展方法
var response = await manager.CreateRequest(HttpMethod.Get, "users")
    .WithAuthentication(new BearerTokenAuthProvider("your-token"))
    .SendAsync();

Basic 认证

// 方式1：设置默认认证
manager.SetDefaultAuthentication(new BasicAuthProvider("username", "password"));

// 方式2：请求级别认证
var response = await manager.CreateRequest(HttpMethod.Get, "users")
    .WithBasicAuth("username", "password")
    .SendAsync();

API Key 认证

// 在请求头中添加 API Key
var response = await manager.CreateRequest(HttpMethod.Get, "users")
    .WithAuthentication(new ApiKeyAuthProvider("your-api-key", "X-API-Key"))
    .SendAsync();

// 在查询参数中添加 API Key
var response = await manager.CreateRequest(HttpMethod.Get, "users")
    .WithAuthentication(new ApiKeyAuthProvider("your-api-key", "api_key", ApiKeyLocation.QueryParameter))
    .SendAsync();

自定义认证

// 创建自定义认证提供者
var customAuth = new CustomAuthProvider(request =>
{
    // 实现自定义认证逻辑
    request.Headers.Add("X-Custom-Auth", "custom-value");
    return Task.CompletedTask;
});

// 使用自定义认证
var response = await manager.CreateRequest(HttpMethod.Get, "users")
    .WithAuthentication(customAuth)
    .SendAsync();

### 文件上传

#### 上传单个文件

```csharp
// 从流创建文件参数
using var fileStream = File.OpenRead("file.pdf");
var fileParam = new FileParameter(fileStream, "file.pdf", "file", "application/pdf");

// 发送请求
var response = await manager.CreateRequest(HttpMethod.Post, "upload")
    .WithFile(fileParam)
    .SendAsync();

上传多个文件

// 创建多个文件参数，指定不同的字段名
var files = new List<FileParameter>
{
    new FileParameter(File.OpenRead("file1.pdf"), "file1.pdf", "file1"),
    new FileParameter(File.OpenRead("file2.jpg"), "file2.jpg", "file2", "image/jpeg")
};

// 发送请求
var response = await manager.CreateRequest(HttpMethod.Post, "upload")
    .WithFiles(files)
    .SendAsync();

从文件路径添加文件

// 直接从文件路径添加文件，自动检测 MIME 类型
var response = await manager.CreateRequest(HttpMethod.Post, "upload")
    .AddFileFromPath("file.pdf", "file")
    .SendAsync();

文件下载

使用 DownloadAsync 方法（推荐）

// 下载到文件
var progress = new Progress<float>(p => Console.WriteLine($"下载进度: {p * 100}%"));
long bytesDownloaded = await manager.DownloadAsync(
    HttpMethod.Get,
    "files/document.pdf",
    "downloaded-document.pdf",
    progress);

// 下载到流
using var stream = new MemoryStream();
long bytesDownloaded = await manager.DownloadAsync(
    HttpMethod.Get,
    "files/document.pdf",
    stream,
    progress);

使用 HttpClient 扩展方法

// 下载到文件
var progress = new Progress<float>(p => Console.WriteLine($"下载进度: {p * 100}%"));
long bytesDownloaded = await manager.HttpClient.DownloadFileAsync(
    "files/document.pdf",
    "downloaded-document.pdf",
    progress);

// 下载到流
using var stream = new MemoryStream();
long bytesDownloaded = await manager.HttpClient.DownloadToStreamAsync(
    "files/document.pdf",
    stream,
    progress);

请求进度跟踪

上传进度

// 创建进度报告
var progress = new Progress<float>(p => Console.WriteLine($"上传进度: {p * 100}%"));

// 上传文件并跟踪进度
using var fileStream = File.OpenRead("large-file.zip");
var fileParam = new FileParameter(fileStream, "large-file.zip");

var response = await manager.CreateRequest(HttpMethod.Post, "upload")
    .WithFile(fileParam)
    .WithProgress(progress) // 设置进度报告
    .SendAsync();

下载进度

// 创建进度报告
var progress = new Progress<float>(p => Console.WriteLine($"下载进度: {p * 100}%"));

// 下载文件并跟踪进度
await manager.DownloadAsync(
    HttpMethod.Get,
    "files/large-file.zip",
    "downloaded-large-file.zip",
    progress);

JSON 序列化/反序列化

发送 JSON 请求

// 发送 JSON 请求
var user = new User { Name = "John", Email = "john@example.com" };
var response = await manager.CreateRequest(HttpMethod.Post, "users")
    .WithJsonContent(user)
    .SendAsync();

接收 JSON 响应

// 方式1：使用 SendAsJsonAsync
var user = await manager.CreateRequest(HttpMethod.Get, "users/1")
    .SendAsJsonAsync<User>();

// 方式2：使用扩展方法
var user = await manager.GetFromJsonAsync<User>("users/1");

高级功能

请求重试与熔断高级配置

熔断器模式

熔断器模式可以防止系统在服务不可用时持续发送请求，从而避免级联失败。

// 配置熔断器选项
var circuitBreakerOptions = new CircuitBreakerOptions
{
    Enabled = true,
    FailureThreshold = 5,           // 触发熔断的失败次数阈值
    RecoveryTimeMs = 30000,         // 熔断后的恢复时间（毫秒）
    HalfOpenMaxRequests = 3          // 半开状态下允许的最大请求数
};

// 添加带有熔断器的 HTTP 客户端
services.AddHttpClientWithResilience(
    "resilient-client",
    client => client.BaseAddress = new Uri("https://api.example.com"),
    circuitBreakerOptions: circuitBreakerOptions);

重试机制

重试机制可以自动重试失败的请求，使用指数退避策略避免对服务造成额外负担。

// 配置重试选项
var retryOptions = new RetryOptions
{
    Enabled = true,
    MaxRetryCount = 3,              // 最大重试次数
    InitialDelayMs = 1000,          // 初始延迟（毫秒）
    BackoffMultiplier = 2.0,        // 退避乘数
    MaxDelayMs = 30000,             // 最大延迟（毫秒）
    RetryStatusCodes = [408, 429, 500, 502, 503, 504]  // 需要重试的状态码
};

// 添加带有重试机制的 HTTP 客户端
services.AddHttpClientWithResilience(
    "resilient-client",
    client => client.BaseAddress = new Uri("https://api.example.com"),
    retryOptions: retryOptions);

超时控制

超时控制可以防止请求长时间挂起，确保系统资源得到及时释放。

// 配置默认超时
var defaultTimeout = TimeSpan.FromSeconds(30);

// 添加带有超时控制的 HTTP 客户端
services.AddHttpClientWithResilience(
    "resilient-client",
    client => client.BaseAddress = new Uri("https://api.example.com"),
    defaultTimeout: defaultTimeout);

// 为单个请求设置超时
var request = new HttpRequestMessage(HttpMethod.Get, "slow-endpoint");
request.Options.Set(new HttpRequestOptionsKey<TimeSpan>("RequestTimeout"), TimeSpan.FromSeconds(60));

流式处理

处理大型 JSON 数据集

// 使用 GetStreamingAsync 处理大型 JSON 数据集
await foreach (var item in manager.GetStreamingAsync<DataItem>(HttpMethod.Get, "data/stream"))
{
    // 处理每个数据项，无需等待整个响应加载到内存中
    await ProcessItemAsync(item);
}

使用自定义反序列化器

// 创建自定义反序列化器
var deserializer = (string json) => 
{
    try 
    {
        return JsonSerializer.Deserialize<DataItem>(json);
    }
    catch (JsonException ex)
    {
        Console.WriteLine($"反序列化错误: {ex.Message}");
        return null;
    }
};

// 使用自定义反序列化器处理流式数据
await foreach (var item in manager.GetStreamingAsync(HttpMethod.Get, "data/stream", deserializer))
{
    if (item != null)
    {
        await ProcessItemAsync(item);
    }
}

API 参考

HttpRequestManager 核心方法

• HttpClient - 获取底层的 HttpClient 实例
• DefaultAuthenticationProvider - 获取或设置默认的认证提供者
• CreateRequest(HttpMethod, string) - 创建 HTTP 请求构建器
• CreateRequestWithOptions(HttpRequestOptions) - 使用选项创建请求构建器
• CreateJsonRequest<T>(HttpMethod, string, T) - 创建 JSON 请求构建器
• SendAsync(HttpRequestOptions) - 使用选项发送请求
• GetAsync(string) - 发送 GET 请求
• PostAsync(string, HttpContent) - 发送 POST 请求
• PutAsync(string, HttpContent) - 发送 PUT 请求
• DeleteAsync(string) - 发送 DELETE 请求
• GetStringAsync(string) - 发送 GET 请求并返回字符串
• GetStreamAsync(string) - 发送 GET 请求并返回流
• GetStreamingAsync<T>(HttpMethod, string) - 发送请求并返回流式数据
• DownloadAsync(HttpMethod, string, string) - 下载文件到指定路径
• DownloadAsync(HttpMethod, string, Stream) - 下载文件到指定流

HttpRequestBuilder 核心方法

• WithHeader(string, string) - 添加请求头
• WithHeaders(IDictionary<string, string>) - 添加多个请求头
• WithContentType(string) - 设置内容类型
• WithUserAgent(string) - 设置用户代理
• AcceptJson() - 设置接受 JSON 响应
• AcceptXml() - 设置接受 XML 响应
• WithQuery(string, string) - 添加查询参数
• WithQueries(IDictionary<string, string>) - 添加多个查询参数
• WithBody(string, string) - 添加请求体
• WithJsonContent<T>(T) - 添加 JSON 请求体
• WithXmlContent<T>(T) - 添加 XML 请求体
• WithTextContent(string) - 添加文本请求体
• WithForm(string, string) - 添加表单字段
• WithForms(IDictionary<string, string>) - 添加多个表单字段
• WithFile(FileParameter) - 添加文件
• WithFiles(IEnumerable<FileParameter>) - 添加多个文件
• WithAuthentication(IAuthenticationProvider) - 设置认证提供者
• WithBearerToken(string) - 设置 Bearer Token 认证
• WithBasicAuth(string, string) - 设置 Basic 认证
• WithCancellationToken(CancellationToken) - 设置取消令牌
• WithProgress(IProgress<float>) - 设置上传进度报告
• SendAsync() - 发送请求
• SendAsJsonAsync<T>() - 发送请求并返回 JSON 响应
• SendAsStreamAsync<T>() - 发送请求并返回流式数据
• DownloadToStreamAsync(Stream, IProgress<float>) - 下载到流

最佳实践

1. 使用工厂和依赖注入：优先使用 IHttpRequestManagerFactory 和依赖注入创建 HttpRequestManager 实例。

2. 设置默认认证：如果所有请求都使用相同的认证方式，设置默认认证提供者。

3. 使用流式 API：利用链式调用使代码更简洁清晰。

4. 处理大型数据集：使用 GetStreamingAsync 处理大型 JSON 数据集，避免内存压力。

5. 配置重试和熔断：对于不稳定的外部服务，配置适当的重试策略和熔断器。

6. 监控上传下载进度：对于大文件传输，使用进度报告功能提供更好的用户体验。

7. 正确释放资源：使用 using 语句或 await using 语句确保资源正确释放。

8. 处理异常：捕获并适当处理 HttpRequestException、TaskCanceledException 和 TimeoutException。

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。

贡献

欢迎提交问题报告和改进建议。如果您想贡献代码，请提交拉取请求。

作者

• LiuPengLai - 甲壳虫科技 欢迎提交问题和功能请求。 QQ Group: 1054304346