error-handling-rfc9457

用途

该技能用于按照 RFC 9457（Problem Details for HTTP APIs）标准，统一 HTTP API 的错误响应格式，使错误信息具备机器可读的结构。适用于实现 problem details 格式、结构化 API 错误、错误注册表等场景。

RFC 9457 与 RFC 7807 对比

资料给出的对比：

状态：RFC 7807 已废弃（Obsolete），RFC 9457 为现行标准（Active Standard）。
多问题支持：RFC 7807 未规定，RFC 9457 明确支持。
错误注册表：RFC 7807 无，RFC 9457 有（IANA registry）。
扩展字段：RFC 7807 为隐式，RFC 9457 明确允许。

主要能力

Problem Details 模式

使用 Pydantic 定义 ProblemDetail 模型，字段包括：

type：标识问题类型的 URI，默认 "about:blank"
title：简短的人类可读摘要
status：HTTP 状态码（400–599）
detail：针对本次出现的人类可读说明（可选）
instance：标识本次具体出现的 URI 引用（可选）

通过 model_config = {"extra": "allow"} 允许扩展字段。

FastAPI 集成

提供 ProblemException 基类（继承 HTTPException），包含 problem_type、title、detail、instance、extensions，并提供 to_problem_detail() 方法。

具体问题类型示例：

ValidationProblem：422，扩展字段 errors
NotFoundProblem：404，扩展字段 resource、resource_id
RateLimitProblem：429，扩展字段 retry_after

异常处理器

为 ProblemException、RequestValidationError 以及通用 Exception 注册异常处理器，统一返回 media_type 为 application/problem+json 的 JSONResponse。

端点使用

在路由中通过抛出具体 Problem 异常（如 NotFoundProblem）来返回标准化错误。

响应示例

资料给出 404、422、429 三种响应示例，均包含 type、title、status、detail、instance 及相应扩展字段。

错误类型注册表

提供 PROBLEM_TYPES 字典，登记 validation-error、resource-not-found、rate-limit-exceeded、unauthorized、forbidden、conflict、internal-error 等类型的 uri、title、status。

使用方式

资料中的使用方式为 Python 代码示例，涉及 pydantic、fastapi 等库。具体安装命令与依赖版本暂未提供。

适用场景

需要标准化 API 错误响应的后端服务
使用 FastAPI 构建的 HTTP API
需要结构化、机器可读错误信息与错误类型管理的项目

限制与反模式

资料明确列出禁止的做法：

不要返回纯文本错误（如 Response("Not found", status_code=404)）
不要使用不一致的错误格式
不要在生产环境暴露内部细节（如 traceback）
不要对所有情况都使用通用 500

关键决策建议

媒体类型：application/problem+json
类型 URI：使用你的 API 域名 + /problems/
detail：仅包含用户可操作的信息
扩展字段：用于机器可读的上下文
日志：记录问题类型以便监控

能力细节

problem-details：关键词 problem details、RFC 9457、RFC 7807、structured error；解决如何标准化 API 错误响应、API 错误使用什么格式。
fastapi-errors：关键词 fastapi exception、error handler、HTTPException；解决如何在 FastAPI 中处理错误、自定义异常处理器。
error-registry：关键词 error registry、problem types、error catalog；解决如何记录所有 API 错误、错误类型管理。

技能介绍

用途