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 缺省不转,防凭据泄漏)。
不装本包时客户端行为完全不变。