Pydantic 模型定义、校验与序列化（v2 详解）

1
2
3

  ① 校验   进来的数据不符合声明 → 报错（ValidationError）
  ② 转换   能安全转的自动转（"20" → 20、123 → "123"）
  ③ 序列化 模型 ↔ dict ↔ JSON ↔ 模型，随时互转

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

def register(user_data: dict):
    # 手写防御三连：判存在 → 判类型 → 判值域，然后一个个手转
    if "age" not in user_data:
        raise ValueError("缺 age")
    age = user_data["age"]
    if not isinstance(age, int):
        try:
            age = int(age)          # "20" 能转，但 "abc" 呢？还得再包 try
        except ValueError:
            raise ValueError("age 必须是数字")
    if age < 0 or age > 150:
        raise ValueError("age 范围不对")
    name = str(user_data.get("name", "")).strip()
    ...

1
2
3
4
5
6
7
8
9

from pydantic import BaseModel, Field

class UserInput(BaseModel):
    name: str = Field(min_length=1, max_length=50)
    age: int = Field(ge=0, le=150)
    email: str | None = None          # 可空

# 一行过安检：
u = UserInput.model_validate({"name": " Alice ", "age": "20"})

1

pip install "pydantic[email]"   # email 可选：EmailStr 需要 email-validator

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from pydantic import BaseModel

class Student(BaseModel):
    name: str            # 字段 = 类属性 + 类型注解
    age: int
    score: float = 0.0   # 带默认值 = 可选字段

# 实例化：位置参数 / 关键字 / dict 都行
s = Student("Alice", 20, 85.5)                 # 位置参数
s = Student(name="Bob", age=21)                # 关键字（score 用默认 0.0）
s = Student.model_validate({"name": "Cara", "age": 19, "score": 90})   # 从 dict 过安检

# 访问：就是普通属性
s.name     # 'Cara'
s.age      # 19

1
2
3
4
5

for name, field in Student.model_fields.items():
    print(name, "→", field.annotation, "| 默认:", field.default)
# name → <class 'str'> | 默认: PydanticUndefined   （undefined = 必填）
# age → <class 'int'>  | 默认: PydanticUndefined
# score → <class 'float'> | 默认: 0.0

1
2
3

s = Student(name="Alice", age=20)
s                    # Student(name='Alice', age=20, score=0.0)  清晰 repr
s == Student(name="Alice", age=20)   # True  ← 模型自动实现值相等（不是身份相等）

1
2
3
4
5
6
7
8
9

class Demo(BaseModel):
    a: int
    b: float
    c: str
    d: bool

d = Demo(a="42", b="3.14", c=99, d="yes")
d.model_dump()
# {'a': 42, 'b': 3.14, 'c': '99', 'd': True}

1
2
3
4

try:
    Demo(a="abc", b="x", c=None, d="maybe")
except ValidationError as e:
    print(e)

1
2
3
4
5
6
7
8
9

4 validation errors for Demo
a
  Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='abc', input_type=str]
b
  Input should be a valid number, unable to parse string as a number [type=float_parsing, ...]
c
  Input should be a valid string [type=string_type, input_value=None, input_type=NoneType]
d
  Input should be a valid boolean, unable to interpret input [type=bool_parsing, ...]

1
2
3
4
5
6

except ValidationError as e:
    for err in e.errors():            # 每条的完整结构
        print(err["loc"],    # ('a',)         ← 哪个字段（嵌套时是元组路径）
              err["type"],   # 'int_parsing'  ← 错误类型码
              err["msg"],    # 人类可读信息
              err["input"])  # 原始输入

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from pydantic import StrictInt, ConfigDict

# 方式① 全局：整个模型严格
class S1(BaseModel):
    model_config = ConfigDict(strict=True)
    age: int

# 方式② 单字段严格：用 Strict* 类型
from typing import Annotated
class S2(BaseModel):
    age: StrictInt            # 只这个字段严格

# 方式③ 调用时严格：单次校验覆盖
Student.model_validate({"name": "A", "age": 20}, strict=True)

1
2

S2(age="20")     # ❌ ValidationError：strict 模式下 str 不再转 int
S2(age=20)       # ✅

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from pydantic import BaseModel
from typing import Optional, Union, Literal  # 或直接用 |（3.10+）

class Everything(BaseModel):
    id: int
    ratio: float
    name: str
    flag: bool
    tags: list[str]                      # 元素也校验：list 里每个都必须是 str
    attrs: dict[str, int]                # 键 str、值 int
    coords: tuple[float, float]          # 长度、元素类型都校验
    unique_ids: set[int]                 # 自动去重 + 元素校验
    anything: Any                        # 不校验，原样存

1
2
3
4
5
6

Everything(
    id=1, ratio=0.5, name="x", flag=True,
    tags=["a", "b"], attrs={"k": 1},
    coords=(1.0, 2.0), unique_ids=[1, 1, 2],   # set 自动去重 → {1, 2}
    anything={"随便": [1, 2, "什么"]},
)

1
2
3
4

class Opt(BaseModel):
    maybe: int | None = None      # 可空：int 或 None
    a_or_b: int | str             # 联合类型：是 int 就给 int，否则试 str
    kind: Literal["dev", "prod", "test"] = "dev"   # 字面量枚举

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from pydantic import EmailStr, HttpUrl, UUID4
from datetime import datetime, date
from decimal import Decimal

class Profile(BaseModel):
    email: EmailStr            # ✅ 语法校验（需要 pip install email-validator）
    url: HttpUrl               # ✅ 必须是合法 http(s) URL
    uid: UUID4                 # ✅ 必须是 UUID v4
    created: datetime          # ✅ 自动解析 ISO 字符串
    day: date
    amount: Decimal            # ✅ 金额用 Decimal，别用 float（精度）

1
2

Profile(email="not-an-email", url="ftp://x", uid="abc", created="2026-09-06T20:00:00")
# ❌ email / url / uid 三条都报

1
2
3
4
5

class Conf(BaseModel):
    env: str = "dev"                       # ① 字面量默认
    tags: list[str] = Field(default_factory=list)      # ② 工厂默认（可变对象必用）
    extra: dict[str, Any] = Field(default_factory=dict)
    created_at: datetime = Field(default_factory=datetime.now)   # 每次实例化取当前时间

1
2
3

class Req(BaseModel):
    a: int = Field(default_factory=lambda: 0)     # 缺省时生成 0
    b: int | None = None                          # 缺省时是 None

1
2
3

r = Req()          # a=0, b=None（都"没传"但拿到了值）
r2 = Req(a=5)      # a=5
r.model_dump(exclude_unset=True)   # {}  ← 只导出"显式传过"的字段！

1
2
3
4
5
6

class C(BaseModel):
    code: str = Field(default_factory=lambda: gen_code())

# 默认值要不要也过校验？默认不校验（省性能）。想校验：
class C2(BaseModel):
    model_config = ConfigDict(validate_default=True)   # 默认值也过安检

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

from pydantic import BaseModel, Field

class Product(BaseModel):
    # —— 标识 ——
    id: int = Field(description="数据库主键")            # 描述（进 JSON Schema）
    code: str = Field(title="货号", alias="product_code")  # title + 别名

    # —— 值域 ——
    price: float = Field(ge=0, le=100000)              # ge≥ le≤（gt/lt 不含等号）
    discount: float = Field(ge=0, multiple_of=0.1)     # multiple_of：必须是 0.1 的倍数
    name: str = Field(min_length=2, max_length=50)     # 长度
    sn: str = Field(pattern=r"^[A-Z]{2}-\d{4}$")       # 正则

    # —— 行为 ——
    stock: int = Field(default=0)                      # 默认值
    tags: list[str] = Field(default_factory=list)      # 工厂默认
    secret: str = Field(repr=False)                    # repr 里隐藏（打印模型时不显示密码）
    frozen_flag: bool = Field(frozen=True)             # 该字段赋值后不可改

1
2
3

Product(id=1, product_code="AB-1234", price=99.5)     # ✅ 用别名 product_code 传入
Product(id=1, product_code="AB-1234", price=-1)       # ❌ price < 0
Product(id=1, product_code="XX-1234", sn="AB-1234" )  # ❌ 如果 sn 必填却没给

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from pydantic import field_validator

class User(BaseModel):
    username: str
    password: str
    email: str

    @field_validator("username")           # 指定要管的字段
    @classmethod
    def check_username(cls, v: str) -> str:      # v = 该字段的输入值
        v = v.strip()                            # 清洗：去空格
        if len(v) < 3:
            raise ValueError("用户名至少 3 个字符")   # 抛 ValueError → 校验失败
        return v                                 # 返回值会覆盖原输入（存进模型）

1
2

User(username="  ab ", password="x", email="a@b.c")   # ❌ strip 后 "ab" < 3
User(username="  alice ", password="x", email="a@b.c").username   # ✅ → "alice"

1
2
3
4
5
6
7
8
9

class N(BaseModel):
    age: int | None = None

    @field_validator("age", mode="before")
    @classmethod
    def blank_to_none(cls, v):
        if isinstance(v, str) and v.strip() in ("", "未知"):
            return None            # 转换前拦截：空串 → None
        return v

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from pydantic import model_validator

class Order(BaseModel):
    coupon: str | None = None
    total: float
    discount: float = 0

    @model_validator(mode="after")                 # after：所有字段都校验完后跑
    def check_discount(self) -> "Order":
        """跨字段规则：有券才有折扣，且折扣不能超总额"""
        if self.discount > 0 and not self.coupon:
            raise ValueError("有折扣必须提供优惠券")
        if self.discount > self.total:
            raise ValueError("折扣不能超过总额")
        return self                                  # after 模式返回整个 self

1
2

Order(total=100, discount=10)                 # ❌ 有折扣没券
Order(coupon="SAVE10", total=100, discount=10)  # ✅

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

  原始输入
    │
    ▼
  field_validator(mode="before")     ← 每个字段：转换前的自定义拦截
    │
    ▼
  类型转换 + Field 约束               ← 框架内建（str→int、ge=0、pattern…）
    │
    ▼
  field_validator(mode="after")      ← 每个字段：转换后的自定义检查
    │
    ▼
  model_validator(mode="after")      ← 模型级：跨字段规则（最后）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

class Address(BaseModel):
    city: str
    zipcode: str = Field(pattern=r"^\d{6}$")

class User(BaseModel):
    name: str
    address: Address                       # 字段类型是另一个模型
    tags: list[str] = Field(default_factory=list)

u = User(
    name="Alice",
    address={"city": "北京", "zipcode": "100000"},   # dict 自动转 Address
    tags=["vip"],
)
u.address.city      # 链式访问：u.address.city → '北京'

1
2
3
4

try:
    User(name="Bob", address={"city": "上海"})    # 内层缺 zipcode
except ValidationError as e:
    print(e.errors()[0]["loc"])      # ('address', 'zipcode')  ← 路径元组

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

class Item(BaseModel):
    sku: str
    qty: int = Field(ge=1)

class Cart(BaseModel):
    user_id: int
    items: list[Item] = Field(default_factory=list)      # 每个元素都过 Item 安检

cart = Cart.model_validate({
    "user_id": 1,
    "items": [
        {"sku": "A1", "qty": 2},
        {"sku": "A2", "qty": 0},       # ❌ 第二个商品 qty < 1（ge 约束）
    ],
})
# 报错：items[1].qty ... Input should be greater than or equal to 1
# 错误路径 ('items', 1, 'qty') 精确定位到"第 2 个商品的 qty"

1
2
3
4
5
6

class TreeNode(BaseModel):
    value: int
    children: list["TreeNode"] = Field(default_factory=list)   # 引用自身（前向引用）

# 类体内引用自身，v2 需要构建后重建（或在定义后用）
TreeNode.model_rebuild()     # ← 前向引用解析

1
2
3

tree = TreeNode(value=1, children=[TreeNode(value=2)])
tree.model_dump()
# {'value': 1, 'children': [{'value': 2, 'children': []}]}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

from pydantic import ConfigDict

class Settings(BaseModel):
    model_config = ConfigDict(
        # —— 输入侧 ——
        str_strip_whitespace=True,      # 所有 str 字段自动去首尾空格
        str_to_lower=False,             # 可开：str 自动转小写
        extra="forbid",                 # "ignore" 默认忽略 / "forbid" 多传报错 / "allow" 收进 __pydantic_extra__
        populate_by_name=True,          # 允许同时用别名和字段原名传入
        validate_assignment=True,       # 赋值时也校验（默认只在构造时校验）
        validate_default=True,          # 默认值也过校验

        # —— 输出侧 ——
        frozen=True,                    # 模型整体只读（类似 @dataclass(frozen=True)）
        arbitrary_types_allowed=True,   # 允许字段类型是任意普通类（非 pydantic 模型）

        # —— 行为 ——
        strict=False,                   # 默认宽松
        extra="forbid",
    )
    api_key: str = Field(min_length=10)
    env: str = "dev"

1
2
3
4
5
6
7
8
9

# extra="ignore"（默认）：多传的字段悄悄丢掉
# extra="forbid"：多传直接报错 —— 配置/契约类用它，写错名字立刻暴露
# extra="allow"：多传的收进 obj.__pydantic_extra__（dict），不丢

class A(BaseModel):
    model_config = ConfigDict(extra="forbid")
    x: int

A(x=1, y=2)     # ❌ Extra inputs are not permitted

1
2
3
4
5
6

class B(BaseModel):
    model_config = ConfigDict(validate_assignment=True)
    age: int = Field(ge=0)

b = B(age=20)
b.age = -5        # ❌ 赋值也会被拦（默认配置下赋值不校验，只有构造时校验）

1
2
3
4
5
6

class C(BaseModel):
    model_config = ConfigDict(frozen=True)
    v: int

c = C(v=1)
c.v = 2           # ❌ ValidationError: Instance is frozen

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

from datetime import datetime

class Event(BaseModel):
    name: str
    when: datetime

e = Event(name="发布", when="2026-09-06T20:00:00")

e.model_dump()                  # ① dict（Python 原生类型）
# {'name': '发布', 'when': datetime.datetime(2026, 9, 6, 20, 0)}

e.model_dump(mode="json")       # ② dict，但值已转成"可 JSON 化"的
# {'name': '发布', 'when': '2026-09-06T20:00:00'}   ← datetime → str

e.model_dump_json()             # ③ JSON 字符串
# '{"name":"发布","when":"2026-09-06T20:00:00"}'

Event.model_validate(e.model_dump())         # ④ 再过一遍安检（round-trip）

1
2
3
4
5
6
7

u = User(name="Alice", age=20, email=None, tags=["vip"])

u.model_dump(exclude={"tags"})                # 排除指定字段
u.model_dump(exclude_none=True)               # 跳过值为 None 的字段
u.model_dump(exclude_unset=True)              # 只导出"显式传过"的字段（PATCH 用）
u.model_dump(include={"name", "age"})         # 白名单
u.model_dump(by_alias=True)                   # 用别名当 key（见第十一章）

1
2
3

e2 = e.model_copy(update={"name": "更新版"})    # 返回新对象，e 原样不动
e.name      # '发布'（没变）
e2.name     # '更新版'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from pydantic import Field

class ApiUser(BaseModel):
    model_config = ConfigDict(populate_by_name=True)   # 允许原名也能传入
    user_name: str = Field(alias="userName")
    api_key: str = Field(alias="apiKey")

# 输入走别名：
u = ApiUser.model_validate({"userName": "alice", "apiKey": "sk-xxx"})
u.user_name        # 'alice'（内部还是 Python 命名）

# 输出走别名：
u.model_dump(by_alias=True)
# {'userName': 'alice', 'apiKey': 'sk-xxx'}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from pydantic import TypeAdapter

# 校验单值
ta = TypeAdapter(int)
ta.validate_python("42")       # → 42（宽松转换）
# ta.validate_python("abc")    # → ValidationError

# 校验容器结构
items_ta = TypeAdapter(list[str])
items_ta.validate_python(["a", "b"])     # ✅
# items_ta.validate_python(["a", 1])     # ❌ 1 不会转成 str？会——lax 下 1 → "1"
# 想严格：TypeAdapter(list[StrictStr]) 之类

# JSON 输入一步到位
TypeAdapter(list[dict[str, int]]).validate_json('[{"a": 1}]')

1
2

Movie.model_json_schema()
# {'properties': {'title': {'title': 'Title', 'type': 'string'}, ...}, 'required': ['title'], 'type': 'object'}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# 结构化输出（W4 见过，这里看全链路）：
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.prompts import ChatPromptTemplate

class Movie(BaseModel):
    title: str = Field(description="电影标题")
    rating: float = Field(description="评分（0-10）", ge=0, le=10)
    genres: list[str] = Field(description="类型标签，2-4 个")

parser = PydanticOutputParser(pydantic_object=Movie)

prompt = ChatPromptTemplate.from_messages([
    ("system", "根据描述提取信息。只输出 JSON。\n{format_instructions}"),
    ("user", "{input}"),
])
chain = prompt | llm | parser      # 模型输出 → JSON → 校验 → Movie 对象
# 输出格式不对时 parser 会抛 ValidationError —— 你能看见并重试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 定义一个"参数模型"，交给 @tool：
from langchain_core.tools import tool

class WeatherArgs(BaseModel):
    city: str = Field(description="城市名，如 北京")
    days: int = Field(default=1, ge=1, le=7, description="预报天数")

@tool(args_schema=WeatherArgs)          # 模型自动帮你生成参数 schema
def get_weather(city: str, days: int = 1) -> str:
    """查询城市天气"""
    return f"{city} 未来{days}天天气……"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

from datetime import date
from decimal import Decimal
from pydantic import BaseModel, Field, ConfigDict, field_validator, model_validator

# ① 定义模型（含别名、清洗、跨字段规则）
class Item(BaseModel):
    model_config = ConfigDict(str_strip_whitespace=True)

    name: str = Field(min_length=1, max_length=50)
    price: Decimal = Field(ge=0, description="单价")
    qty: int = Field(ge=1)

class OrderInput(BaseModel):
    model_config = ConfigDict(extra="forbid")          # 不收未声明字段

    customer: str = Field(alias="customerName")        # 外部叫 customerName
    ship_date: date | None = None
    items: list[Item]

    @field_validator("customer", mode="before")
    @classmethod
    def strip_customer(cls, v):
        return v.strip() if isinstance(v, str) else v

    @model_validator(mode="after")
    def ensure_not_empty(self) -> "OrderInput":
        if not self.items:
            raise ValueError("订单至少要有一个商品")
        return self

    def total(self) -> Decimal:                        # 模型上可以带方法
        return sum((i.price * i.qty for i in self.items), Decimal("0"))

# ② LLM/接口返回的"脏 JSON" → 一行过安检
raw = {
    "customerName": "  Alice  ",
    "shipDate": "2026-09-10",
    "items": [
        {"name": "键盘", "price": "199.5", "qty": "2"},    # 价格/数量是字符串！
        {"name": "鼠标", "price": 59, "qty": 1},
    ],
}

order = OrderInput.model_validate(raw)     # 别名解析 + 去空格 + 字符串转 Decimal/int
order.customer      # 'Alice'（自动去空格）
order.items[0].price  # Decimal('199.5')（字符串自动转 Decimal）
order.total()         # Decimal('458.0')

# ③ 序列化出去（供存储 / 回给前端）
order.model_dump(mode="json", by_alias=True, exclude_none=True)
# {'customerName': 'Alice', 'items': [{'name': '键盘', 'price': '199.5', ...}], ...}

1
2
3
4
5
6

  model_validate + alias      → 第十一章  外部名 → Python 名
  str_strip_whitespace        → 第九章    ConfigDict
  price: Decimal + 字符串自动转 → 第三章   宽松转换
  @field_validator / @model_validator → 第七章  自定义规则
  带方法 total()              → 第二章   模型=数据+行为
  model_dump(mode="json", by_alias=True) → 第十章  序列化