端点元数据是附加到路由端点上的描述信息，用于控制请求处理行为。每个MVC或Minimal API路由生成的Endpoint对象包含URL、委托和元数据集合，元数据可存储授权策略、缓存设置、自定义标记等。通过特性（如[Authorize]）、WithMetadata()方法或自定义类（实现IEndpointMetadataProvider）添加元数据，并在中间件中通过HttpContext.GetEndpoint()读取，实现审计日志、权限控制、速率限制、API文档过滤等功能，提升架构灵活性与解耦性。
在 ASP.NET Core 中，端点元数据（Endpoint Metadata）是一种附加到路由端点上的额外信息，可用于影响请求处理流程。它常用于中间件、过滤器、授权机制等场景中，帮助开发者根据特定条件控制行为。
什么是端点元数据？
每个通过 MVC 或 Minimal API 定义的路由都会生成一个 Endpoint 对象，该对象包含 URL 模式、请求委托以及一组“元数据”集合。这个元数据是一个对象列表，可以存放任意类型的信息，比如：
- 授权策略（如 [Authorize] 特性）
- 缓存设置
- 是否公开文档（如 Swagger UI 显示控制）
- 自定义标记或配置
这些元数据是在路由映射阶段添加的，可以在运行时由中间件读取并做出决策。
如何添加元数据？
有多种方式可以为端点添加元数据：
● 使用特性（Attributes）MVC 控制器或动作方法上的特性会自动转换为元数据。例如：
[Authorize(Policy = "AdminOnly")]
[HttpGet("/api/users")]
public IActionResult GetUsers() { ... }
这里的 [Authorize] 会被转化为对应的元数据对象，供授权中间件使用。
● 在 Minimal API 中显式添加使用 WithMetadata() 或各类扩展方法：
app.MapGet("/public", () => "Hello")
.WithDisplayName("公开接口")
.RequireAuthorization("PublicPolicy");
上面的 RequireAuthorization 实际上就是向该端点添加了授权元数据。
定义自己的元数据类型：
public class AuditLogAttribute : Attribute, IEndpointMetadataProvider
{
public void SetMetadata(IEndpointConventionBuilder builder)
{
builder.WithMetadata(this);
}
}
然后应用到 Minimal API 或控制器上，即可将该实例加入元数据集合。
如何读取和利用元数据？
最常见的使用场景是在中间件中检查当前请求的端点是否有特定元数据。
● 在中间件中访问元数据通过 HttpContext.GetEndpoint() 获取当前端点：
app.Use(async (ctx, next) =>
{
var endpoint = ctx.GetEndpoint();
if (endpoint == null)
{
await next();
return;
}
// 检查是否存在某个元数据
if (endpoint.Metadata.GetMetadata() != null)
{
// 记录审计日志
Console.WriteLine($"Auditing request to {ctx.Request.Path}");
}
await next();
});
● 配合授权或资源过滤器在更高级的场景中，你可以创建基于元数据的自定义授权逻辑：
var requireAudit = endpoint.Metadata.GetMetadata(); if (requireAudit != null && !IsUserAuditor(ctx.User)) { ctx.Response.StatusCode = 403; return; }
实际应用场景举例
- API 文档过滤：Swashbuckle 可以根据元数据决定是否在 Swagger UI 中显示某些端点。
- 速率限制：根据不同元数据标识的接口应用不同限流策略。
- 监控与追踪：标记关键接口，在中间件中自动记录性能指标。
- 多租户支持：通过元数据指定租户类型，动态切换数据库连接。
基本上就这些。端点元数据是 ASP.NET Core 路由系统灵活设计的核心部分，合理使用可以让架构更清晰、解耦更强。关键是理解它作为“附加描述信息”的角色，并在合适的地方读取它来驱动行为。
