端点(服务端)
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。