beartype 运行时入参校验

beartype 和 pydantic 都是 Python 中用于类型检查和数据验证的工具，但它们的设计理念和应用场景有所不同。我们来详细对比一下它们的区别，以便你根据需求选择合适的工具。

🔍 beartype vs pydantic

特性	`beartype`	`pydantic`
类型检查时机	运行时类型检查	运行时类型验证 + 数据模型构建
使用场景	函数、方法、类的类型检查	数据模型验证、序列化/反序列化
自动装饰	`beartype_this_package` 自动装饰	不支持自动装饰，每个模型需要手动定义
性能	高效、轻量，函数级别检查	性能较高，但因为有数据模型构建和验证，开销更大
错误提示	详细的参数和返回值错误提示	报错信息详细，支持字段级别的错误提示
复杂类型支持	对复杂类型支持有限	完全支持 Union、List、Dict、嵌套模型等复杂类型
静态代码支持	兼容 Python 原生类型提示（PEP 484）	使用自定义类型提示，与 MyPy 兼容
数据转换	无数据转换功能	自动数据转换（如 `str` 转 `int`，`datetime` 等）

🎯 功能对比分析

特性	`beartype` 示例	`pydantic` 示例
函数类型检查	✅ 自动装饰 `@beartype_this_package`	❌ 不支持函数类型装饰
数据模型验证	❌ 不支持（只能用于参数和返回值检查）	✅ 强大的数据模型验证和序列化
数据解析与转换	❌ 不支持	✅ 自动数据转换，如字符串转数字、日期
默认值和校验	❌ 仅支持 Python 默认参数	✅ 支持默认值、校验器（`@validator` 装饰器）
数据序列化/反序列化	❌ 无内置序列化和反序列化功能	✅ 支持 `.json()`、`.dict()` 等序列化

💡 代码示例对比

1. 使用 `beartype` 进行函数类型检查

from beartype import beartype

@beartype
def add(x: int, y: int) -> int:
    return x + y

print(add(1, 2))      # 正常输出 3
print(add(1, "2"))    # 运行时报错，类型不匹配

优点：轻量、简单、零配置
缺点：仅用于类型检查，无法数据转换或序列化

2. 使用 `pydantic` 进行数据模型验证和转换

from pydantic import BaseModel, ValidationError

class User(BaseModel):
    id: int
    name: str
    age: int = 18  # 默认值

try:
    user = User(id="123", name="Alice")
    print(user)
except ValidationError as e:
    print(e)

输出：

1	id=123 name='Alice' age=18

优点：

强大的数据转换和默认值支持
结构化数据验证

缺点：

需要手动定义数据模型
运行时有性能开销

🔧 适用场景建议

使用场景	适合工具	说明
轻量级的函数参数和返回值类型检查	`beartype`	高效、简洁、轻量，适合快速类型检查
复杂的业务数据模型验证和序列化	`pydantic`	复杂数据验证、转换、序列化的最佳选择，支持 FastAPI 等框架
快速调试、原型开发	`beartype`	不需要复杂的数据模型，只需检查类型一致性
严格的输入校验和数据转换需求	`pydantic`	需要严格的类型转换、字段验证和数据解析