响应模型定义

Pydantic 模型在 API 数据管理中扮演着核心角色。它们用于验证传入的请求数据，并且在定义和管理 API 响应回传的数据方面尤其有用。通过使用 response_model，API 能够遵守预定义的契约，自动过滤传出数据，并显著提升其文档性和易用性。

为何定义响应模型？

虽然您可以直接从路径操作函数返回任意数据结构，如字典或列表，但明确定义响应模型有多项好处：

1. 数据验证： FastAPI 验证您从函数返回的数据是否符合 response_model 中定义的结构和类型。这作为一项安全检查，避免意外暴露不正确或格式错误的数据。
2. 数据过滤： 如果您的函数返回的对象字段多于 response_model 中定义的，FastAPI 会自动过滤掉多余的字段。这对于精确控制向客户端公开的数据、隐藏内部实现细节或敏感信息非常有用。
3. 序列化控制： Pydantic 会根据 response_model 的定义，将您的返回对象（可以是 Pydantic 模型实例、字典、数据库对象等）转换为客户端期望的 JSON 格式。
4. 自动文档： FastAPI 使用 response_model 在您的 API 文档中（例如 /docs 处的交互式 Swagger UI）生成预期响应的模式。这使得您的 API 可以自我文档化，并且更易于使用者理解。
5. 编辑器支持： 使用明确的模型可在您的开发环境中提供更好的自动补全和类型检查。

定义和使用响应模型

定义响应模型与定义请求模型相同：您创建一个继承自 Pydantic BaseModel 的类。

我们设想一个机器学习预测场景。假设我们的模型预测一个分类标签（字符串）和一个置信度得分（浮点数）。我们可以为这个输出定义一个 Pydantic 模型：

from pydantic import BaseModel, Field

class PredictionResult(BaseModel):
    label: str = Field(..., description="预测的类别标签。")
    confidence: float = Field(..., ge=0.0, le=1.0, description="预测置信度得分（0.0 到 1.0）。")

# 我们的函数可能生成的内部数据结构示例
# 注意它有一个额外的 'internal_model_version' 字段
internal_data = {
    "label": "cat",
    "confidence": 0.95,
    "internal_model_version": "v1.2.3"
}

现在，我们使用路径操作装饰器中的 response_model 参数，将此模型应用于响应：

# 假设 'app' 是您的 FastAPI 实例
# from fastapi import FastAPI
# app = FastAPI()

@app.post("/predict/", response_model=PredictionResult)
async def make_prediction(input_data: dict): # 假设输入验证在其他地方进行
    # ... 处理 input_data 并运行机器学习模型 ...
    # 函数返回一个字典，其字段多于 PredictionResult 定义的字段
    prediction_output = {
        "label": "cat",
        "confidence": 0.95,
        "internal_model_version": "v1.2.3",
        "processing_time_ms": 50
    }
    return prediction_output

当客户端调用 /predict/ 端点时，即使 make_prediction 函数返回的字典包含 internal_model_version 和 processing_time_ms，FastAPI 也会执行以下步骤：

1. 它获取返回的字典 prediction_output。
2. 它根据 PredictionResult 模型验证此字典。它检查 label 是否为字符串以及 confidence 是否为 0.0 到 1.0 之间的浮点数。如果验证失败，它将引发内部服务器错误。
3. 它过滤数据，只保留 PredictionResult 中定义的字段（label 和 confidence）。internal_model_version 和 processing_time_ms 字段将从最终响应中丢弃。
4. 它将过滤后的数据序列化为发送给客户端的 JSON 响应。

客户端将收到：

{
  "label": "cat",
  "confidence": 0.95
}

这种过滤机制是维护清晰 API 约定的一个强大功能。您可以在应用程序逻辑中使用更丰富的内部对象，但仅在外部公开必要的字段。

响应序列化微调

FastAPI 提供参数，可进一步控制响应中包含的字段，通常有助于优化负载大小或隐藏默认值：

• response_model_exclude_unset=True：排除在返回数据中未明确设置且仍具有默认值的字段。
• response_model_exclude_defaults=True：排除值等于其默认值的字段，即使已明确设置。
• response_model_exclude_none=True：排除值为 None 的字段。

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = 0.0 # 默认税率为 0.0

@app.get("/items/{item_id}", response_model=Item, response_model_exclude_none=True)
async def read_item(item_id: str):
    # 设想获取一个没有描述的物品
    item_data = {"name": "Thingamajig", "price": 10.50, "description": None, "tax": 0.0}
    return item_data

在此示例中，使用 response_model_exclude_none=True，响应将省略 description 字段，因为其值为 None。如果同时使用 response_model_exclude_defaults=True，则 tax 字段也会被省略，因为其值（0.0）与默认值匹配。

处理多种响应类型

有时，端点可能需要根据结果返回不同的数据结构。一种常见的处理方式是在 response_model 中使用 Python 的 Union 类型提示。

from typing import Union

class SuccessResponse(BaseModel):
    message: str
    result_id: int

class ErrorResponse(BaseModel):
    error_code: int
    detail: str

@app.post("/process/", response_model=Union[SuccessResponse, ErrorResponse])
async def process_data(data: dict):
    try:
        # ... 处理数据 ...
        if success:
             return SuccessResponse(message="Processing successful", result_id=123)
        else:
             # 这通常通过 HTTPException 处理，
             # 但这里是为了说明返回不同的模型结构。
             return ErrorResponse(error_code=5001, detail="Processing failed")
    except Exception as e:
        return ErrorResponse(error_code=9999, detail=str(e))

FastAPI 会尝试将返回的对象与 Union 中指定的类型匹配，并在 API 模式中记录这两种可能性。请注意，对于标准 HTTP 错误（如 4xx 或 5xx），通常更推荐抛出 HTTPException，而不是在成功路径中返回自定义错误模型。

通过定义清晰的响应模型，您可以提升机器学习 API 的可靠性、可维护性和文档，确保客户端以正确的格式收到他们预期的数据。这是构建可靠 Web 服务的基本做法。