文章目录一、为什么需要 Pydantic二、安装三、基础模型BaseModel四、Field更精细的控制五、自定义验证器1. 字段验证器field_validator2. 模型级验证器model_validator六、嵌套模型与复杂类型七、配置管理pydantic-settings八、常用进阶特性速览九、与 FastAPI 的结合预告十、最佳实践Pydantic 是 Python 中最流行的数据验证与设置管理库深度结合类型注解能自动做类型转换、数据校验、生成文档和序列化。它是 FastAPI 的核心依赖也广泛应用于配置管理、API 接口、数据处理等场景。当前主流版本是Pydantic v2性能大幅提升API 更清晰。一、为什么需要 Pydantic传统手动验证defcreate_user(data:dict):ifnamenotindataornotisinstance(data[name],str):raiseValueError(name 必须是字符串)ifageindataand(notisinstance(data[age],int)ordata[age]0):raiseValueError(age 必须是非负整数)# ... 非常繁琐使用 Pydantic 后frompydanticimportBaseModelclassUser(BaseModel):name:strage:intuserUser(nameAlice,age25)# 自动验证 转换print(user.name,user.age)优点声明式代码简洁自动类型转换如25→25详细的错误信息与 IDE / 类型检查器完美配合支持 JSON 序列化/反序列化可生成 JSON Schema二、安装pipinstallpydantic# 如果需要配置管理pipinstallpydantic-settings三、基础模型BaseModelfrompydanticimportBaseModel,FieldclassUser(BaseModel):name:strage:intemail:str|NoneNone# 可选字段is_active:boolTrue# 默认值# 创建实例自动验证userUser(nameAlice,age25)# 字符串 25 会自动转成 intprint(user)# nameAlice age25 emailNone is_activeTrueprint(user.model_dump())# 转成字典v2 推荐用法print(user.model_dump_json())# 转成 JSON 字符串常用方法Pydantic v2方法作用model_dump()转成 Python 字典model_dump_json()转成 JSON 字符串model_validate()从字典/对象创建并验证model_validate_json()从 JSON 字符串创建并验证model_json_schema()生成 JSON Schema四、Field更精细的控制frompydanticimportBaseModel,FieldclassUser(BaseModel):name:strField(min_length2,max_length50,description用户名)age:intField(gt0,lt150,example25)# gt大于, lt小于score:floatField(default0,ge0,le100)# ge大于等于tags:list[str]Field(default_factorylist)# 可变默认值用 default_factorypassword:strField(reprFalse)# 不在 repr 中显示常用约束参数min_length/max_length字符串、列表等gt/ge/lt/le数值pattern正则字符串default/default_factorydescription、example用于文档生成alias别名用于接收/输出不同字段名五、自定义验证器1. 字段验证器field_validatorfrompydanticimportBaseModel,field_validatorclassUser(BaseModel):name:strage:intfield_validator(name)classmethoddefname_must_not_be_empty(cls,v:str)-str:ifnotv.strip():raiseValueError(姓名不能为空)returnv.strip().title()# 可顺便做转换field_validator(age)classmethoddefage_check(cls,v:int)-int:ifv0:raiseValueError(年龄不能为负数)returnv2. 模型级验证器model_validator用于跨字段校验frompydanticimportBaseModel,model_validatorclassRegisterForm(BaseModel):password:strconfirm_password:strmodel_validator(modeafter)defcheck_passwords_match(self)-RegisterForm:ifself.password!self.confirm_password:raiseValueError(两次密码不一致)returnselfmodebefore在验证前处理原始数据modeafter在字段验证后处理。六、嵌套模型与复杂类型frompydanticimportBaseModelfromdatetimeimportdatetimeclassAddress(BaseModel):city:strstreet:strclassUser(BaseModel):name:straddress:Address# 嵌套模型tags:list[str][]metadata:dict[str,str]{}created_at:datetime userUser(nameAlice,address{city:北京,street:中关村大街},# 自动转成 Address 对象created_at2026-08-24T12:00:00# 自动解析时间)print(user.address.city)# 北京支持的类型非常丰富list、dict、set、tuple、Optional、Union、Literal、自定义类等。七、配置管理pydantic-settings非常适合读取环境变量和.env文件frompydantic_settingsimportBaseSettings,SettingsConfigDictclassSettings(BaseSettings):model_configSettingsConfigDict(env_file.env,env_file_encodingutf-8,extraignore# 忽略未定义的环境变量)app_name:strMyAppdebug:boolFalsedatabase_url:strmax_connections:int10settingsSettings()print(settings.database_url)对应.env文件DATABASE_URLpostgresql://user:passlocalhost/db DEBUGtrue八、常用进阶特性速览特性说明Literal限制字段只能是特定值EmailStr邮箱格式验证需安装email-validatorHttpUrlURL 验证conint/constr等带约束的类型v2 更推荐用 FieldConfigDict模型配置frozenTrue不可变、extraforbid禁止额外字段等computed_field计算字段model_serializer自定义序列化逻辑TypeAdapter不需要完整模型也能验证简单类型示例禁止额外字段 不可变frompydanticimportBaseModel,ConfigDictclassUser(BaseModel):model_configConfigDict(extraforbid,frozenTrue)name:strage:int九、与 FastAPI 的结合预告FastAPI 直接使用 Pydantic 模型做请求体验证和响应序列化fromfastapiimportFastAPIfrompydanticimportBaseModel appFastAPI()classUserCreate(BaseModel):name:strage:intapp.post(/users/)defcreate_user(user:UserCreate):return{message:f创建用户{user.name}}这就是为什么学 FastAPI 之前强烈建议先掌握 Pydantic。十、最佳实践优先使用类型注解 Field 约束少写手动 if 判断可变默认值一定要用default_factory生产环境建议设置extraforbid防止多余字段悄悄进入复杂校验优先用field_validator/model_validator配置类继承BaseSettings业务数据模型继承BaseModelv2 中统一使用model_dump()、model_validate()等方法旧的.dict()、.parse_obj()已弃用 感谢阅读想了解更多 我的博客网站 | 记录思考分享干货 我的个人主页 | 关于我、开源项目