Pydantic 进阶：不调用函数验证其参数的类型提示

本文探讨了如何利用 Pydantic 动态验证函数参数，而无需实际执行函数本身。针对 Pydantic 现有装饰器（如 validate_call）无法直接提供此功能的问题，我们提出了一种解决方案：通过解析函数的类型提示 (__annotations__)，程序化地构建一个 Pydantic BaseModel。这种方法允许开发者在函数调用前，对传入的关键字参数进行严格的类型和数据校验，从而提高代码的健壮性和可靠性，尽管它目前不支持位置参数的验证。

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接口验证层或任何需要解耦参数校验与函数执行的场景都非常有用。