ln-772-error-handler-setup

ln-772-error-handler-setup

类型： L3 Worker 类别： 7XX 项目引导

为 .NET 和 Python 后端应用配置全局错误处理。

---

概述

方面	详情
输入	来自 ln-770 的 Context Store
输出	异常处理中间件和自定义异常
技术栈	.NET（ASP.NET Core 中间件）、Python（FastAPI 异常处理器）

---

阶段 1：接收上下文

从协调器接收 Context Store。

必需上下文：

• STACK：.NET 或 Python
• FRAMEWORK：ASP.NET Core 或 FastAPI
• PROJECT_ROOT：项目目录路径
• ENVIRONMENT：Development 或 Production

幂等性检查：

• .NET：搜索 GlobalExceptionMiddleware 或 UseExceptionHandler
• Python：搜索 @app.exception_handler 或 exception_handlers.py
• 如果找到：返回 { "status": "skipped" }

---

阶段 2：调研错误处理模式

使用 MCP 工具获取最新文档。

针对 .NET：

MCP ref: "ASP.NET Core global exception handling middleware"
Context7: /dotnet/aspnetcore

针对 Python：

MCP ref: "FastAPI exception handlers custom exceptions"
Context7: /tiangolo/fastapi

需要调研的关键模式：

1. 中间件管道中的位置
2. 异常类型到 HTTP 状态码的映射
3. ProblemDetails（RFC 7807）格式
4. Development 与 Production 环境中的错误详情
5. 日志集成

---

阶段 3：决策点

Q1：错误响应格式

选项	描述
ProblemDetails（RFC 7807）（推荐）	标准化格式，广泛采用
自定义格式	项目特定要求

Q2：错误详情级别

环境	堆栈跟踪	内部异常	请求详情
Development	✓ 显示	✓ 显示	✓ 显示
Production	✗ 隐藏	✗ 隐藏	✗ 隐藏

Q3：错误分类

定义标准错误代码：

代码	HTTP 状态	描述
VALIDATION_ERROR	400	输入数据无效
UNAUTHORIZED	401	需要身份验证
FORBIDDEN	403	权限不足
NOT_FOUND	404	未找到资源
CONFLICT	409	资源状态冲突
INTERNAL_ERROR	500	意外的服务端错误

---

阶段 4：生成配置

.NET 输出文件

文件	用途
Middleware/GlobalExceptionMiddleware.cs	异常处理中间件
Exceptions/AppException.cs	基础异常类
Exceptions/ValidationException.cs	验证错误
Exceptions/NotFoundException.cs	未找到错误
Models/ErrorResponse.cs	错误响应模型

生成流程：

1. 使用 MCP ref 获取当前 ASP.NET Core 异常处理模式
2. 生成 GlobalExceptionMiddleware，其中包含：
   • 异常类型到 HTTP 状态码的映射
   • 异常日志记录
   • ProblemDetails 响应格式
   • 根据环境调整详情级别
3. 生成自定义异常类

注册代码：

app.UseMiddleware<GlobalExceptionMiddleware>();

Python 输出文件

文件	用途
exceptions/app_exceptions.py	自定义异常类
exceptions/handlers.py	FastAPI 异常处理器
models/error_response.py	Pydantic 错误模型

生成流程：

1. 使用 MCP ref 获取当前 FastAPI 异常处理模式
2. 生成异常处理器，其中包含：
   • HTTPException 处理
   • 自定义 AppException 处理
   • 验证错误处理
   • 请求验证错误处理
3. 生成自定义异常类

注册代码：

app.add_exception_handler(AppException, app_exception_handler)
app.add_exception_handler(RequestValidationError, validation_exception_handler)

---

阶段 5：验证

验证步骤：

1. 语法检查：

   • .NET：dotnet build --no-restore
   • Python：python -m py_compile exceptions/handlers.py

2. 测试错误处理：

   • 创建会抛出异常的测试端点
   • 验证错误响应格式
   • 检查 Production 环境中是否隐藏堆栈跟踪

预期错误响应（ProblemDetails）：

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid input data",
  "instance": "/api/users",
  "errors": [
    { "field": "email", "message": "Invalid email format" }
  ],
  "traceId": "abc-123-def-456"
}

---

返回协调器

{
  "status": "success",
  "files_created": [
    "Middleware/GlobalExceptionMiddleware.cs",
    "Exceptions/AppException.cs",
    "Models/ErrorResponse.cs"
  ],
  "packages_added": [],
  "registration_code": "app.UseMiddleware<GlobalExceptionMiddleware>();",
  "message": "Configured global exception handling"
}

---

参考链接

• ASP.NET Core 错误处理
• FastAPI 错误处理
• RFC 7807 问题详情

---

关键规则

• 默认使用 ProblemDetails (RFC 7807) — 标准化的错误响应格式
• 在 Production 中隐藏堆栈跟踪 — 必须根据环境调整详情级别
• 使用 MCP ref 获取当前模式 — 不要凭记忆硬编码中间件
• 保持幂等 — 如果已存在 GlobalExceptionMiddleware 或 exception_handlers.py，返回 status: "skipped"
• 将所有自定义异常映射到 HTTP 状态码 — 不得有未处理的异常类型传递给客户端

完成标准

• 已接收 Context Store（技术栈、框架、环境）
• 已通过 MCP 工具研究错误处理模式
• 已生成 GlobalExceptionMiddleware（.NET）或异常处理器（Python）
• 已创建自定义异常类（AppException、ValidationException、NotFoundException）
• 已创建错误响应模型（ProblemDetails 格式）
• 已验证语法（dotnet build 或 py_compile）
• 已向 ln-770 协调器返回结构化 JSON 响应

---

版本： 2.0.0 最后更新： 2026-01-10