用途:为 .NET 10 应用提供统一的错误处理策略,区分预期失败与异常情况,并规范 API 错误响应格式。
核心原则:预期失败(如“订单未找到”“校验失败”)使用 Result 模式,不抛异常;异常仅保留给真正意外的情况(数据库断连、空引用、网络超时),并交由全局处理器;每个 API 错误都返回符合 RFC 9457 的 ProblemDetails,包含 type、title、status、detail,可选 errors;校验在 API 边界完成,而非深入业务逻辑。
主要能力:Result 泛型类型承载值或错误列表,并提供 Result 到 ProblemDetails 的映射扩展;全局异常处理器捕获未处理异常并转为 ProblemDetails,生产环境不泄露细节,开发环境可输出异常消息;FluentValidation 配合通用端点过滤器 ValidationFilter<TRequest> 在请求进入处理器前校验,失败时返回 TypedResults.ValidationProblem;还提供类型化错误对象(NotFoundError、ValidationError、ConflictError)及到 HTTP 状态码的映射。
使用方式:在端点中调用 sender.Send 后判断 result.IsSuccess,成功返回 Created,失败调用 result.ToProblemDetails();在 Program.cs 中通过 app.UseExceptionHandler 注册全局处理;用 group.MapPost(...).AddEndpointFilter<ValidationFilter<CreateOrderRequest>>() 挂载校验过滤器。
适用场景:ASP.NET Core 最小 API、CQRS 处理器、需要一致错误契约的后端服务。
限制与反模式:不要用异常控制流程;不要从 API 返回原始错误字符串;不要捕获后静默吞掉异常;外部服务失败应捕获特定异常并返回 Result.Failure;错误日志建议使用带关联 ID 的结构化日志。具体安装命令与包版本资料未提供。