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, Any
class 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 JSONResponse
app = FastAPI()
@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
return JSONResponse(
status_code=exc.status_code,
content=ErrorResponse(
code=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()
)

							

								
								

									eMart 网店系统
									
功能列表：底层程序与前台页面分离的效果，对页面的修改无需改动任何程序代码。完善的标签系统，支持自定义标签，公用标签，快捷标签，动态标签，静态标签等等，支持标签内的vbs语法，原则上运用这些标签可以制作出任何想要的页面效果。兼容原来的栏目系统，可以很方便的插入一个栏目或者一个栏目组到页面的任何位置。底层模版解析程序具有非常高的效率，稳定性和容错性，即使模版中有错误的标签也不会影响页面的显示。所有的标
								
								下载 
							
						
定义并抛出自定义业务异常
为不同业务场景创建继承自 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 可用性与前端协作效率。