Table of Contents

HTTP 客户端([HttpApi] 生成器)

KernLab.Loom.Http:声明一个接口,编译期自动生成实现类——不用写任何 HTTP 调用代码。

可运行 sample:samples/HttpClient/App(真实 Kestrel 往返)。

从零跑通(4 步)

1. 声明契约接口

[HttpApi(Service = "shop")]
public interface IShopApi
{
    [HttpGet("orders/{id}")]
    Task<Order> GetOrderAsync(Guid id, CancellationToken ct = default);
}

[HttpApi] 声明服务名;[HttpGet("orders/{id}")] 声明路由。方法签名即调用协议。 地址不必写死在契约里——BaseAddress 可留空,在注册时配置(单地址/多地址/服务发现,见运行时 · 服务选址)。

2. 注册(DI)——地址集中一处配,N 个接口零配置

// 全局一次:服务选址(单地址/多地址/服务发现,见[运行时 · 服务选址](http.html))+ 全局默认
services.AddLoomHttp(o =>
{
    o.ServiceEndpoints["shop"] = new[]
    {
        new Endpoint(new Uri("https://shop-1.internal/")),
        new Endpoint(new Uri("https://shop-2.internal/")),
    };
    o.Timeout = TimeSpan.FromSeconds(30);
});

// N 个接口:裸注册即可——地址按 [HttpApi(Service=...)] 的服务名自动解析
services.AddLoomHttpClient<IShopApi>();
services.AddLoomHttpClient<IAdminApi>();
services.AddLoomHttpClient<IReportApi>();

3. 注入使用

public class OrderService(IShopApi shop)
{
    public async Task<Order> LoadAsync(Guid id) => await shop.GetOrderAsync(id);
}

4. 完事——GetOrderAsync 发出 GET <解析到的 shop 地址>/orders/{id}(RoundRobin 轮换/服务发现/健康冷却由全局配置决定)。

单接口快捷形态:AddLoomHttpClient<IShopApi>(o => o.Services["shop"] = new Uri(...)) 也行(内部已含 AddLoomHttp)——适合只有一两个接口、懒得开全局配置时。

声明语法

要素 写法
动词 [HttpGet]/[HttpPost]/[HttpPut]/[HttpPatch]/[HttpDelete]/[HttpHead]/[HttpOptions]
路由 "orders/{id}"——{id} 由同名参数(或 [Path] 标注)填充
查询参数 [Query] string status 或 [Query(Name = "per_page")] int? page
请求头 方法级 [HttpHeader("Accept", "application/json")];参数级 [Header("X-Request-Id")]
请求体 [Body] NewOrder body(POST/PUT/PATCH)
表单 [Multipart]/[FormUrlEncoded] + [FormField]/[FormFile]
策略 [HttpTimeout(毫秒)] 接口/方法级超时(覆盖 per-client 默认);[HttpRetryPolicy("name")] 指向命名重试策略
返回 Task<T>(业务体);Task<HttpResponse<T>>(含状态码);IAsyncEnumerable<T>(SSE 流);Task<Stream>(下载)

运行时行为

  • 实现类编译期生成(无 DispatchProxy/运行时代理),AOT 安全——接口实现类 + 源生成序列化往返由 AOT 发布探针守门。
  • 线格式:JSON(o.JsonSerializerOptions 可换——AOT 部署换 JsonSerializerContext)。
  • 错误:非 2xx → LoomEndpointException(服务端 ProblemDetails 解包)。
  • 传输执行:默认走 KernLab.Loom.Http.Runtime 通道(选址/超时/重试/熔断见运行时)。
  • AddLoomHttpClient<T> 与全局 AddLoomHttp 是同一张 LoomHttpOptions 表的两层写法(不冲突,内部自动调 AddLoomHttp)——完整关系见运行时 · AddLoomHttp 与 AddLoomHttpClient 的关系。

记录子集

[HttpApi] + IHttpApi<T> 的记录契约走另一形态(IEndpointChannel 扩展方法),适合轻量调用。

宿主集成(可选,ASP.NET Core)

在 ASP.NET Core 宿主内可装 KernLab.Loom.Http.AspNetCore(AddLoomHttpAspNetCore + o.UseAspNetCoreAmbient()): 入站请求取消级联到出站调用、traceparent 等传播头透传(Authorization/Cookie 缺省不转,防凭据泄漏)。 不装本包时客户端行为完全不变。

相关

  • 传输通道(选址/超时/重试/熔断/序列化):运行时。
  • 服务端端点契约([EndpointCommand]/[EndpointQuery]):服务端。