1. 引言：为何需要函数参数的预验证？
在复杂的 python 应用中，函数是核心的逻辑单元。为了确保函数的健壮性，我们通常会对其输入参数进行校验。pydantic 作为一个强大的数据验证库，提供了基于类型提示的验证能力，例如通过 @validate_call 装饰器。然而，在某些场景下，我们可能需要在不实际执行函数体的情况下，仅验证其参数是否符合预期的类型提示。例如，构建 api 请求体校验器、模拟函数调用前的参数检查，或在动态代码生成前进行参数预检。pydantic 的 @validate_call 装饰器虽然能进行验证，但它会实际调用函数，并且其返回结果并不直接暴露底层的验证模型，这使得我们无法在不调用函数的情况下单独进行参数验证。
2. 核心思路：从函数签名到 Pydantic 模型
Python 函数的类型提示信息存储在其 __annotations__ 属性中。这个属性是一个字典，键是参数名，值是对应的类型提示。Pydantic 的 BaseModel 也是通过其类定义中的类型提示来定义字段的。因此，核心思路是：我们可以程序化地读取一个函数的 __annotations__，并将其转换为一个临时的 Pydantic BaseModel 类。然后，通过实例化这个动态生成的模型，即可对传入的参数进行 Pydantic 级别的验证。
3. 实现动态验证模型
我们将创建一个辅助函数 form_validator_model，它接收一个可调用对象（函数），并返回一个动态生成的 Pydantic BaseModel 类型。
import collections.abc
import pydantic
from typing import Optional, Type
def form_validator_model(func: collections.abc.Callable) -> Type[pydantic.BaseModel]:
"""
根据函数的类型提示动态生成一个 Pydantic 验证模型。
Args:
func: 需要为其生成验证模型的函数。
Returns:
一个 Pydantic BaseModel 类型，可用于验证 func 的参数。
"""
# 复制函数的 __annotations__，因为我们可能需要修改它
annotations = func.__annotations__.copy()
# 移除函数的返回值注解，因为它不是参数
# Pydantic 模型只关注输入字段
annotations.pop('return', None)
# 动态创建 Pydantic BaseModel 类
# type() 函数的第三个参数是类的属性字典
# 我们将 __annotations__ 直接传递给它，Pydantic 会自动识别并创建字段
model_name = f'{func.__name__}_Validator'
DynamicValidatorModel = type(model_name, (pydantic.BaseModel,), {'__annotations__': annotations})
return DynamicValidatorModel
代码解析：
- func.__annotations__.copy(): 获取函数的类型提示字典，并创建一个副本。这是为了避免直接修改原始函数的 __annotations__，确保函数的元数据不受影响。
- annotations.pop('return', None): 函数的 __annotations__ 可能包含 'return' 键，表示返回值的类型。Pydantic 模型只关心输入字段，因此我们需要将其移除。pop(key, default) 方法在键不存在时不会报错。
- type(name, bases, dict): 这是 Python 内置的用于动态创建类的函数。
- name: 新类的名称，我们使用函数名加上 _Validator 来生成一个描述性名称。
- bases: 新类的基类元组。这里我们指定 (pydantic.BaseModel,)，使其继承 Pydantic 的验证能力。
- dict: 新类的属性字典。我们将处理过的 annotations 字典作为 __annotations__ 属性传递给新类。Pydantic 在类定义时会自动解析这个 __annotations__ 并生成对应的模型字段。
4. 示例与验证
让我们定义一个示例函数 foo，并使用上述 form_validator_model 来验证其参数。
# 定义一个示例函数
def foo(x: int, y: str, z: Optional[list] = None) -> str:
"""一个带有类型提示的示例函数。"""
return f"{x} - {y} - {z}"
# 使用辅助函数生成验证模型
FooValidator = form_validator_model(foo)
# 示例 1: 有效的参数
print("--- 验证有效参数 ---")
try:
valid_kwargs = {'x': 10, 'y': 'hello', 'z': [1, 2, 3]}
validated_data = FooValidator(**valid_kwargs)
print(f"验证成功: {validated_data.model_dump()}")
# 此时，validated_data 是一个 FooValidator 实例，其属性已通过验证
# 我们可以访问它们，例如 validated_data.x, validated_data.y
except pydantic.ValidationError as e:
print(f"验证失败: {e}")
print("\n--- 验证部分参数 (可选参数缺失) ---")
try:
valid_kwargs_partial = {'x': 20, 'y': 'world'} # z 缺失，但它是 Optional
validated_data_partial = FooValidator(**valid_kwargs_partial)
print(f"验证成功 (部分参数): {validated_data_partial.model_dump()}")
except pydantic.ValidationError as e:
print(f"验证失败: {e}")
# 示例 2: 无效的参数类型
print("\n--- 验证无效参数类型 ---")
try:
invalid_kwargs_type = {'x': 'not_an_int', 'y': 'hi'}
FooValidator(**invalid_kwargs_type) # 这将引发 ValidationError
except pydantic.ValidationError as e:
print(f"验证失败: {e}")
# Pydantic 会详细指出哪个字段验证失败以及原因
# 示例 3: 缺少必需参数
print("\n--- 验证缺少必需参数 ---")
try:
missing_kwargs = {'y': 'only_y'}
FooValidator(**missing_kwargs) # 这将引发 ValidationError
except pydantic.ValidationError as e:
print(f"验证失败: {e}")
通过上述示例，我们可以清晰地看到，即使 foo 函数本身从未被调用，我们也能利用 FooValidator 模型对其预期参数进行严格的 Pydantic 验证。
5. 注意事项与局限性
- 仅支持关键字参数 (kwargs): 当前这种动态模型生成的方法，只能通过关键字参数进行验证。Pydantic BaseModel 实例化时默认接收关键字参数。如果你尝试传入位置参数，Pydantic 会将其视为模型中未定义的字段，并可能导致错误或无法正确验证。这意味着你不能像调用函数那样直接传入 FooValidator(10, 'hello')。
- 默认值处理: Pydantic BaseModel 会正确处理函数参数中定义的默认值。如果一个参数在函数签名中定义了默认值，并且在传入的 kwargs 中缺失，Pydantic 会使用该默认值填充模型字段，除非该参数被标记为必需。
- 复杂类型与Pydantic集成: 这种方法与 Pydantic 对复杂类型（如 List, Dict, Union, 自定义模型等）的强大验证能力完全兼容。只要函数签名中使用了 Pydantic 支持的类型提示，动态模型就能正确解析和验证。
6. 总结
本文介绍了一种在不实际调用函数的情况下，利用 Pydantic 对其参数进行类型和数据验证的高级技巧。通过动态地从函数的 __annotations__ 创建一个 Pydantic BaseModel，我们能够实现灵活且强大的参数预校验机制。尽管存在仅支持关键字参数的局限性，但这种方法为需要提前验证函数输入的场景提供了宝贵的解决方案，极大地增强了 Python 代码的健壮性和可靠性。这对于构建可配置的系统、API接口验证层或任何需要解耦参数校验与函数执行的场景都非常有用。
