第八章：序列化：把模型变回数据

校验完、处理完，总要输出。v2 的序列化 API：

user = User(name="小明", age=18)

user.model_dump()              # → dict：{"name": "小明", "age": 18}
user.model_dump_json()         # → JSON 字符串

（v1 对应：user.dict()、user.json()，v2 中已废弃。）

8.1 常用的输出控制

user.model_dump(
    exclude_none=True,      # 丢掉值为 None 的字段
    exclude_unset=True,     # 只保留显式传过的字段（局部更新接口神器）
    exclude={"password"},   # 排除指定字段（千万别把密码返回给前端！）
    by_alias=True,          # 用别名输出（对接 camelCase 前端）
    mode="json",            # 输出成 JSON 兼容的类型（datetime → 字符串等）
)

💡 exclude_unset=True 特别值得记住：实现 PATCH 接口时，它能区分"用户没传这个字段"和"用户把它设成了 None"。

8.2 自定义序列化：field_serializer

from pydantic import BaseModel, field_serializer
from datetime import datetime

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

    @field_serializer("start")
    def serialize_start(self, dt: datetime) -> str:
        return dt.strftime("%Y年%m月%d日 %H:%M")

Event(name="发布会", start=datetime.now()).model_dump()
# start 输出为 "2026年10月10日 19:54" 这样的格式