FastAPI数据验证全攻略 从基础规则到高级验证器实战解析

FastAPI 是一个现代、高性能的 Python Web 框架,它基于 Python 3.6+ 的类型提示(type hints)提供了强大的数据验证、序列化和文档生成功能。数据验证是 Web 开发中的核心环节,它确保了 API 接收和返回的数据符合预期格式,从而提升应用的健壮性和安全性。本文将从基础规则入手,逐步深入到高级验证器,提供实战解析和完整代码示例,帮助你全面掌握 FastAPI 的数据验证机制。我们将使用 Pydantic 库(FastAPI 的核心依赖)来处理验证,所有代码均基于 FastAPI 0.100+ 版本,确保兼容最新实践。
1. FastAPI 数据验证基础:类型提示与基本规则
FastAPI 的数据验证建立在 Pydantic 的类型提示之上。这意味着你只需在函数参数或模型定义中使用 Python 的类型注解,FastAPI 就会自动验证输入数据。如果验证失败,它会返回详细的 422 错误响应,而无需编写额外的验证代码。
1.1 为什么使用类型提示进行验证?
自动化
:FastAPI 解析请求体、查询参数或路径参数时,会根据类型提示自动验证。
文档生成
:结合 OpenAPI,自动生成交互式 API 文档(Swagger UI 和 ReDoc)。
错误处理
:内置错误响应,包含具体错误位置和原因。
1.2 基本示例:路径参数和查询参数验证
让我们从一个简单的 API 开始,验证用户 ID(整数)和可选的用户名(字符串)。
首先,安装依赖:
pip install fastapi uvicorn
创建
main.py
:
from fastapi import FastAPI, Path, Query
from typing import Optional

app = FastAPI()

@app.get(“/users/{user_id}”)
async def get_user(
user_id: int = Path(…, title=”用户 ID”, description=”必须是正整数”),
name: Optional[str] = Query(None, title=”用户名”, description=”可选字符串,最大长度 50″)
):
“””
获取用户信息。
– user_id: 路径参数,必须是整数。
– name: 查询参数,可选字符串。
“””
if name:
return {“user_id”: user_id, “name”: name}
return {“user_id”: user_id}
运行和测试
:
启动服务器:
uvicorn main:app –reload
访问
http://localhost:8000/docs
查看 Swagger UI。
测试有效请求:
http://localhost:8000/users/123?name=Alice
→ 返回
{“user_id”: 123, “name”: “Alice”}
。
测试无效请求:
http://localhost:8000/users/abc
→ 返回 422 错误,提示
user_id
必须是整数。
支持细节
:
Path(…)
用于路径参数,
…
表示必需参数。
Query(None)
表示可选参数,默认值为 None。
类型如
int
、
str
自动验证:字符串 “abc” 无法转换为 int,会触发验证错误。
对于字符串,你可以添加约束,如
min_length
或
max_length
,但这些将在后续高级验证中讨论。
1.3 请求体验证:使用 Pydantic 模型
对于 POST/PUT 请求,FastAPI 使用 Pydantic 模型定义数据结构。模型中的每个字段都有类型提示,验证会自动应用。
示例:用户注册 API,验证邮箱、年龄和密码。
from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

class UserCreate(BaseModel):
email: str # 必须是字符串
age: int # 必须是整数
password: str # 必须是字符串
nickname: Optional[str] = None # 可选,默认 None

@app.post(“/register”)
async def register_user(user: UserCreate):
“””
用户注册。
– 验证 email 为字符串,age 为整数。
“””
return {“message”: f”User {user.email} registered with age {user.age}”}
测试
:
有效请求体(JSON):
{
“email”: “user@example.com”,
“age”: 25,
“password”: “securepass”
}
响应:
{“message”: “User user@example.com registered with age 25”}
。
无效请求体(age 为字符串):
{
“email”: “user@example.com”,
“age”: “twenty”,
“password”: “securepass”
}
响应:422 错误,
age
字段提示 “value is not a valid integer”。
支持细节
:
BaseModel
是 Pydantic 的核心,字段类型如
str
、
int
、
bool
等直接验证。
可选字段使用
Optional[Type]
和默认值。
FastAPI 会自动将 JSON 解析为模型实例,如果解析失败,返回结构化错误。
1.4 常见基础验证规则总结
必需 vs 可选
:无默认值为必需;有默认值或
Optional
为可选。
类型转换
:FastAPI 尝试转换输入(如字符串 “123” 到 int 123),但失败则报错。
嵌套模型
:支持复杂结构,如列表或嵌套对象。
示例:
“`python
class Address(BaseModel):
city: str
zip: str
class UserWithAddress(BaseModel):
name: str
addresses: list[Address] # 列表验证每个元素为 Address 模型
@app.post(”/user-with-address”)
async def create_user(user: UserWithAddress):
return user.dict()
测试嵌套:有效 JSON 如 `{“name”: “Bob”, “addresses”: [{“city”: “Beijing”, “zip”: “100000”}]}`。

基础验证覆盖了 80% 的场景,但当需要更精细控制时,我们转向高级验证器。

## 2. 高级验证器:Pydantic 的 Field 和约束

Pydantic 提供了 `Field` 函数,用于在模型字段上添加元数据和约束。这允许你定义最小/最大值、正则表达式、自定义错误消息等。FastAPI 直接集成这些,无需额外库。

### 2.1 使用 Field 添加约束
`Field` 是一个函数,用于替换默认的类型提示,提供额外参数。

示例:增强用户模型,添加长度、范围和模式约束。
“`python
from fastapi import FastAPI
from pydantic import BaseModel, Field, EmailStr # EmailStr 需要 pip install pydantic[email]
from typing import Optional
import re

app = FastAPI()

class AdvancedUser(BaseModel):
email: EmailStr = Field(…, description=”有效的邮箱地址”, example=”user@example.com”)
age: int = Field(…, ge=18, le=120, description=”年龄必须在 18-120 之间”)
username: str = Field(…, min_length=3, max_length=20, description=”用户名 3-20 字符”)
bio: Optional[str] = Field(None, max_length=200, description=”简介最多 200 字”)
phone: str = Field(…, pattern=r”^\d{11}$”, description=”11 位手机号码,如 13800138000″)

@app.post(“/advanced-register”)
async def advanced_register(user: AdvancedUser):
return {“user”: user.dict()}
支持细节
:
…
表示必需字段。
ge
(>=),
le
(<=), gt (>),
lt
(<):数值范围。 min_length , max_length :字符串长度。 pattern :正则表达式,用于自定义模式(如手机号)。 description 和 example :用于 API 文档。 EmailStr :内置邮箱验证器,需要额外安装 pydantic[email] 。 测试 : 有效: { "email": "user@example.com", "age": 25, "username": "alice", "bio": "A developer", "phone": "13800138000" } 响应:成功。 无效(age=15 < 18): { "email": "user@example.com", "age": 15, "username": "alice", "phone": "13800138000" } 响应:422, age 错误 “ensure this value is greater than or equal to 18”。 无效手机号(非 11 位): { "email": "user@example.com", "age": 25, "username": "alice", "phone": "123" } 响应:422, phone 错误 “string does not match regex”。 2.2 自定义错误消息 使用 Field 的 description 或 Pydantic 的 __errors__ ,但更直接的是在 Field 中用 title 或自定义验证器(见下节)。 示例:自定义年龄错误。 age: int = Field(..., ge=18, le=120, title="Age", description="Must be 18+") 错误消息会显示 “Must be 18+” 在文档中。 2.3 内置高级验证器 Pydantic 提供专用验证器类,如 constr (约束字符串)、 conint (约束整数)等。 示例:使用 constr 。 from pydantic import constr class StrictUser(BaseModel): username: constr(min_length=3, max_length=20, strip_whitespace=True) # 自动去除空格 password: constr(min_length=8, regex=r"^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$") # 至少一个大写、小写、数字 测试密码 : 有效:”Pass1234”。 无效:”pass123” → 错误,缺少大写。 这些是类型化的约束,编译时优化,性能更好。 3. 自定义验证器:处理复杂业务逻辑 当内置规则不足时,使用 Pydantic 的 validator 或 root_validator 实现自定义验证。这些是装饰器函数,在模型实例化时运行。 3.1 字段级自定义验证器 使用 @validator 装饰器,针对单个字段。 示例:验证用户名不包含敏感词。 from pydantic import BaseModel, validator, ValidationError class CustomUser(BaseModel): username: str age: int @validator('username') def username_not_sensitive(cls, v): sensitive_words = ['admin', 'root', 'superuser'] if any(word in v.lower() for word in sensitive_words): raise ValueError('Username cannot contain sensitive words') return v @validator('age') def age_positive(cls, v): if v <= 0: raise ValueError('Age must be positive') return v @app.post("/custom-user") async def create_custom_user(user: CustomUser): return user.dict() 支持细节 : @validator('field_name') :指定字段。 cls 是类本身, v 是字段值。 可以访问其他字段: @validator('age', always=True) 并使用 values 参数检查依赖(如 values['username'] )。 抛出 ValueError 或 AssertionError 触发验证错误。 测试 : 有效: {"username": "alice", "age": 25} 。 无效: {"username": "admin", "age": 25} → 错误 “Username cannot contain sensitive words”。 无效: {"username": "alice", "age": -5} → 错误 “Age must be positive”。 3.2 根级自定义验证器(Root Validator) 使用 @root_validator 验证整个模型,适合跨字段检查(如开始日期 < 结束日期)。 示例:事件模型,验证日期范围。 from pydantic import BaseModel, root_validator from datetime import date class Event(BaseModel): start_date: date end_date: date @root_validator def check_dates(cls, values): start = values.get('start_date') end = values.get('end_date') if start and end and start >= end:
raise ValueError(‘Start date must be before end date’)
return values

@app.post(“/event”)
async def create_event(event: Event):
return event.dict()
测试
:
有效:
{“start_date”: “2023-01-01”, “end_date”: “2023-01-02”}
。
无效:
{“start_date”: “2023-01-02”, “end_date”: “2023-01-01″}
→ 错误 “Start date must be before end date”。
支持细节
:
pre=True
可在其他验证前运行。
always=True
即使字段缺失也运行。
这允许复杂逻辑,如数据库查询(但避免在验证器中做 I/O,保持轻量)。
3.3 高级模式:依赖注入与验证
FastAPI 的
Depends
可用于验证依赖,如认证。
示例:验证 API 密钥。
from fastapi import Depends, HTTPException, status
from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name=”X-API-Key”)

def verify_api_key(api_key: str = Depends(api_key_header)):
if api_key != “secret-key”:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=”Invalid API Key”)
return api_key

@app.get(“/secure”)
async def secure_endpoint(api_key: str = Depends(verify_api_key)):
return {“message”: “Access granted”}
测试
:
有效 Header:
X-API-Key: secret-key
。
无效:401 错误。
这不是 Pydantic 验证,但 FastAPI 的整体验证生态。
4. 实战解析:完整应用示例
让我们构建一个完整的用户管理 API,结合所有验证:基础、高级、自定义。
4.1 完整代码
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field, EmailStr, validator, constr
from typing import List, Optional
from datetime import date

app = FastAPI(title=”User Management API”)

# 基础模型
class Address(BaseModel):
city: str = Field(…, min_length=1)
zip_code: constr(pattern=r”^\d{6}$”) # 6 位邮编

# 高级用户模型
class User(BaseModel):
id: Optional[int] = None
email: EmailStr
username: constr(min_length=3, max_length=20, strip_whitespace=True)
age: int = Field(…, ge=18, le=100)
password: constr(min_length=8, regex=r”^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$”)
addresses: List[Address] = Field(…, min_items=1, max_items=5)
join_date: date = Field(default_factory=lambda: date.today())

@validator(‘username’)
def no_sensitive_words(cls, v):
if ‘admin’ in v.lower():
raise ValueError(‘Username cannot be admin’)
return v

@validator(‘password’)
def strong_password(cls, v):
if len(set(v)) < 4: # 简单检查多样性 raise ValueError('Password must have diverse characters') return v @root_validator def check_age_and_date(cls, values): age = values.get('age') join_date = values.get('join_date') if age and join_date and age < 18 and join_date.year < 2020: raise ValueError('Underage users cannot join before 2020') return values # 请求和响应模型 class UserCreateRequest(User): pass # 继承所有验证 class UserResponse(BaseModel): id: int email: str username: str message: str # 模拟数据库 users_db = [] @app.post("/users", response_model=UserResponse, status_code=status.HTTP_201_CREATED) async def create_user(user: UserCreateRequest): """ 创建用户。 - 所有字段验证通过后,模拟存储。 """ # 模拟 ID 分配 user_id = len(users_db) + 1 user_data = user.dict() user_data['id'] = user_id users_db.append(user_data) return UserResponse( id=user_id, email=user_data['email'], username=user_data['username'], message="User created successfully" ) @app.get("/users/{user_id}", response_model=UserResponse) async def get_user(user_id: int): """ 获取用户。 - 路径参数验证整数。 """ if user_id < 1 or user_id > len(users_db):
raise HTTPException(status_code=404, detail=”User not found”)
user_data = users_db[user_id – 1]
return UserResponse(
id=user_data[‘id’],
email=user_data[’email’],
username=user_data[‘username’],
message=”User retrieved”
)

@app.get(“/users”, response_model=List[UserResponse])
async def list_users(min_age: int = Query(18, ge=18, description=”Minimum age”)):
“””
列出用户。
– 查询参数验证最小年龄。
“””
filtered = [u for u in users_db if u[‘age’] >= min_age]
return [UserResponse(id=u[‘id’], email=u[’email’], username=u[‘username’], message=”User list”) for u in filtered]
4.2 运行与测试
启动:
uvicorn main:app –reload
。
访问
http://localhost:8000/docs
。
创建用户 POST
/users
:
{
“email”: “test@example.com”,
“username”: “alice123”,
“age”: 25,
“password”: “SecurePass123”,
“addresses”: [{“city”: “Beijing”, “zip_code”: “100000”}]
}
响应:
{“id”: 1, “email”: “test@example.com”, “username”: “alice123”, “message”: “User created successfully”}
。
无效创建(弱密码):
{
“email”: “test@example.com”,
“username”: “alice123”,
“age”: 25,
“password”: “pass”,
“addresses”: [{“city”: “Beijing”, “zip_code”: “100000”}]
}
响应:422,
password
错误 “string does not match regex” 或自定义 “Password must have diverse characters”。
获取用户:GET
/users/1
→ 成功。
列出用户:GET
/users?min_age=20
→ 过滤结果。
支持细节
:
这个示例展示了分层验证:模型级(类型+Field)、字段级(validator)、根级(root_validator)。
错误处理:FastAPI 自动转换 Pydantic 错误为 HTTP 422,但你可以用
HTTPException
覆盖(如在 get_user 中)。
性能:验证在请求处理前完成,高效。
扩展:对于生产,添加日志、数据库集成(如 SQLAlchemy),并在验证器中避免阻塞操作。
5. 最佳实践与常见陷阱
保持验证轻量
:验证器中不要做数据库查询或复杂计算;用依赖或中间件处理。
文档友好
:始终添加
description
和
example
到 Field,便于 Swagger。
错误一致性
:用自定义异常或
HTTPException
统一错误响应。
测试覆盖
:用
TestClient
(来自 FastAPI)测试验证:
from fastapi.testclient import TestClient
client = TestClient(app)
response = client.post(“/users”, json={…}) # 测试各种无效输入
assert response.status_code == 422
常见陷阱
:
忘记
Optional
导致必需字段错误。
正则表达式性能:复杂模式可能慢,优化为简单规则。
版本兼容:确保 Pydantic >= 2.0(FastAPI 0.100+ 默认支持),旧版语法略有不同。
安全考虑
:验证输入防止注入(如 SQL/NoSQL),但结合 sanitization(如去除 HTML)。
通过这些,你可以构建安全、可靠的 FastAPI 应用。如果需要特定场景的扩展(如文件上传验证或 OAuth),可以进一步探索 Pydantic 的高级功能。