19 数据验证与序列化之数据模型定义

在上一篇文章中，我们讨论了路径参数与查询参数的定义与验证，此篇教程将继续围绕数据验证主题展开，重点讲解如何通过定义数据模型来实现有效的数据验证和序列化。这是一个重要的环节，有助于确保我们所接收和发送的数据都是符合预期的格式和类型。

数据模型的概念

在 FastAPI 中，数据模型通常是通过 Pydantic 提供的 BaseModel 类来定义的。Pydantic 是一个数据验证和设置管理的库，它不仅能够帮助我们定义数据结构，还能验证和序列化这些数据。

定义一个数据模型的基本步骤如下：

1. **继承 BaseModel**：创建一个新的类，继承自 pydantic.BaseModel。
2. 定义属性：在新类中定义属性，并且为这些属性指定类型。
3. 添加验证：可以使用 Pydantic 提供的多种字段类型和验证器来确保数据的有效性。

创建数据模型实例

接下来，让我们通过一个示例来演示如何定义数据模型。假设我们要处理用户信息，用户信息包含 id、name 和 email 等字段：

from pydantic import BaseModel, EmailStr, conint

class User(BaseModel):
    id: conint(ge=1)  # id 必须是大于等于 1 的整数
    name: str
    email: EmailStr  # 确保 email 符合 email 格式

在这个例子中，我们使用了以下 Pydantic 特性：

• conint(ge=1)：定义一个整数类型，且要求其值大于或等于 1。
• EmailStr：这个类型会自动验证字符串是否符合电子邮件格式。

使用数据模型进行验证与序列化

定义好数据模型后，我们可以在 FastAPI 的路径操作中使用它。以下是一个简单的 FastAPI 应用示例：

from fastapi import FastAPI
from typing import List

app = FastAPI()

# 定义用户模型
class User(BaseModel):
    id: conint(ge=1)
    name: str
    email: EmailStr

# 创建一个用户
@app.post("/users/", response_model=User)
async def create_user(user: User):
    return user

在上述代码中，我们创建了一个 POST 路径 /users/，要求请求体中的数据符合 User 模型的定义。FastAPI 会自动处理输入数据的验证。如果输入数据不符合模型定义，FastAPI 会返回一个 422 Unprocessable Entity 错误。

示例请求

POST /users/
Content-Type: application/json

{
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
}

这个请求将成功返回：

{
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
}

如果尝试提交一个无效的用户，例如缺少 email 字段或 id 是负数，FastAPI 会自动返回出错信息。

处理复杂数据模型

在实际应用中，我们的模型可能会更加复杂，如嵌套模型或列表等。以下是一个示例，展示了如何使用嵌套数据模型：

class Address(BaseModel):
    city: str
    state: str
    zip_code: str

class UserWithAddress(BaseModel):
    id: conint(ge=1)
    name: str
    email: EmailStr
    address: Address

@app.post("/users_with_address/", response_model=UserWithAddress)
async def create_user_with_address(user: UserWithAddress):
    return user

在这个例子中，UserWithAddress 包含一个嵌套的 Address 模型。输入数据需要符合所有字段的 validation 规则。

示例请求

POST /users_with_address/
Content-Type: application/json

{
    "id": 2,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "address": {
        "city": "New York",
        "state": "NY",
        "zip_code": "10001"
    }
}

成功的返回将是：

{
    "id": 2,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "address": {
        "city": "New York",
        "state": "NY",
        "zip_code": "10001"
    }
}

小结

在这一节中，我们学习了如何定义数据模型以实现数据验证与序列化，使用 Pydantic 创建了简单与复杂的模型，并通过 FastAPI 路径操作验证输入数据的有效性。这些技能将为后续的内容铺平道路，接下来我们将深入探讨如何使用 Pydantic 进行更复杂的数据验证。

接下来，我们将继续探索更高级的 Pydantic 功能，期待与您在下一篇文章中见面！