ASP.NET Core Web API 错误处理指南

前言

在开发 ASP.NET Core Web API 时，合理的错误处理机制对于构建健壮的应用程序至关重要。本文将深入探讨 ASP.NET Core 中控制器式 Web API 的错误处理策略，帮助开发者构建更可靠的 API 服务。

开发环境错误处理

开发者异常页面

在开发环境中，ASP.NET Core 提供了开发者异常页面（Developer Exception Page），它能显示详细的错误堆栈信息：

// 示例控制器动作，故意抛出异常
public IActionResult ThrowError()
{
    throw new Exception("示例异常");
}

当访问此端点时，开发者异常页面会返回两种格式的响应：

1. 纯文本格式：包含详细的堆栈跟踪信息
2. HTML格式：更友好的可视化错误页面（需设置请求头 Accept: text/html）

重要提示：开发者异常页面仅应在开发环境中启用，生产环境必须禁用，以避免泄露敏感信息。

生产环境错误处理

异常处理中间件

在生产环境中，推荐使用异常处理中间件来生成标准化的错误响应：

// Program.cs 中配置
app.UseExceptionHandler("/error");

然后创建一个处理错误的控制器动作：

[Route("/error")]
[ApiExplorerSettings(IgnoreApi = true)]  // 从OpenAPI文档中排除
public IActionResult HandleError()
{
    // 返回RFC 7807兼容的问题详情响应
    return Problem(
        detail: "服务器发生错误",
        statusCode: StatusCodes.Status500InternalServerError
    );
}

统一开发与生产环境的错误格式

为了保持环境间的一致性，可以这样配置：

// 根据环境配置不同的错误路径
if (app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/error-development");
}
else
{
    app.UseExceptionHandler("/error");
}

对应的控制器动作：

[Route("/error")]
public IActionResult HandleError() { /* 生产环境处理 */ }

[Route("/error-development")]
public IActionResult HandleErrorDevelopment() { /* 开发环境处理 */ }

高级错误处理技术

自定义异常响应

可以通过自定义异常和过滤器来修改响应：

1. 创建自定义异常类型：

public class HttpResponseException : Exception
{
    public int StatusCode { get; }
    public HttpResponseException(int statusCode, string message) 
        : base(message) => StatusCode = statusCode;
}

2. 实现异常过滤器：

public class HttpResponseExceptionFilter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext context) { }
    
    public void OnActionExecuted(ActionExecutedContext context)
    {
        if (context.Exception is HttpResponseException httpResponseException)
        {
            context.Result = new ObjectResult(httpResponseException.Message)
            {
                StatusCode = httpResponseException.StatusCode
            };
            context.ExceptionHandled = true;
        }
    }
}

3. 注册过滤器：

builder.Services.AddControllers(options =>
{
    options.Filters.Add<HttpResponseExceptionFilter>();
});

验证失败响应

对于模型验证失败的情况，可以自定义响应格式：

builder.Services.Configure<ApiBehaviorOptions>(options =>
{
    options.InvalidModelStateResponseFactory = context =>
    {
        var problemDetails = new ValidationProblemDetails(context.ModelState)
        {
            Type = "https://tools.ietf.org/html/rfc7231#section-6.5.1",
            Title = "验证失败",
            Status = StatusCodes.Status400BadRequest,
            Detail = "请查看errors字段获取详细信息",
            Instance = context.HttpContext.Request.Path
        };
        
        return new BadRequestObjectResult(problemDetails)
        {
            ContentTypes = { "application/problem+json", "application/problem+xml" }
        };
    };
});

问题详情服务

ASP.NET Core 提供了问题详情服务（Problem Details Service）来标准化错误响应：

// 启用问题详情服务
builder.Services.AddProblemDetails();

// 配置中间件
app.UseExceptionHandler();
app.UseStatusCodePages();

自定义问题详情

可以进一步定制问题详情响应：

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Extensions.Add("timestamp", DateTime.UtcNow);
        if (ctx.HttpContext.GetEndpoint()?.Metadata.GetMetadata<MathErrorAttribute>() is { } mathError)
        {
            ctx.ProblemDetails.Type = mathError.ErrorType;
            ctx.ProblemDetails.Title = mathError.Title;
        }
    };
});

最佳实践总结

1. 环境区分：开发环境显示详细错误，生产环境返回标准化响应
2. 统一格式：使用RFC 7807标准的问题详情格式
3. 适当抽象：通过自定义异常和过滤器实现业务错误处理
4. 验证处理：为模型验证失败提供清晰的错误信息
5. 安全考虑：避免在生产环境泄露敏感信息

通过合理运用这些技术，可以构建出既健壮又易于维护的ASP.NET Core Web API服务。