.NET Web API中如何使用中间件（Middleware）

中间件是.NET Web API请求管道的核心组成部分，每个中间件都可以对进入的HTTP请求进行处理，也能对返回的响应进行修改，多个中间件按注册顺序形成请求处理链路，共同完成请求的全生命周期管理。

中间件的基本工作原理

当HTTP请求到达.NET Web API应用时，请求会依次经过所有注册的中间件，每个中间件可以选择将请求传递给下一个中间件，也可以直接返回响应终止请求处理流程。响应生成后会按相反的顺序再次经过中间件，让中间件有机会对响应内容做最后处理。

中间件的典型结构包含两个部分：一个是接收HttpContext的异步处理方法，另一个是接收RequestDelegate类型的下一个中间件委托的参数，RequestDelegate代表请求管道中的下一个处理步骤。

注册内置中间件

.NET Web API框架已经提供了很多常用的内置中间件，我们可以直接通过WebApplication实例的扩展方法进行注册，常见的内置中间件包括异常处理、HTTPS重定向、路由、跨域等。

以下是一个基础的中间件注册示例，在Program.cs中配置常用内置中间件：

var builder = WebApplication.CreateBuilder(args);

// 添加控制器服务
builder.Services.AddControllers();

// 配置跨域策略
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAll",
        policy => policy.AllowAnyOrigin()
                        .AllowAnyMethod()
                        .AllowAnyHeader());
});

var app = builder.Build();

// 注册异常处理中间件，开发环境显示详细错误
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/error");
}

// 注册HTTPS重定向中间件
app.UseHttpsRedirection();

// 注册跨域中间件，使用上面定义的策略
app.UseCors("AllowAll");

// 注册路由中间件
app.UseRouting();

// 注册端点中间件，映射控制器路由
app.MapControllers();

app.Run();

自定义中间件

如果内置中间件无法满足需求，我们可以自定义中间件实现特定功能，比如请求日志记录、自定义请求头校验等。自定义中间件有两种常见实现方式：按约定实现类和通过lambda表达式定义。

方式一：按约定实现中间件类

自定义中间件类需要满足以下约定：构造函数接收RequestDelegate类型的下一个中间件参数，包含一个名为InvokeAsync或Invoke的异步方法，方法第一个参数为HttpContext。

以下是一个记录请求耗时的自定义中间件示例：

// 自定义请求耗时记录中间件
public class RequestTimingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<RequestTimingMiddleware> _logger;

    // 构造函数接收下一个中间件委托，可通过依赖注入获取其他服务
    public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    // 处理请求的核心方法
    public async Task InvokeAsync(HttpContext context)
    {
        var startTime = DateTime.UtcNow;
        
        // 调用下一个中间件处理请求
        await _next(context);
        
        var endTime = DateTime.UtcNow;
        var duration = endTime - startTime;
        // 记录请求路径和耗时
        _logger.LogInformation($"请求 {context.Request.Path} 处理耗时: {duration.TotalMilliseconds} 毫秒");
    }
}

定义好中间件类后，需要为其添加扩展方法方便注册：

// 中间件注册扩展方法
public static class RequestTimingMiddlewareExtensions
{
    public static IApplicationBuilder UseRequestTiming(this IApplicationBuilder builder)
    {
        return builder.UseMiddleware<RequestTimingMiddleware>();
    }
}

之后在Program.cs中就可以直接调用扩展方法注册该中间件：

var app = builder.Build();

// 注册自定义请求耗时中间件
app.UseRequestTiming();

// 其他中间件注册...
app.Run();

方式二：通过lambda表达式定义中间件

对于逻辑比较简单的场景，也可以直接使用Use方法传入lambda表达式定义中间件，无需单独创建类：

var app = builder.Build();

// 通过lambda定义请求头校验中间件
app.Use(async (context, next) =>
{
    // 检查请求头是否包含自定义标识
    if (!context.Request.Headers.ContainsKey("X-App-Version"))
    {
        context.Response.StatusCode = 400;
        await context.Response.WriteAsync("缺少X-App-Version请求头");
        return;
    }
    // 传递给下一个中间件
    await next();
});

app.Run();

中间件的执行顺序注意事项

中间件的注册顺序直接决定了请求的处理顺序，以下是我们配置中间件时需要遵循的常见顺序规则：

• 异常处理中间件通常放在最前面，这样可以捕获后续所有中间件抛出的异常
• HTTPS重定向、跨域等基础处理中间件放在异常处理之后，路由中间件之前
• 路由中间件之后才是端点映射中间件，因为端点中间件会终止请求管道，后续注册的中间件不会被执行
• 自定义的业务相关中间件根据需求放在合适的位置，比如请求日志中间件可以放在靠前位置，方便记录完整请求处理耗时

如果需要在响应返回时做处理，可以在调用next委托之后编写对应逻辑，这部分逻辑会在响应生成后执行，顺序和请求处理顺序相反。

中间件中的依赖注入配置

中间件类的构造函数中的依赖是通过应用启动时解析的，属于单例生命周期，如果需要在每个请求中解析不同实例的依赖，需要在InvokeAsync方法中通过HttpContext.RequestServices获取：

public class CustomMiddleware
{
    private readonly RequestDelegate _next;

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

    public async Task InvokeAsync(HttpContext context)
    {
        // 每个请求中解析瞬态或作用域服务
        var scopedService = context.RequestServices.GetRequiredService<IMyScopedService>();
        await scopedService.DoWork();
        
        await _next(context);
    }
}

这样就能保证每个请求使用的依赖实例是对应请求作用域内的，避免单例中间件持有短生命周期服务导致的问题。

Middleware.NET_Web_API请求管道依赖注入HTTP上下文修改时间：2026-07-04 04:57:30