FastAPI中统一错误响应需结合自定义异常类、@app.exception_handler()装饰器和Pydantic模型。先定义ErrorResponse模型，再创建继承Exception的APIException类，接着注册全局处理器返回JSONResponse，最后在路由中raise实例即可输出标准化错误。
FastAPI 中让错误响应统一使用自定义异常模型，核心是结合 Exception 类、@app.exception_handler() 装饰器和 Pydantic 模型三者完成标准化输出。
定义统一的错误响应模型
先用 Pydantic 创建一个结构清晰的错误响应模型，例如包含状态码、错误码、消息和可选详情：
from pydantic import BaseModel from typing import Optional <p>class ErrorResponse(BaseModel): code: int message: str detail: Optional[str] = None
创建自定义异常类
继承 Python 的 Exception，并携带必要字段（如 status_code、code、message），方便后续处理器提取：
class APIException(Exception):
def __init__(self, status_code: int, code: int, message: str, detail: str = None):
self.status_code = status_code
self.code = code
self.message = message
self.detail = detail注册全局异常处理器
使用 @app.exception_handler(APIException) 拦截所有该类型异常，并返回符合 ErrorResponse 模型的 JSON 响应：
from fastapi import FastAPI, Request from fastapi.responses import JSONResponse <p>@app.exception_handler(APIException) async def api_exception_handler(request: Request, exc: APIException): return JSONResponse( status_code=exc.status_code, content=ErrorResponse( code=exc.code, message=exc.message, detail=exc.detail ).dict() )
注意：这个处理器只捕获 APIException 及其子类。若需统一处理所有未捕获异常（如 422 验证错误），可额外注册 RequestValidationError 或通用 Exception 处理器，但建议保持语义明确，避免掩盖开发问题。
在路由中主动抛出自定义异常
直接 raise 实例即可，FastAPI 会自动交由对应 handler 处理：
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id < 1:
raise APIException(
status_code=400,
code=1001,
message="无效的 item ID",
detail="item_id 必须大于 0"
)
return {"id": item_id}此时响应体为标准 JSON：
{
"code": 1001,
"message": "无效的 item ID",
"detail": "item_id 必须大于 0"
}状态码也正确设为 400。
进阶：支持多种错误类型（可选）
可定义不同业务异常子类，复用同一 handler：
class NotFoundException(APIException):
def __init__(self, resource: str):
super().__init__(
status_code=404,
code=2001,
message=f"{resource} 不存在"
)
<h1>使用时</h1><p>raise NotFoundException("用户")这样既保持统一格式，又提升代码可读性和维护性。
