ASP.NET Core 端点约定生成器使用教程

ASP.NET Core 的端点约定生成器（EndpointConventionBuilder）是一个强大而灵活的内置机制，它在你调用 MapControllerRoute、MapRazorPages 或 Minimal API 的 MapGet/Post 等路由注册方法时自动返回，让你能以链式调用方式为端点集中添加授权策略、CORS 配置、缓存头、自定义元数据（如日志标记）等行为，既支持开箱即用的扩展方法（如 RequireAuthorization），也允许深度定制约定，并可结合 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 在收集你要附加的元数据或行为。不复杂但容易忽略其灵活性。

理论要掌握，实操不能落！以上关于《ASP.NET Core 端点约定生成器使用教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！