Clean Architecture异常处理与全局错误处理：构建健壮的Web API服务

Clean Architecture异常处理与全局错误处理构建健壮的Web API服务【免费下载链接】CleanArchitectureASP.NET Core 6 Web API Clean Architecture Solution Template项目地址: https://gitcode.com/gh_mirrors/cleanarchitecture/CleanArchitecture在构建企业级ASP.NET Core Web API时异常处理是保证系统稳定性和用户体验的关键环节。Clean Architecture解决方案模板提供了一套完整的异常处理机制帮助开发者构建健壮的API服务。本文将为您深入解析Clean Architecture的异常处理体系展示如何实现全局错误处理和优雅的异常响应。为什么异常处理如此重要 ️在分布式系统中异常是不可避免的。没有良好的异常处理机制API可能会泄露敏感信息给客户端返回不一致的错误格式导致客户端无法正确处理错误难以进行问题排查和监控Clean Architecture通过分层架构和统一的异常处理策略解决了这些问题。Clean Architecture异常处理的核心架构1. 异常过滤器全局异常捕获Clean Architecture使用ApiExceptionFilterAttribute作为全局异常过滤器这是异常处理的第一道防线// src/Apps/CleanArchitecture.Api/Filters/ApiExceptionFilterAttribute.cs public class ApiExceptionFilterAttribute : ExceptionFilterAttribute { private readonly IDictionaryType, ActionExceptionContext _exceptionHandlers; public ApiExceptionFilterAttribute() { _exceptionHandlers new DictionaryType, ActionExceptionContext { { typeof(ValidationException), HandleValidationException }, { typeof(NotFoundException), HandleNotFoundException }, { typeof(UnauthorizedAccessException), HandleUnauthorizedAccessException }, { typeof(ForbiddenAccessException), HandleForbiddenAccessException }, }; } }这个过滤器会自动捕获Controller层抛出的所有异常并根据异常类型进行相应的处理。2. 统一的异常类型体系Clean Architecture定义了一系列标准化的异常类型异常类型HTTP状态码使用场景ValidationException400参数验证失败NotFoundException404资源不存在UnauthorizedAccessException401未授权访问ForbiddenAccessException403权限不足ValidateModelException400模型状态验证失败每个异常类型都有明确的职责确保错误信息的准确传达。3. ServiceResult统一的响应格式所有API响应都使用ServiceResultT包装确保响应格式的一致性// src/Common/CleanArchitecture.Application/Common/Models/ServiceResult.cs public class ServiceResultT : ServiceResult { public T Data { get; set; } public ServiceResult(T data) { Data data; } }错误响应包含标准化的错误代码和消息// src/Common/CleanArchitecture.Application/Common/Models/ServiceError.cs public static ServiceError DefaultError new ServiceError(An exception occured., 999); public static ServiceError NotFound new ServiceError(The specified resource was not found., 990); public static ServiceError Validation new ServiceError(One or more validation errors occurred., 900);实战异常处理流程详解第1步配置全局异常过滤器在Startup.cs中注册异常过滤器// src/Apps/CleanArchitecture.Api/Startup.cs services.AddControllers(options options.Filters.AddApiExceptionFilterAttribute()) .AddFluentValidation(x x.AutomaticValidationEnabled false);第2步异常处理中间件配置根据环境配置不同的异常处理策略// src/Apps/CleanArchitecture.Api/Startup.cs if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); app.UseMigrationsEndPoint(); } else { app.UseExceptionHandler(/Error); app.UseHsts(); }第3步MediatR管道异常处理Clean Architecture使用MediatR实现CQRS模式通过UnhandledExceptionBehaviour处理应用层异常// src/Common/CleanArchitecture.Application/Common/Behaviours/UnhandledExceptionBehaviour.cs public async TaskTResponse Handle(TRequest request, CancellationToken cancellationToken, RequestHandlerDelegateTResponse next) { try { return await next(); } catch (Exception ex) { var requestName typeof(TRequest).Name; _logger.LogError(ex, CleanArchitecture Request: Unhandled Exception for Request {Name} {Request}, requestName, request); throw; } }完整的异常处理流程示例让我们通过一个用户注册的场景看看异常处理的完整流程1. 参数验证异常当用户提交无效数据时系统会抛出ValidationException// 验证失败时抛出异常 throw new ValidationException(failures);异常过滤器捕获后返回{ succeeded: false, error: { message: One or more validation errors occurred., code: 900 }, errors: { Email: [Email格式不正确], Password: [密码长度至少8位] } }2. 资源不存在异常当查询不存在的用户时// 在服务层 var user await _context.Users.FindAsync(id); if (user null) { throw new NotFoundException($用户 {id} 不存在); }返回响应{ succeeded: false, error: { message: 用户 123 不存在, code: 990 } }3. 权限异常处理当用户尝试访问未授权的资源if (!await _authorizationService.AuthorizeAsync(user, resource, policy)) { throw new ForbiddenAccessException(); }返回响应{ succeeded: false, error: { message: You are not authorized to call this action., code: 998 } }最佳实践与配置建议1. 日志记录策略Clean Architecture集成了Serilog进行结构化日志记录// src/Apps/CleanArchitecture.Api/Program.cs .UseSerilog(((context, configuration) { configuration.Enrich.FromLogContext() .Enrich.WithMachineName() .WriteTo.Console() .WriteTo.Elasticsearch(...) .Enrich.WithProperty(Environment, context.HostingEnvironment.EnvironmentName) .ReadFrom.Configuration(context.Configuration); }))2. 开发与生产环境差异化配置开发环境显示详细错误信息便于调试生产环境隐藏敏感信息记录到日志系统3. 自定义异常扩展您可以根据业务需求扩展异常类型public class BusinessException : Exception { public string ErrorCode { get; } public BusinessException(string message, string errorCode) : base(message) { ErrorCode errorCode; } }然后在异常过滤器中注册处理逻辑。监控与告警健康检查集成Clean Architecture内置健康检查端点services.AddHealthChecks() .AddDbContextCheckApplicationDbContext(); app.UseHealthChecks(/health);异常监控建议集成APM工具如Application Insights、Datadog设置告警规则针对特定错误代码设置告警错误仪表盘监控错误率和趋势常见问题排查Q1为什么我的自定义异常没有被正确处理确保在ApiExceptionFilterAttribute中注册了您的异常类型_exceptionHandlers.Add(typeof(YourCustomException), HandleYourCustomException);Q2如何返回自定义错误消息使用ServiceError.CustomMessage()var details ServiceResult.Failed(ServiceError.CustomMessage(自定义错误消息));Q3如何处理未知异常系统会自动处理未知异常返回500状态码和标准错误信息同时记录详细日志。总结Clean Architecture的异常处理体系提供了一套完整、可扩展的解决方案✅统一响应格式所有API响应遵循相同结构✅分层异常处理从Controller到Application层都有相应的处理机制✅环境感知开发环境提供详细信息生产环境保护敏感数据✅易于扩展支持自定义异常类型和处理逻辑✅完整监控集成结构化日志和健康检查通过这套异常处理机制您可以构建出既健壮又易于维护的Web API服务。记住好的异常处理不仅仅是捕获错误更是提供清晰的错误信息、保持系统稳定性和改善用户体验的关键。现在您已经掌握了Clean Architecture异常处理的精髓开始构建更健壮的API服务吧【免费下载链接】CleanArchitectureASP.NET Core 6 Web API Clean Architecture Solution Template项目地址: https://gitcode.com/gh_mirrors/cleanarchitecture/CleanArchitecture创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考