在现代Web开发中，数据模型的定义和处理是核心环节之一。FastAPI作为高性能Python API框架，搭配Pydantic这个强大的数据验证与序列化库，能让数据处理变得既简单又可靠。本文将从零开始，用通俗易懂的语言和实用的例子，带你掌握FastAPI+Pydantic的数据模型定义与序列化最佳实践。
为什么选FastAPI+Pydantic？¶
- FastAPI：高性能、自动生成API文档（Swagger UI）、支持异步，且对数据验证有原生支持。
- Pydantic：专为数据验证设计，能自动检查输入数据类型、格式，并将其转换为Python对象；同时支持序列化和反序列化。
两者结合后，你只需定义一个数据模型，FastAPI就能自动帮你处理请求验证、数据转换和响应格式化，大幅减少重复代码。
一、快速上手：定义第一个Pydantic模型¶
Pydantic的核心是BaseModel类，所有数据模型都继承自它。我们先从最简单的模型开始：
from pydantic import BaseModel
# 定义一个用户信息模型
class User(BaseModel):
id: int # 整数类型，必填（无默认值则必须提供）
name: str # 字符串类型，必填
age: int = 18 # 整数类型，有默认值18（可选填）
email: str | None = None # Python 3.10+ 可选类型，默认None
# 使用模型
user1 = User(id=1, name="Alice", age=25) # 不提供email，使用默认值None
user2 = User(id=2, name="Bob", email="bob@example.com") # 不提供age，使用默认值18
关键点：
- 字段类型由Python类型注解指定（如int、str），Pydantic会自动验证输入类型。
- 无默认值的字段（如id、name）是必填项，若不提供会报错。
- 带默认值的字段（如age=18）是可选的，未提供时自动使用默认值。
- 可选类型用| None（Python 3.10+）或Optional[int]（兼容旧版本），表示该字段可以为None。
二、数据验证：Pydantic的“安全网”¶
Pydantic最强大的功能是自动验证数据。当输入数据不符合模型定义时，它会抛出详细的错误信息，帮你快速定位问题。
1. 基础验证：类型与格式检查¶
# 错误示例：age为字符串类型，与模型定义的int不匹配
try:
invalid_user = User(id=3, name="Charlie", age="twenty", email="charlie@example.com")
except Exception as e:
print(e) # 输出错误："twenty" is not a valid integer
2. 高级验证：自定义约束条件¶
通过Pydantic的Field类，可以给字段添加更细粒度的验证规则（需导入Field）：
from pydantic import Field
class User(BaseModel):
name: str = Field(..., min_length=2, max_length=50) # 字符串长度2-50
age: int = Field(18, ge=18, le=120) # age必须≥18且≤120
email: str | None = Field(None, regex=r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$") # 邮箱格式正则
# 验证示例
valid_user = User(name="David", age=20, email="david@example.com")
invalid_email = User(name="Eve", age=25, email="invalid-email") # 邮箱格式错误
常用约束条件：
- min_length/max_length：字符串长度限制
- ge（Greater Than or Equal）：大于等于（如ge=18）
- le（Less Than or Equal）：小于等于（如le=100）
- gt/lt：大于/小于
- regex：字符串格式正则匹配
- const：固定值（如const="admin"）
三、序列化与反序列化：模型与数据的双向转换¶
Pydantic模型能轻松实现Python对象与字典、JSON的互相转换，这在API请求/响应处理中非常关键。
1. 模型→字典/JSON¶
user = User(id=1, name="Alice", age=25, email="alice@example.com")
# 转为字典（字段名+值）
user_dict = user.dict()
print(user_dict) # {'id': 1, 'name': 'Alice', 'age': 25, 'email': 'alice@example.com'}
# 转为JSON字符串
user_json = user.json()
print(user_json) # {"id": 1, "name": "Alice", "age": 25, "email": "alice@example.com"}
2. 字典/JSON→模型¶
Pydantic可以直接从字典创建模型实例，自动完成类型转换和验证：
data = {"id": 2, "name": "Bob", "age": 30}
user = User(**data) # 相当于 User(id=2, name="Bob", age=30)
3. FastAPI中的实际应用¶
在FastAPI中，Pydantic模型可直接作为请求体（POST/PUT）和响应体（GET/POST返回数据）：
from fastapi import FastAPI
app = FastAPI()
# 定义请求体模型
class CreateUser(BaseModel):
name: str = Field(..., min_length=2)
age: int = Field(18, ge=18)
# 定义响应模型
class UserResponse(BaseModel):
id: int
name: str
age: int
# 模拟数据库存储
fake_db = {1: User(id=1, name="Alice", age=25)}
@app.post("/users/", response_model=UserResponse)
def create_user(user: CreateUser):
# 假设新用户ID为len(fake_db)+1
new_id = len(fake_db) + 1
new_user = User(id=new_id, name=user.name, age=user.age)
fake_db[new_id] = new_user
return new_user # FastAPI自动序列化为JSON响应
效果：当你发送POST /users/请求，请求体包含name和age，FastAPI会自动验证并转换为CreateUser模型，处理后返回UserResponse模型，同时生成Swagger文档。
四、最佳实践：让模型更实用的技巧¶
1. 字段别名：统一命名风格¶
当JSON字段名与Python变量名不一致时（如JSON用user_id，Python用userId），用alias解决：
class User(BaseModel):
user_id: int = Field(..., alias="user_id") # 前端JSON中的键名是user_id
name: str
# 解析JSON时，"user_id"对应Python变量user_id
json_data = {"user_id": 1, "name": "Alice"}
user = User(**json_data)
print(user.user_id) # 1，Python变量名与JSON键名通过alias映射
2. 嵌套模型：复杂结构复用¶
如果模型包含另一个模型（如用户信息包含地址），直接嵌套定义即可：
class Address(BaseModel):
street: str
city: str
class User(BaseModel):
name: str
address: Address # 嵌套Address模型
# 使用时，直接传入嵌套字典
user_data = {
"name": "Bob",
"address": {"street": "123 Main St", "city": "Beijing"}
}
user = User(**user_data)
print(user.address.city) # "Beijing"
3. 模型继承：代码复用¶
当多个模型有共同字段时，用继承减少重复代码：
class BaseModel(BaseModel):
id: int
created_at: datetime = Field(default_factory=datetime.utcnow) # 当前时间
class User(BaseModel):
name: str
class Admin(BaseModel):
is_admin: bool
class SuperUser(User, Admin): # 继承User和Admin
pass # 继承后包含User的name、Admin的is_admin、BaseModel的id和created_at？
# 注意：Pydantic模型继承需确保父模型无冲突字段，且使用单继承更稳妥
4. 忽略额外字段：处理未知数据¶
当输入数据包含模型中没有的字段时，默认会报错。若允许忽略额外字段，用extra="ignore"：
class User(BaseModel):
name: str
model_config = ConfigDict(extra="ignore") # 忽略额外字段，不报错
# 即使JSON包含"gender": "male"，模型也会忽略
user_data = {"name": "Charlie", "gender": "male"}
user = User(**user_data)
print(user) # User(name='Charlie')
五、常见问题与解决¶
-
Q：如何处理必填字段但允许空值？
A：用Field(..., ...)或Optional类型，并确保类型正确（如Optional[str]允许None但仍需类型匹配）。 -
Q：FastAPI返回模型时，如何避免暴露敏感字段？
A：用model_config的exclude参数排除字段：
class User(BaseModel):
name: str
password: str
model_config = ConfigDict(exclude_unset=False) # 默认不排除字段
# 或在返回时显式指定需要返回的字段：return user.dict(exclude={"password"})
- Q：如何处理模型之间的复杂关系？
A：用嵌套模型、联合类型（Union）或枚举（Literal），避免过度嵌套导致可读性下降。
总结¶
FastAPI+Pydantic的数据模型定义与序列化是现代Python API开发的黄金组合。通过本文，你已经掌握了：
- 基础模型定义与验证规则
- 序列化/反序列化的核心方法
- 字段别名、嵌套、继承等最佳实践
- 在FastAPI中如何结合模型处理请求与响应
接下来，你可以尝试在自己的项目中应用这些知识，从简单模型开始，逐步构建复杂业务逻辑。记住，Pydantic的强大之处在于“数据验证”和“自动转换”，合理使用它能让你的API更健壮、开发更高效！