FastAPI可通过异常处理器与Pydantic模型统一错误响应格式为{"code":int,"message":str,"details":Any}；需定义ErrorResponse模型、注册HTTPException/Exception/自定义异常处理器，并在路由中用responses参数声明OpenAPI错误结构。
FastAPI 中可以通过异常处理器（exception handlers）和 Pydantic 模型配合，实现所有错误响应都统一返回你定义的结构化错误格式，比如 {"code": 400, "message": "xxx", "details": {...}}。
定义统一错误响应模型
先用 Pydantic 创建一个标准错误响应模型，它将作为所有异常响应的序列化格式：
from pydantic import BaseModel from typing import Optional, Anyclass ErrorResponse(BaseModel): code: int message: str details: Optional[Any] = None
注册全局异常处理器
使用 app.add_exception_handler() 注册对 Exception 或具体异常（如 HTTPException、自定义异常）的处理逻辑。推荐按需注册两类：
- 处理 FastAPI 内置的
HTTPException：提取 status_code 和 detail - 处理未捕获的通用异常（可选）：记录日志并返回 500 错误
from fastapi import FastAPI, HTTPException, Request from fastapi.responses import JSONResponseapp = FastAPI()
@app.exception_handler(HTTPException) async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse: return JSONResponse( status_code=exc.status_code, content=ErrorResponse( c
ode=exc.status_code, message=exc.detail, details=getattr(exc, "headers", None) or getattr(exc, "data", None) ).model_dump() )
@app.exception_handler(Exception) async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:
生产环境建议只返回泛化错误，避免泄露敏感信息
return JSONResponse( status_code=500, content=ErrorResponse( code=500, message="Internal server error", details=None ).model_dump() )
定义并抛出自定义业务异常
为不同业务场景创建继承自 Exception 的异常类，并在视图中主动 raise。这样既能保持逻辑清晰，又可被统一处理器捕获：
class ValidationError(Exception):
def __init__(self, message: str, details: Optional[dict] = None):
self.message = message
self.details = details
self.status_code = 422
在路由中使用
@app.get("/items/{item_id}")
def get_item(item_id: int):
if item_id < 1:
raise ValidationError("Item ID must be positive", {"field": "item_id"})
return {"id": item_id}
然后为其注册专属处理器（注意注册顺序：更具体的异常要先注册）：
@app.exception_handler(ValidationError)
async def validation_error_handler(request: Request, exc: ValidationError) -> JSONResponse:
return JSONResponse(
status_code=exc.status_code,
content=ErrorResponse(
code=exc.status_code,
message=exc.message,
details=exc.details
).model_dump()
)让 OpenAPI 文档也反映统一错误结构
默认情况下，FastAPI 不会自动把异常响应写入 OpenAPI schema。你可以通过 responses 参数显式声明，并复用 ErrorResponse 模型：
@app.get(
"/users/{user_id}",
responses={
404: {"model": ErrorResponse, "description": "User not found"},
422: {"model": ErrorResponse, "description": "Validation failed"},
}
)
def get_user(user_id: int):
if user_id != 123:
raise HTTPException(status_code=404, detail="User not found")
return {"name": "Alice"}这样 Swagger UI 就会显示对应状态码的错误响应结构，提升 API 可用性与前端协作效率。
