Table of Contents

端点(服务端)

KernLab.Loom.Endpoints:声明契约 + 端点方法,编译期直接挂成 Minimal API 路由—— 无中介者、无 Handler 派发层、无运行期扫描。

可运行 sample:samples/Endpoints/Server(全动词/SSE/切面/校验)。

从零跑通

[EndpointCommand("orders/{id}")]
public interface IOrderQuery : IEndpointQuery<Order>   // 结果类型由标记接口承载
{
    Task<Order> GetOrderAsync(string id);              // 实现 = 端点方法
}

public class GetOrder : IOrderQuery
{
    public Task<Order> GetOrderAsync(string id) => ...;
}

builder.Services.AddLoomEndpoints();                  // 注册
var app = builder.Build();
app.MapLoomEndpoints();                               // 挂载(可前缀:MapLoomEndpoints("api/v1"))

GET http://host/orders/123 即命中 GetOrder.GetOrderAsync。路由/动词/绑定全编译期生成。

声明契约

[EndpointCommand("orders/{id}")]                      // 动词/路由来自特性
public interface IOrderQuery : IEndpointQuery<Order> { }

[EndpointQuery("orders")]
public interface IOrderListQuery : IEndpointQuery<OrderList>
{
    Task<OrderList> SearchAsync(string? status, [Query] int? page);   // 查询参数
}

[EndpointCommand("orders/{id}", Verb = EndpointVerb.Delete)]
public interface IDeleteOrder : IEndpointCommand<Unit> { }

规则:

  • 契约 = 接口([EndpointCommand]/[EndpointQuery])+ 标记接口 IEndpointCommand<T>/IEndpointQuery<T> 承载结果类型。
  • 端点方法 = 契约接口的同名方法,首参配对;参数从路由/查询/体解析。
  • 路由占位 {id} → 方法参数 string id;其余参数默认查询绑定([Query]/[Header]/[Body] 显式)。

挂载

var app = builder.Build();
app.MapLoomEndpoints();                  // 无前缀
app.MapLoomEndpoints("api/v1");          // 全局前缀 = MapGroup(路由表保持无前缀)
var group = app.MapLoomEndpoints();
group.AddEndpointFilter(async (ctx, next) => { var r = await next(ctx); return r; });  // 组级过滤

与 ASP.NET Core 原生认证/授权无缝(AddAuthentication/AddAuthorization 照常进管道)。

能力

能力 说明
校验 端点参数用校验条件族标注(T1 直访校验器)
切面 [Aspect] 切面链编译期织入,切面实例解析自 DI(IAspect/AspectContext/AspectContinuation)
SSE [Sse] + IAsyncEnumerable<T> 返回 = SSE 端点;[FromLastEventId] 接续游标
错误 ProblemDetails 信封(客户端 LoomEndpointException 解包)
客户端配对 同一契约反向发射客户端代理(声明一次、两端共用)

诊断

KLSG070-079 + 240-241:契约形态/路由模板与参数不匹配/绑定非法/切面标注非法/SSE 形态/端点方法配对等——全默认 Error。

诚实边界

  • 外部 API 客户端(任意 method/path、非 2xx 业务体)请走独立面 HTTP 客户端([HttpApi])。
  • 契约只声明"要发生一次调用/一次流"——传输/选址/线格式归 IEndpointChannel 实现方(运行时)。