EndpointConventionBuilder是ASP.NET Core中用于为路由端点添加元数据或配置策略的构建器对象，它在调用MapControllerRoute、MapRazorPages或Minimal API的MapGet等方法时由框架返回，支持链式调用以附加授权、CORS、缓存等约定。例如，通过RequireAuthorization()可为端点添加授权策略，Add()方法可直接操作元数据添加缓存头，还可扩展自定义约定如WithTraceTag添加日志标记，结合MapGroup可批量应用到多个端点，实现集中式配置管理。
端点约定生成器（EndpointConventionBuilder）在 ASP.NET Core 中用于为路由端点附加元数据或配置策略，比如授权、CORS、缓存等。它不是直接创建的，而是在添加控制器、Razor 页面、Minimal API 等端点时由框架返回的一个构建器对象，你可以链式地为其添加约定。
1. 什么是 EndpointConventionBuilder？
当你使用 MapControllerRoute、MapRazorPages 或 MapGet/Post 等方法注册端点时，它们会返回一个 EndpointConventionBuilder 实例。你可以用这个实例来附加一些“约定”（conventions），这些约定会在路由构建时应用到对应的端点上。
2. 常见用法示例
为 Minimal API 添加授权：
app.MapGet("/api/values", () => "Hello")
.RequireAuthorization(); // 返回 EndpointConventionBuilder
这里 RequireAuthorization() 是对 EndpointConventionBuilder 的扩展方法，它将授权策略添加到该端点。
为控制器路由添加缓存头：
app.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}")
.Add(b => b.Metadata.Add(new CacheProfile("DefaultCache")));
Add() 方法接收一个 Action
自定义约定：添加日志标记
public static class MyEndpointConventionExtensions
{
public static TBuilder WithTraceTag(this TBuilder builder, string tag)
where TBuilder : IEndpointConventionBuilder
{
builder.Add(endpointBuilder =>
{
if (endpointBuilder is RouteEndpointBuilder routeBuilder)
{
routeBuilder.Metadata.Add(new CustomTagMetadata(tag));
}
});
return builder;
}
}
然后在 Map 时使用：
app.MapGet("/info", () => "Info")
.WithTraceTag("diagnostics");
3. 在 Controller 中使用 ApiController 特性组合
虽然不是直接调用 EndpointConventionBuilder，但 [ApiController] 实际上就是一种约定，它通过应用多个元数据影响行为。你也可以自定义特性并配合 ApplicationModel 来实现类似效果。
但在 Minimal API 或集中式路由中，EndpointConventionBuilder 提供了更灵活的运行时控制方式。
4. 与 MapGroup 结合使用
MapGroup 返回的是 RouteGroupBuilder，它也实现了 IEndpointConventionBuilder，所以可以批量设置：
var group = app.MapGroup("/api/v1")
.RequireAuthorization()
.WithOpenApi();
group.MapGet("/users", () => new[] { "Alice", "Bob" });
group.MapPost("/users", () => Results.Created());
这样所有属于该组的端点都会继承授权和 OpenAPI 描述。
基本上就这些。关键是理解：每次你调用 MapXXX 得到的对象支持链式配置，背后的机制就是 EndpointConventionBuilder 在收集你要附加的元数据或行为。不复杂但容易忽略其灵活性。
