Galosys.Foundation.HttpClient 26.9.23.1

Galosys.Foundation.HttpClient

成熟度: 🟢 稳定 — 生产可用，测试充分，活跃维护

简介

Galosys.Foundation.HttpClient 是基于 Microsoft.Extensions.Http 和 Polly 的 HTTP 客户端模块，提供声明式 REST 客户端、请求头传播、服务发现集成、委托处理器等能力，简化微服务间的 HTTP 调用。

功能特性

• 声明式 REST 客户端 - 通过接口定义 HTTP 调用
• 请求头传播 - 自动传递 Authorization、租户等请求头
• 服务发现集成 - 支持服务名称解析
• 委托处理器 - 可扩展的请求/响应管道
• 作用域感知 - 支持 DI 作用域的 HttpClient 工厂

安装

<PackageReference Include="Galosys.Foundation.HttpClient" Version="x.x.x" />

使用

注册服务

// Program.cs 或 Module 中
services.AddRestClient();

定义 REST 客户端接口

using System.Net.Http;
using System.Threading.Tasks;

[RestClient("https://api.example.com")]
public interface IUserService
{
    [GetMapping("/api/users/{id}")]
    Task<UserDto> GetUserAsync(int id);

    [PostMapping("/api/users")]
    Task CreateUserAsync(CreateUserRequest request);

    [GetMapping("/api/users")]
    Task<List<UserDto>> ListUsersAsync(int page = 1, int size = 10);
}

注入使用

public class UserController : ControllerBase
{
    private readonly IUserService _userService;

    public UserController(IUserService userService)
    {
        _userService = userService;
    }

    [HttpGet("{id}")]
    public async Task<UserDto> GetUser(int id)
    {
        return await _userService.GetUserAsync(id);
    }
}

自定义委托处理器

通过 AddHttpClient 注册自定义 DelegatingHandler：

services.AddHttpClient("MyClient")
    .AddHttpMessageHandler<AuthTokenHandler>();

public class AuthTokenHandler : DelegatingHandler
{
    private readonly ITokenProvider _tokenProvider;

    public AuthTokenHandler(ITokenProvider tokenProvider)
    {
        _tokenProvider = tokenProvider;
    }

    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var token = await _tokenProvider.GetTokenAsync();
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        return await base.SendAsync(request, cancellationToken);
    }
}

作用域感知 HttpClient

services.AddHttpClient("MyClient")
    .AddScopeAwareHttpHandler<ScopedDelegatingHandler>();

出向 HTTP 诊断

AddScopeAwareHttpHandler 自动注册 Microsoft.Extensions.Http.Diagnostics 的可观测性管道：

• AddRedaction()（先于 LatencyTelemetry 注册，幂等）
• AddHttpClientLatencyTelemetry() — 产出分阶段延迟分解（DNS/连接/TLS/首字节/GC）
• AddExtendedHttpClientLogging() — 记录方法、URL、状态码、耗时

services.AddHttpClient("MyClient")
    .AddScopeAwareHttpHandler<ScopedDelegatingHandler>();

路由参数默认 Strict 脱敏（/api/users/{userId} 的序列值被掩码）。该默认已固化在 AddScopeAwareHttpHandler 内部链中；如自建客户端链，可通过 options.RequestPathParameterRedactionMode 覆盖：

services.AddHttpClient("MyClient")
    .AddExtendedHttpClientLogging(o =>
    {
        o.LogBody = false;
        o.RequestPathParameterRedactionMode = HttpRouteParameterRedactionMode.None; // 调试用
    });

注意：直接使用原生 AddHttpClient(...)（不经 AddScopeAwareHttpHandler）时，需自行 services.AddRedaction(); + services.AddHttpClientLatencyTelemetry();，且 AddRedaction() 必须先调用。

核心类

配置说明

请求头传播

Web 应用自动启用请求头传播（通过 AddHeaderPropagation）。

服务发现

通过 AddServiceDiscovery() 集成服务发现，支持：

• 配置中心服务注册
• Consul 服务发现
• Nacos 服务发现

依赖包

• Microsoft.AspNetCore.HeaderPropagation
• Microsoft.Extensions.Http.Polly
• Microsoft.Extensions.Http.Diagnostics
• Microsoft.Extensions.Compliance.Redaction

依赖项目

• Galosys.Foundation.Core

目录结构

Galosys.Foundation.HttpClient/
├── Galosys/Foundation/HttpClient/
│   └── RestClientDispatchProxy.cs      # 动态代理实现
├── Microsoft/Extensions/DependencyInjection/
│   ├── HttpClientServiceCollectionExntensions.cs  # 服务注册扩展
│   └── ScopeAwareHttpClientFactory.cs  # 作用域感知工厂
├── RestClientModule.cs                 # 模块注册
└── README.md

注意事项

• 接口方法需使用 [GetMapping]、[PostMapping] 特性标记（来自 System.Net.Http 命名空间）
• 简单类型参数自动拼接到 URL 查询字符串
• 复杂类型参数自动序列化为 JSON（POST 请求体）
• 方法缺少 [GetMapping]/[PostMapping] 特性时会抛出 InvalidOperationException
• 默认超时时间为 10 秒