在 Python 工程里，函数入参的合法性往往决定了后续逻辑是否稳定。Pydantic 作为数据校验库，除了用固定类定义模型，还支持在运行中构造模型，这就是动态模型。借助它，我们可以把函数参数的检查从散落的判断语句收敛为统一的预验证层。
为什么需要动态参数预验证
很多团队在写工具函数时，习惯在函数体开头写一串判断：如果不是整型就抛异常，如果字符串为空就返回错误。这类代码短期能跑，但参数一多就难以维护，而且错误提示不统一。当同一个函数被不同调用方复用，或者参数结构随配置变化时，硬编码校验就成了负担。
Pydantic 的静态模型要求提前声明所有字段，这在参数 schema 固定的场景很好用。可实际业务中，有时字段名、类型要从配置文件或上游元数据读取，这时候静态类就不够灵活。动态模型通过 create_model 在运行时拼装字段，既保留类型校验能力，又不被固定结构绑死。
动态模型的核心用法
Pydantic 提供 pydantic.create_model 函数，它接收模型名和一组字段定义，返回一个新的模型类。字段定义通常是元组，形如 (类型, 默认值或 Field 描述)。我们可以在函数装饰器或入口处，根据签名动态生成模型并校验入参。
下面示例展示一个简单工厂：根据传入的字段要求构造模型，并用它验证字典数据。注意代码块中 HTML 特殊字符已转义。
from pydantic import create_model, Field, ValidationError
# 动态定义一个用户模型
def build_user_model():
# 字段元组：(类型, Field说明)
fields = {
'name': (str, Field(..., min_length=1)),
'age': (int, Field(..., gt=0, lt=150)),
}
# 动态创建模型类
UserModel = create_model('UserModel', **fields)
return UserModel
def validate_user(data: dict):
model_cls = build_user_model()
try:
# 用动态模型校验
return model_cls(**data)
except ValidationError as e:
print('校验失败:', e.json())
return None
sample = {'name': '张三', 'age': 28}
result = validate_user(sample)
print(result)
上述代码中，build_user_model 不需要在文件加载时就确定结构，而是在调用时生成。如果后续字段变化，只需改 fields 字典，校验逻辑不变。这种写法把参数契约从代码层移到了数据层。
封装为函数预验证装饰器
为了让动态模型真正服务于函数参数预验证，可以写一个装饰器：它读取目标函数的注解，动态建立模型，在调用前把参数转成模型实例。这样业务函数体内拿到的就是干净对象。
以下示例用动态模型包裹函数参数，实现自动预验证。我们故意转义了所有小于号与大于号。
from functools import wraps
from inspect import signature
from pydantic import create_model, ValidationError
def dynamic_validate(func):
sig = signature(func)
# 根据函数注解动态建模型
fields = {}
for name, param in sig.parameters.items():
if param.annotation is not param.empty:
fields[name] = (param.annotation, ...)
Model = create_model(func.__name__ + 'Args', **fields)
@wraps(func)
def wrapper(*args, **kwargs):
try:
# 绑定参数并校验
bound = sig.bind(*args, **kwargs)
bound.apply_defaults()
model = Model(**bound.arguments)
except ValidationError as e:
raise ValueError('参数预验证失败: ' + e.json())
# 用校验后的数据调用原函数
return func(**model.dict())
return wrapper
@dynamic_validate
def create_order(uid: int, amount: float, note: str = ''):
return {'uid': uid, 'amount': amount, 'note': note}
print(create_order(uid=12, amount=9.9))
这个装饰器在导入时仅捕获签名，在每次调用时才构建并校验模型。如果传入 uid='abc'，Pydantic 会抛出清晰错误，而不是让函数内部因类型错乱崩溃。相比手动判断，它支持嵌套类型、自动转换，例如字符串 '12' 可被转为 int。
动态模型与静态模型怎么选
静态模型适合长期稳定的 API 契约，代码可读性强，IDE 能补全字段。动态模型胜在灵活，尤其当字段来自数据库配置、网关元数据或插件系统时，不必为每个变体都写新类。
需要注意，频繁调用 create_model 会产生不少类对象，如果放在热点路径，建议加缓存：以字段签名做键，复用已生成的模型类。另外动态模型错误信息虽结构化，但构造开销略高于裸判断，在非性能敏感入口使用最划算。
| 对比维度 | 静态模型 | 动态模型 |
|---|---|---|
| 定义时机 | 代码加载期 | 运行期 |
| 适用场景 | 固定 schema | 配置驱动 schema |
| 维护成本 | 低 | 中 |
| 灵活度 | 弱 | 强 |
常见误区与规避
有人误以为动态模型等于不写类型，其实它仍强制类型约束，只是类型在运行时确定。另一个误区是在循环里无缓存地建模型，导致内存上涨。正确做法是将模型类缓存到字典或 lru_cache 中。
还有开发者把动态模型当万能闸，把所有业务规则塞进 Field 校验，这会让模型臃肿。预验证应只管基础类型与边界，复杂规则留给领域服务，保持层次清晰。
小结
基于 Pydantic 动态模型的函数参数预验证，本质是把参数契约外置并自动化。它用少量运行期成本，换来了统一的错误格式、更低的维护负担和更早的故障暴露。在配置化、插件化系统中，这种实践能明显提升代码健壮性。