FastAPI + Pydantic 模型终极实战手册：从能跑就行到固若金汤，这些技巧你一定用得上-育师

这篇文章能帮你搞定什么

用最少的时间学会定义稳固的BaseModel，分清必填和可选字段，用别名搞定前后端字段不一致的尴尬。

再深入一点，用field_validator做好自定义校验，最后彻底搞清楚model_dump()和model_dump_json()的区别。

这些可能就是让你明天上班直接用的东西。

📌 先搭地基：字段类型与默认值

咱们先把模型理解成一份严谨的合同。定义好字段类型和默认值，FastAPI 才能自动生成精准的请求体文档，并在数据进来那一刻就帮你拦住不靠谱的参数。

举个最基础的用户注册模型：

from pydantic import BaseModel class UserRegister(BaseModel): username: str password: str age: int = 18

你可能会问：这样简单，还用讲？重点在后面。这里 age 有个默认值 18，意味着不传也不会报错，而 username 和 password 不传就直接 422。

🧩 必填 vs 可选：别再满屏 Optional 了

早期想着偷懒😅，简单一点，所有非必填字段都写成 Optional[str] = None ，看着没问题，但有一次没注意，一个应该必填的昵称字段没传，代码也没挂，新用户顶着空昵称到处跑。

所以记住一个原则：真正可选的字段才用 Optional 或 Union[..., None]，并且给个 None 默认值。如果业务上必须传，就老老实实只写类型。

from typing import Optional class UserProfile(BaseModel): nickname: str bio: Optional[str] = None

这样做的额外好处是：FastAPI 自动生成的文档里，哪个字段必填一目了然，前端小伙伴再也不会跑来问你“这个要不要传”。

🏷️ 别名与数据转换：字段名打架的终结者

接下来说个最容易翻车的点：
后端模型习惯用 snake_case 下划线命名法，比如 user_name ，但前端传来的 JSON 里全是 camelCase 驼峰命名的 userName 。

这里要记得，别手动改 dict，用 Pydantic 的alias一招搞定。

from pydantic import BaseModel, Field class User(BaseModel): user_name: str = Field(..., alias="userName")

还有一点要注意，用了 alias 却在返回数据时忘了序列化配置。好在 Pydantic v2 里，调用 model_dump(by_alias=True) 就能优雅地在输出时保持别名，这时前端才算彻底舒服了。

🔍 深度点：自定义校验怎么玩

是不是以为加上类型就万事大吉了？别太天真。
用户传个 phone="123" ，类型检查不会报错，但这却不是有效的手机号。怎么办？这时候就该field_validator出场了。

官方文档虽然提供了很多示例，但根据以往的经验，把校验逻辑拆成独立方法、加上 @field_validator 装饰器，比塞在模型里写一大堆 lambda 好维护得多。

from pydantic import BaseModel, field_validator import re class RegisterForm(BaseModel): phone: str password: str @field_validator("phone") @classmethod def check_phone(cls, v): if not re.match(r"^1[3-9]\d{9}$", v): raise ValueError("手机号格式不正确") return v

加上这么一段，校验不通过，Pydantic 直接抛出 ValidationError，FastAPI 会帮你转成友好的 422 响应，干净利落，后台再也不会收到乱七八糟的电话号了！

🛡️ 全流程拦截的 model_validator

上面说了 field_validator 管单个字段，有时需要横跨多个字段做联动校验，比如“密码和确认密码是否一致”，这就要请出model_validator了。

from pydantic import model_validator class RegisterForm(BaseModel): password: str confirm_password: str @model_validator(mode="after") def check_passwords_match(self): if self.password != self.confirm_password: raise ValueError("两次密码不一致，好好检查下") return self

mode 选 "after" 意思是在各个字段单独校验都通过后再跑，拿到的 self 里字段值已经可靠了。

这种跨字段校验扔在模型里，比在路由函数里写 if 判断要利落得多，还不会忘了校验导致脏数据溜进去。

⚙️ 计算字段 computed_field，别再手动拼属性了

有些字段根本不需要前端传，而是根据其他字段算出来的。
以前我都写个@property，然后序列化时还得手动拼字典绕一大圈。后来发现 Pydantic 直接提供了computed_field，丝滑得不行。

from pydantic import BaseModel, computed_field class Order(BaseModel): unit_price: float quantity: int @computed_field @property def total_price(self) -> float: return self.unit_price * self.quantity

这样total_price会像普通字段一样出现在序列化结果里，但模型初始化时根本不用传它。⚠️ 但要注意那个@property装饰器不能省，不然 Pydantic 不认。

这个组合用顺手了，代码里少写很多冗余逻辑。

🔄 model_dump() 与 model_dump_json()：序列化的分叉口

再说个我曾经犯迷糊的点，以为这俩差不多。其实区别还是很明显的：

model_dump() 返回的是 Python 字典，
model_dump_json() 返回的是 JSON 字符串。

在 FastAPI 的路径函数里直接 return 模型实例即可，框架会自动调用序列化，但假如你要自己处理后返回给前端，或者存到 Redis，那必须搞清用哪个。

一个顺手的小技巧：
如果想在接口响应里把字段转成别名形式，直接 model_dump(by_alias=True)，而 model_dump_json 默认就会尊重别名配置，省得手动替换 key。
还有，model_dump 有个参数 exclude_unset=True ，可以只输出显式赋值的字段，在更新接口里格外好用，避免把没改的字段覆盖成默认值。

🎯 模型配置 ConfigDict，你的模型管家

说到这了，再加个知识点：就是用 alias 时那个model_dump(by_alias=True)老得手动传，要是忘了咋整？总不能每次都赌自己记性好吧。
这时候就该请出模型的管家——ConfigDict。直接在模型里定义一套默认行为，省心多了。

from pydantic import BaseModel, ConfigDict class User(BaseModel): model_config = ConfigDict( populate_by_name=True, # 允许用字段名或别名填充，容错率拉满（请求体里传 user_name 或者 userName 都认） str_strip_whitespace=True, # 自动去掉字符串首尾空格，别再手动 strip 了 use_enum_values=True, # 枚举字段序列化时直接用值而不是对象 ) user_name: str = Field(..., alias="userName") age: int

✂️ 序列化时排除字段，exclude 用得巧省大事

再说个经常翻车的场景：
用户登录接口返回用户信息，password_hash 字段绝不能返回给前端。怎么优雅地排除？

三种常用姿势，看情况选：

第一种，直接在模型配置里设exclude，这样所有用到这模型的地方都不会暴露密码了，适合全局保护。

class UserInDB(BaseModel): model_config = ConfigDict(exclude={"password_hash"}) username: str password_hash: str

第二种，调用model_dump()时临时排除，适合同一个模型不同场景不同需求的弹性操作。

user = UserInDB(username="xiaohei", password_hash="secret123") data = user.model_dump(exclude={"password_hash"})

第三种，用Field(exclude=True)钉死在这个字段上，一劳永逸。

💡 建议把密码、加密密钥这种敏感字段从源头设成exclude=True，千万别等上线了再补救。

🌱 嵌套模型与继承，解决模型膨胀

当请求模型、数据库模型、响应模型长得像但又略有不同时，别复制粘贴一堆差不多的类，Pydantic 的继承很好用。

class UserBase(BaseModel): username: str email: str class UserCreate(UserBase): password: str # 创建时需要密码 class UserResponse(UserBase): model_config = ConfigDict(from_attributes=True) # 支持 ORM 对象直接转换 id: int

这样基础字段定义一次，不同场景只加各自需要的。

其中from_attributes=True这个尤其关键，它让你可以直接把 SQLAlchemy 模型对象丢进 Pydantic 并自动转换。没用之前，你可能要手动一条条取属性赋值，那个中滋味……。