如何在 ASP.NET Core 配置请求超时中间件

'# 如何在 ASP.NET Core 配置请求超时中间件

一、背景与问题

在分布式系统中，请求超时是常见的性能瓶颈和安全威胁。当请求处理时间超过预设阈值时，可能导致以下问题：

资源泄露（如数据库连接、内存占用）
服务雪崩（多个服务相互阻塞）
用户体验下降（等待时间过长）
安全风险（恶意用户耗尽服务器资源）

传统的解决方案包括：

服务端设置超时时间（如SQL Server的timeout参数）
客户端设置超时（如HttpClient的Timeout属性）
业务层主动控制处理时间

但这些方案都存在局限性：它们无法统一管理整个请求生命周期，也无法在中间件层进行全局控制。因此需要设计一个自定义的请求超时中间件，在请求进入业务逻辑前设置超时机制，确保整个请求流程在可控范围内。

二、基本原理

ASP.NET Core中间件通过IApplicationBuilder接口的Use方法注册，本质上是管道式处理。请求会按顺序经过每个中间件，每个中间件可以：

修改请求/响应
短路处理（next参数）
重定向请求

请求超时中间件的核心原理是：

在请求进入业务逻辑前设置超时时间
启动一个后台任务监控请求处理时间
如果超过阈值则触发超时处理
确保超时处理不影响其他请求

关键挑战在于：

如何在异步处理中准确判断超时
如何避免死锁（如使用CancellationTokenSource）
如何安全地中断长时间运行的业务逻辑

三、环境准备

创建ASP.NET Core项目（推荐.NET 6+）：

dotnet new webapi -n TimeoutMiddlewareDemo
cd TimeoutMiddlewareDemo

安装依赖（如使用Polly库）：
```
dotnet add package Polly
```

项目结构建议：

TimeoutMiddlewareDemo/
├── Controllers/
├── Services/
├── Middlewares/
│   └── TimeoutMiddleware.cs
├── Startup.cs
└── Program.cs

四、核心实现

1. 基础中间件实现（基于CancellationToken）

// Middlewares/TimeoutMiddleware.cs
public class TimeoutMiddleware
{
    private readonly RequestDelegate _next;
    private readonly TimeSpan _timeout;

    public TimeoutMiddleware(RequestDelegate next, IConfiguration configuration)
    {
        _next = next;
        _timeout = configuration.GetSection("TimeoutSettings").Get<TimeoutSettings>().MaxTimeout;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var tokenSource = new CancellationTokenSource();
        var timeoutToken = tokenSource.Token;

        // 记录请求开始时间
        var startTime = DateTime.UtcNow;

        // 启动后台任务监控超时
        var task = Task.Run(async () =>
        {
            await Task.Delay(_timeout, timeoutToken);
            if (!timeoutToken.IsCancellationRequested)
            {
                // 触发超时处理
                await HandleTimeout(context, startTime);
                tokenSource.Cancel();
            }
        });

        try
        {
            // 继续处理请求
            await _next(context);
        }
        catch (OperationCanceledException)
        {
            // 超时处理逻辑
            await HandleTimeout(context, startTime);
        }
        finally
        {
            // 确保后台任务终止
            await task;
        }
    }

    private async Task HandleTimeout(HttpContext context, DateTime startTime)
    {
        var elapsed = DateTime.UtcNow - startTime;
        context.Response.StatusCode = 408; // Request Timeout
        await context.Response.WriteAsync($"Request timeout after {elapsed.TotalSeconds:F2} seconds");
    }
}

关键点解释：

使用CancellationTokenSource控制超时
通过Task.Delay监控超时时间
在finally块确保后台任务终止
自定义超时处理逻辑（返回408状态码）

2. 使用Polly库的高级实现

// Startup.cs
public void Configure(IApplicationBuilder app, IHostEnvironment env)
{
    // 配置Polly超时策略
    var timeoutPolicy = Policy
        .TimeoutAsync(TimeSpan.FromSeconds(5), TimeoutStrategy.Pessimistic)
        .Handle<OperationCanceledException>()
        .FallbackAsync(async (context, ct) =>
        {
            var response = new HttpResponseMessage(HttpStatusCode.RequestTimeout);
            response.Content = new StringContent("Request timeout");
            return response;
        });

    app.Use(async (context, next) =>
    {
        await timeoutPolicy.ExecuteAsync(async () =>
        {
            await next();
        });
    });
}

对比分析：

方案	优点	缺点
基础实现	简单直接	不支持重试、降级等策略
Polly	功能丰富	需引入额外依赖，配置复杂

3. 带日志记录的完整中间件（含异常处理）

// Middlewares/TimeoutMiddlewareWithLogging.cs
public class TimeoutMiddlewareWithLogging
{
    private readonly RequestDelegate _next;
    private readonly ILogger<TimeoutMiddlewareWithLogging> _logger;
    private readonly TimeSpan _timeout;

    public TimeoutMiddlewareWithLogging(
        RequestDelegate next,
        ILogger<TimeoutMiddlewareWithLogging> logger,
        IConfiguration configuration)
    {
        _next = next;
        _logger = logger;
        _timeout = configuration.GetSection("TimeoutSettings").Get<TimeoutSettings>().MaxTimeout;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var tokenSource = new CancellationTokenSource();
        var timeoutToken = tokenSource.Token;

        var startTime = DateTime.UtcNow;

        var task = Task.Run(async () =>
        {
            await Task.Delay(_timeout, timeoutToken);
            if (!timeoutToken.IsCancellationRequested)
            {
                _logger.LogWarning("Request {Id} timeout after {Seconds} seconds", context.TraceIdentifier, _timeout.TotalSeconds);
                await HandleTimeout(context, startTime);
                tokenSource.Cancel();
            }
        });

        try
        {
            _logger.LogInformation("Processing request {Id} at {Time}", context.TraceIdentifier, startTime);
            await _next(context);
        }
        catch (OperationCanceledException ex)
        {
            _logger.LogWarning(ex, "Request {Id} canceled", context.TraceIdentifier);
            await HandleTimeout(context, startTime);
        }
        finally
        {
            await task;
        }
    }

    private async Task HandleTimeout(HttpContext context, DateTime startTime)
    {
        var elapsed = DateTime.UtcNow - startTime;
        context.Response.StatusCode = 408;
        await context.Response.WriteAsync($"Request timeout after {elapsed.TotalSeconds:F2} seconds");
    }
}

五、完整案例

1. 创建测试接口

// Controllers/TimeoutController.cs
[ApiController]
[Route("[controller]")]
public class TimeoutController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        // 模拟长时间处理
        Thread.Sleep(3000);
        return Ok("Success");
    }
}

2. 配置中间件

// Startup.cs
public void Configure(IApplicationBuilder app, IHostEnvironment env)
{
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });

    // 注册自定义中间件
    app.UseMiddleware<TimeoutMiddlewareWithLogging>();
}

3. 配置文件（appsettings.json）

{
  "TimeoutSettings": {
    "MaxTimeout": "5s"
  }
}

4. 测试流程

发送GET请求到/timeout接口
中间件记录请求开始时间
3秒后模拟处理完成（返回200）
若未完成则触发超时（返回408）

六、源码解析

重点分析HandleTimeout方法：

private async Task HandleTimeout(HttpContext context, DateTime startTime)
{
    var elapsed = DateTime.UtcNow - startTime;
    context.Response.StatusCode = 408;
    await context.Response.WriteAsync($"Request timeout after {elapsed.TotalSeconds:F2} seconds");
}

该方法在超时触发时执行
设置HTTP 408状态码
记录超时耗时
直接写入响应内容（避免阻塞）

七、进阶使用

1. 结合限流中间件

app.UseMiddleware<RateLimitMiddleware>();
app.UseMiddleware<TimeoutMiddlewareWithLogging>();

2. 动态调整超时时间

var timeout = configuration.GetSection("TimeoutSettings")
    .Get<TimeoutSettings>().GetDynamicTimeout(HttpContext.Request.Headers["User-Agent"]);

3. 支持重试机制

var retryPolicy = Policy
    .Handle<TimeoutException>()
    .Retry(3);

八、性能与工程实践

1. 性能优化建议

使用TimeSpan而非DateTime计算耗时
避免频繁创建CancellationTokenSource
对关键业务逻辑进行性能监控
使用Polly的PolicyWrap组合策略

2. 异常处理建议

捕获OperationCanceledException避免程序崩溃
使用try/catch块包裹业务逻辑
记录超时日志用于后续分析

3. 安全风险分析

恶意请求可能触发大量超时处理
需要配合限流策略防止DDoS
避免暴露敏感信息（如数据库连接字符串）

九、常见问题与踩坑

1. 超时未生效

// 错误示例：未正确处理异步任务
await _next(context);
await task;

问题：await _next(context)会阻塞当前线程，导致task无法执行
解决：使用Task.Run或async/await配合CancellationToken

2. 死锁问题

// 错误示例：未正确取消任务
await Task.Delay(1000);

问题：未传递cancellationToken导致任务无法终止
解决：使用Task.Delay(timeout, cancellationToken)

3. 超时处理未记录日志

问题：未配置日志记录导致问题排查困难
解决：在中间件中注入ILogger并记录关键节点

十、最佳实践

推荐场景：
- 长周期业务处理（如文件上传、大数据计算）
- 依赖外部服务的接口
- 需要统一错误处理的业务模块
不推荐场景：
- 实时性要求极高的接口（如金融交易）
- 需要等待外部服务响应的场景
- 超时时间极短（<1秒）的接口
配置建议：
- 超时时间应设置为业务逻辑的平均耗时的1.5倍
- 保留30%的缓冲时间应对突发流量
- 对关键接口使用Polly组合策略

十一、总结

ASP.NET Core请求超时中间件是保障系统稳定性的关键组件。通过自定义中间件，可以实现对请求处理时间的全局控制，避免资源泄露和雪崩效应。本文深入分析了不同实现方案，提供了完整的代码示例和最佳实践，涵盖性能优化、安全风险和常见问题。在实际开发中，应根据业务需求选择合适方案，配合限流、重试等策略，构建健壮的分布式系统。