Pydantic v2实战：7个特性提升Python API设计稳定性与可维护性

告别“试一下才知道”的API开发，用确定性的契约替代模糊的约定。

你是否曾在维护大型API时，面对层层嵌套的模型验证感到力不从心？是否担心某个字段的改动会像多米诺骨牌一样引发连锁错误？如果你的API模式（Schema）感觉像一堆勉强搭在一起的积木，每次修改都心惊胆战——那么Pydantic v2就是你一直在等待的那次优雅重构。

Pydantic v2保留了v1的表达力，但削减了魔法，增加了清晰。它为大规模验证、序列化和文档化提供了简单而明确的工具。今天，我们就来深度解析7个能让你的API设计从“摇摇欲坠”变为“坚如磐石”的关键特性。

一、TypeAdapter：无需完整模型的精准验证

痛点：为了一小块数据，非得定义整个模型？

在API开发中，我们经常遇到这样的场景：只需要验证一个数据片段（比如查询参数中的ID列表、第三方webhook的特定字段），却不得不为此定义一个完整的Pydantic模型。这就像为了修一扇窗，非得重建整栋房子。

解决方案：手术刀式的精准验证

TypeAdapter就是为解决这个问题而生。它允许你直接验证和序列化单个类型或简单结构，无需创建完整的模型类。

from typing import List
from pydantic import TypeAdapter, Field
from typing_extensions import Annotated

# 定义一个带约束的类型：正整数列表
PositiveIntList = Annotated[int, Field(gt=0)]
adapter = TypeAdapter(List[PositiveIntList])

# 验证并转换数据
data = adapter.validate_python(["3", 4, 5])  # 自动转换字符串"3"为整数3
print(data)  # 输出: [3, 4, 5]

# 快速序列化为JSON字节（API返回常用）
json_bytes = adapter.dump_json(data)
print(json_bytes)  # 输出: b'[3,4,5]'

# 也可以直接验证JSON字符串
data_from_json = adapter.validate_json('[1, 2, 3]')
print(data_from_json)  # 输出: [1, 2, 3]

实际应用场景

• 路由参数验证：在FastAPI路由中直接验证查询参数
• 第三方数据清洗：处理Kafka消息、Redis缓存或外部webhook的片段数据
• 临时数据处理：在后台任务或脚本中快速验证数据，避免污染模型层

核心优势：即使是一次性使用的类型，也能享受Pydantic v2基于 pydantic-core 的高性能验证路径。

二、Annotated + Field：约束与类型形影不离

痛点：字段定义和约束规则天各一方

在Pydantic v1中，字段的约束常常散落在模型各处：有些在 Field() 里，有些在 validators 中，还有些在模型配置里。这种分离让代码可读性下降，也让代码审查变得困难。

解决方案：声明式的一站式定义

Pydantic v2拥抱了Python的 typing.Annotated ，让类型和约束在同一个地方定义，形成自文档化的代码。

from typing import Annotated
from pydantic import BaseModel, Field, field_validator
import re

# 创建可复用的自定义类型
# 邮箱类型：必须符合邮箱格式，最大长度254
EmailStr = Annotated[str, Field(pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$", max_length=254)]

# 价格类型：必须非负，且是0.01的倍数（适合货币计算）
Price = Annotated[float, Field(ge=0, multiple_of=0.01)]

class ProductOrder(BaseModel):
    """产品订单模型"""
    # 类型和约束一目了然
    product_id: Annotated[int, Field(gt=0, description="产品ID，必须为正整数")]
    product_name: Annotated[str, Field(min_length=1, max_length=100)]
    unit_price: Price
    quantity: Annotated[int, Field(gt=0, le=1000)]
    customer_email: EmailStr

    # 还可以添加字段级别的验证器
    @field_validator("product_name")
    @classmethod
    def normalize_product_name(cls, v: str) -> str:
        """规范化产品名称：去除首尾空格，单词首字母大写"""
        return v.strip().title()

    # 计算总价的方法（非字段，但很有用）
    @property
    def total_price(self) -> float:
        return round(self.unit_price * self.quantity, 2)

# 使用示例
try:
    order = ProductOrder(
        product_id=101,
        product_name="  python编程指南  ",  # 会自动规范化
        unit_price=29.99,
        quantity=2,
        customer_email="customer@example.com"
    )
    print(f"订单创建成功: {order.product_name}")
    print(f"总价: ${order.total_price}")
    print("生成的JSON Schema片段:", order.model_json_schema()["properties"]["customer_email"])
except Exception as e:
    print(f"验证失败: {e}")

规模化优势

1. 代码可读性：审查者一眼就能看到字段的所有约束
2. 减少认知负担：不再需要到处寻找约束定义
3. 精准的文档生成：生成的OpenAPI Schema与代码完全一致
4. 类型复用：自定义类型可以在多个模型间共享

三、确定性验证器：field_validator与model_validator

痛点：验证器的执行顺序像魔法一样难以预测

Pydantic v1的 @validator 虽然强大，但有时执行顺序和模式选择不够明确，特别是在复杂验证场景中。

解决方案：明确意图的验证器

v2将验证器分为两类，并提供了清晰的执行模式：

• field_validator：字段级别验证，关注单个字段
• model_validator：模型级别验证，关注字段间关系

from pydantic import BaseModel, field_validator, model_validator, ValidationError
from datetime import datetime, timedelta

class Subscription(BaseModel):
    """用户订阅模型"""
    email: str
    plan_type: str  # "basic", "premium", "enterprise"
    start_date: datetime
    end_date: datetime
    promo_code: str | None = None

    # 字段验证器：标准化邮箱
    @field_validator("email")
    @classmethod
    def normalize_and_validate_email(cls, v: str) -> str:
        v = v.strip().lower()
        if "@" not in v:
            raise ValueError("无效的邮箱格式")
        return v

    # 字段验证器：验证计划类型
    @field_validator("plan_type")
    @classmethod
    def validate_plan_type(cls, v: str) -> str:
        valid_plans = {"basic", "premium", "enterprise"}
        if v not in valid_plans:
            raise ValueError(f"计划类型必须是: {', '.join(valid_plans)}")
        return v

    # 模型验证器（模式1）：在字段验证后执行，检查日期逻辑
    @model_validator(mode="after")
    def validate_dates(self):
        """验证开始日期早于结束日期"""
        if self.start_date >= self.end_date:
            raise ValueError("开始日期必须早于结束日期")

        # 基本计划最多30天
        if self.plan_type == "basic":
            max_duration = timedelta(days=30)
            if self.end_date - self.start_date > max_duration:
                raise ValueError("基本计划最多订阅30天")
        return self

    # 模型验证器（模式2）：在字段验证前执行，可以预处理数据
    @model_validator(mode="before")
    @classmethod
    def preprocess_promo_code(cls, data):
        """预处理促销码：如果提供了促销码，转为大写"""
        if isinstance(data, dict) and "promo_code" in data and data["promo_code"]:
            data["promo_code"] = data["promo_code"].upper()
        return data

# 测试验证器
try:
    # 有效订阅
    sub1 = Subscription(
        email="USER@EXAMPLE.COM  ",  # 会被规范化
        plan_type="premium",
        start_date=datetime(2024, 1, 1),
        end_date=datetime(2024, 12, 31),
        promo_code="save20"  # 会被预处理为"SAVE20"
    )
    print(f"订阅创建成功: {sub1.email}, 促销码: {sub1.promo_code}")

    # 无效订阅：基本计划超过30天
    sub2 = Subscription(
        email="test@example.com",
        plan_type="basic",
        start_date=datetime(2024, 1, 1),
        end_date=datetime(2024, 2, 15),  # 45天，超过30天限制
        promo_code=None
    )
except ValidationError as e:
    print(f"验证错误: {e.errors()[0]['msg']}")

为什么这很重要

1. 可预测的执行顺序：明确指定验证器在字段验证“前”、“后”还是“包裹”执行
2. 清晰的职责分离：字段级验证和模型级验证各司其职
3. 更易维护：当验证逻辑增长时，代码结构依然清晰
4. 更好的错误信息：可以针对不同验证阶段提供具体的错误提示

四、精确序列化控制：field_serializer与model_serializer

痛点：API输出格式与内部数据结构纠缠不清

我们常常遇到这样的需求：内部使用Python的 datetime 对象，但API需要返回ISO 8601格式的字符串；或者需要在API响应中隐藏某些内部字段。在v1中，我们往往在视图函数中进行后处理，这导致序列化逻辑分散在各处。

解决方案：第一方序列化钩子

Pydantic v2提供了专门的序列化装饰器，让你在模型内部定义如何序列化数据：

from datetime import datetime, timezone
from pydantic import BaseModel, field_serializer, model_serializer, ConfigDict
from decimal import Decimal
from typing import Any

class FinancialTransaction(BaseModel):
    """金融交易模型"""
    model_config = ConfigDict(
        extra="ignore",  # 忽略额外字段
        str_strip_whitespace=True  # 自动去除字符串首尾空格
    )

    transaction_id: str
    amount: Decimal  # 使用Decimal保证精度
    currency: str
    timestamp: datetime
    internal_metadata: dict[str, Any]  # 内部使用，不暴露给API

    # 字段序列化器：仅当序列化为JSON时应用
    @field_serializer("amount", when_used="json")
    def serialize_amount(self, amount: Decimal) -> float:
        """金额序列化：Decimal转为浮点数，保留2位小数"""
        return float(round(amount, 2))

    @field_serializer("timestamp", when_used="json")
    def serialize_timestamp(self, ts: datetime) -> str:
        """时间戳序列化：转为UTC时区的ISO格式"""
        if ts.tzinfo is None:
            ts = ts.replace(tzinfo=timezone.utc)
        return ts.astimezone(timezone.utc).isoformat()

    # 模型序列化器：控制整个模型的JSON输出
    @model_serializer(mode="wrap")
    def serialize_model(self, serializer):
        """包装序列化过程，隐藏内部字段"""
        # 先获取默认序列化结果
        data = serializer(self)

        # 移除内部字段
        data.pop("internal_metadata", None)

        # 添加一些计算字段
        data["display_amount"] = f"{float(self.amount):.2f}{self.currency}"
        data["is_recent"] = (datetime.now(timezone.utc) - self.timestamp).days < 7

        return data

# 使用示例
transaction = FinancialTransaction(
    transaction_id="TX123456",
    amount=Decimal("123.4567"),
    currency="USD",
    timestamp=datetime(2024, 1, 15, 14, 30, 0),
    internal_metadata={
        "risk_score": 0.2,
        "processed_by": "system_v2",
        "audit_id": "AUDIT_789"
    },
    # 注意：这个额外字段会被忽略（因为extra="ignore"）
    unexpected_field="will be ignored"
)

print("内部Python对象表示:")
print(f"  金额类型: {type(transaction.amount)}")  # <class 'decimal.Decimal'>
print(f"  时间类型: {type(transaction.timestamp)}")  # <class 'datetime.datetime'>

print("\n序列化为JSON:")
json_output = transaction.model_dump_json(indent=2)
print(json_output)

输出效果对比

{
  "transaction_id": "TX123456",
  "amount": 123.46,
  "currency": "USD",
  "timestamp": "2024-01-15T14:30:00+00:00",
  "display_amount": "123.46 USD",
  "is_recent": true
}

契约设计的胜利

1. 单一职责：序列化逻辑集中在模型内部，而不是分散在各处
2. 契约一致性：API文档（OpenAPI Schema）与实际输出完全一致
3. 安全控制：可以安全地隐藏或转换敏感字段
4. 格式统一：确保所有端点返回相同格式的数据

五、computed_field：自文档化的只读计算字段

痛点：派生字段在文档中“隐身”

API响应中经常包含基于现有字段计算出的值（如“剩余座位数”、“是否过期”等）。在v1中，这些字段要么作为属性添加（但不会出现在Schema中），要么在序列化后处理中临时添加。

解决方案：一等公民的计算字段

@computed_field 装饰器让计算字段成为模型的正式成员，自动包含在JSON Schema中。

from pydantic import BaseModel, computed_field, Field
from datetime import datetime, timezone, timedelta
from typing import List

class ConferenceTicket(BaseModel):
    """会议门票模型"""
    ticket_id: str = Field(min_length=10, max_length=50)
    attendee_name: str
    ticket_type: str = Field(pattern="^(vip|standard|student)$")
    price_paid: float = Field(ge=0)
    purchase_date: datetime
    seat_number: str | None = None  # 可能还没有分配座位

    # 计算字段：门票是否已过期（购买后30天内有效）
    @computed_field
    @property
    def is_expired(self) -> bool:
        expiry_date = self.purchase_date + timedelta(days=30)
        return datetime.now(timezone.utc) > expiry_date

    # 计算字段：门票状态
    @computed_field
    @property
    def status(self) -> str:
        if self.is_expired:
            return "expired"
        elif self.seat_number:
            return "confirmed"
        else:
            return "pending"

    # 计算字段：显示用的购买日期
    @computed_field
    @property
    def purchase_date_display(self) -> str:
        """用户友好的日期显示"""
        return self.purchase_date.strftime("%Y年%m月%d日 %H:%M")

class Conference(BaseModel):
    """会议模型"""
    name: str
    total_seats: int = Field(gt=0)
    tickets_sold: List[ConferenceTicket] = []

    # 计算字段：已售出票数
    @computed_field
    @property
    def tickets_sold_count(self) -> int:
        return len(self.tickets_sold)

    # 计算字段：剩余座位数
    @computed_field
    @property
    def available_seats(self) -> int:
        return max(self.total_seats - self.tickets_sold_count, 0)

    # 计算字段：上座率百分比
    @computed_field
    @property
    def occupancy_rate(self) -> float:
        if self.total_seats == 0:
            return 0.0
        return round(self.tickets_sold_count / self.total_seats * 100, 1)

# 创建示例数据
conference = Conference(
    name="PyCon 2024",
    total_seats=100,
    tickets_sold=[
        ConferenceTicket(
            ticket_id="TICKET-001-VIP",
            attendee_name="张三",
            ticket_type="vip",
            price_paid=299.99,
            purchase_date=datetime(2024, 3, 1, 10, 0, 0),
            seat_number="A1"
        ),
        ConferenceTicket(
            ticket_id="TICKET-002-STANDARD",
            attendee_name="李四",
            ticket_type="standard",
            price_paid=149.99,
            purchase_date=datetime(2024, 4, 15, 14, 30, 0)
            # 没有分配座位号
        )
    ]
)

# 查看计算字段的值
print(f"会议: {conference.name}")
print(f"总座位: {conference.total_seats}")
print(f"已售出: {conference.tickets_sold_count}")
print(f"剩余座位: {conference.available_seats}")
print(f"上座率: {conference.occupancy_rate}%")

print("\n第一张门票状态:")
ticket1 = conference.tickets_sold[0]
print(f"  门票ID: {ticket1.ticket_id}")
print(f"  状态: {ticket1.status}")
print(f"  是否过期: {ticket1.is_expired}")
print(f"  购买日期: {ticket1.purchase_date_display}")

# 查看生成的JSON Schema
print("\n计算字段在JSON Schema中的表示:")
schema = conference.model_json_schema()
for field_name in ["available_seats", "occupancy_rate"]:
    if field_name in schema["properties"]:
        print(f"  {field_name}: {schema['properties'][field_name]}")

规模化优势

1. 客户端稳定性：计算字段成为API契约的正式部分
2. 逻辑集中：计算逻辑保持在数据附近，而非分散在业务逻辑中
3. 自动文档化：OpenAPI文档会包含这些计算字段及其描述
4. 减少重复计算：可以在多个端点中重用相同的计算逻辑

六、RootModel[T]：优雅包装简单类型

痛点：简单列表响应需要不必要的包装器

列表端点通常返回“只是一个列表”加上分页信息。在v1中，我们常常需要创建像 {"items": [...], "total": 100} 这样的包装器模型，即使不需要额外的元数据。

解决方案：轻量级类型包装

RootModel 可以干净地包装任何类型，特别适合数组或标量响应体：

from typing import List, Dict, Any
from pydantic import BaseModel, RootModel, Field
from datetime import date

# 场景1：纯列表响应（无包装器）
class User(BaseModel):
    id: int = Field(gt=0)
    username: str = Field(min_length=3, max_length=50)
    email: str = Field(pattern=r".+@.+\..+")

# User列表的根模型
class UserList(RootModel[List[User]]):
    """用户列表响应"""

    # 可以添加模型级别的方法
    def find_by_username(self, username: str) -> User | None:
        for user in self.root:
            if user.username == username:
                return user
        return None

    @property
    def usernames(self) -> List[str]:
        return [user.username for user in self.root]

# 场景2：简单标量包装
class ApiToken(RootModel[str]):
    """API令牌响应"""
    def __str__(self):
        # 安全地显示令牌
        token = self.root
        if len(token) > 8:
            return f"{token[:4]}...{token[-4:]}"
        return "***"

# 场景3：字典包装
class Metadata(RootModel[Dict[str, Any]]):
    """灵活元数据响应"""
    pass

# 使用示例
print("=== 用户列表示例 ===")
users = UserList([
    {"id": 1, "username": "alice", "email": "alice@example.com"},
    {"id": 2, "username": "bob", "email": "bob@example.com"},
    {"id": 3, "username": "charlie", "email": "charlie@example.com"}
])

# 访问列表
print(f"用户数: {len(users.root)}")
print(f"用户名列表: {users.usernames}")

# 查找用户
found = users.find_by_username("bob")
print(f"找到用户: {found.username if found else '未找到'}")

# 序列化
print(f"JSON响应: {users.model_dump_json()}")

print("\n=== API令牌示例 ===")
token = ApiToken("sk_live_1234567890abcdef")
print(f"令牌: {token}")  # 输出: sk_l...cdef
print(f"原始值: {token.root}")

print("\n=== 元数据示例 ===")
metadata = Metadata({
    "version": "1.0.0",
    "environment": "production",
    "features": ["auth", "billing", "analytics"],
    "limits": {"api_calls": 1000}
})
print(f"元数据: {metadata.model_dump()}")

输出示例

// UserList的JSON输出
[
  {
    "id": 1,
    "username": "alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "username": "bob",
    "email": "bob@example.com"
  },
  {
    "id": 3,
    "username": "charlie",
    "email": "charlie@example.com"
  }
]

适用场景

1. 批量端点： /api/users/bulk 返回用户列表
2. 无包装webhook：第三方webhook直接发送数组或简单值
3. 强类型标量： RootModel[str] 用于令牌， RootModel[int] 用于计数器
4. 保持响应简洁：避免不必要的 {"data": [...], "meta": {...}} 包装

七、ConfigDict + 高性能核心：统一配置，极致性能

痛点：配置分散，性能优化困难

Pydantic v1的配置分散在多个地方，而v2通过 model_config 统一了所有设置，并结合 pydantic-core （Rust实现的核心）提供了显著的性能提升。

from pydantic import BaseModel, ConfigDict, Field, field_validator
from typing import ClassVar
from datetime import datetime
import json

class HighPerformanceModel(BaseModel):
    """高性能配置示例"""

    # 统一配置字典
    model_config = ConfigDict(
        # 安全性设置
        extra="forbid",           # 禁止额外字段（防止客户端发送未定义字段）
        strict=True,             # 严格模式：减少意外类型转换

        # 序列化优化
        ser_json_bytes="utf8",   # 序列化为UTF-8字节，而非字符串
        ser_json_timedelta="float",  # 时间差序列化为浮点数

        # 性能优化
        from_attributes=True,    # 支持从ORM对象转换
        revalidate_instances="always",  # 总是重新验证实例

        # 行为控制
        frozen=False,            # 允许模型可变性（需要时可设为True）
        populate_by_name=True,   # 允许通过别名和字段名两种方式填充
        use_enum_values=True,    # 使用枚举的值而非枚举对象本身

        # 隐藏配置
        hide_input_in_errors=False,  # 不在错误中隐藏输入
    )

    # 字段定义
    id: int = Field(gt=0, strict=True)  # 严格整数：不接受字符串"1"
    name: str = Field(min_length=1, max_length=100)
    created_at: datetime
    tags: list[str] = Field(default_factory=list, max_items=10)

    # 类变量（不会成为字段）
    _cache: ClassVar[dict] = {}

    @field_validator("name")
    @classmethod
    def validate_name(cls, v: str) -> str:
        v = v.strip()
        if not v:
            raise ValueError("名称不能为空")
        return v

    # 性能对比：新旧API
    def performance_demo(self):
        """演示性能相关的API"""

        # 新API（v2）：统一、高效
        print("\n=== V2 API ===")

        # 1. 验证
        data_dict = {"id": 1, "name": "Test", "created_at": "2024-01-01T00:00:00"}
        instance = self.model_validate(data_dict)
        print(f"模型验证: {instance.id}")

        # 2. 序列化为字典（快速）
        dict_output = self.model_dump()
        print(f"字典输出: {dict_output}")

        # 3. 序列化为JSON字节（最快，适合API响应）
        json_bytes = self.model_dump_json()
        print(f"JSON字节长度: {len(json_bytes)} 字节")

        # 4. 获取JSON Schema
        schema = self.model_json_schema()
        print(f"JSON Schema包含字段数: {len(schema.get('properties', {}))}")

# 性能测试比较
def compare_performance():
    """比较严格模式 vs 非严格模式的差异"""

    print("=== 严格模式演示 ===")

    # 创建严格模式模型实例
    model = HighPerformanceModel(
        id=123,
        name="Performance Test",
        created_at=datetime.now(),
        tags=["fast", "reliable"]
    )

    # 测试严格验证
    print("\n测试1: 字符串数字（应该失败，因为strict=True）")
    try:
        broken_data = {"id": "123", "name": "Test", "created_at": "2024-01-01"}
        HighPerformanceModel.model_validate(broken_data)
        print("  意外成功！")
    except Exception as e:
        print(f"  失败（符合预期）: {type(e).__name__}")

    print("\n测试2: 额外字段（应该失败，因为extra='forbid'）")
    try:
        extra_data = {"id": 123, "name": "Test", "created_at": "2024-01-01", "extra_field": "oops"}
        HighPerformanceModel.model_validate(extra_data)
        print("  意外成功！")
    except Exception as e:
        print(f"  失败（符合预期）: {type(e).__name__}")

    return model

# 运行演示
if __name__ == "__main__":
    model = compare_performance()
    model.performance_demo()

关键性能与操作改进

1. 统一的配置入口： model_config 替代了多个配置类和装饰器
2. 性能飞跃：关键路径由Rust实现的 pydantic-core 驱动，处理大型、深度嵌套载荷时显著更快
3. 一致的API：
   • model_validate() 替代 parse_obj()
   • model_dump() 替代 dict()
   • model_dump_json() 替代 json()
4. 确定性行为： model_json_schema() 生成可预测的OpenAPI Schema

实战集成：一个完整的FastAPI示例

让我们把这些特性组合起来，创建一个实际的FastAPI端点：

# fastapi_example.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field, computed_field, ConfigDict
from typing import List, Annotated
from datetime import datetime, timezone
import uvicorn

app = FastAPI(title="Pydantic v2示例API")

# 可复用的自定义类型
Username = Annotated[str, Field(min_length=3, max_length=50, pattern=r"^[a-zA-Z0-9_]+$")]
Email = Annotated[str, Field(pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")]

class UserBase(BaseModel):
    """用户基础模型"""
    username: Username
    email: Email

class UserCreate(UserBase):
    """创建用户请求"""
    password: str = Field(min_length=8, max_length=100)

class UserResponse(UserBase):
    """用户响应模型"""
    model_config = ConfigDict(from_attributes=True)

    id: int
    created_at: datetime
    is_active: bool = True

    @computed_field
    @property
    def account_age_days(self) -> int:
        """账号创建天数"""
        delta = datetime.now(timezone.utc) - self.created_at
        return delta.days

# 内存存储（示例用）
users_db = []
next_id = 1

@app.post("/users/", response_model=UserResponse)
async def create_user(user: UserCreate):
    """创建新用户"""
    global next_id

    # 检查用户名是否已存在
    if any(u.username == user.username for u in users_db):
        raise HTTPException(status_code=400, detail="用户名已存在")

    # 创建用户（模拟数据库保存）
    db_user = UserResponse(
        id=next_id,
        username=user.username,
        email=user.email,
        created_at=datetime.now(timezone.utc),
        is_active=True
    )

    users_db.append(db_user)
    next_id += 1

    return db_user

@app.get("/users/", response_model=List[UserResponse])
async def list_users(active_only: bool = True):
    """列出用户"""
    if active_only:
        return [u for u in users_db if u.is_active]
    return users_db

@app.get("/users/stats")
async def user_stats():
    """用户统计信息（演示计算字段）"""
    if not users_db:
        return {"total_users": 0, "avg_account_age": 0}

    total = len(users_db)
    avg_age = sum(u.account_age_days for u in users_db) / total

    return {
        "total_users": total,
        "active_users": sum(1 for u in users_db if u.is_active),
        "avg_account_age": round(avg_age, 1)
    }

if __name__ == "__main__":
    print("启动FastAPI服务器...")
    print("访问 http://localhost:8000/docs 查看API文档")
    uvicorn.run(app, host="0.0.0.0", port=8000)

写在最后

Pydantic v2的核心哲学是：用明确性替代魔法。这七个特性共同构成了一个更可靠、更易维护的API设计体系：

1. TypeAdapter - 像手术刀一样精准验证
2. Annotated + Field - 约束与类型形影不离
3. 确定性验证器 - 明确的执行顺序和职责分离
4. 精确序列化控制 - 在源头控制API输出格式
5. computed_field - 自文档化的计算字段
6. RootModel[T] - 优雅的简单类型包装
7. ConfigDict + 高性能核心 - 统一配置，极致性能

从“勉强工作的模式”到“可以自信演进的设计”，Pydantic v2提供了我们需要的所有工具。特别是对于正在扩张的API表面，这些特性能够显著降低维护成本，提高开发效率。

你的下一步：在你的下一个项目（或现有项目的重构中）尝试引入 Annotated 类型定义，或者用 computed_field 替换那些散落在各处的派生属性。小步快跑，逐步体验Pydantic v2带来的清晰和稳定。

欢迎在技术社区如云栈社区分享你在API设计中遇到的验证问题，或者你尝试Pydantic v2特性的经验！

参考资料

[1] Pydantic官方文档: https://docs.pydantic.dev/latest/

[2] Pydantic v1到v2迁移指南: https://docs.pydantic.dev/latest/migration/

[3] FastAPI + Pydantic最佳实践: https://fastapi.tiangolo.com/tutorial/extra-models/