登录/ 注册
 找回密码
 立即注册
关闭

CSDN热搜

程序园 精品问答 技术交流 资源下载
返回列表 发新帖
首页 › 业界区 › 安全 ›Pydantic 学习与使用

Pydantic 学习与使用

厥轧匠 2025-5-30 15:29:59
Pydantic 学习与使用

在 Fastapi 的 Web 开发中的数据验证通常都是在使用 Pydantic 来进行数据的校验，本文将对 Pydantic 的使用方法做记录与学习。
简介：Pydantic 是一个在 Python 中用于数据验证和解析的第三方库，它现在是 Python 使用最广泛的数据验证库。它利用声明式的方式定义数据模型和Python 类型提示的强大功能来执行数据验证和序列化，使您的代码更可靠、更可读、更简洁且更易于调试。它还可以从模型生成 JSON 架构，提供了自动生成文档等功能，从而轻松与其他工具集成。
参考文章：
作者：暴走的海鸽
链接：https://juejin.cn/post/7395080141130039305
1. Pydantic 快速上手
  1. # 安装
  2. pip install pydantic
  4. # 使用 email 验证的时候需要额外安装
  5. pip install pydantic[email]
复制代码
Pydantic 使用起来简单直观，需要最少的样板代码和配置。它适用于许多流行的 IDE 和静态分析工具，例如 PyCharm、VS Code、mypy 等。Pydantic 可以轻松与其他流行的 Python 库（如 Flask、Django、FastAPI 和 SQLAlchemy）集成，使其易于在现有项目中使用。
Pydantic 使用类型注解来定义模型的字段类型,以确保确保数据符合预期的类型和格式。你可以使用Python 内置的类型、自定义类型或者其他Pydantic 提供的验证类型。
Pydantic 提供了从各种数据格式（例如 JSON、字典）到模型实例的转换功能。它可以自动将输入数据解析成模型实例，并保留类型安全性和验证规则。
Pydantic 的核心验证逻辑是用 Rust 编写的，使其成为 Python 中最快的数据验证库之一。它还支持延迟验证和缓存，以提高效率。
1.1  数据验证

Pydantic 的核心验证逻辑是用 Rust 编写的，使其成为 Python 中最快的数据验证库之一。它还支持延迟验证和缓存，以提高效率。然后，您可以使用类型注释定义模型的属性，并选择性地提供默认值或验证器。
  1. from enum import Enum
  2. from datetime import datetime
  3. from typing import Optional
  4. from pydantic import BaseModel, conint, EmailStr, constr
  7. class GenderEnum(str, Enum):
  8.     """
  9.     性别类的枚举, 使用多继承创建;
  10.     """
  11.     male = "男"
  12.     female = "女"
  15. class User(BaseModel):
  16.     """
  17.     继承的基类;
  18.     """
  19.     id: int
  20.     name: str
  21.     age: conint(ge=0, le=100)  # 使用 Pydantic 限制数字范围;
  22.     gender: GenderEnum
  23.     email: EmailStr  # 使用 Pydantic 的邮件约束来限制约束;
  24.     signup_ts: Optional[datetime] = None
  25.     password: constr(min_length=8, max_length=16)
  28. if __name__ == '__main__':
  29.     user_data = {
  30.         "id": 1,
  31.         "name": "傻狗",
  32.         "age": 18,
  33.         "gender": GenderEnum.male,
  34.         "email": "123456788@qq.com",
  35.         "signup_ts": datetime.now(),
  36.         "password": "<PASSWORD>",
  37.     }
  38.     user = User.model_validate(user_data)
  39.     print(user)
  40.     print(f"User id: {user.id}, User name: {user.name}, User email: {user.email}")
  42. """
  43. >>> 输出:
  44. id=1 name='傻狗' age=18 gender=<GenderEnum.male: '男'> email='123456788@qq.com' signup_ts=datetime.datetime(2025, 5, 24, 14, 25, 6, 493690) password='<PASSWORD>'
  45. User id: 1, User name: 傻狗, User email: 123456788@qq.com
  46. """
复制代码
上述的代码就是针对字典中的数据完成数据的校验；
当我们的校验需求比较复杂的时候，我们就可以自己定义比较复杂的校验函数进行使用
  1. from enum import Enum
  2. from datetime import datetime
  3. from typing import Optional, List
  4. from pydantic import BaseModel, conint, EmailStr, constr, field_validator
  7. class GenderEnum(str, Enum):
  8.     """
  9.     性别类的枚举, 使用多继承创建;
  10.     """
  11.     male = "男"
  12.     female = "女"
  15. def check_name(name: str) -> str:
  16.     """
  18.     :param name:
  19.     :return:
  20.     """
  21.     if not name.startswith("小"):  # 检查字符串是否以特定字符开头
  22.         raise ValueError("must be startswith 小")
  23.     return name
  26. class User(BaseModel):
  27.     """
  28.     继承的基类;
  29.     """
  30.     id: int
  31.     name: str
  32.     age: conint(ge=0, le=100)  # 使用 Pydantic 限制数字范围;
  33.     # gender: GenderEnum
  34.     email: EmailStr  # 使用 Pydantic 的邮件约束来限制约束;
  35.     signup_ts: Optional[datetime] = None
  36.     # password: constr(min_length=8, max_length=16)
  37.     friends: List[str] = []
  39.     validate_fields = field_validator("name")(check_name)
  41.     @field_validator("age")
  42.     @classmethod  # 装饰器的顺序不要放错, 否则可能不生效;
  43.     def check_age(cls, age: int):
  44.         if age < 18:
  45.             raise ValueError("age must be >= 18")
  46.         return age
  49. if __name__ == '__main__':
  50.     user_data = {
  51.         "id": 123,
  52.         "name": "小卤蛋",
  53.         "age": 28,  # 小于18 就会报错;
  54.         "email": "xiaoludan@example.com",
  55.         'signup_ts': '2024-07-19 00:22',
  56.         'friends': ["公众号：海哥python", '小天才', b''],
  57.     }
  58.     user = User(**user_data)
  59.     print(user.age)  # 取出模型中的数据
  60.     print(user.model_dump())  # 字典的形式输出;
复制代码
特别注意：Pydantic 是强制的校验，不满足的时候程序会进行报错，注意和泛型进行区分；
上述的代码，我们是一个字段的进行的校验，那么我们能不能一次校验多个字段呢？
  1. from datetime import datetime
  2. from typing import List, Optional
  3. from typing_extensions import Self  # 如果python版本不低于3.11，则可以直接从typing中导入Self
  4. from pydantic import BaseModel, ValidationError, EmailStr, field_validator, model_validator
  7. def check_name(v: str) -> str:
  8.     """Validator to be used throughout"""
  9.     if not v.startswith("小"):
  10.         raise ValueError("must be startswith 小")
  11.     return v
  14. class User(BaseModel):
  15.     id: int
  16.     name: str = "小卤蛋"
  17.     age: int
  18.     email: EmailStr
  19.     signup_ts: Optional[datetime] = None
  20.     friends: List[str] = []
  22.     validate_fields = field_validator("name")(check_name)
  24.     @field_validator("age")
  25.     @classmethod
  26.     def check_age(cls, age):
  27.         if age < 18:
  28.             raise ValueError("用户年龄必须大于18岁")
  29.         return age
  31.     @model_validator(mode="after")  # after 模式表示是所有字段完成验证之后再进行额外的验证;
  32.     def check_age_and_name(self) -> Self:
  33.         if self.age < 30 and self.name != "小卤蛋":
  34.             raise ValueError("用户年龄必须小于30岁, 且名字必须为小卤蛋")
  36.         return self
  39. if __name__ == '__main__':
  40.     user_data = {
  41.         "id": 123,
  42.         "name": "小xi卤蛋",
  43.         "age": 20,
  44.         "email": "xiaoludan@example.com",
  45.         'signup_ts': '2024-07-19 00:22',
  46.         'friends': ["公众号：海哥python", '小天才', b''],
  47.     }
  48.     try:
  49.         user = User(**user_data)
  50.         print(user.model_dump())
  51.     except ValidationError as e:
  52.         print(f"Validation error: {e.json()}")
复制代码
上述的代码会同时对age和name字段进行验证，使用的是装饰器model_validator;
额外补充：上述的代码中用到了Enum枚举类，枚举类是一种特殊的类，用于定义一组固定的常量。在编程中，我们经常需要表示一些有限的、固定的状态或者选项。例如，一周的星期几（星期一、星期二……星期日），或者一个交通信号灯的状态（红灯、黄灯、绿灯）。使用枚举类可以清晰地表示这些固定的状态，避免使用容易出错的字符串或者整数来表示。

  • 创建枚举类
    1. # Enum 是 Python 的标准库 enum 模块中的一个类，是创建枚举类的基础。
    2. from enum import Enum
    4. class Color(Enum):
    5.     """ 枚举类;
    6.     """
    7.     RED = 1
    8.     GREEN = 2
    9.     BLUE = 3
    复制代码
  • 枚举类的基本属性和方法

    • name 属性，表示枚举成员的名称
      1. print(Color.RED.name)  # 输出 "RED"
      复制代码
    • value 属性：表示枚举成员的值。
      1. print(Color.RED.value)  # 输出 1
      复制代码
    • __members__ 属性：返回一个包含枚举类中所有成员的字典，键是成员名称，值是成员本身。
      1. for name, member in Color.__members__.items():
      2.     print(name, member)
      4. """
      5. RED Color.RED
      6. GREEN Color.GREEN
      7. BLUE Color.BLUE
      8. """
      复制代码
    • __iter__ 方法：可以对枚举类进行迭代，迭代的是枚举成员。
      1. for color in Color:
      2.     print(color)
      4. """
      5. Color.RED
      6. Color.GREEN
      7. Color.BLUE
      8. """
      复制代码

  • 枚举类的应用场景
    在开发软件时，很多对象都有状态。例如，一个订单的状态可以是“已下单”“已支付”“已发货”“已完成”等。使用枚举类来表示这些状态可以避免使用字符串或者整数来直接表示状态，减少错误。当需要从一组固定的选项中选择时，枚举类也很有用。比如在一个图形界面程序中，用户可以选择不同的字体样式，这些字体样式可以用枚举类来表示。使用枚举类可以使代码更清晰。例如，用枚举类表示星期几，相比直接使用数字或者字符串，代码更容易理解。
model_validator 是 Pydantic 中的一个装饰器，用于在模型实例创建后进行验证。它允许开发者在模型的所有字段都被解析和验证之后，执行额外的验证逻辑。这个装饰器可以用于确保模型的多个字段之间的关系或其他复杂的验证条件。
  1. from typing import Annotated
  3. from pydantic import BaseModel, Field, validate_call
  6. class Person(BaseModel):
  7.     name: str = Field(..., min_length=1, max_length=100)
  8.     age: int = Field(..., gt=0, lt=20)
  11. # @validate_call  
  12. def greet(person: Person, message: Annotated[str, Field(min_length=1, max_length=100)]):
  13.     print(f"Hello, {person.name}! {message}")
  16. # 正确的调用
  17. greet(Person(name="公众号", age=18), "How are you?")
  18. greet(Person(name="公众号", age=18), 1)  # 不使用装饰器会运行,但是与类型不符, 使用 @ 装饰器后会报错;
复制代码
然而，我们通常是希望定义和使用要符合我们的预期，以避免不可预见的错误。
此时validate_call装饰器就可以很好的为我们实现这一需求。
1.2 计算属性

核心的装饰器： @computed_field  # 计算属性 @property 被装饰函数以值的形式返回；
  1. from datetime import datetime
  2. from typing import List, Optional
  3. from pydantic import BaseModel, ValidationError, EmailStr, computed_field
  6. class User(BaseModel):
  7.     id: int
  8.     name: str = "小卤蛋"
  9.     age: int
  10.     email: EmailStr
  11.     signup_ts: Optional[datetime] = None
  12.     friends: List[str] = []
  14.     @computed_field  # 计算属性
  15.     @property
  16.     def link(self) -> str:
  17.         return f"尼古拉斯 · {self.name}"
  20. if __name__ == '__main__':
  22.     user_data = {
  23.         "id": 123,
  24.         "name": "小卤蛋",
  25.         "age": 20,
  26.         "email": "xiaoludan@example.com",
  27.         'signup_ts': '2024-07-19 00:22',
  28.         'friends': ["公众号：海哥python", '小天才', b''],
  29.     }
  30.     #
  31.     try:
  32.         user = User(**user_data)
  33.         print(f"{user.model_dump()} .... type: {type(user.model_dump())}")
  34.     except ValidationError as e:
  35.         print(f"Validation error: {e.json()}")
复制代码
当使用装饰link 属性会跟随着结果一起显示出来，
2. Pydantic 配置管理
  1. # 安装依赖
  2. pip install pydantic_settings
复制代码
2.1 直接设置

pydantic_settings可以很好的管理服务中的配置信息；使用的时候继承 BaseSettings 可以直接从环境变量中读取相对应的配置信息，也可以以手动填入的方式进行；
  1. import os
  3. # 导入需要的配置;
  4. from pydantic import HttpUrl, Field
  5. from pydantic_settings import BaseSettings
  7. # 初始化环境变量
  8. os.environ['DATABASE_HOST'] = "http://baidu.com"
  9. os.environ['DATABASE_USER'] = "公众号：海哥python"
  10. os.environ['DATABASE_PASSWORD'] = "123456abcd"
  11. os.environ['API_KEY'] = "DHKSDsdh*(sdds"
  14. class AppConfig(BaseSettings):
  15.     """
  16.     应用配置类, 用来管理应用程序的配置信息;
  18.     """
  19.     # 定义配置项
  20.     # 定义 url 形式的配置;
  21.     DATABASE_HOST: HttpUrl
  23.     # 定义配置项database_user，类型为字符串，默认最小长度为5
  24.     DATABASE_USER: str = Field(min_length=5)
  25.     # 定义配置项database_password，类型为字符串，默认最小长度为10
  26.     DATABASE_PASSWORD: str = Field(min_length=10)
  27.     # 定义配置项api_key，类型为字符串，默认最小长度为8
  28.     API_KEY: str = Field(min_length=8)
  31. # 打印配置类的实例化对象的模型信息，用于调试和确认配置的正确性
  32. print(AppConfig().model_dump())
复制代码
1.png

2.2 配置文件

在代码的同级目录下创建一个.env的配置文件；
  1. DATABASE_HOST=http://baidu.com
  2. DATABASE_USER=公众号：海哥python
  3. DATABASE_PASSWORD=123456abcd
  4. API_KEY=DHKSDsdh*(sdds
复制代码
代码变化不大, 只有加载的部分发生一些变化；
  1. # 导入需要的配置;
  2. from pydantic import HttpUrl, Field
  3. from pydantic_settings import BaseSettings, SettingsConfigDict
  6. class Settings(BaseSettings):
  7.     """
  8.     定义模型的基本类；
  9.     """
  10.     # 定义配置模型的设置，包括.env文件位置、编码、大小写敏感性和额外参数策略
  11.     model_config = SettingsConfigDict(
  12.         env_file=".env",
  13.         env_file_encoding="utf-8",
  14.         case_sensitive=False,
  15.         extra="forbid"
  16.     )
  18.     # 数据库主机的URL，必须是一个有效的HTTP或HTTPS URL
  19.     database_host: HttpUrl
  20.     # 数据库用户的名称，最小长度为5个字符
  21.     database_user: str = Field(min_length=5)
  22.     # 数据库用户的密码，最小长度为10个字符
  23.     database_password: str = Field(min_length=10)
  24.     # API的密钥，最小长度为8个字符
  25.     api_key: str = Field(min_length=8)
  28. if __name__ == '__main__':
  29.     # 打印配置类的实例化对象的模型信息，用于调试和确认配置的正确性
  30.     print(Settings().model_dump())
复制代码
3. Pydantic 高级应用

3.1 数据嵌套

Pydantic 支持嵌套数的数据模型，方便管理复杂的数据结构。
  1. from typing import List
  2. from pydantic import BaseModel, conint
  5. class Friend(BaseModel):
  6.     name: str
  7.     age: conint(gt=0, le=99)
  10. class User(BaseModel):
  11.     name: str
  12.     age: conint(gt=0, le=99)
  13.     friends: List[Friend]  # 设置字段嵌套 Friend 类.
  16. if __name__ == '__main__':
  17.     # 创建并验证数据
  18.     user_data = {
  19.         'name': '三体-章北海',
  20.         'age': 30,
  21.         # 设置嵌套,
  22.         'friends': [{'name': '小卤蛋', 'age': 3}, {'name': '李元芳', 'age': 18}]
  23.     }
  24.     user = User(**user_data)
  25.     print(user)
复制代码
3.2 Filed 的使用

Pydantic 的Field函数是一个强大的工具，它允许你在模型字段上设置额外的验证规则和默认值。Field 函数通常与模型字段一起使用，以提供更多的定制选项。
参数具体含义...表示该字段是必填项default用于定义字段的默认值default_factory用于定义字段的默认值函数alias字段定义别名validation_alias字段定义别名，只想将别名用于验证serialization_alias 字段定义别名，只想定义用于序列化的别名gt、lt、ge等约束数值，大于、小于、大于或等于等min_length、max_length等约束字符串min_items、max_items等元组、列表或集合约束validate_default 控制是否应验证字段的默认值，默认情况下，不验证字段的默认值。strict指定是否应在“严格模式”下验证字段frozen用于模拟冻结的数据类行为exclude用于控制导出模型时应从模型中排除哪些字段pattern对于字符串字段，您可以设置为 pattern 正则表达式以匹配该字段所需的任何模式。示例代码：
  1. from datetime import datetime
  2. from typing import List, Optional
  3. from pydantic import BaseModel, Field, EmailStr, ValidationError, SecretStr
  6. class User(BaseModel):
  7.     id: int = Field(..., alias="_id", frozen=True, strict=True)
  8.     name: str = Field(default="小卤蛋", min_length=1, max_length=100)  # 设置默认值，使用 min_length 和 max_length 来限制字符串长度
  9.     age: int = Field(gt=0)  # 支持各类条件验证，这里假设年龄必须大于0
  10.     email: EmailStr
  11.     signup_ts: Optional[datetime] = Field(default_factory=datetime.now, nullable=False, validate_default=True)
  12.     friends: List[str] = Field(default=[], min_items=0)
  13.     passwd: SecretStr = Field(min_length=6, max_length=20, exclude=True)  # passwd不会被序列化
  16. if __name__ == '__main__':
  18.     print(User.model_json_schema())
  20.     user_data = {
  21.         "_id": 123,  # 使用别名 _id
  22.         "name": "小卤蛋",
  23.         "age": 20,
  24.         "email": "xiaoludan@example.com",
  25.         # 'signup_ts': '2024-07-19 00:22',
  26.         'friends': ["公众号：海哥python", '小天才', b''],
  27.         "passwd": "123456"
  28.     }
  30.     try:
  31.         user = User(**user_data)
  32.         print(f"创建用户: {user}")
  33.         print(f"转成字典形式： {user.model_dump()} .... type: {type(user.model_dump())}")
  34.         print(f"转成json格式：{user.model_dump_json()} .... type: {type(user.model_dump_json())}")
  35.         print(f"用户属性： User id: {user.id}, User name: {user.name}, User email: {user.email}")
  36.         # user.id = 456   # 这里修改会报错
  37.     except ValidationError as e:
  38.         print(f"Validation error: {e.json()}")
复制代码
2.png

3.3 Config 配置

如果要对BaseModel中的某一基本型进行统一的格式要求，我们还可以使用Config类来实现。以下是一些 Config 类中常见的属性及其含义：
参数取值类型具体含义str_min_lengthintstr 类型的最小长度，默认值为Nonestr_max_lengthintstr 类型的最大长度。默认值为Noneextrastr在模型初始化期间是否忽略、允许或禁止额外的属性。默认值为 'ignore'。allow - 允许任何额外的属性。forbid - 禁止任何额外的属性。ignore - 忽略任何额外的属性。frozen bool模型是否可变str_to_upper bool是否将 str 类型的所有字符转换为大写。默认值为 False 。str_strip_whitespacebool是否去除 str 类型的前导和尾随空格。str_to_lowerbool是否将 str 类型的所有字符转换为小写。默认值为 False 。
  1. #! -*-conding: UTF-8 -*-
  3. from pydantic import BaseModel
  6. class User(BaseModel):
  7.     name: str
  8.     age: int
  10.     class Config:
  11.         str_min_length = 10  # 字符串最小长度
  12.         str_max_length = 20  # 字符串最大长度
  15. user = User(name="John Doe", age=30)  # 此时字段不满足约束会报错;
复制代码
3.4 数据序列化

使用模型类.model_dump()方法可以将一个模型类型实例对象转换为字典类型的数据。
  1. #! -*-conding: UTF-8 -*-
  2. # @公众号: 海哥python
  3. from datetime import datetime
  4. from typing import List, Optional
  5. from pydantic import BaseModel, ValidationError, EmailStr, field_validator, field_serializer
  6. from enum import Enum
  9. class GenderEnum(str, Enum):
  10.     """
  11.     性别枚举
  12.     """
  13.     male = "男"
  14.     female = "女"
  17. class User(BaseModel):
  18.     id: int
  19.     name: str = "小卤蛋"
  20.     age: int
  21.     email: EmailStr
  22.     signup_ts: Optional[datetime] = datetime.now()
  23.     friends: List[str] = []
  24.     sex: GenderEnum
  26.     @field_validator("age")  # 装饰器的顺序不能变化;
  27.     @classmethod
  28.     def check_age(cls, age):
  29.         if age < 18:
  30.             raise ValueError("用户年龄必须大于18岁")
  31.         return age
  33.     @field_serializer('signup_ts', when_used="always")
  34.     def serialize_signup_ts(self, value: datetime) -> str:
  35.         """
  36.         默认情况下， datetime 对象被序列化为 ISO 8601 字符串。这里使用field_serializer自定义序列化规则。
  37.         """
  38.         return value.strftime('%Y-%m-%d %H:%M:%S')
  40.     @field_serializer('sex', when_used="always")
  41.     def serialize_sex(self, value) -> str:
  42.         return value.value
  45. if __name__ == '__main__':
  47.     user_data = {
  48.         "id": 123,
  49.         "name": "小卤蛋",
  50.         "age": 20,
  51.         "email": "xiaoludan@example.com",
  52.         # 'signup_ts': '2024-07-19 00:22',
  53.         'friends': ["公众号：海哥python", '小天才', b''],
  54.         "sex": "男",
  55.     }
  57.     try:
  58.         user = User.model_validate(user_data)
  59.         print(f"{user.model_dump()} .... type: {type(user.model_dump())}")
  60.     except ValidationError as e:
  61.         print(f"Validation error: {e.json()}")
复制代码
使用模型类的.model_dump_json()方法可以将一个模型的实例转换成为 JSON 字符串。
  1. from datetime import datetime
  2. from typing import List, Optional, Any
  3. from pydantic import BaseModel, ValidationError, EmailStr, field_validator, field_serializer, model_serializer
  6. class User(BaseModel):
  7.     id: int
  8.     name: str = "小卤蛋"
  9.     age: int
  10.     email: EmailStr
  11.     signup_ts: Optional[datetime] = datetime.now()
  12.     friends: List[str] = []
  14.     @field_validator("age")
  15.     @classmethod
  16.     def check_age(cls, age):
  17.         if age < 18:
  18.             raise ValueError("用户年龄必须大于18岁")
  19.         return age
  21.     @field_serializer('signup_ts', when_used="json")
  22.     def serialize_signup_ts(self, value: datetime) -> str:
  23.         return value.strftime('%Y-%m-%d %H:%M:%S')
  25.     @model_serializer(when_used="json")
  26.     def serialize_model(self) -> dict[str, Any]:
  27.         return {
  28.             'id': self.id,
  29.             'name': self.name,
  30.             'age': self.age + 1,
  31.             'email': self.email,
  32.             'signup_ts': self.serialize_signup_ts(self.signup_ts),
  33.             'friends': self.friends,
  34.         }
  37. if __name__ == '__main__':
  39.     user_data = {
  40.         "id": 123,
  41.         "name": "小卤蛋",
  42.         "age": 20,
  43.         "email": "xiaoludan@example.com",
  44.         # 'signup_ts': '2024-07-19 00:22',
  45.         'friends': ["公众号：海哥python", '小天才', b''],
  46.     }
  48.     try:
  49.         user = User.model_validate(user_data)
  50.         print(f"{user.model_dump_json()} .... type: {type(user.model_dump_json())}")
  51.         print(f"{user.model_dump()} .... type: {type(user.model_dump())}")
  52.     except ValidationError as e:
  53.         print(f"Validation error: {e.json()}")
复制代码
也可以使用model_serializer对整体模型的序列化做定制。结果如下：
  1. """
  2. {"id":123,"name":"小卤蛋","age":21,"email":"xiaoludan@example.com","signup_ts":"2024-07-24 14:17:42","friends":["公众号：海哥python","小天才",""]} .... type: <class 'str'>
  3. {'id': 123, 'name': '小卤蛋', 'age': 20, 'email': 'xiaoludan@example.com', 'signup_ts': datetime.datetime(2024, 7, 24, 14, 17, 42, 45474), 'friends': ['公众号：海哥python', '小天才', '']} .... type: <class 'dict'>
  4. """
复制代码
3.5 文档生成

Pydantic 可以自动生成 API 文档。
  1. #! -*-conding: UTF-8 -*-
  3. from datetime import datetime
  4. from typing import List, Optional
  5. from pydantic import BaseModel, EmailStr, field_validator
  8. class User(BaseModel):
  9.     id: int
  10.     name: str = "小卤蛋"
  11.     age: int
  12.     email: EmailStr
  13.     signup_ts: Optional[datetime] = None
  14.     friends: List[str] = []
  16.     @field_validator("age")
  17.     def check_age(cls, age):
  18.         if age < 18:
  19.             raise ValueError("用户年龄必须大于18岁")
  20.         return age
  23. if __name__ == '__main__':
  24.     print(User.model_json_schema())
复制代码
通过model_json_schema方法可以得到API文档。
4. Fastapi 中的 Pydantic

在 FastAPI 中，与普通的程序相同，可以通过定义 Pydantic 模型来指定请求参数的结构和类型。以下是一个简单的例子：
  1. """ 定义参数模型;
  2. """
  4. from pydantic import BaseModel
  6. class Item(BaseModel):
  7.     name: str
  8.     description: str = None
  9.     price: float
  10.     tax: float = None
复制代码
在 Fastapi 中，你可以将 Pydantic 模型作为函数参数，Fastapi 会自动解析请求中的 json 数据，并将其转换成为 Pydantic 模型实例。如果数据不符合模型定义，FastApi 会自动返回一个 422 错误。
  1. import uvicorn
  2. from fastapi import FastAPI, Request, Form
  3. from fastapi.params import Depends
  4. from pydantic import BaseModel
  5. from watchfiles import awatch
  7. app = FastAPI(
  8.     title="测试小Demo",
  9.     description="文档描述",
  10.     version="1.0",
  11. )
  14. class QueryParam(BaseModel):
  15.     q: str | None = None
  16.     limit: int = 10
  17.     offset: int = 0
  20. def get_query_params(params: QueryParam = Depends()):
  21.     print(params)
  22.     return params
  25. @app.get("/query", tags=["query"])
  26. async def query(params: QueryParam = Depends(get_query_params)):
  27.     return {"params": params}
  30. @app.get("/filter", tags=["filter"])
  31. async def my_filter(params: QueryParam):
  32.     print(params)
  33.     return params
  36. if __name__ == '__main__':
  37.     uvicorn.run(app, host="127.0.0.1", port=8000)
复制代码
3.png

上述返回的就是 422 错误表明，没有通过校验。
上述的函数并没有指定通过那种方式指定解析数据，如果不显式指定 Body 或 Query，FastAPI 会根据参数的位置和类型自动推断参数的来源：

  • 如果参数是函数的路径参数（即在路径中定义的参数），则会从路径中提取。
  • 如果参数是函数的普通参数（非路径参数），且没有显式指定 Body 或 Query，则会根据参数的类型来推断：

    • 如果参数是复杂类型（如 Pydantic 模型），则会从请求体中提取。
    • 如果参数是简单类型（如 str、int 等），则会从查询字符串中提取。

4.1 设置校验规则
  1. from pydantic import BaseModel, Field
  3. class Item(BaseModel):
  4.     name: str = Field(..., min_length=3)
  5.     description: str = Field(None, max_length=100)
  6.     price: float = Field(..., gt=0, le=100)
  7.     tax: float = Field(None, ge=0, le=100)
  9. """
  10. min_length=3：name 的长度至少为 3。
  11. max_length=100：description 的长度最多为 100。
  12. gt=0：price 必须大于 0。
  13. le=100：price 必须小于或等于 100。
  14. ge=0：tax 必须大于或等于 0。
  15. le=100：tax 必须小于或等于 100。
  16. """
复制代码
4.2 自定义校验方法

可以使用@validator装饰器来定义自定义校验方法。
  1. from pydantic import BaseModel, validator
  3. class Item(BaseModel):
  4.     name: str
  5.     description: str = None
  6.     price: float
  7.     tax: float = None
  9.     @validator("price")
  10.     def check_price(cls, v):
  11.         if v < 0:
  12.             raise ValueError("price must be greater than 0")
  13.         return v
复制代码
4.3 路径参数和查询参数

Pydantic 模型不仅可以用于请求体，还可以用于查询参数和路径参数。例如：
  1. from fastapi import FastAPI, Query
  2. from pydantic import BaseModel
  4. app = FastAPI()
  6. class QueryParams(BaseModel):
  7.     query: str = Query(..., min_length=3, max_length=50)
  9. @app.get("/items/")
  10. async def get_items(query_params: QueryParams):
  11.     return {"query": query_params.query}
复制代码
在这个例子中，query_params 是一个 QueryParams 类型的 Pydantic 模型，它定义了一个查询参数 query。FastAPI 会自动解析查询参数，并将其转换为 QueryParams 实例。
4.4 响应模型

可以使用 Pydantic 模型来定义响应数据的结构。例如：
  1. import uvicorn
  2. from fastapi import FastAPI, Request, Form
  3. from fastapi.params import Depends
  4. from pydantic import BaseModel
  5. from watchfiles import awatch
  7. app = FastAPI(
  8.     title="测试小Demo",
  9.     description="文档描述",
  10.     version="1.0",
  11. )
  14. class Item(BaseModel):
  15.     name: str
  16.     description: str = None
  17.     price: float
  18.     tax: float = None
  21. @app.post("/items/", response_model=Item)
  22. async def create_item(item: Item):
  23.     return item
  26. if __name__ == '__main__':
  27.     uvicorn.run(app, host="127.0.0.1", port=8000)
复制代码
4.png

在这个例子中，response_model=Item 表示响应数据的结构将遵循 Item 模型的定义。FastAPI 会自动将返回的数据转换为 Item 实例，并确保其符合模型定义。
4.5 结合 Depends

Pydantic 和 Depends 可以结合使用，以实现更强大的参数校验和依赖注入功能。

  • 模型校验
    Depends 主要用于声明依赖，例如获取数据库连接、验证用户身份等。而 Pydantic 模型则用于数据验证和转换。你可以将 Pydantic 模型作为依赖函数的返回值，这样就可以在路由函数中直接使用经过校验的数据。
    1. # !/usr/bin/env python
    2. # -*-coding:utf-8 -*-
    4. """
    5. # File   : app.py
    6. # Time   : 2025/5/27 15:49
    7. # Author : 紫青宝剑
    8. """
    9. import uvicorn
    10. from fastapi import FastAPI, Request, Form, HTTPException
    11. from fastapi.params import Depends
    12. from pydantic import BaseModel
    13. from watchfiles import awatch
    15. app = FastAPI(
    16.     title="测试小Demo",
    17.     description="文档描述",
    18.     version="1.0",
    19. )
    21. class Item(BaseModel):
    22.     name: str
    23.     description: str = None
    24.     price: float
    25.     tax: float = None
    28. def val_item(item: Item):
    29.     print("接收到了执行的逻辑....")
    30.     if item.tax < 0.0:
    31.         raise HTTPException(status_code=400, detail="Price must be greater than zero")
    32.     else:
    33.         return item
    36. @app.post("/items/", response_model=Item)
    37. async def create_item(item: Item = Depends(val_item)):
    38.     return item
    41. if __name__ == '__main__':
    42.     uvicorn.run(app, host="127.0.0.1", port=8000)
    复制代码
    5.png

    此时，会直接在模型校验数据的类型之后执行视图函数之前，执行的校验步骤。
  • 参数查询
    1. from fastapi import FastAPI, Depends, Query
    2. from pydantic import BaseModel
    4. app = FastAPI()
    6. class QueryParameters(BaseModel):
    7.     q: str = Query(..., min_length=3, max_length=50)
    9. @app.get("/items/")
    10. async def read_items(query_params: QueryParameters = Depends()):
    11.     return {"q": query_params.q}
    复制代码
    QueryParameters 是一个 Pydantic 模型，它定义了一个查询参数 q。通过将 query_params 作为依赖项，FastAPI 会自动解析查询参数并将其转换为 QueryParameters 实例。
  • 前置校验
    在路由函数中使用 Depends，创建一个前置依赖函数来执行复杂的验证逻辑。
    1. from fastapi import FastAPI, Depends, HTTPException
    3. app = FastAPI()
    5. def complex_query_validator(query: str):
    6.     if "forbidden" in query:
    7.         raise HTTPException(status_code=400, detail="Forbidden query")
    8.     return query
    10. @app.get("/items/")
    11. async def read_items(query: str = Depends(complex_query_validator)):
    12.     return {"query": query}
    复制代码
    complex_query_validator 是一个依赖函数，它接收一个查询参数 query 并对其进行校验。如果校验失败，它会抛出一个 HTTPException。
  • 用户认证
    Depends 也可以用于用户认证和授权。你可以定义一个依赖函数来验证用户身份，并返回用户信息。然后在路由函数中使用这个依赖函数。
    1. from fastapi import FastAPI, Depends, HTTPException, status
    2. from fastapi.security import HTTPBasic, HTTPBasicCredentials
    3. from pydantic import BaseModel
    5. app = FastAPI()
    6. security = HTTPBasic()
    8. class User(BaseModel):
    9.     """ 定义用户模型的类。
    10.     """
    11.     username: str
    12.     password: str
    14. def get_current_user(credentials: HTTPBasicCredentials = Depends(security)) -> User:
    15.     """ 设置校验的函数;
    16.     """
    17.     valid_users = {"Alice": "alice_passwd"}
    18.     if credentials.username not in valid_users or valid_users[credentials.username] != credentials.password:
    19.         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
    20.     return User(username=credentials.username, password=credentials.password)
    22. @app.post("/users/")
    23. async def read_users(user: User = Depends(get_current_user)):
    24.     return user
    复制代码
    在这个例子中，get_current_user 是一个依赖函数，它接收 HTTP 基本认证的凭据，并验证用户身份。如果验证成功，它会返回一个 User 实例。
  • 总结
    Pydantic 和 Depends 的结合使用可以让你在 FastAPI 中实现强大的参数校验和依赖注入功能。你可以通过定义 Pydantic 模型来校验请求数据，同时使用 Depends 来声明依赖项，从而实现复杂的业务逻辑和数据校验。这种组合不仅提高了代码的可维护性和可读性，还增强了 API 的安全性。
继续努力，终成大器！

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

使用道具 举报
相关推荐
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册
发帖
厥轧匠
2025-5-30 15:29:59

0

粉丝关注

11

主题发布

板块介绍填写区域，请于后台编辑
微信扫一扫