pydantic教程🐧#

️🤔1.extra：如何处理多余字段？ (最重要！)#

这个参数的作用防止你的憨批前端同志传入了一个额外字段，就如上面实例化fatdog的例子一样

胖狗建议：无脑选 'forbid'！除非你完全信任前端开发者，即使就是你自己🤪

🤔2.str_strip_whitespace：自动去空格 (最爽！)#

值：布尔值 (True/False)。

• True：所有字符串字段自动去除首尾空格。
• 场景：用户表单提交 " ZhangSan "，自动变成 "ZhangSan"。省得你每个字段都写 .strip()！

🤔3.populate_by_name：字段别名兼容性 (前后端分离必备)#

值：布尔值 (True/False)。

• True：既可以通过原名赋值，也可以通过别名 (alias) 赋值。

• 场景

  ：

  • 模型定义：user_name: str = Field(alias="userName")
  • 如果设为 True：传 {"user_name": "A"} ✅ 和 {"userName": "A"} ✅ 都能成功。
  • 如果设为 False (默认)：只能传 {"userName": "A"} (必须用别名)。

这个也很重要，毕竟前端喜欢驼峰式命名参数！

🤔4.from_attributes (原 orm_mode)：对接数据库 ORM (操作数据库必用！)#

可以把对象序列化成JSON的神器！！！

值：布尔值 (True/False)。

开启后 (True)：Pydantic 变成了杂食动物。你给它字典 {“name”: “张三”} ✅，它吃；你给它对象 user_obj (它会自动去读 user_obj.name) ✅，它也吃！老吃家了哈哈哈！

• True：允许从对象属性读取数据，而不仅仅是字典。

• 场景

  FastAPI 返回数据库模型实例时。

  • 数据库对象 db_user 有 db_user.name。
  • 如果设为 True：User.model_validate(db_user) 能成功。
  • 如果设为 False：必须传字典 {"name": "..."}，传对象会报错。

• 注意：V1 叫 orm_mode = True，V2 改名叫 from_attributes = True！别写错了！

1
#fastapi里的案例！
2
@app.get("/users/{user_id}", response_model=UserResponse)
3
def get_user(user_id: int):
4
    # 1. 从数据库查出来的是个对象 (db_user)
5
    db_user = session.query(DBUserModel).filter(...).first()
6

7
    # 2. FastAPI 内部会自动调用 UserResponse.model_validate(db_user)
8
    # 如果没有 from_attributes=True，这里就会崩！
9
    return db_user
10
流程如下
11
数据库返回：DBUserModel 对象 (有 .name 属性)
12
FastAPI 拦截返回值。
13
FastAPI 看到 response_model=UserResponse。
14
Pydantic 检查 UserResponse 配置。
15
若 from_attributes=False ❌：报错，因为它期待字典。
16
若 from_attributes=True ✅：Pydantic 自动执行 data = {"id": obj.id, "name": obj.name, ...}，然后验证通过。
17
最终返回给前端：{"id": 1, "name": "张三", ...} (纯 JSON)。

🤔5.frozen：不可变模型 (线程安全)#

值：布尔值 (True/False)。

• True：模型实例化后，所有字段不可修改 (类似 tuple)。
• 场景：配置项、常量数据、多线程共享数据。
• 效果：尝试 user.name = "New" 会直接报 ValidationError。

🤔6.title / description / json_schema_extra：生成文档用#

主要用于自动生成 OpenAPI/Swagger 文档的说明。

• title: 模型的标题。
• json_schema_extra: 自定义 JSON Schema 的额外内容（比如添加示例 example）。

如下，简直就是安全的配置！😎😎😎😎

1
from pydantic import BaseModel, ConfigDict
2

3
class UserCreate(BaseModel):
4
    """用户创建模型 (接收前端参数)"""
5
    model_config = ConfigDict(
6
        extra='forbid',             # 1. 禁止多余字段，安全！
7
        str_strip_whitespace=True,  # 2. 自动去空格，省心！
8
        populate_by_name=True,      # 3. 兼容原名和别名，灵活！
9
        title="UserCreateSchema"    # 4. Swagger 文档标题
10
    )

model_dump() —— 人家是个转换器捏！😋#

• 功能：把模型实例变成 Python 字典 (dict)。
• 类比：就像把“精装书”拆成“散页纸”。
• 用途
  • 存进 MongoDB。
  • 传给其他只认字典的函数。
  • FastAPI 默认就在后台偷偷用这个把对象转成 JSON。

1
user = User(name="张三", age=18)
2
data = user.model_dump()
3
# 结果：{'name': '张三', 'age': 18} (类型是 dict)

model_dump_json() —— json起飞神器！#

• 功能：直接把模型实例变成 JSON 字符串 (str)。
• 类比：不仅拆成散页，还直接打包成“快递包裹”准备发货。
• 用途
  • 直接写入 Redis。
  • 写入日志文件。
  • 手动通过 socket 发送数据。
• 注意：它返回的是字符串，不是字典！💢💢💢别特喵被坑了！

1
user = User(name="张三", age=18)
2
json_str = user.model_dump_json()
3
# 结果：'{"name": "张三", "age": 18}' (类型是 str，可以直接存文件)

📥 第二组：【输入组】(把外面的数据塞进模型) 场景： 收到了前端请求、读到了配置文件、查到了数据库对象，要验证并创建模型实例。

model_validate() —— 最常用的接收器#

• 功能：接收 字典 (dict) 或 对象 (Object)，验证后生成模型实例。
• 类比：安检口。不管你是坐飞机来的（字典）还是坐火车来的（ORM 对象），只要符合规定就放行。
• 关键点
  • 如果配置了 from_attributes=True，它能直接吃 ORM 对象。
  • 如果不配置，它主要吃字典。

1
# 情况 A: 传字典 (常规操作)
2
data = {"name": "李四", "age": 20}
3
user = User.model_validate(data)
4

5
# 情况 B: 传对象 (配合 from_attributes=True)
6
db_obj = DBUser(name="王五", age=25)
7
user = User.model_validate(db_obj)

model_validate_json()——json字符串解码器#

• 功能：接收 JSON 字符串 (str)，先解析成字典，再验证生成模型实例。
• 类比：专门处理“快递包裹”的安检口。先拆包（json.loads），再安检。
• 用途
  • 从 Redis 读取了 JSON 字符串，想恢复成模型对象。
  • 接收了微服务传来的 JSON 报文。

1
json_str = '{"name": "赵六", "age": 30}'
2
user = User.model_validate_json(json_str)
3
# 等价于：User.model_validate(json.loads(json_str))
4
# 但写起来更爽，一步到位！

🛠️ 第三组：【修改组】(在原有基础上动刀子) 场景： 对象已经创建好了，只想改其中一两个字段，不想重新 model_validate 一遍。

model_copy() —— *克隆机*#

• 功能：复制当前模型，生成一个新的实例。
• 类比：影分身之术。
• 用途
  • 你想基于现有数据创建一个新数据，只改一点点。
  • 重要：默认是浅拷贝（Shallow Copy），如果里面有列表/字典，改新的会影响旧的！需要深拷贝得加参数 deep=True。

1
user1 = User(name="张三", age=18)
2

3
# 复制一个，顺便改个年龄
4
user2 = user1.model_copy(update={"age": 19})
5

6
print(user1.age) # 18 (原身没变)
7
print(user2.age) # 19 (分身变了)

想“复制并修改”？直接用 model_copy(update={键：值})。这是最稳妥的套路！

终极奶龙搜查表#

*fields (必填)#

你要验证哪个字段？

• @field_validator('name')：只验证 name。
• @field_validator('name', 'nickname')：同一个逻辑验证两个字段。

mode **(模式：什么时候验？很七八重要，别问为什么🤡) **#

决定你的函数是在“原始数据”上跑，还是在“转换后数据”上跑。

如果你只是做逻辑判断（如：不能为负、长度限制），不用写 mode，默认就是 ‘after’，此时 v 已经是正确的类型了，爽歪歪！ 如果你需要预处理数据（如：把 “2023/01/01” 这种奇怪格式转成日期），才用 mode=‘before’。）