Pydantic：在不调用函数的情况下验证函数参数

1. 问题背景与挑战

在Python开发中，我们经常需要对函数接收的参数进行严格的类型和结构验证，以提高代码的健壮性和可维护性。Pydantic是一个优秀的Python数据验证库，它通过类型提示（type hints）提供了强大的数据解析和验证能力。通常，Pydantic的@validate_call装饰器可以用于在函数调用前自动验证参数。然而，在某些特定场景下，我们可能需要仅验证参数，而不实际执行函数本身。例如，在API请求预处理、配置加载或模拟测试等场景中，我们可能只想检查传入的数据是否符合函数的预期签名，而不是立即触发函数的业务逻辑。

Pydantic早期版本提供了@validate_arguments装饰器，它允许在不实际调用函数的情况下进行参数验证。但该装饰器已被弃用，而新的@validate_call装饰器虽然功能更强大，其设计目的在于包装并执行函数，因此无法直接用于“只验证不调用”的场景。这就提出了一个挑战：如何在不依赖已弃用功能的前提下，利用Pydantic的强大验证能力实现函数参数的预验证？

2. 解决方案：动态构建Pydantic模型

解决上述问题的核心思路是：将函数的参数类型提示信息提取出来，然后利用这些信息动态地构建一个Pydantic BaseModel。这个动态模型将“模仿”函数的签名，从而能够对传入的参数进行Pydantic式的验证。

Python函数对象的__annotations__属性包含了其所有参数（和返回值）的类型提示信息。我们可以利用这个属性来动态创建Pydantic模型。

2.1 核心实现函数

以下是一个用于动态生成Pydantic验证模型的函数：

怪兽AI数字人

数字人短视频创作，数字人直播，实时驱动数字人

44

查看详情

import collections.abc
import pydantic
from typing import Type, Callable, Any

def form_validator_model(func: Callable[..., Any]) -> Type[pydantic.BaseModel]:
    """
    根据函数的类型提示动态生成一个Pydantic BaseModel，用于验证函数参数。

    Args:
        func: 待验证参数的函数对象。

    Returns:
        一个Pydantic BaseModel类，其字段对应于函数的参数。
    """
    # 复制函数的__annotations__属性，避免修改原始函数对象
    annotations = func.__annotations__.copy()

    # 移除返回值类型注解，因为我们只关心参数验证
    # 'return' 键在__annotations__中表示返回值类型
    annotations.pop('return', None) 

    # 动态创建Pydantic BaseModel
    # type() 函数的第三个参数是一个字典，用于定义类的属性和方法。
    # 在这里，我们将__annotations__字典作为该字典的一个键值对，
    # 这样Pydantic在创建模型时就能识别并使用这些类型提示。
    model_name = f'{func.__name__}_Validator'
    return type(model_name, (pydantic.BaseModel,), {'__annotations__': annotations})

2.2 示例用法

假设我们有以下一个带有类型提示的函数 foo：

from typing import Optional, List

def foo(x: int, y: str, z: Optional[List[str]] = None):
    """一个示例函数，带有类型提示。"""
    print(f"x: {x}, y: {y}, z: {z}")

# 使用我们的form_validator_model函数为foo生成验证模型
FooValidator = form_validator_model(foo)

# 1. 成功验证的例子
print("--- 成功验证示例 ---")
valid_kwargs = {'x': 10, 'y': 'hello world'}
try:
    validated_data = FooValidator(**valid_kwargs)
    print(f"验证成功！传入参数: {validated_data.model_dump()}")
except pydantic.ValidationError as e:
    print(f"验证失败: {e}")

# 2. 带有可选参数的成功验证例子
print("\n--- 带有可选参数的成功验证示例 ---")
valid_kwargs_with_z = {'x': 20, 'y': 'test', 'z': ['item1', 'item2']}
try:
    validated_data_with_z = FooValidator(**valid_kwargs_with_z)
    print(f"验证成功！传入参数: {validated_data_with_z.model_dump()}")
except pydantic.ValidationError as e:
    print(f"验证失败: {e}")

# 3. 验证失败的例子（类型不匹配）
print("\n--- 验证失败示例 (类型不匹配) ---")
invalid_kwargs_type = {'x': 'not_an_int', 'y': 123}
try:
    FooValidator(**invalid_kwargs_type)
except pydantic.ValidationError as e:
    print(f"验证失败！错误信息:\n{e}")

# 4. 验证失败的例子（缺少必需参数）
print("\n--- 验证失败示例 (缺少必需参数) ---")
invalid_kwargs_missing = {'x': 5} # 缺少 'y'
try:
    FooValidator(**invalid_kwargs_missing)
except pydantic.ValidationError as e:
    print(f"验证失败！错误信息:\n{e}")

2.3 工作原理分析

1. func.__annotations__.copy(): 这一步获取了函数 func 的所有类型提示。__annotations__ 是一个字典，其键是参数名（或'return'），值是对应的类型对象。我们复制它以避免对原始函数对象造成任何意外修改。
2. annotations.pop('return', None): 如果函数定义了返回值类型，__annotations__ 字典中会有一个键为 'return' 的项。由于我们只关心函数参数的验证，不关心返回值，因此将其移除。
3. type(model_name, (pydantic.BaseModel,), {'__annotations__': annotations}): 这是Python中动态创建类的核心。
   • model_name: 动态生成的Pydantic模型的名称，这里我们使用{func.__name__}_Validator以保持其与原函数的关联性。
   • (pydantic.BaseModel,): 指定新创建的类将继承自 pydantic.BaseModel。
   • {'__annotations__': annotations}: 这是关键。Pydantic在解析 BaseModel 时，会查找其 __annotations__ 属性来确定模型的字段及其类型。通过将我们从函数中提取的参数注解字典赋值给新模型的 __annotations__，Pydantic就能够像处理普通 BaseModel 一样，将这些参数视为模型的字段进行验证。

3. 注意事项与局限性

虽然这种方法有效地解决了在不调用函数的情况下验证参数的问题，但它也存在一些局限性：

1. 仅支持关键字参数验证: 这种方法生成的Pydantic模型期望以关键字参数（**kwargs）的形式接收数据。它无法直接验证位置参数。如果你的函数大量依赖位置参数调用，你需要确保在传入数据时将其转换为字典形式。
2. 不处理默认值逻辑: Pydantic模型会根据类型提示和是否为 Optional 来判断字段是否必需或有默认值。如果函数的默认值逻辑比简单的 Optional 更复杂（例如，默认值是通过某个函数调用生成的），Pydantic模型可能无法完全模拟。
3. 不处理 *args 和 **kwargs*: 对于函数签名中的 `args和kwargs`（可变位置参数和可变关键字参数），这种方法无法为其生成对应的Pydantic字段，因为它们没有具体的命名和类型提示。
4. 无Pydantic特有配置: 动态生成的模型不会自动继承任何Pydantic Config 类设置（如 extra='forbid'）。如果需要，可以手动在 type() 的第三个参数中添加 Config 类。

4. 总结

通过动态构建Pydantic BaseModel，我们提供了一种灵活且强大的方法，可以在不实际执行函数的情况下，对其传入参数进行严格的类型和结构验证。这种技术对于构建健壮的应用程序接口、配置解析器或任何需要数据预验证的系统都非常有用。尽管存在一些局限性，但对于大多数常见的函数签名和参数验证需求，它提供了一个优雅且符合Pydantic设计哲学的高效解决方案。在实际应用中，开发者应根据具体需求权衡其优缺点，并在必要时结合其他验证策略。

以上就是Pydantic：在不调用函数的情况下验证函数参数的详细内容，更多请关注php中文网其它相关文章！