高效构建 API：FastAPI 请求体验证与数据清洗的实践

高效构建 API：FastAPI 请求体验证与数据清洗的实践

目录

• 🛠️ 1. 使用 Pydantic 定义请求体模型
• 🔍 2. 对 JSON 请求体进行验证
• 🔄 3. 数据清洗和转换

---

🛠️ 1. 使用 Pydantic 定义请求体模型

FastAPI 利用 Pydantic 的强大功能来简化请求体的验证工作。通过使用 Pydantic 定义请求体模型，开发者可以轻松地指定 API 期望接收到的数据格式，并自动执行验证。这使得开发过程更加高效，避免了手动验证和数据处理的繁琐。

Pydantic 模型的定义

在 FastAPI 中，Pydantic 模型是请求体数据的核心定义。每个 Pydantic 模型类都继承自 BaseModel，并通过类型注解来声明字段的类型。FastAPI 会根据这些定义自动生成验证逻辑，确保请求体数据的完整性和正确性。以下是一个简单的例子，展示了如何使用 Pydantic 定义一个请求体模型：

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str
    price: float
    tax: float = None

在这个示例中，Item 是一个 Pydantic 模型类。它包含了四个字段：name、description、price 和 tax。其中，name、description 和 price 是必填字段，而 tax 是可选字段，因为它有默认值 None。这种定义方式不仅简洁直观，还提供了类型安全的保障。

Pydantic 字段类型的校验

Pydantic 的强大之处在于，它不仅能够定义字段的类型，还能自动执行类型校验。当 API 接收到请求时，Pydantic 会检查字段值的类型是否符合预期。如果类型不匹配，Pydantic 会自动抛出错误，提示开发者请求体数据不符合规范。比如，以下代码展示了一个 price 字段强制要求为 float 类型：

@app.post("/items/")
async def create_item(item: Item):
    return {"name": item.name, "price": item.price}

当 API 接收到的请求体中，price 字段的类型不符合 float 类型时，FastAPI 会自动返回 422 错误，提示数据验证失败。这种自动验证的机制大大减少了手动编写验证代码的需求。

使用 Pydantic 定义复杂数据结构

在实际的开发过程中，API 请求体的数据结构可能会更复杂。Pydantic 支持嵌套模型，这意味着你可以在一个模型中引用其他模型，从而构建更复杂的请求体。以下是一个包含嵌套模型的例子：

from pydantic import BaseModel
from typing import List

class Category(BaseModel):
    name: str
    description: str

class Item(BaseModel):
    name: str
    description: str
    price: float
    categories: List[Category]  # 使用 List 来表示多个嵌套模型

在这个例子中，Item 模型包含了一个 categories 字段，该字段是一个 Category 类型的列表。FastAPI 会自动解析和验证 categories 字段中的每个元素是否符合 Category 模型的结构和数据类型要求。

小结

使用 Pydantic 定义请求体模型是一种高效、简洁且强大的方式来确保 API 接收到的数据符合预期。通过类型注解，Pydantic 会自动验证字段的数据类型、必填性等，并且能够支持嵌套复杂的数据结构。这使得开发者能够集中精力在业务逻辑上，而无需担心数据验证和格式化问题。

---

🔍 2. 对 JSON 请求体进行验证

FastAPI 和 Pydantic 提供了非常便捷的方式来验证 JSON 请求体。JSON 是 Web API 中常见的数据格式，而通过 FastAPI，开发者无需手动解析 JSON 数据，只需将数据传递给 Pydantic 模型，FastAPI 会自动将其转换为相应的 Python 数据类型，并进行验证。这使得处理请求体变得更加高效和自动化。

JSON 请求体的自动解析与验证

FastAPI 在接收到 JSON 请求体时，会自动将 JSON 数据解析为 Python 字典，然后将其传递给对应的 Pydantic 模型类进行验证。以下是一个简单的 FastAPI 视图函数，它接收 JSON 请求体并将其传递给 Pydantic 模型：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str
    price: float

@app.post("/items/")
async def create_item(item: Item):
    return {"name": item.name, "price": item.price}

当客户端发送一个如下格式的 JSON 请求体时，FastAPI 会自动将其转换为 Item 类型的实例，并进行验证：

{
    "name": "Laptop",
    "description": "A high-end gaming laptop",
    "price": 1200.00
}

校验 JSON 请求体的字段

FastAPI 会根据 Pydantic 模型中定义的字段类型，自动校验请求体中的字段。例如，如果请求体中的 price 字段为字符串类型，而 Pydantic 模型中的 price 字段要求为 float 类型，FastAPI 会自动返回 422 错误，提示字段类型不符合预期。以下是一个带有验证错误的示例：

{
    "name": "Laptop",
    "description": "A high-end gaming laptop",
    "price": "not-a-number"
}

这种自动的类型验证机制大大减少了开发者需要手动编写验证代码的工作量，并且确保了请求数据的一致性。

复杂数据结构的 JSON 请求体验证

FastAPI 和 Pydantic 还支持处理更复杂的 JSON 请求体结构。例如，当请求体包含嵌套对象或数组时，FastAPI 会递归地解析和验证每个字段。以下是一个包含嵌套数据结构的例子：

from typing import List

class Category(BaseModel):
    name: str
    description: str

class Item(BaseModel):
    name: str
    description: str
    price: float
    categories: List[Category]  # 这里是嵌套的 JSON 对象数组

@app.post("/items/")
async def create_item(item: Item):
    return {"name": item.name, "categories": [cat.name for cat in item.categories]}

客户端可以发送如下格式的 JSON 请求体：

{
    "name": "Laptop",
    "description": "A high-end gaming laptop",
    "price": 1200.00,
    "categories": [
        {"name": "Electronics", "description": "Gadgets and devices"},
        {"name": "Gaming", "description": "Gaming laptops and accessories"}
    ]
}

FastAPI 会自动解析 categories 字段中的每个对象，并验证其是否符合 Category 模型的结构和类型要求。

小结

FastAPI 在处理 JSON 请求体时，能够自动解析和验证数据。通过 Pydantic 模型定义，开发者可以确保请求体的数据格式和类型完全符合预期。无论是简单的字段校验还是复杂的嵌套结构，FastAPI 和 Pydantic 都能高效地完成这些工作，大大提高了开发效率。

---

🔄 3. 数据清洗和转换

在实际的 Web 开发中，收到的请求体数据往往需要进行清洗和转换，以便适应应用的需求。FastAPI 和 Pydantic 提供了强大的数据清洗和转换功能，帮助开发者在接收数据时自动处理数据的预处理工作。

数据清洗和转换的基本概念

数据清洗和转换指的是对请求体数据进行必要的预处理，使得数据更符合应用的需求。例如，将字符串类型的数字转换为整数，去除无效的空格，或者转换日期格式等。FastAPI 和 Pydantic 通过模型的钩子方法和字段验证功能，可以自动进行这些处理。

使用 Pydantic 的 @root_validator 进行数据清洗

Pydantic 提供了 @root_validator 装饰器，用于对模型进行更复杂的验证和数据清洗。@root_validator 可以访问整个模型的字段，并根据需要执行数据的清洗或转换。例如，假设你希望在数据提交时，将价格字段的字符串去除前后的空格并转换为浮动类型：

from pydantic import BaseModel, root_validator

class Item(BaseModel):
    name: str
    price: str  # price 字段将传入字符串类型

    @root_validator(pre=True)
    def clean_data(cls, values):
        price = values.get("price")
        if price:
            values["price"] = float(price.strip())  # 清洗并

转换 price 字段
        return values

在这个例子中，@root_validator 会在模型实例化前（通过 pre=True）对 price 字段进行清洗，将其去除空格并转换为 float 类型。

自定义数据转换逻辑

FastAPI 和 Pydantic 还允许开发者定义自定义的字段转换逻辑。例如，如果你希望对某个字段进行更复杂的清洗或格式化，可以使用 @validator 装饰器。以下是一个使用 @validator 进行数据清洗的例子：

from pydantic import BaseModel, validator

class Item(BaseModel):
    name: str
    price: float

    @validator("price")
    def validate_price(cls, v):
        if v <= 0:
            raise ValueError("Price must be greater than 0")
        return v

在这个例子中，@validator 被用于验证价格字段，确保价格大于零。如果价格无效，Pydantic 会抛出一个验证错误。

小结

FastAPI 和 Pydantic 提供了强大的数据清洗和转换功能。开发者可以使用 @root_validator 和 @validator 来实现复杂的数据预处理，确保数据符合应用的需求。这些功能帮助开发者在接收请求数据时，自动完成数据清洗和转换的工作，简化了开发流程并提高了代码的可维护性。

---

原文地址：https://blog.csdn.net/weixin_52392194/article/details/144203963

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！