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 自动跳过响应体审计)