Package Description
License
—
Deps
12
Install Size
—
Vulns
✓ 0
Published
Mar 3, 2026
$ dotnet add package Common.HttpClients一个功能丰富的HTTP客户端库，基于 Microsoft.Extensions.Http.Resilience 和 Polly，提供强大的弹性和韧性功能。
dotnet add package Common.HttpClients
// 使用默认配置
services.AddHttpClientService();
// 或自定义配置
services.AddHttpClientService(options =>
{
options.AuditLog = true; // 启用审计日志
options.FailThrowException = false; // 失败时不抛出异常，返回 null
options.Timeout = 30; // 自定义超时时间（秒），范围：1-3600
options.MaxRetryAttempts = 3; // 最大重试次数，范围：0-10
options.RetryDelaySeconds = 1; // 重试基础延迟（秒），范围：1-300
options.ConcurrencyLimit = 100; // 并发限制，范围：1-10000
options.MaxOutputResponseLength = 1024 * 1024; // 日志最大输出长度 1MB
options.IgnoreUntrustedCertificate = false; // ⚠️ 生产环境建议设为 false
options.RetryOnUnauthorized = true; // 401未授权错误时自动重试
options.AdditionalSensitiveHeaders = new[] { "X-Secret" }; // 额外脱敏请求头
options.AdditionalSensitiveFields = new[] { "mobile" }; // 额外脱敏字段
});
// ⚠️ 无效配置将抛出异常
// services.AddHttpClientService(options =>
// {
// options.Timeout = 5000; // ❌ ArgumentOutOfRangeException: Timeout必须在1-3600秒之间
// });
public class MyService
{
private readonly IHttpHelper _httpHelper;
public MyService(IHttpHelper httpHelper)
{
_httpHelper = httpHelper;
}
public async Task<string> GetDataAsync()
{
var result = await _httpHelper.GetAsync<string>(Host + "/get?q1=11&q2=22");
return result;
}
}
| 属性 |
|---|
| 类型 |
|---|
| 默认值 |
|---|
| 说明 |
|---|
AuditLog | bool | true | 是否启用审计日志 |
FailThrowException | bool | false | 失败时是否抛出异常。false 时返回 null，true 时抛出异常 |
EnableLogRedaction | bool | true | 是否启用日志脱敏 |
Timeout | int | 100 | 超时时间（秒），范围：1-3600 |
ConcurrencyLimit | int | 100 | 并发限制，范围：1-10000，建议按下游容量调整 |
MaxRetryAttempts | int | 3 | 最大重试次数，范围：0-10 |
RetryDelaySeconds | int | 1 | 重试基础延迟（秒），指数退避，范围：1-300 |
MaxOutputResponseLength | int | 0 | 日志最大输出响应长度（字节），≥0。0 表示不限制 |
IgnoreUntrustedCertificate | bool | false | 是否忽略不安全的SSL证书，⚠️ 仅建议开发/测试环境使用 |
RetryOnUnauthorized | bool | false | 401未授权错误时是否重试 |
AdditionalSensitiveHeaders | ICollection<string> | 空 | 额外需要脱敏的请求头（不区分大小写） |
AdditionalSensitiveFields | ICollection<string> | 空 | 额外需要脱敏的字段名（JSON/key=value，不区分大小写） |
配置验证：所有参数都有范围限制，超出范围将抛出
ArgumentOutOfRangeException。
下面示例已经注入IHttpHelper
var result = await _httpHelper.GetAsync<string>(Host + "/get?q1=11&q2=22");还支持传递token以及传递请求头
支持传递字符串以及对象
var content = "{\"q\":\"123456\",\"a\":\"222\"}";
var result = await _httpHelper.PostAsync<string>(Host + "/post", content);using var form = new MultipartFormDataContent();
// bytes为文件字节数组
using var fileContent = new ByteArrayContent(bytes);
fileContent.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
{
Name = "file", // 表单字段名称
FileName = fileName // 文件名
};
fileContent.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
form.Add(fileContent);
// 其他参数
using var content = new StringContent("其他参数值");
form.Add(content, "其他参数名称");
var requestUrl = $"{_difyApiBase}/v1/files/upload";
var response = await _httpHelper.PostFormDataAsync<FileUploadResponse>(requestUrl, form,
new Dictionary<string, string> { { "Authorization", $"Bearer {_difyApiKey}" } });可以设置配置AuditLog来设置是否启用审计日志，默认为启用状态。
builder.Services.AddHttpClientService();也可以为指定地址请求设置关闭审计日志，例如
var result = await _httpHelper.PostAsync<string>(Host + "/anything", list,
headers: new Dictionary<string, string>() { { "X-Logger", "skip" } });
var result2 = await _httpHelper.PostAsync<string>(Host + "/anything", list,
headers: new Dictionary<string, string>() { { "X-Skip-Logger", "" } });可以通过在请求头设置X-Skip-Logger或者设置X-Logger值为none、skip进行跳过日志
password、token、access_token、refresh_token、api_key 等常见字段Authorization、Cookie、X-Api-Key 等AdditionalSensitiveFields、AdditionalSensitiveHeaders 扩展脱敏范围key=value 文本，不保证覆盖所有嵌套/编码场景（例如复杂嵌套 JSON、base64 token）
GetStreamAsync会自动跳过响应体审计，避免流式读取场景下日志提前消费响应流。
本库使用 Polly 实现了完整的弹性策略链，按以下顺序执行（从外层到内层）：
当所有策略都失败时的最后保障：
FailThrowException = false：返回 503 响应，方法返回 null
X-Fallback-Response: true 头，可区分真实服务端错误FailThrowException = true：重新抛出原始异常限制同时进行的HTTP请求数量，默认 ConcurrencyLimit = 100，可按业务压测结果调整
自动重试失败的请求：
MaxRetryAttempts（默认 3）RetryDelaySeconds（默认 1 秒）作为基础值，使用指数退避RetryOnUnauthorized = true）TimeoutException、TaskCanceledException、TimeoutRejectedException）HttpRequestException）当错误率达到阈值时暂时停止请求，保护下游系统
防止请求长时间阻塞：
Timeout 值（默认 100 秒）重要说明：超时策略放在最内层，每次重试都会应用超时限制。总超时上界约为：
Timeout × (MaxRetryAttempts + 1) + 重试延迟总和。
本库自动支持分布式追踪，通过 X-Trace-Id 请求头传播追踪ID：
X-Trace-Id 请求头获取HttpContext.Request.Headers 中获取 X-Trace-IdHttpContext.TraceIdentifier所有日志都包含 TraceId，方便追踪整个请求链路：
Http请求开始.TraceId：a1b2c3d4e5f6 Url：https://api.example.com/data Method：GET
Http请求审计日志.TraceId：a1b2c3d4e5f6 Url：https://api.example.com/data Method：GET StatusCode：OK 耗时：1234.56ms
Timeout 值options.Timeout = 30;
options.MaxRetryAttempts = 2;
options.RetryDelaySeconds = 1;// 不设置 Timeout，使用默认值 100 秒options.RetryOnUnauthorized = true;options.FailThrowException = false;null 或 default(T)X-Fallback-Response: true 头，可据此判断是否为 Fallback 响应options.FailThrowException = true;// 使用原始 SendAsync 获取完整响应
using var request = new HttpRequestMessage(HttpMethod.Get, url);
var response = await _httpHelper.SendAsync(request);
if (response.StatusCode == HttpStatusCode.ServiceUnavailable)
{
var isFallback = response.Headers.Contains("X-Fallback-Response");
if (isFallback)
{
// 这是 Fallback 产生的响应，说明所有重试都失败了
_logger.LogWarning("All retries failed for {Url}", url);
}
else
{
// 这是真实的服务端 503 错误
_logger.LogWarning("Service unavailable at {Url}", url);
}
}⚠️ 生产环境安全警告：
// ❌ 不要在生产环境使用
options.IgnoreUntrustedCertificate = true;IgnoreUntrustedCertificate 选项会完全禁用SSL证书验证，这会使您的应用容易受到中间人攻击（MITM）。
建议做法：
#if DEBUG
options.IgnoreUntrustedCertificate = true;
#else
options.IgnoreUntrustedCertificate = false;
#endif
默认情况下，库会自动脱敏常见的敏感字段和请求头。但如果您的 API 使用自定义字段名（如 userSecret、apiKey 等），请务必配置：
options.AdditionalSensitiveFields = new[] { "userSecret", "customToken" };
options.AdditionalSensitiveHeaders = new[] { "X-Custom-Auth" };IHttpHelper 全部方法中的 int? timeout 参数，避免与 Resilience Timeout 策略冲突AddHttpClientService(options => options.Timeout = xx) 全局配置控制CancellationTokenConcurrencyLimit：并发限制数量（默认 100）MaxRetryAttempts：最大重试次数（默认 3）RetryDelaySeconds：重试基础延迟（默认 1 秒）AdditionalSensitiveHeaders：额外脱敏请求头AdditionalSensitiveFields：额外脱敏字段X-Fallback-Response 标识头JsonHelper 性能（使用静态配置）ResponseStream.DisposeAsync 释放顺序GetStreamAsync 自动跳过响应体审计）