深入理解 ASP.NET Core 终结点元数据扩展（手把手教你实现自定义元数据）

什么是终结点元数据？

在 ASP.NET Core 中，每个路由终结点（如 Controller Action 或 Minimal API）都可以携带一组元数据（Metadata）。这些元数据本质上是实现了 IMetadata 接口的对象，用于描述该终结点的附加属性，例如授权策略、CORS 策略、速率限制规则等。

通过自定义元数据，我们可以为特定的 API 添加业务逻辑标记，比如“需要审计日志”、“仅限内部调用”等，然后在中间件中统一处理这些逻辑，避免在每个方法中重复编写代码。

第一步：创建自定义元数据类

首先，我们定义一个简单的元数据接口和实现类：

// 定义一个标记接口，表示该终结点需要记录操作日志public interface IAuditLogMetadata{    string OperationName { get; }}// 实现该接口class AuditLogMetadata : IAuditLogMetadata{    public string OperationName { get; }    public AuditLogMetadata(string operationName)    {        OperationName = operationName;    }}

第二步：创建扩展方法，方便使用

为了让开发者能像使用内置特性一样使用我们的元数据，我们可以创建一个 Attribute 和对应的扩展方法：

using Microsoft.AspNetCore.Builder;using Microsoft.AspNetCore.Http;using Microsoft.AspNetCore.Routing;[AttributeUsage(AttributeTargets.Method)]public class AuditLogAttribute : Attribute, IAuditLogMetadata{    public string OperationName { get; }    public AuditLogAttribute(string operationName)    {        OperationName = operationName;    }}// 扩展 EndpointConventionBuilder，使其支持 AuditLogpublic static class AuditLogEndpointConventionBuilderExtensions{    public static TBuilder RequireAuditLog<TBuilder>(        this TBuilder builder,        string operationName) where TBuilder : IEndpointConventionBuilder    {        builder.WithMetadata(new AuditLogMetadata(operationName));        return builder;    }}

第三步：在 Minimal API 或 Controller 中使用

现在，你可以在 Minimal API 中这样使用：

var builder = WebApplication.CreateBuilder(args);var app = builder.Build();app.MapGet("/users", () => Results.Ok(new[] { "Alice", "Bob" }))   .RequireAuditLog("ListUsers"); // ← 添加自定义元数据app.Run();

如果你使用的是 Controller，也可以直接使用 Attribute：

[ApiController][Route("[controller]")]public class UsersController : ControllerBase{    [HttpGet]    [AuditLog("ListUsers")] // ← 自定义特性    public IActionResult Get()    {        return Ok(new[] { "Alice", "Bob" });    }}

第四步：在中间件中读取元数据

接下来，我们创建一个中间件，在请求到达时检查当前终结点是否包含审计日志元数据：

public class AuditLogMiddleware{    private readonly RequestDelegate _next;    public AuditLogMiddleware(RequestDelegate next)    {        _next = next;    }    public async Task InvokeAsync(HttpContext context)    {        var endpoint = context.GetEndpoint();        if (endpoint != null)        {            // 尝试获取 IAuditLogMetadata            var auditMetadata = endpoint.Metadata.GetMetadata<IAuditLogMetadata>();            if (auditMetadata != null)            {                // 记录日志（这里简化为输出到控制台）                Console.WriteLine($"[AUDIT] 操作: {auditMetadata.OperationName}, 用户: {context.User?.Identity?.Name ?? "匿名"}");            }        }        await _next(context);    }}// 注册中间件app.UseMiddleware<AuditLogMiddleware>();

为什么这很重要？

通过这种模式，你可以将横切关注点（如日志、权限、缓存）与业务逻辑解耦。这正是 Endpoint元数据编程 的核心价值所在。无论是构建企业级应用还是微服务，掌握 C# Web API开发 中的元数据机制，都能显著提升代码的可维护性和扩展性。

总结

本文详细讲解了如何在 ASP.NET Core 中创建和使用自定义终结点元数据。从定义接口、创建扩展方法，到在 API 中使用并配合中间件读取，每一步都配有清晰的代码示例。希望你能将这一技术应用到自己的项目中，打造更优雅的 ASP.NET Core终结点元数据 架构！

—— 本文完 ——