dotnet-exception-handling

.NET 异常处理质量改进

目的

系统地调查并修复 .NET 异常处理反模式。检测、记录并修复 .NET 应用程序中最常见的 10 个异常处理错误。

适用场景：准备发布到生产环境、代码质量审计、安全审查，或开始熟悉 .NET 代码库时。

用法

# Investigation only (default)
/dotnet-exception-handling <path-to-dotnet-project>

# Filter by severity
/dotnet-exception-handling <project-path> --priority critical

# Auto-implement all fixes
/dotnet-exception-handling <project-path> --fix-all

参数：

• project-path：包含 .csproj 或 .sln 的目录（默认：当前目录）
• --priority：critical | high | medium | low | all（默认：all）
• --fix-all：自动实施修复（默认：仅调查）

10 个常见错误

1. 捕获过于宽泛的异常 - 使用基类 Exception，而非特定类型
2. 悄无声息地吞掉异常 - 空的 catch 块会隐藏错误
3. 使用 throw ex; - 会重置堆栈跟踪（应使用 throw;）
4. 所有代码都用 Try/Catch 包裹 - 防御式编码造成冗杂
5. 将异常用于控制流 - 对预期情况而言会带来性能开销
6. 忘记等待异步操作 - 后台线程上的异常无法处理
7. 忽略后台任务异常 - 即发即弃会丢失错误
8. 使用通用异常类型 - 使用含糊的 new Exception()，而非特定类型
9. 丢失内部异常 - 破坏异常链
10. 缺少全局处理程序 - 没有集中式错误处理（堆栈跟踪会暴露）

详细说明、检测模式和修复模板 → 请参见 reference.md

执行工作流

阶段 1：调查（6 个步骤）

步骤 1：检测项目

• 扫描 .csproj、.sln 文件
• 识别项目类型（ASP.NET Core、工作者服务、库）
• 统计 C# 文件数量，以估算范围

步骤 2：并行分析

• 部署 5 个专用 Agent：
  • 后台工作者专家
  • API 层专家
  • 服务层专家
  • 数据层专家
  • 基础设施专家

步骤 3：检测违规

• 使用 rg -P（ripgrep PCRE 模式）进行模式匹配：

  # Mistake #1: Broad catches
  rg -P 'catch\s*\(Exception\b' --glob '*.cs'
  
  # Mistake #2: Empty catches
  rg -P 'catch[^{]*\{\s*(//[^\n]*)?\s*\}' --glob '*.cs'
  
  # Mistake #3: throw ex
  rg 'throw\s+ex;' --glob '*.cs'
  

• 完整模式列表请参见 reference.md

步骤 4：严重性分类

• CRITICAL：安全问题（堆栈跟踪暴露、缺少全局处理程序）
• HIGH：可靠性问题（吞掉异常、捕获范围过宽）
• MEDIUM：代码质量问题（过度使用 try/catch）
• LOW：风格问题

步骤 5：调查结果报告

• 生成包含文件:行号引用的 Markdown
• 代码片段 + 建议的修复方法
• 基于优先级的路线图

步骤 6：知识记录

• 保存到 .claude/runtime/logs/EXCEPTION_INVESTIGATION_YYYY-MM-DD.md
• 更新项目记忆

阶段 2：开发（如果指定 --fix-all）

步骤 7：编排默认工作流

• 根据调查结果创建 GitHub issue
• 为修复设置 worktree
• 实施 GlobalExceptionHandler、Result 等
• 编写全面的测试（TDD）
• 由三个 Agent 审查（审查、安全、理念）

步骤 8：验证

• 所有测试均通过
• 安全性：零堆栈跟踪
• 性能：p99 开销 <5ms

快速入门示例

示例 1：仅调查

/dotnet-exception-handling ./src/MyApi

输出：调查报告包含 23 项违规（1 项 CRITICAL、8 项 HIGH、12 项 MEDIUM、2 项 LOW）

示例 2：仅修复 CRITICAL 项

/dotnet-exception-handling ./src/MyApi --priority critical --fix-all

输出：GitHub issue + 实施 GlobalExceptionHandler 的 PR + 15 个测试

示例 3：完整修复

/dotnet-exception-handling ./src/MyApi --fix-all

输出：已修复 23 项违规，包含 67 个测试，PR 已就绪（CI 通过）

核心架构模式

GlobalExceptionHandler（IExceptionHandler）

ASP.NET Core 的集中式异常到 HTTP 映射：

public class GlobalExceptionHandler : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        var (statusCode, title) = exception switch
        {
            ArgumentException => (400, "Invalid request"),
            NotFoundException => (404, "Not found"),
            ConflictException => (409, "Conflict"),
            _ => (500, "Internal server error")
        };

        httpContext.Response.StatusCode = statusCode;
        await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Status = statusCode,
            Title = title,
            Detail = statusCode >= 500
                ? "An error occurred"
                : exception.Message
        }, cancellationToken);

        return true;
    }
}

// Registration in Program.cs
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
app.UseExceptionHandler();

优点：不暴露堆栈跟踪、响应一致、控制器中无需 try/catch

Result 模式

面向铁路的验证编程（对预期情况不使用异常）：

public Result<Order> ValidateOrder(CreateOrderDto dto)
{
    if (dto.Items.Count == 0)
        return Result<Order>.Failure("Order must have items");

    return Result<Order>.Success(new Order(dto));
}

// Controller usage
var result = await _service.ValidateOrder(dto);
return result.Match(
    onSuccess: order => Ok(order),
    onFailure: error => BadRequest(error)
);

优点：速度比异常处理快 100 倍、错误处理清晰明确、组合性更佳

完整实现 → 请参见 examples.md

导航指南

何时阅读辅助文件

reference.md - 在需要以下内容时阅读：

• 全部 10 种异常处理错误的详细说明
• ripgrep/grep 的完整检测模式
• 每种错误类型的修复模板
• 安全注意事项（符合 OWASP 要求、防止堆栈跟踪泄露）
• 严重性分类参考
• 集成模式（Azure SDK、EF Core、Service Bus）

examples.md - 在需要以下内容时阅读：

• 每种错误的修复前后代码示例
• 完整可运行的实现（GlobalExceptionHandler、Result、DbContextExtensions）
• 真实场景（订单处理、支付系统）
• 单元测试和集成测试模式
• 可直接复制粘贴的代码

patterns.md - 在需要以下内容时阅读：

• 架构决策树（全局处理器与 try/catch、Result 与异常）
• 后台工作线程异常处理模式
• Azure SDK 异常转换模式
• EF Core 并发和事务模式
• 性能基准（Result 与异常）
• 应避免的反模式

工作流集成

此技能编排两个规范工作流：

1. 调查工作流（第 1 阶段）：界定范围 → 探索 → 分析 → 分类 → 报告 → 记录
2. 默认工作流（第 2 阶段，若使用 --fix-all）：需求 → 架构 → TDD → 实现 → 审查 → CI/CD

参考资料

• 文章：Top 10 Exception Handling Mistakes in .NET
• Microsoft：Best Practices for Exceptions
• ASP.NET Core：Handle Errors in Web APIs
• 调查工作流：~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md
• 默认工作流：~/.amplihack/.claude/workflow/DEFAULT_WORKFLOW.md

版本历史

• v1.0.0（2026-02-10）：基于 CyberGym 调查的初始实现（修复了 52 个违规问题，包含 87 项测试）

已知限制

• IExceptionHandler 需要 .NET 6+
• Result 模式面向 C# 7.0+（readonly struct、表达式主体成员）
• 模式专用于 ASP.NET Core（可能不适用于类库）