这篇文章能帮你搞定什么用最少的时间学会定义稳固的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(..., aliasuserName)还有一点要注意用了 alias 却在返回数据时忘了序列化配置。好在 Pydantic v2 里调用 model_dump(by_aliasTrue) 就能优雅地在输出时保持别名这时前端才算彻底舒服了。 深度点自定义校验怎么玩是不是以为加上类型就万事大吉了别太天真。用户传个 phone123 类型检查不会报错但这却不是有效的手机号。怎么办这时候就该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 直接抛出 ValidationErrorFastAPI 会帮你转成友好的 422 响应干净利落后台再也不会收到乱七八糟的电话号了️ 全流程拦截的 model_validator上面说了 field_validator 管单个字段有时需要横跨多个字段做联动校验比如“密码和确认密码是否一致”这就要请出model_validator了。from pydantic import model_validator class RegisterForm(BaseModel): password: str confirm_password: str model_validator(modeafter) def check_passwords_match(self): if self.password ! self.confirm_password: raise ValueError(两次密码不一致好好检查下) return selfmode 选 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_aliasTrue)而 model_dump_json 默认就会尊重别名配置省得手动替换 key。还有model_dump 有个参数 exclude_unsetTrue 可以只输出显式赋值的字段在更新接口里格外好用避免把没改的字段覆盖成默认值。 模型配置 ConfigDict你的模型管家说到这了再加个知识点就是用 alias 时那个model_dump(by_aliasTrue)老得手动传要是忘了咋整总不能每次都赌自己记性好吧。这时候就该请出模型的管家——ConfigDict。直接在模型里定义一套默认行为省心多了。from pydantic import BaseModel, ConfigDict class User(BaseModel): model_config ConfigDict( populate_by_nameTrue, # 允许用字段名或别名填充容错率拉满请求体里传 user_name 或者 userName 都认 str_strip_whitespaceTrue, # 自动去掉字符串首尾空格别再手动 strip 了 use_enum_valuesTrue, # 枚举字段序列化时直接用值而不是对象 ) user_name: str Field(..., aliasuserName) age: int✂️ 序列化时排除字段exclude 用得巧省大事再说个经常翻车的场景用户登录接口返回用户信息password_hash 字段绝不能返回给前端。怎么优雅地排除三种常用姿势看情况选第一种直接在模型配置里设exclude这样所有用到这模型的地方都不会暴露密码了适合全局保护。class UserInDB(BaseModel): model_config ConfigDict(exclude{password_hash}) username: str password_hash: str第二种调用model_dump()时临时排除适合同一个模型不同场景不同需求的弹性操作。user UserInDB(usernamexiaohei, password_hashsecret123) data user.model_dump(exclude{password_hash})第三种用Field(excludeTrue)钉死在这个字段上一劳永逸。 建议把密码、加密密钥这种敏感字段从源头设成excludeTrue千万别等上线了再补救。 嵌套模型与继承解决模型膨胀当请求模型、数据库模型、响应模型长得像但又略有不同时别复制粘贴一堆差不多的类Pydantic 的继承很好用。class UserBase(BaseModel): username: str email: str class UserCreate(UserBase): password: str # 创建时需要密码 class UserResponse(UserBase): model_config ConfigDict(from_attributesTrue) # 支持 ORM 对象直接转换 id: int这样基础字段定义一次不同场景只加各自需要的。其中from_attributesTrue这个尤其关键它让你可以直接把 SQLAlchemy 模型对象丢进 Pydantic 并自动转换。没用之前你可能要手动一条条取属性赋值那个中滋味……。 最后啰嗦几句这套搭配就像给数据加了安检门BaseModel 定义形状Field 管别名和描述field_validator 把坏东西挡在外面最后用合适的序列化方法把干净数据送出去。一旦顺手了你就再也不想回到那个手动校验的手工作坊时代。 给前端小伙伴的馈赠JSON Schema 生成只要你老老实实定义好了 Pydantic 模型FastAPI 会自动帮你生成详尽的 JSON Schema 放进 OpenAPI 文档里字段类型、必填性、示例值、描述全都有。想让体验更好可以给每个 Field 加上 description 和 examples。这样不仅文档清晰配合一些代码生成工具甚至能自动产生前端类型定义。Pydantic 就像洋葱一层有一层的惊喜。初期用基础类型定义和可选字段就能跑但等你把 ConfigDict、校验器、计算字段、嵌套继承这些拎起来之后模型层才是真正稳固的铠甲。