第一章：认识 Pydantic

1.1 它是什么？

Pydantic 是一个 用 Python 类型注解（type hints）来做数据校验 的库。它的名字来自 "Python" + "pedantic"（一丝不苟的），意思就是：像最较真的检查员一样，帮你把关每一份数据。

简单说，你平时写的类型注解：

def greet(name: str, age: int) -> str:
    ...

Python 解释器 并不会真正检查 它们——传个字符串给 age 也照样运行。而 Pydantic 让这些注解在 运行时真正生效：数据不对，立刻报错，并告诉你错在哪。

1.2 为什么需要它？

想象你写一个接口接收用户注册数据：

data = {"username": "小明", "age": "十八", "email": "not-an-email"}

不用 Pydantic，你得手写一堆 if 判断：age 是不是数字？email 格式对不对？字段缺了怎么办？字段多了怎么办？代码又臭又长还容易漏。

用 Pydantic，你只需要 声明"数据应该长什么样"，脏活累活它全包了：

• ✅ 类型校验：age 必须是整数
• ✅ 自动转换："18"（字符串）能自动转成 18（整数）
• ✅ 详细的错误信息：哪个字段、为什么错、值是什么
• ✅ IDE 友好：完整的自动补全和类型提示

1.3 v1 还是 v2？

Pydantic 在 2023 年发布了 v2，核心用 Rust 重写，性能提升 5~50 倍，API 也有较大变化。本指南全部基于 v2（2.x）。如果你在老项目里见到 parse_obj()、@validator 这类写法，那是 v1 的旧 API，文中会顺带指出对应关系。

1.4 安装

pip install pydantic
# 需要邮箱等额外类型时：
pip install "pydantic[email]"

验证安装：

import pydantic
print(pydantic.VERSION)  # 应该输出 2.x.x