一句话总结Pydantic 就是帮你管数据、查错、自动转格式的工具靠 Python 自带的「类型注解」干活不用手写一堆判断逻辑。一、先搞懂它是干嘛的日常写代码经常遇到这些麻烦接口 / 爬虫拿到数据字符串数字混在一起还要手动转类型要写一堆if判断年龄不能负数、手机号必须 11 位、邮箱格式对不对数据字段乱传多传、少传字段程序莫名报错Pydantic 专门解决以上问题自动帮你转换数据类型自动帮你校验数据规则长度、范围、格式数据不对直接抛出清晰错误不用自己写大量判断轻松把对象转字典、JSON方便网络传输 / 存文件二、安装打开命令行执行bash运行pip install pydantic三、核心入门基础模型 BaseModel所有数据模板都要继承BaseModel我们把它理解成 **「数据模板 / 表单」**。1. 最简单例子定义一个「用户表单」规定好每个字段是什么类型python运行from pydantic import BaseModel # 定义数据模板表单 class User(BaseModel): name: str # 姓名必须是字符串 age: int # 年龄必须是整数 is_member: bool # 是否会员必须是布尔值 # 传入数据字典形式解包 data {name: 小明, age: 20, is_member: true} user User(**data) # 查看结果 print(user.name) print(user.age, type(user.age)) # 原本是字符串20自动转成整数 20 print(user.is_member) 重点不用手动int()转换Pydantic 自动帮你转类型。2. 数据错误会自动报错如果数据不符合类型直接报错提醒不用你写if判断python运行# age 传了文字转不成数字 user User(name小红, ageabc, is_memberFalse)运行会弹出明确错误age 输入无效不是合法整数。四、常用基础配置1. 默认值字段可不传像表单选填项不传就用默认值python运行class User(BaseModel): name: str age: int 18 # 不传age默认就是182. 可选字段允许为空 None有些字段可填可不填用Optional或| Nonepython运行from typing import Optional class User(BaseModel): name: str remark: Optional[str] None # 选填不填就是空3. 数据传入的 3 种方式python运行class User(BaseModel): name: str age: int # 方式1直接传关键字最常用 u1 User(name小李, age22) # 方式2解包字典接口/配置文件常用 d {name: 小张, age: 25} u2 User(**d) # 方式3从普通对象读取数据 class Temp: name 小王 age 30 u3 User.model_validate(Temp())五、数据互转模型 ↔ 字典 ↔ JSON拿到模型实例后快速转成通用格式用于接口、存文件。1. 模型 → 字典python运行u User(name小明, age20) res_dict u.model_dump() print(res_dict) # {name: 小明, age: 20}2. 模型 → JSON 字符串网络传输专用python运行res_json u.model_dump_json() print(res_json)3. JSON 字符串 → 模型接收接口数据专用python运行json_str {name: 小美, age: 21} u User.model_validate_json(json_str) print(u.name)六、进阶给字段加规则Field字段重点只限制类型不够比如年龄必须 0~120用户名长度 2~20 位手机号必须是 11 位数字这时用Field相当于给表单加填写规则。1. 基础用法python运行from pydantic import BaseModel, Field class User(BaseModel): # 年龄0 ≤ age ≤ 120默认18 age: int Field(ge0, le120, default18) # 用户名最短2位最长20位 username: str Field(min_length2, max_length20)参数通俗解释ge大于等于le小于等于gt大于lt小于min_length/max_length字符串最短 / 最长长度default默认值2. 正则校验手机号、账号用pattern写正则限制格式python运行class User(BaseModel): # 手机号必须11位以1开头 phone: str Field(patternr^1\d{10}$)传13800138000正常传123直接报错。3. 搭配 Annotated推荐规则可复用如果多个模板都要用「年龄、手机号」规则不用重复写结合之前学的Annotated抽成公共规则python运行from typing import Annotated from pydantic import BaseModel, Field # 定义通用规则一次定义到处使用 AgeRule Annotated[int, Field(ge0, le120)] PhoneRule Annotated[str, Field(patternr^1\d{10}$)] # 第一个模板使用 class User(BaseModel): age: AgeRule phone: PhoneRule # 第二个模板直接复用规则不用重写 class Student(BaseModel): age: AgeRule phone: PhoneRule4. 列表 / 字典默认值避坑列表、字典不能直接写默认值用default_factorypython运行class User(BaseModel): # 每次新建用户自动生成空列表 tags: list[str] Field(default_factorylist)七、自带专用格式类型开箱即用Pydantic 内置了很多常用格式不用自己写正则python运行from pydantic import BaseModel, EmailStr, HttpUrl class Info(BaseModel): email: EmailStr # 自动校验邮箱格式 url: HttpUrl # 自动校验网址http/https输入错误格式会自动拦截。八、复杂结构嵌套模型现实数据是分层的比如「用户」包含「地址」可以模型套模型python运行from pydantic import BaseModel # 子模板地址 class Address(BaseModel): city: str street: str # 主模板用户嵌套地址 class User(BaseModel): name: str addr: Address # 直接嵌入地址模板 # 传入分层数据 data { name: 小明, addr: {city: 北京, street: XX路} } user User(**data) print(user.addr.city) # 读取嵌套内容九、自定义校验规则复杂逻辑内置规则不够用时自己写校验函数分两种1. 单字段校验field_validator单独检查某一个字段python运行from pydantic import BaseModel, field_validator class User(BaseModel): username: str # 自定义校验用户名不能包含 admin field_validator(username) def check_name(cls, value): if admin in value.lower(): raise ValueError(用户名不能包含admin) return value2. 多字段联合校验model_validator多个字段互相约束比如「单价 × 数量 总价」python运行from pydantic import BaseModel, model_validator class Order(BaseModel): price: float count: int total: float model_validator(modeafter) def check_total(self): if self.price * self.count ! self.total: raise ValueError(总价计算错误) return self十、模型全局配置 model_config统一设置模板行为常用配置python运行from pydantic import BaseModel, ConfigDict class User(BaseModel): name: str age: int # 全局配置 model_config ConfigDict( extraforbid, # 严格模式不允许传模板以外的字段接口必备 str_strip_whitespaceTrue # 自动去掉字符串首尾空格 )extraforbid多传字段直接报错防止脏数据。十一、错误捕获数据校验失败会抛出ValidationError可以捕获异常做友好提示python运行from pydantic import BaseModel, ValidationError class User(BaseModel): age: int Field(ge0) try: User(age-10) except ValidationError as e: print(数据错误, e)十二、Pydantic v1 和 v2 简单区分老代码兼容现在新项目一律用v2速度更快语法看这里对照表格功能Pydantic v2新Pydantic v1旧转字典model_dump()dict()转 JSONmodel_dump_json()json()解析 JSONmodel_validate_json()parse_raw()字段校验field_validatorvalidator十三、日常使用场景知道什么时候用Web 接口FastAPI最主流用法校验前端传的参数配置文件解析 JSON/YAML 配置保证格式正确爬虫清洗爬取的杂乱数据统一格式、过滤脏数据微服务 / 数据交互统一多方传递的数据结构避免混乱十四、极简综合示例可直接运行python运行from typing import Annotated, Optional from pydantic import BaseModel, Field, EmailStr, ConfigDict # 通用规则 UserName Annotated[str, Field(min_length2, max_length20)] Age Annotated[int, Field(ge0, le120, default18)] class User(BaseModel): model_config ConfigDict(extraforbid) name: UserName age: Age email: Optional[EmailStr] None # 测试 data {name: 测试, age: 25, email: test123.com} user User(**data) print(user.model_dump_json(indent2))