Table of Contents

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 下载零缓冲透传。

相关

  • 客户端生成器:[HttpApi] 契约 → 实现类,见生成器。
  • 服务端端点契约:[EndpointCommand]/[EndpointQuery] → Minimal API,见服务端。