ASP.NET Core自定义中间件怎么创建？

自定义中间件是在ASP.NET Core请求管道中处理请求和响应的组件，通过创建实现InvokeAsync方法并接收HttpContext的类，结合RequestDelegate调用下一个中间件，可实现日志、认证等跨切面逻辑；需在Program.cs中使用app.UseMiddleware()注册，且顺序至关重要；推荐使用构造函数注入配置或单例服务，通过InvokeAsync参数注入作用域服务以避免生命周期错误，调试时应关注_next调用、异步await及中间件执行顺序。

在ASP.NET Core中，自定义中间件就是你在HTTP请求处理管道中插入的一段逻辑，它能拦截、检查、修改甚至终止请求，或者在请求处理完毕后对响应做些操作。这就像一个交通检查站，每个请求在到达最终目的地（你的控制器或最小API）之前，都必须经过它，你可以在这里做身份验证、日志记录、错误处理、请求限流等任何你想在请求流中统一处理的事情。

解决方案

创建自定义中间件主要有两种方式，一种是直接在Startup.cs（或Program.cs）中使用app.Use()方法内联定义，另一种是创建独立的类。考虑到复用性和代码组织，通常我们会选择后者。

1. 创建自定义中间件类

一个典型的自定义中间件类需要满足以下条件：

• 包含一个RequestDelegate类型的字段或属性，用于调用管道中的下一个中间件。
• 包含一个名为InvokeAsync（或Invoke）的方法，该方法接收HttpContext作为参数，并返回Task。这是中间件的核心逻辑所在。

让我们创建一个简单的日志记录中间件，它会在请求开始和结束时记录一些信息：

using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using System.Diagnostics;
using System.Threading.Tasks;

public class RequestLoggingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger _logger;

    public RequestLoggingMiddleware(RequestDelegate next, ILogger logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var stopwatch = Stopwatch.StartNew();
        _logger.LogInformation($"Request started: {context.Request.Method} {context.Request.Path}");

        // 调用管道中的下一个中间件
        await _next(context);

        stopwatch.Stop();
        _logger.LogInformation($"Request finished: {context.Request.Method} {context.Request.Path} in {stopwatch.ElapsedMilliseconds}ms. Status: {context.Response.StatusCode}");
    }
}

2. 注册和使用自定义中间件

在Program.cs（或Startup.cs的Configure方法）中，你需要使用app.UseMiddleware()或app.Use()扩展方法来将你的中间件添加到HTTP请求管道中。

// Program.cs
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// 在这里注册你的自定义中间件
// 注意：中间件的注册顺序至关重要！
app.UseMiddleware();

app.UseAuthorization();

app.MapControllers();

app.Run();

通过app.UseMiddleware()，我们就把RequestLoggingMiddleware插入到了请求管道中。每次请求到来，都会先经过它，然后才到达后续的中间件，最终抵达你的API控制器。

何时应该选择自定义中间件，而不是过滤器或服务？

这确实是个让人头疼的问题，因为ASP.NET Core提供了多种方式来处理请求。我的经验是，选择哪种方案，很大程度上取决于你的逻辑在“请求生命周期”中的位置和作用域。

中间件位于HTTP请求管道的最前端，或者说，它直接操作的是原始的HttpContext对象。这意味着它能对请求进行最早期、最全局的拦截和处理。比如，如果你需要处理所有请求的身份验证、日志记录、错误捕获（全局异常处理中间件就是典型）、请求限流、URL重写，甚至是一些CDN相关的缓存逻辑，那么中间件是你的首选。它的执行发生在MVC/API控制器选择和执行之前，所以它对整个应用程序的请求流有最高级别的控制力。你可以想象它是一个“门卫”，在任何人进入大楼之前就进行检查。

而过滤器（如Action Filter, Authorization Filter等）则更专注于MVC/API的特定阶段。它们是在某个控制器、某个Action方法，或者某个Razor Page执行前后插入逻辑。比如，你只想对某个特定的API方法进行参数验证、权限检查（基于角色或策略）、结果缓存，或者在Action执行前后修改Model或ViewData，那么过滤器更合适。它就像大楼里的“部门主管”，只负责自己部门的业务。它能访问到ActionContext、ResultContext等更具体、更高级别的上下文信息，但无法像中间件那样直接操作原始的HTTP请求/响应流。

至于服务，那更是应用程序的核心业务逻辑了。服务通常不直接参与请求管道的拦截和处理，而是被控制器、过滤器或中间件所调用，来完成具体的业务计算、数据存储等任务。它们是“大楼里的员工”，负责具体的工作。

简而言之：

• 中间件： 全局性、管道级、早期执行、操作HttpContext，适用于通用且不依赖特定MVC/API上下文的横切关注点。
• 过滤器： 特定MVC/API上下文、Action级、依赖ActionContext等，适用于与MVC/API行为紧密相关的逻辑。
• 服务： 业务逻辑、被调用、不直接参与请求管道。

当你发现你的逻辑需要作用于所有或大部分请求，并且不关心具体的控制器或Action时，中间件通常是更自然、更高效的选择。

开发自定义中间件时常见的陷阱与调试策略

在实际开发中，自定义中间件虽然强大，但也容易踩坑。我见过最常见的几个问题和相应的调试策略如下：

1. 中间件顺序问题

这是最容易让人迷惑的地方。ASP.NET Core的请求管道是线性的，中间件的注册顺序决定了它们的执行顺序。如果你的认证中间件放在授权中间件之后，那授权可能就无法正常工作了，因为它拿不到认证信息。同样，如果一个错误处理中间件放在了其他可能抛出异常的中间件之前，那它就无法捕获到后续中间件的异常。

调试策略：

• 可视化管道： 在脑海中或者画出你的中间件管道图。想象请求从左到右流过，响应从右到左流回。
• 日志输出： 在每个中间件的InvokeAsync方法入口和出口处添加详细的日志（如前面示例），明确请求经过了哪些中间件，顺序是否正确。
• 断点调试： 这是最直接有效的方法。在每个中间件的InvokeAsync方法中设置断点，逐步执行，观察HttpContext的状态变化，以及_next(context)的调用时机。

2. _next(context)调用遗漏或位置不当

忘记调用await _next(context);会导致请求无法继续向下传递，管道会在这里“断裂”，后续的中间件和控制器将永远不会被执行。如果把它放在了不正确的位置（比如在一个return语句之后），也可能导致类似问题。

调试策略：

• 断点检查： 确保_next(context)被正确调用，并且是在你希望逻辑继续执行的地方。
• 观察响应： 如果你的请求总是返回空响应或不完整的响应，或者请求超时，很可能就是_next(context)出了问题。

3. 异步操作处理不当

在InvokeAsync方法中，如果涉及到异步操作（如数据库查询、外部API调用），务必使用await关键字。如果忘记await，可能会导致请求过早返回，或者出现意想不到的并发问题。

调试策略：

• 编译器警告： 留意IDE的警告，通常会提示你“因为此调用未被等待，所以执行将继续进行，而不会等待调用完成”。
• 异步流追踪： 使用Visual Studio的并行堆栈窗口，可以帮助你追踪异步方法的执行流程。

4. 依赖注入问题

中间件本身可能需要依赖其他服务。如果在构造函数中注入了生命周期不匹配的服务（比如在单例中间件中注入了作用域服务），或者在InvokeAsync方法中需要注入作用域服务却直接从构造函数获取，都可能导致问题。

调试策略：

• 理解DI生命周期： 牢记Singleton（单例）、Scoped（作用域）、Transient（瞬态）的区别。
• 日志DI解析： 在启动时，可以短暂地将日志级别调高，观察DI容器解析服务时的日志，看是否有异常或警告。
• InvokeAsync参数注入： 对于需要作用域服务的中间件，优先考虑在InvokeAsync方法中通过参数注入，因为InvokeAsync是在每次请求作用域内被调用的，可以正确解析作用域服务。

如何在自定义中间件中安全地注入服务或配置？

在自定义中间件中集成依赖服务或配置，是实现其功能和灵活性的关键。这通常通过依赖注入（DI）机制来完成，但具体操作方式会因服务生命周期和中间件的实现方式而异。

1. 构造函数注入（Constructor Injection）

这是最常见和推荐的方式，适用于那些生命周期与中间件实例本身一致的服务。通常，中间件实例在应用程序启动时只创建一次（如果是单例），或者每次请求时创建一次（如果是通过IMiddleware接口实现）。

// 注入日志服务和配置
public class MyCustomMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger _logger;
    private readonly MyCustomOptions _options; // 假设有一个配置类

    public MyCustomMiddleware(RequestDelegate next, ILogger logger, IOptions options)
    {
        _next = next;
        _logger = logger;
        _options = options.Value; // 获取配置值
    }

    public async Task InvokeAsync(HttpContext context)
    {
        _logger.LogInformation($"Middleware option value: {_options.SomeSetting}");
        await _next(context);
    }
}

// 对应的配置类
public class MyCustomOptions
{
    public string SomeSetting { get; set; } = "Default Value";
}

注册配置： 在Program.cs中，你需要先将配置绑定到DI容器：

builder.Services.Configure(builder.Configuration.GetSection("MyCustomSection"));
// 假设appsettings.json中有这样的配置:
// "MyCustomSection": {
//   "SomeSetting": "Hello from config!"
// }

注意： 如果你在构造函数中注入了Scoped（作用域）或Transient（瞬态）服务，而你的中间件实例是单例的（通常通过app.UseMiddleware()注册的类式中间件默认是单例），这可能会导致“Captive Dependency”问题，即一个生命周期较长的服务持有了生命周期较短的服务实例，可能导致状态污染或资源泄露。

2. InvokeAsync方法参数注入（Method Injection）

对于那些需要作用域（Scoped）生命周期的服务，或者你希望每次请求都获取到最新的服务实例时，最佳实践是在InvokeAsync方法中通过参数注入。InvokeAsync方法会在每个请求的作用域内被调用，因此DI容器能够正确地解析作用域服务。

// 假设有一个作用域服务
public interface IScopedService
{
    string GetOperationId();
}

public class ScopedService : IScopedService
{
    private readonly Guid _operationId = Guid.NewGuid();
    public string GetOperationId() => _operationId.ToString();
}

// 在中间件中使用 InvokeAsync 参数注入
public class AnotherCustomMiddleware
{
    private readonly RequestDelegate _next;

    public AnotherCustomMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context, IScopedService scopedService) // 在这里注入 IScopedService
    {
        context.Items["OperationId"] = scopedService.GetOperationId(); // 将服务数据存入HttpContext
        _logger.LogInformation($"Operation ID for this request: {scopedService.GetOperationId()}");
        await _next(context);
    }
}

注册作用域服务：

builder.Services.AddScoped();

总结：

• 构造函数注入： 适用于单例服务、配置（IOptions）或生命周期与中间件实例一致的服务。
• InvokeAsync参数注入： 专门用于注入作用域（Scoped）服务，确保每次请求都能获取到独立、正确的实例，避免Captive Dependency问题。

理解这两种注入方式的区别和适用场景，能让你更安全、高效地构建自定义中间件，并避免潜在的运行时问题。