这个项目能做什么

fastapi-faults 为 FastAPI 提供了类型化的错误契约，将 Python 异常与 RFC 9457 问题详情及 OpenAPI 文档相连接。其核心理念是每个应用程序错误都拥有一个不可变的定义，该定义一致地用于异常处理、application/problem+json 响应以及生成的 OpenAPI 模式。该项目旨在避免重复的响应字典、进程全局注册表以及文档与实际端点错误之间的偏差。 核心概念是 Fault 和 FaultRegistry。Fault 将领域异常映射到状态码、稳定代码、标题、详情、请求头、示例和模式等字段。功能模块可以在其代码旁定义一个小型 FaultRegistry，应用程序通过 FaultRegistry.merge 显式地组合这些注册表。定义是不可变的，合并顺序是确定性的，且在配置期间，冲突的异常类、代码、类型 URI 或模式名称会导致失败。type_base 选项可从每个故障代码派生出稳定的问题类型 URI；故障也可以提供显式类型。如果领域故障两者皆无，安装将失败，从而防止不完整的契约进入运行中的应用程序。 路由使用 FastAPI 标准的 APIRouter，而 registry.responses(...) 为声明的故障生成响应元数据。该库不继承或替换 APIRouter。声明的故障必须属于安装在应用程序上的注册表。RFC 9457 扩展成员可以使用 Pydantic 模型进行类型化：extensions_model 验证自定义问题字段，extensions 可调用对象产生值，生成的问题模式会描述这些成员。 安装注册表默认可以标准化框架故障。请求验证将变为带有稳定且位置感知的错误的 422 问题详情响应。HTTPException 和路由错误将收到相应的问题详情响应。响应验证和未预料的异常将变为安全的内部错误响应。安装选项包括 include_validation_error、include_http_exceptions 和 include_unhandled_error。 测试助手位于仓库的 tests/helpers.py 中，不随库一起分发。在检出代码后，可以通过 assert_no_undeclared_faults、assert_openapi_contract 和 assert_problem 等函数断言运行时与文档的偏差。未声明故障监控必须在应用程序接收第一个请求之前启动。 要求为 CPython 3.12、3.13 或 3.14；FastAPI 0.115 或更新版本（低于 1.0）；以及 Pydantic 2.9 或更新版本（低于 3.0）。通过 pip install fastapi_faults 安装。开发使用 uv sync --all-groups，质量门禁运行 ruff format --check、ruff check、mypy、pytest 和 uv build。可运行的示例位于 examples/minimal 和 examples/namespaced 中。该项目根据 MIT 许可证发布。