攻克 ASP.NET Core Minimal API：中间件与过滤器的极致实战指南

 客户端请求 ---> [中间件 1] ---> [中间件 2] ---> [路由匹配] ---> [过滤器 1] ---> [过滤器 2] ---> [Endpoint Handler]
                                                                                                     |
 客户端响应 <--- [中间件 1] <--- [中间件 2] <------------------- [过滤器 1] <--- [过滤器 2] <--------+

 app.Use(async (HttpContext context, RequestDelegate next) =>
 {
     // 中间件拿到的是原始 Path 字符串，需要自己写正则或手动拆分字符串解析 id！
     var path = context.Request.Path.Value; // "/orders/0"
     
     if (path != null && path.StartsWith("/orders/"))
     {
         var idSegment = path.Split('/').LastOrDefault();
         if (int.TryParse(idSegment, out int id) && id <= 0)
         {
             // 中间件无法使用 Results.BadRequest()，必须手写 Response 流
             context.Response.StatusCode = StatusCodes.Status400BadRequest;
             context.Response.ContentType = "application/json";
             await context.Response.WriteAsJsonAsync(new { Error = "ID 必须大于 0" });
             return; // 短路，不调用 next
         }
     }
 ​
     await next(context);
 });

 app.MapPost("/orders/{id:int}", (int id) => Results.Ok($"Order {id}"))
    .AddEndpointFilter(async (EndpointFilterInvocationContext context, EndpointFilterDelegate next) =>
    {
        // 1. 直接从 context.Arguments 中强类型提取 id，框架已经帮你解析并转成了 int！
        var id = context.GetArgument<int>(0);
 ​
        if (id <= 0)
        {
            // 2. 直接返回 Minimal API 熟悉的 Results 对象打断请求
            return Results.BadRequest(new { Error = "ID 必须大于 0" });
        }
 ​
        return await next(context);
    });

 var builder = WebApplication.CreateBuilder(args);
 var app = builder.Build();
 ​
 // 自定义中间件
 app.Use(async (HttpContext context, RequestDelegate next) =>
 {
     // 【1. 请求前置处理】
     Console.WriteLine($"[Middleware IN] Path: {context.Request.Path}");
 ​
     // 【2. 调用管道中的下一个中间件】
     await next(context);
 ​
     // 【3. 响应后置处理】
     Console.WriteLine($"[Middleware OUT] Status: {context.Response.StatusCode}");
 });
 ​
 app.MapGet("/hello", () => "Hello World!");
 ​
 app.Run();

 // 1. 定义中间件类
 public class RequestTimingMiddleware
 {
     private readonly RequestDelegate _next;
     private readonly ILogger<RequestTimingMiddleware> _logger;
 ​
     // 构造函数传入 next 委托和 Singleton/Transient 服务
     public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
     {
         _next = next;
         _logger = logger;
     }
 ​
     // 必须包含名为 InvokeAsync 或 Invoke 的方法，第一个参数必须是 HttpContext
     public async Task InvokeAsync(HttpContext context)
     {
         var stopwatch = System.Diagnostics.Stopwatch.StartNew();
 ​
         // 执行下一个中间件
         await _next(context);
 ​
         stopwatch.Stop();
         _logger.LogInformation("请求 {Path} 耗时: {Elapsed} ms", context.Request.Path,          stopwatch.ElapsedMilliseconds);
     }
 }
 ​
 // 2. 编写扩展方法
 public static class MiddlewareExtensions
 {
     public static IApplicationBuilder UseRequestTiming(this IApplicationBuilder app)
     {
         return app.UseMiddleware<RequestTimingMiddleware>();
     }
 }
 ​
 // 3. 在 Program.cs 中使用
 app.UseRequestTiming();

 app.MapPost("/users", (UserDto user) => Results.Created($"/users/{user.Name}", user))
    .AddEndpointFilter(async (EndpointFilterInvocationContext context, EndpointFilterDelegate next) =>
    {
        // 【1. 前置逻辑】
        Console.WriteLine("过滤器前置校验开启...");
 ​
        // 【2. 执行下一个过滤器或真正 Handler】
        var result = await next(context);
 ​
        // 【3. 后置逻辑】
        Console.WriteLine("过滤器后置处理完成...");
 ​
        return result;
    });

 using FluentValidation;
 ​
 public class ValidationFilter<T> : IEndpointFilter where T : class
 {
     public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
     {
         // 1. 在参数列表中寻找类型为 T 的待校验对象
         var argToValidate = context.Arguments.OfType<T>().FirstOrDefault();
 ​
         if (argToValidate is not null)
         {
             // 2. 从 HttpContext 的 DI 容器中拿到对应的 Validator
             var validator = context.HttpContext.RequestServices.GetService<IValidator<T>>();
             if (validator is not null)
             {
                 var validationResult = await validator.ValidateAsync(argToValidate);
                 if (!validationResult.IsValid)
                 {
                     // 校验失败，直接拦截并返回 400
                     var errors = validationResult.ToDictionary();
                     return Results.ValidationProblem(errors);
                 }
             }
         }
 ​
         // 3. 校验通过，放行
         return await next(context);
     }
 }

 // 单个 Endpoint 链式调用
 app.MapPost("/products", (ProductDto product) => Results.Ok(product))
    .AddEndpointFilter<ValidationFilter<ProductDto>>();

 var app = WebApplication.CreateBuilder(args).Build();
 ​
 // 1. 创建路由组，并统一定义前缀与过滤器
 var adminGroup = app.MapGroup("/api/admin")
                     .RequireAuthorization("AdminPolicy") // 授权策略
                     .AddEndpointFilter<AdminAuditLogFilter>(); // 统一挂载审计日志过滤器
 ​
 // 2. 在组内注册具体的 Endpoint，它们会自动继承路由组的所有过滤器！
 adminGroup.MapGet("/users", () => "Admin: All Users");
 adminGroup.MapDelete("/users/{id}", (int id) => $"Deleted User {id}");
 ​
 app.Run();

 var builder = WebApplication.CreateBuilder(args);
 var app = builder.Build();
 ​
 // ---------------- 1. 全局中间件阶段 ----------------
 ​
 // 1.1 全局未捕获异常处理中间件
 app.Use(async (context, next) =>
 {
     try
     {
         await next(context);
     }
     catch (Exception ex)
     {
         context.Response.StatusCode = 500;
         await context.Response.WriteAsJsonAsync(new { Error = "服务器内部错误", Detail = ex.Message });
     }
 });
 ​
 // ---------------- 2. 路由组与 Endpoint 阶段 ----------------
 ​
 var orderGroup = app.MapGroup("/orders")
                     .AddEndpointFilter(async (context, next) =>
                     {
                         // 组级过滤器：给所有订单接口加上统一耗时日志
                         var sw = System.Diagnostics.Stopwatch.StartNew();
                         var result = await next(context);
                         sw.Stop();
                         Console.WriteLine($"[Orders API] 耗时 {sw.ElapsedMilliseconds}ms");
                         return result;
                     });
 ​
 // 结合单个 Endpoint 专属过滤器
 orderGroup.MapPost("/", (CreateOrderDto order) => Results.Ok(new { OrderId = 1001, order.Amount }))
           .AddEndpointFilter(async (context, next) =>
           {
               // Endpoint 专属过滤器：校验订单金额
               var order = context.GetArgument<CreateOrderDto>(0);
               if (order.Amount <= 0)
               {
                   return Results.BadRequest(new { Error = "订单金额必须大于 0" });
               }
               return await next(context);
           });
 ​
 app.Run();
 ​
 // DTO 定义
 public record CreateOrderDto(string ProductId, decimal Amount);