HTTP 运行时(传输通道)
KernLab.Loom.Http.Runtime:IEndpointChannel 的开箱即用 HTTP 实现——客户端生成器的调用
在这里真正变成网络请求(选址、序列化、错误映射、弹性策略全在这层)。
可运行 sample:
samples/Http/App(多实例 RoundRobin/动态头)、samples/Http.AspNetCore/App(ambient)。
怎么接上
生成器包 + 运行时包都引用后,AddLoomHttpClient<T> 自动走本通道;也可独立用通道直接发 EndpointCall。
dotnet add package KernLab.Loom.Http
dotnet add package KernLab.Loom.Http.Runtime
配置(LoomHttpOptions)
services.AddLoomHttp(o =>
{
o.Timeout = TimeSpan.FromSeconds(30); // 总超时(含全部重试尝试)
o.AttemptTimeout = TimeSpan.FromSeconds(5); // 单次尝试超时(重试时每次各自计时)
o.JsonSerializerOptions = myAotContext.Options; // AOT 部署换消费方 JsonSerializerContext
o.HeadersProvider = async sp => new Dictionary<string, string?>
{
["Authorization"] = await GetTokenAsync(sp), // 每请求动态头(鉴权令牌)
};
});
- 命名客户端
LoomHttpDefaults.HttpClientName公开——HttpClientFactory处理程序/重试策略按名配置。 - 地址不必写死:
o.Services[...]只是最简入口,多地址/发现/健康见下。
服务选址(4 层,从简单到生产)
① 单地址(入门)
o.Services["shop"] = new Uri("https://shop.internal/");
② 一服务多地址(高可用——RoundRobin 轮换 + 权重)
o.ServiceEndpoints["shop"] = new[]
{
new Endpoint(new Uri("https://shop-1.internal/"), Weight = 3),
new Endpoint(new Uri("https://shop-2.internal/")),
};
缺省选择器 RoundRobin;Endpoint 带 Weight/Tag。失败端点被被动健康冷却剔除
(缺省连续 3 次失败 → 冷却 30s),IEndpointHealth 可自定义策略。
③ 服务发现 SPI(运行时动态解析,非空优先于静态表)
o.EndpointProvider = new ConsulProvider(); // 或 o.EndpointProviderFactory = sp => new(...);
// IEndpointProvider.GetEndpointsAsync(service, ct) → 候选端点(地址可随时变)
④ 自定义负载均衡
o.EndpointSelector = new LeastConnectionsSelector(); // IEndpointSelector.Select(ctx)
// 每次尝试重新选择(Attempt 递增);可感知健康与权重
地址还可以从配置注入(configure 里读 IConfiguration/DI),不用改代码。
AddLoomHttp 与 AddLoomHttpClient 的关系
两个入口看着像、作用不同——不冲突,是同一张表的两层写法:
AddLoomHttp(运行时全局) |
AddLoomHttpClient<T>(生成器·每个 [HttpApi] 一个) |
|
|---|---|---|
| 管什么 | 通道本身:命名 HttpClient + IEndpointChannel 单例 + 全局默认(超时/序列化/动态头) |
把 T 注册成可注入实现类;内部自动调用 AddLoomHttp |
o.Services |
全局选址表手工填项 | 把 [HttpApi(Service, BaseAddress)] 声明写进同一张表(ContainsKey 守卫不覆盖已有项),再跑你的 configure |
o 是谁 |
同一个 LoomHttpOptions 单例(IOptions) |
同一个实例——两者 configure 顺序执行,后写覆盖同 key |
| 何时需要 | 设全局默认,或直接发 EndpointCall 不走生成器 |
声明一个 [HttpApi] 客户端 |
实际用法(推荐——全局一处,N 个接口零配置):
// ① 全局一次:选址(单地址/多地址/服务发现)+ 全局默认(超时/动态头/AOT 序列化)
services.AddLoomHttp(o =>
{
o.EndpointProvider = new ConsulProvider(); // 或 ServiceEndpoints / Services 静态表
o.Timeout = TimeSpan.FromSeconds(30);
o.JsonSerializerOptions = myAotContext.Options;
o.HeadersProvider = async sp => new Dictionary<string, string?> { ["Authorization"] = await GetTokenAsync(sp) };
});
// ② N 个接口裸注册——地址按 [HttpApi(Service=...)] 自动解析,不写第二次
services.AddLoomHttpClient<IShopApi>();
services.AddLoomHttpClient<IAdminApi>();
services.AddLoomHttpClient<IReportApi>();
单接口快捷形态:AddLoomHttpClient<IShopApi>(o => o.Services["shop"] = new Uri(...)) 一行也行(内部已含 AddLoomHttp),适合接口少、不想开全局配置时。
冲突规则:同一个 Services key 两边都写 → 后执行者覆盖(同一单例实例);生成器自带 ContainsKey 守卫所以 [HttpApi(BaseAddress)] 声明永不被你手动 configure 覆盖。推荐全局一处配地址、接口只标 Service 名——N 个接口零重复。
- 通道单类实现八接口(
IEndpointChannel/Envelope/Text/Raw/Response/Download/Form/FormEnvelope)——按需升级能力。
弹性(Policies)
| 能力 | 说明 |
|---|---|
| 负载均衡 | 候选端点 RoundRobin/自定义选择(每次尝试重选) |
| 健康检查 | 被动健康——失败冷却剔除(缺省阈值 3/冷却 30s,Health 可关) |
| 重试 | o.Retry(per-client)/ o.RetryPolicies["name"]([HttpRetryPolicy] 指向)——Retry-After 尊重、指数退避、抖动 |
| 熔断 | o.CircuitBreaker(缺省关闭;打开后恢复窗口试探) |
| 过滤器 | o.AddFilter<T>() per-client 过滤器管线 + 方法级 [HttpFilter] |
错误处理
- 非 2xx →
LoomEndpointException(服务端 ProblemDetails 解包)。 - 畸形报文/超上限一律失败返回,不抛半成品对象。
SSE 与流
IAsyncEnumerable<T>流式、SSE 帧解析、Last-Event-ID续传。Stream下载零缓冲透传。