ASP.NET Core 全局异常处理

一、引言

在ASP.NET Core 的开发过程中，全局异常处理是保障应用程序健壮性与稳定性的关键环节。当应用程序遭遇未预料的错误时，妥善的异常处理机制不仅能够避免程序崩溃，还能为用户提供清晰、友好的反馈，同时帮助开发者快速定位和解决问题。

在实际应用场景中，假设我们正在开发一个在线商城系统。当用户进行商品下单操作时，可能由于网络波动、数据库连接异常或业务逻辑错误等原因，导致订单提交失败。如果没有良好的全局异常处理机制，用户可能会看到一个空白页面或系统报错信息，这无疑会极大地影响用户体验，甚至可能导致用户流失。而通过实施全局异常处理，我们可以捕获这些异常，向用户展示诸如 “订单提交失败，请稍后重试” 的友好提示，同时在后台记录详细的异常信息，方便开发人员排查问题。

本文将深入探讨在ASP.NET Core 中实现全局异常处理的多种方式，涵盖中间件、过滤器等技术手段，并结合实际代码示例，详细阐述如何构建高效、可靠的全局异常处理方案，助力开发者打造更加稳定、健壮的ASP.NET Core 应用程序。

二、为什么需要全局异常处理

在ASP.NET Core 开发中，全局异常处理扮演着举足轻重的角色，其重要性主要体现在以下几个关键方面：

（一）统一错误响应

在一个大型的ASP.NET Core 应用程序中，可能存在众多的控制器和接口。如果没有全局异常处理机制，各个地方出现异常时返回给客户端的响应格式和内容可能会千差万别。这会给客户端的解析和处理带来极大的困扰。而通过全局异常处理，我们能够确保所有的异常都以统一的格式返回给客户端。例如，我们可以定义一个标准的错误响应模型，包含错误码、错误信息和详细描述等字段，如下所示：

public class ErrorResponse
{public int ErrorCode { get; set; }public string ErrorMessage { get; set; }public string Details { get; set; }
}

在全局异常处理逻辑中，无论何处发生异常，都将按照这个模型进行响应的构建，从而极大地提高了客户端处理错误的效率和准确性。

（二）避免敏感信息泄露

当应用程序发生异常时，如果直接将异常的详细信息（如堆栈跟踪、数据库连接字符串等）返回给客户端，可能会导致敏感信息泄露，给系统带来严重的安全隐患。例如，在一个电商系统中，如果数据库连接出现异常，若未经过全局异常处理，可能会将数据库的用户名、密码等信息暴露给恶意用户。通过全局异常处理，我们可以对异常信息进行过滤和处理，只向客户端返回友好的、非敏感的错误提示，如 “服务器内部错误，请稍后重试”，同时在服务器端记录详细的异常信息，以便后续排查问题。

（三）提升用户体验

良好的用户体验是一个成功应用程序的重要标志。当用户在使用ASP.NET Core 应用程序时遇到异常，如果没有全局异常处理，可能会看到一个空白页面、报错信息或程序崩溃，这无疑会使用户感到困惑和不满，甚至可能导致用户流失。而通过全局异常处理，我们可以捕获异常并向用户返回友好、清晰的错误信息，例如 “您的操作失败，请检查输入信息是否正确”，让用户能够清楚地了解问题所在，从而提高用户对应用程序的满意度和信任度。

（四）方便日志记录

在开发和维护ASP.NET Core 应用程序的过程中，详细的日志记录对于快速定位和解决问题至关重要。全局异常处理为我们提供了一个集中记录异常信息的地方。通过在全局异常处理逻辑中集成日志记录功能，我们可以记录异常的类型、发生时间、详细信息以及相关的上下文信息（如请求的 URL、请求参数等）。例如，使用ILogger接口进行日志记录：

private readonly ILogger<GlobalExceptionHandler> _logger;
public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
{_logger = logger;
}
public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{try{await next(context);}catch (Exception ex){_logger.LogError($"发生异常：{ex.Message}，请求路径：{context.Request.Path}，堆栈跟踪：{ex.StackTrace}");// 处理异常并返回响应}
}

这样，当出现问题时，开发人员可以通过查看日志快速定位问题的根源，大大提高了开发和维护的效率。

三、ASP.NET Core 中的异常处理机制剖析

在ASP.NET Core 的框架体系中，异常处理机制主要涵盖两个关键层级：中间件级别的异常处理以及控制器级别的异常处理。这两个层级相互协作，共同为应用程序的稳定性和可靠性提供坚实保障。下面，我们将深入剖析这两种异常处理机制的具体实现方式、特点以及它们在整个请求处理流程中所扮演的重要角色。

3.1 中间件级别的异常处理

异常中间件在ASP.NET Core 的请求处理管道中占据着至关重要的位置，它能够捕获整个请求处理过程中所抛出的各类异常，这其中包括但不限于在中间件自身执行过程、控制器的调用过程、动作方法的执行环节以及视图渲染阶段所产生的异常。异常中间件的实现方式主要有两种：一种是通过实现IMiddleware接口来创建自定义的异常处理中间件；另一种则是通过创建扩展方法来进行注册。

以实现IMiddleware接口为例，我们可以创建一个名为ExceptionHandlingMiddleware的自定义中间件类，具体代码如下：

public class ExceptionHandlingMiddleware : IMiddleware
{public async Task InvokeAsync(HttpContext context, RequestDelegate next){try{await next(context);}catch (Exception ex){// 在这里进行异常处理await HandleExceptionAsync(context, ex);}}private async Task HandleExceptionAsync(HttpContext context, Exception exception){context.Response.StatusCode = StatusCodes.Status500InternalServerError;var result = JsonConvert.SerializeObject(new{Success = false,Message = "An error occurred while processing your request.",Error = exception.Message});context.Response.ContentType = "application/json";await context.Response.WriteAsync(result);}
}

在上述代码中，InvokeAsync方法首先尝试调用下一个中间件（await next(context);）。如果在这个过程中捕获到异常，就会进入catch块，并调用HandleExceptionAsync方法进行异常处理。在HandleExceptionAsync方法中，我们设置了响应的状态码为 500（内部服务器错误），并将错误信息以 JSON 格式返回给客户端。

要将这个自定义的异常处理中间件注册到应用程序的请求处理管道中，我们需要在Startup.cs文件的Configure方法中进行如下配置：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{// 其他中间件注册...app.UseMiddleware<ExceptionHandlingMiddleware>();// 其他中间件注册...
}

异常中间件具有以下几个显著特点：

全局性：它能够捕获整个请求处理管道中的所有异常，无论是哪个环节出现问题，都能被其检测到并进行处理。这确保了应用程序在面对各种异常情况时，都能有一个统一的处理机制。
顺序性：在Startup.cs文件中，中间件的注册顺序至关重要。异常中间件需要被正确地配置在合适的位置，以确保它能够在其他可能抛出异常的中间件之后执行，从而有效地捕获到这些异常。
灵活性：开发者可以根据实际需求，在异常处理逻辑中进行高度自定义。例如，可以将异常信息记录到日志文件中，以便后续排查问题；也可以根据不同类型的异常，返回不同的错误响应格式，为客户端提供更精准的错误提示。

3.2 控制器级别的异常处理

MVC 异常过滤器是专门为ASP.NET Core MVC 应用程序量身定制的异常处理机制。它允许开发者针对特定的控制器或动作方法，精准地配置个性化的异常处理逻辑。这种针对性的处理方式，使得开发者能够在不同的业务场景下，根据具体需求对异常进行更细致、更灵活的处理。

要创建一个异常过滤器，我们可以通过实现IExceptionFilter或IAsyncExceptionFilter接口来达成。下面是一个实现IExceptionFilter接口的示例代码：

public class CustomExceptionFilter : IExceptionFilter
{public void OnException(ExceptionContext context){// 处理异常context.Result = new ContentResult{Content = "An error occurred.",StatusCode = StatusCodes.Status500InternalServerError};context.ExceptionHandled = true;}
}

在这个示例中，OnException方法在捕获到异常时被触发。在该方法中，我们设置了一个简单的错误响应内容和状态码，并将ExceptionHandled属性设置为true，表示该异常已经被处理，避免后续的默认异常处理机制再次介入。

异常过滤器的注册方式非常灵活，提供了多种选择，以满足不同的应用场景需求：

全局注册：在Startup.cs文件中，通过services.AddControllers(options => options.Filters.Add(new CustomExceptionFilter()));这行代码，可以将异常过滤器应用到整个应用程序的所有控制器和动作方法上。这种方式适用于需要对全局的异常进行统一处理的场景。
控制器级别注册：在控制器类上使用[TypeFilter(typeof(CustomExceptionFilter))]属性，这样该异常过滤器就只会对当前控制器及其所有的动作方法生效。当某个控制器有独特的异常处理需求，而与其他控制器不同时，这种注册方式就非常适用。
动作方法级别注册：在具体的动作方法上使用[ExceptionFilter(typeof(CustomExceptionFilter))]属性，此时该异常过滤器仅对标注的动作方法起作用。这种方式能够针对特定的动作方法，提供高度个性化的异常处理逻辑。

MVC 异常过滤器具有以下突出特点：

针对性：正如前面所提到的，它可以针对特定的控制器或动作方法进行异常处理逻辑的配置。这使得开发者能够根据不同业务模块的特点，定制专属的异常处理方案，提高了异常处理的精准性和有效性。
集成性：异常过滤器与 MVC 框架紧密集成，这意味着它可以直接访问ExceptionContext对象。通过这个对象，我们可以获取到丰富的上下文信息，例如当前的请求、响应、异常对象等，从而为异常处理提供了更多的依据和灵活性。
顺序性：在执行过程中，异常过滤器可以在多个不同的阶段对异常进行处理，比如OnException和OnExceptionAsync等方法。这使得开发者能够根据实际需求，在不同的时间点介入异常处理流程，实现更复杂、更精细的异常处理逻辑。

中间件级别的异常处理侧重于全局的、统一的异常捕获和处理，为整个应用程序提供了一个坚实的兜底保障；而控制器级别的异常处理则更强调针对性和灵活性，能够根据不同的业务场景和需求，对特定的控制器或动作方法进行个性化的异常处理。在实际的ASP.NET Core 应用开发中，我们通常会结合这两种异常处理机制，充分发挥它们各自的优势，以构建出健壮、稳定且具有良好用户体验的应用程序。

四、实现全局异常处理的具体步骤

4.1 创建自定义异常处理中间件

在ASP.NET Core 中，中间件是构建请求处理管道的重要组件，我们可以利用它来创建自定义的异常处理逻辑。以下是创建一个简单的全局异常处理中间件的示例代码：

using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using System;
using System.Net;
using System.Text.Json;
using System.Threading.Tasks;public class GlobalExceptionMiddleware
{private readonly RequestDelegate _next;private readonly ILogger<GlobalExceptionMiddleware> _logger;public GlobalExceptionMiddleware(RequestDelegate next, ILogger<GlobalExceptionMiddleware> logger){_next = next;_logger = logger;}public async Task InvokeAsync(HttpContext context){try{await _next(context);}catch (Exception ex){_logger.LogError($"发生异常: {ex.Message}，堆栈跟踪: {ex.StackTrace}");await HandleExceptionAsync(context, ex);}}private async Task HandleExceptionAsync(HttpContext context, Exception exception){context.Response.ContentType = "application/json";context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;var errorResponse = new{StatusCode = context.Response.StatusCode,Message = "服务器内部错误",Error = exception.Message};await context.Response.WriteAsync(JsonSerializer.Serialize(errorResponse));}
}

在上述代码中，GlobalExceptionMiddleware类实现了InvokeAsync方法。在该方法中，首先尝试调用下一个中间件（await _next(context);）。如果在这个过程中捕获到异常，就会进入catch块。在catch块中，使用ILogger记录异常信息，包括异常消息和堆栈跟踪，然后调用HandleExceptionAsync方法来处理异常。

HandleExceptionAsync方法负责设置响应的内容类型为application/json，状态码为500 Internal Server Error，并将错误信息以 JSON 格式返回给客户端。这里定义的错误响应包含了状态码、通用的错误消息以及具体的异常信息。

4.2 注册中间件

创建好自定义的异常处理中间件后，需要将其注册到ASP.NET Core 应用程序的请求处理管道中，以便它能够在请求处理过程中捕获异常。注册中间件的操作通常在Startup.cs文件的Configure方法中完成。以下是具体的注册代码：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;public class Startup
{public void ConfigureServices(IServiceCollection services){// 其他服务注册...}public void Configure(IApplicationBuilder app, IWebHostEnvironment env){if (env.IsDevelopment()){app.UseDeveloperExceptionPage();}else{app.UseExceptionHandler("/Error");app.UseHsts();}app.UseMiddleware<GlobalExceptionMiddleware>();// 其他中间件注册...app.UseRouting();app.UseEndpoints(endpoints =>{endpoints.MapControllers();});}
}

在上述代码中，app.UseMiddleware();这行代码将我们之前创建的GlobalExceptionMiddleware注册到了请求处理管道中。需要注意的是，中间件的注册顺序非常重要。一般来说，异常处理中间件应该尽量在管道的较前面进行注册，这样它才能捕获到后续中间件以及控制器中可能抛出的异常。

在Configure方法中，首先根据应用程序的运行环境进行了不同的配置。在开发环境中（env.IsDevelopment()为true），使用app.UseDeveloperExceptionPage();来显示详细的开发者异常页面，这有助于在开发过程中快速定位和解决问题。而在生产环境中，使用app.UseExceptionHandler(“/Error”);来指定一个统一的错误处理页面，同时使用app.UseHsts();来添加 HSTS（HTTP 严格传输安全）头部，增强应用程序的安全性。

4.3 测试全局异常处理

为了验证全局异常处理中间件是否能够正常工作，我们可以创建一个简单的 API 端点，并在该端点中故意抛出一个异常，然后观察应用程序的响应。以下是创建测试控制器的代码示例：

using Microsoft.AspNetCore.Mvc;[ApiController]
[Route("[controller]")]
public class TestController : ControllerBase
{[HttpGet("throwException")]public IActionResult ThrowException(){throw new Exception("这是一个测试异常");}
}

在上述代码中，TestController类定义了一个名为ThrowException的 HTTP GET 方法。当访问/Test/throwException这个端点时，该方法会故意抛出一个异常。

启动ASP.NET Core 应用程序后，使用工具（如 Postman）访问/Test/throwException。如果全局异常处理中间件配置正确，应该能够看到返回的 HTTP 状态码为 500，并且响应体中包含了我们在GlobalExceptionMiddleware中定义的错误信息，类似于以下内容：

{"StatusCode": 500,"Message": "服务器内部错误","Error": "这是一个测试异常"
}

通过这样的测试，我们可以验证全局异常处理中间件确实能够捕获到应用程序中抛出的异常，并按照我们定义的方式进行处理和响应。这确保了在应用程序运行过程中，即使出现未预料到的异常，也能为用户提供友好的错误提示，同时在服务器端记录详细的异常信息，方便开发人员进行问题排查和修复。

五、改进全局异常处理

5.1 处理不同类型的异常

在实际应用中，不同类型的异常往往需要不同的处理方式，以提供更精准的错误反馈和更好的用户体验。我们可以通过检查异常的类型，来返回不同的 HTTP 状态码或错误信息。以下是在HandleExceptionAsync方法中添加对不同类型异常处理的示例代码：

private async Task HandleExceptionAsync(HttpContext context, Exception exception)
{context.Response.ContentType = "application/json";if (exception is UnauthorizedAccessException){context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;var errorResponse = new{StatusCode = context.Response.StatusCode,Message = "未经授权的访问",Error = exception.Message};await context.Response.WriteAsync(JsonSerializer.Serialize(errorResponse));}else if (exception is ArgumentException){context.Response.StatusCode = (int)HttpStatusCode.BadRequest;var errorResponse = new{StatusCode = context.Response.StatusCode,Message = "请求参数错误",Error = exception.Message};await context.Response.WriteAsync(JsonSerializer.Serialize(errorResponse));}else{context.Response.StatusCode = (int)HttpStatusCode.InternalServerError;var errorResponse = new{StatusCode = context.Response.StatusCode,Message = "服务器内部错误",Error = exception.Message};await context.Response.WriteAsync(JsonSerializer.Serialize(errorResponse));}
}

在上述代码中，当捕获到UnauthorizedAccessException异常时，将响应状态码设置为401 Unauthorized，并返回相应的错误信息，告知用户其访问未经授权。而当捕获到ArgumentException异常时，将响应状态码设置为400 Bad Request，表示请求参数存在问题，同时返回包含具体错误信息的响应。对于其他类型的异常，仍保持默认的500 Internal Server Error状态码和相应的错误提示。

5.2 记录更详细的日志信息

在生产环境中，为了更有效地进行调试和错误分析，记录详细的日志信息至关重要。我们可以利用ILogger来记录异常的堆栈跟踪、请求路径等详细信息。以下是修改后的InvokeAsync方法，展示了如何记录更详细的日志：

public async Task InvokeAsync(HttpContext context)
{try{await _next(context);}catch (Exception ex){_logger.LogError($"发生异常: {ex.Message}, 请求路径: {context.Request.Path}, 堆栈跟踪: {ex.StackTrace}");await HandleExceptionAsync(context, ex);}
}

在上述代码中，当捕获到异常时，_logger.LogError方法会记录详细的异常信息。其中，ex.Message记录了异常的具体消息，context.Request.Path记录了发生异常时的请求路径，这有助于我们快速定位到是哪个接口或页面出现了问题。ex.StackTrace则记录了异常的堆栈跟踪信息，通过它我们可以清晰地看到异常发生的调用堆栈顺序，从而更深入地分析异常产生的原因。这些详细的日志信息对于排查生产环境中的问题非常有帮助，能够大大提高我们解决问题的效率。

六、总结

在ASP.NET Core 开发中，全局异常处理是保障应用程序稳定性、提升用户体验以及便于开发人员调试的关键环节。通过本文介绍的在ASP.NET Core 中实现全局异常处理的方法，从创建自定义异常处理中间件、注册中间件到测试以及进一步的改进，我们能够构建出一个健壮的异常处理体系。它不仅能够统一处理应用程序中各种未预料到的异常情况，避免敏感信息泄露，还能为用户提供清晰、友好的错误反馈，同时通过详细的日志记录为开发人员快速定位和解决问题提供有力支持。

然而，异常处理的优化是一个持续的过程。随着应用程序的不断发展和业务逻辑的日益复杂，可能会出现更多类型的异常情况，需要我们不断地调整和完善异常处理机制。例如，在处理分布式系统中的异常时，可能需要考虑跨服务调用的异常传递和处理；在处理高并发场景下的异常时，需要确保异常处理的性能和效率。希望读者能够在实际项目中不断探索和实践，根据具体需求对全局异常处理进行进一步的优化和扩展，以打造出更加稳定、可靠的ASP.NET Core 应用程序。