Pydantic 进阶：不执行函数即可验证其参数的巧妙方法

本文深入探讨了如何在不实际调用函数的情况下，利用 Pydantic 对其预期接收的参数进行类型和数据验证。针对 pydantic.validate_call 无法满足此“预验证”需求的场景，我们介绍了一种创新的解决方案：通过动态创建 Pydantic 模型，从函数的类型注解中提取参数信息，并以此模型执行参数校验，从而实现高效且解耦的参数“预检”机制，确保数据符合预期。

引言：为何需要不调用函数即验证参数？

在许多应用场景中，我们可能需要在实际执行函数之前，对其接收的参数进行严格的验证。例如：

1. API 请求预处理： 在处理外部传入的 HTTP 请求体时，希望在业务逻辑开始前就验证数据格式和类型。
2. 配置校验： 验证应用程序启动时加载的配置项是否符合预设的结构和类型。
3. 复杂业务逻辑前的快速失败： 避免因参数错误导致函数执行到一半才报错，提高程序健壮性。

Pydantic 的 validate_call 装饰器是一个强大的工具，它能够在函数被调用时自动验证其参数。然而，其核心在于“调用时”验证，这意味着它会实际执行函数。对于上述“预验证”需求，即在不执行函数的情况下仅验证参数，validate_call 无法直接满足。同时，Pydantic 早期版本提供的 validate_arguments 已被弃用，且其返回值的结构也不再适用于此特定场景。

为了解决这一挑战，我们可以利用 Python 的内省能力和 Pydantic 的动态模型创建特性，实现一种灵活且高效的参数预验证机制。

核心原理：从函数签名到 Pydantic 模型

Python 函数的类型提示信息存储在其 __annotations__ 属性中，这是一个字典，键是参数名（或 ‘return’），值是对应的类型注解。Pydantic 的 BaseModel 能够通过其类的 __annotations__ 属性来定义模型字段。

因此，核心思路是：

1. 获取目标函数的 __annotations__ 属性。
2. 对这些注解进行处理，移除与参数无关的注解（如返回值注解）。
3. 利用 Python 内置的 type() 函数，在运行时动态创建一个继承自 pydantic.BaseModel 的新类。
4. 将处理后的函数参数注解作为这个新 Pydantic 模型的 __annotations__。
5. 实例化这个动态创建的模型，并传入待验证的参数，Pydantic 将自动完成验证工作。

实现步骤与代码示例

下面是一个实现上述原理的辅助函数 form_validator_model 及其使用示例：

import collections.abc
from typing import Optional, Type, Dict, Any
import pydantic
def form_validator_model(func: collections.abc.Callable) -> Type[pydantic.BaseModel]:
"""
从函数类型注解动态生成 Pydantic 验证模型。
Args:
func: 带有类型提示的目标函数。
Returns:
一个动态生成的 Pydantic BaseModel 子类，可用于验证函数的参数。
"""
ann = func.__annotations__.copy()
# 移除返回值注解，因为 Pydantic 模型字段不关心函数的返回值类型
ann.pop('return', None)
# 动态创建 Pydantic BaseModel 类
# 类名通常以原函数名加上 '_Validator' 后缀，方便识别
# 基类为 (pydantic.BaseModel,)，字典中包含类的属性，这里主要是 __annotations__
return type(f'{func.__name__}_Validator', (pydantic.BaseModel,), {'__annotations__': ann})
# 示例函数
def foo(x: int, y: str, z: Optional[list] = None):
"""一个带有类型提示的示例函数"""
print(f"Function foo called with x={x}, y={y}, z={z}") # 实际调用时会打印
pass
# 1. 生成验证模型
# 调用 form_validator_model 函数，传入 foo 函数
FooValidator = form_validator_model(foo)
print(f"生成的验证模型类名: {FooValidator.__name__}")
print(f"模型字段 (基于函数注解): {FooValidator.model_fields.keys()}")
# 2. 尝试验证正确的参数
print("\n--- 验证正确的参数 ---")
try:
valid_kwargs = {'x': 10, 'y': 'hello'}
# 实例化 FooValidator，Pydantic 会自动验证传入的关键字参数
validated_data = FooValidator(**valid_kwargs)
print(f"验证成功！Pydantic 模型数据: {validated_data.model_dump()}")
# 此时，foo 函数并未被调用
# foo(**validated_data.model_dump()) # 如果需要，可以再调用函数
except pydantic.ValidationError as e:
print(f"验证失败: {e}")
# 3. 尝试验证错误的参数
print("\n--- 验证错误的参数 ---")
try:
invalid_kwargs = {'x': 'not_an_int', 'y': 123, 'extra_field': True}
validated_data = FooValidator(**invalid_kwargs)
print(f"验证成功！Pydantic 模型数据: {validated_data.model_dump()}")
except pydantic.ValidationError as e:
print(f"验证失败: {e}")
# 4. 验证缺少必要参数的情况
print("\n--- 验证缺少必要参数的情况 ---")
try:
missing_kwargs = {'x': 5} # 缺少 'y'
validated_data = FooValidator(**missing_kwargs)
print(f"验证成功！Pydantic 模型数据: {validated_data.model_dump()}")
except pydantic.ValidationError as e:
print(f"验证失败: {e}")
# 5. 原始问题中提供的例子
print("\n--- 原始问题中的例子 ---")
def func(a: str, b: int) -> str:
"""一个简单的函数，返回字符串"""
return a * b
ModelForFunc = form_validator_model(func)
try:
# 'b' 期望是 int，传入 'bye' 会引发 ValidationError
ModelForFunc(a='hi', b='bye')
except pydantic.ValidationError as e:
print(f"原始例子验证失败 (符合预期): {e}")
try:
# 正确的参数
ModelForFunc(a='hello', b=3)
print("原始例子验证成功 (正确参数)")
except pydantic.ValidationError as e:
print(f"原始例子验证失败 (不应失败): {e}")

在上述代码中，form_validator_model 函数接收一个可调用对象（即函数），然后通过访问其 __annotations__ 属性来获取类型提示。它会复制这个字典并移除 return 键（因为 Pydantic 模型不关心函数的返回值类型）。最后，它使用 type() 函数动态地创建一个新的 Pydantic BaseModel 子类，并将处理后的注解作为其 __annotations__，这样 Pydantic 就能根据这些注解自动生成模型字段和验证规则。

注意事项与局限性

尽管这种方法非常强大和灵活，但也存在一些需要注意的方面：

1. 仅支持关键字参数： 动态生成的 Pydantic 模型只能通过关键字参数进行实例化。这是 Pydantic BaseModel 的设计使然，它将关键字参数映射到模型字段。这意味着你不能像调用函数那样传入位置参数，例如 model(‘hi’, 123) 会报错。如果你需要验证位置参数，可能需要手动将它们转换为字典形式的关键字参数。
2. 默认值处理： 函数参数的默认值会被 Pydantic 模型自动识别为可选字段。例如，如果函数参数 z: Optional[list] = None，则在 Pydantic 模型中 z 将被视为一个可选字段。
3. 复杂类型支持： Pydantic 对 Optional、Union、List、Dict 等复杂类型以及自定义模型类型都有很好的支持，这些都将无缝地集成到动态生成的模型中。
4. 性能考量： 动态创建类会有轻微的运行时开销。对于大多数应用场景而言，这种开销可以忽略不计。如果需要对同一个函数进行频繁的参数验证，建议将 form_validator_model 生成的模型类进行缓存，避免重复创建。
5. 与 validate_call 的区别： 此方法侧重于“数据验证”，即检查传入的数据是否符合类型和结构要求，不涉及函数执行逻辑。而 validate_call 旨在确保函数调用时的参数正确性，并在验证通过后执行函数。两者各有侧重，互为补充。

总结

通过动态创建 Pydantic 模型来验证函数参数，提供了一种灵活、强大的方式，利用 Pydantic 强大的验证能力对函数参数进行“预检”。这种技术特别适用于需要将参数验证逻辑与实际函数执行逻辑解耦的场景，例如在 API 网关层或数据处理管道的早期阶段进行数据校验。它不仅提高了代码的健壮性，也使得错误能够更早地被发现，从而优化了开发和调试体验。