C# 异常管理中间件教程

原创

已于 2025-04-12 15:56:35 修改 · 1.4k 阅读

标签

#c# #中间件 #开发语言

于 2025-04-12 15:05:37 首次发布

从零开始构建异常处理系统：完整教程与项目创建指南

1. 项目创建与初始化

步骤 1：创建 ASP.NET Core Web API 项目

# 使用 .NET 8 SDK 创建 Web API 项目
dotnet new webapi -n ExceptionHandlingDemo
cd ExceptionHandlingDemo

步骤 2：项目结构初始化

在项目根目录下创建以下文件夹和文件：

mkdir Exceptions Middleware Models Controllers
touch Exceptions/NotFoundException.cs Exceptions/ValidationException.cs
touch Middleware/ExceptionHandlingMiddleware.cs
touch Models/ErrorDetails.cs
touch Controllers/DemoController.cs

2. 项目结构（带图标）

📁 ExceptionHandlingDemo/           # 项目根目录
├── 📁 Exceptions/                  # 自定义异常类
│   ├── 📄 NotFoundException.cs     # 404 异常
│   └── 📄 ValidationException.cs   # 400 验证异常
├── 📁 Middleware/                  # 异常处理中间件
│   └── 📄 ExceptionHandlingMiddleware.cs
├── 📁 Models/                      # 错误响应模型
│   └── 📄 ErrorDetails.cs
├── 📁 Controllers/                 # 示例控制器
│   └── 📄 DemoController.cs
├── 📄 Program.cs                   # 主程序配置
├── 📄 appsettings.json            # 配置文件
└── 📄 SerilogConfig.json          # 日志配置（可选）

3. 代码实现与讲解

3.1 自定义异常（Exceptions）

`NotFoundException.cs`

namespace ExceptionHandlingDemo.Exceptions
{
   
   
    public class NotFoundException : Exception
    {
   
   
        public NotFoundException(string message) : base(message) {
   
    }
    }
}

作用：定义 404 状态码的异常，用于资源未找到场景。

`ValidationException.cs`

namespace ExceptionHandlingDemo.Exceptions
{
   
   
    public class ValidationException : Exception
    {
   
   
        public ValidationException(string message) : base(message) {
   
    }
    }
}

作用：定义 400 状态码的异常，用于输入验证失败场景。

3.2 错误响应模型（Models）

`ErrorDetails.cs`

using System.Text.Json;
using System.Text.Json.Serialization;

namespace ExceptionHandlingDemo.Models
{
   
   
    public class ErrorDetails
    {
   
   
        public int StatusCode {
   
    get; set; }
        public required string Message {
   
    get; set; }
        public string? Details {
   
    get; set; }

        public override string ToString() => 
            JsonSerializer.Serialize(this, new JsonSerializerOptions {
   
    
                PropertyNamingPolicy = JsonNamingPolicy.CamelCase 
            });
    }
}

作用：定义错误响应的结构，包含状态码、错误信息和详细堆栈跟踪（开发环境）。

3.3 异常处理中间件（Middleware）

`ExceptionHandlingMiddleware.cs`

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

namespace ExceptionHandlingDemo.Middleware
{
   
   
    public class ExceptionHandlingMiddleware
    {
   
   
        private readonly RequestDelegate _next;
        private readonly ILogger<ExceptionHandlingMiddleware> _logger;
        private readonly IWebHostEnvironment _env;

        public ExceptionHandlingMiddleware(
            RequestDelegate next,
            ILogger<ExceptionHandlingMiddleware> logger,
            IWebHostEnvironment env)
        {
   
   
            _next = next;
            _logger = logger;
            _env = env;
        }

        public async Task InvokeAsync(HttpContext context)
        {
   
   
            try
            {
   
   
                await _next(context);
            }
            catch (Exception ex)
            {
   
   
                await HandleExceptionAsync(context, ex);
            }
        }

        private async Task HandleExceptionAsync(HttpContext context, Exception ex)
        {
   
   
            var statusCode = GetStatusCode(ex);
            var message = GetErrorMessage(ex);
            
            // 🟢 记录日志
            _logger.LogError(ex, "Error: {Message}", ex.Message);

            // 🟢 设置响应格式
            context.Response.ContentType = "application/json";
            context.Response.StatusCode = statusCode;

            // 🟢 返回错误信息
            await context.Response.WriteAsync(new