Pydantic validate_call 为什么默认不校验函数返回值

用 @validate_call 装饰函数后，很多人会自然地以为“参数和返回值都已经按注解检查”。实际边界正好分开：默认只校验调用参数，函数返回什么就把什么交给调用方；只有设置 validate_return=True，返回结果才会再次进入 Pydantic 的校验链。

官方地址：https://docs.pydantic.dev/2.10/concepts/validation_decorator/

一、默认装饰器只守住入参边界

先模拟一个“生成答案”的函数。它声明返回 Answer，但函数体故意返回普通字典。默认模式下，调用方拿到的仍是字典；返回注解不会自动把它变成 Answer。

from pydantic import BaseModel, validate_call

class Answer(BaseModel):
    text: str
    score: float

@validate_call
def build_answer(prompt: str) -> Answer:
    # 参数会先按注解处理，但返回值默认不再检查
    return {"text": prompt, "score": "0.8"}

result = build_answer("解释缓存击穿")
print(type(result).__name__)  # dict
print(result["score"])       # 0.8

这里的 prompt 会接受字符串类型检查；如果传入不合适的参数，装饰器会在函数体执行前抛出 ValidationError。但函数体返回的字典不会因为写了 -> Answer 就自动转换，返回类型注解在默认模式下只是声明，不是出口闸门。

二、打开 validate_return，让结果经过同一套模型规则

当函数是插件、工具调用、模型适配器或团队多人维护的业务边界时，返回值往往比参数更值得锁定。此时把装饰器改成 @validate_call(validate_return=True)：

from pydantic import BaseModel, ValidationError, validate_call

class Answer(BaseModel):
    text: str
    score: float

@validate_call(validate_return=True)
def build_answer(prompt: str) -> Answer:
    # 返回字典会按 Answer 的字段规则转换；非法字段会在出口失败
    return {"text": prompt, "score": "0.8"}

result = build_answer("解释缓存击穿")
print(type(result).__name__)  # Answer
print(result.score)            # 0.8

@validate_call(validate_return=True)
def broken_answer(prompt: str) -> Answer:
    # 这个值无法转换为 float，调用结束时会抛出 ValidationError
    return {"text": prompt, "score": "unknown"}

开启后，字符串 "0.8" 可以按 Pydantic 的规则转换成浮点数，返回对象成为 Answer；"unknown" 则在函数返回阶段失败。它检查的是字段类型、必填项和模型约束，不负责判断答案内容是否“正确”、是否符合业务语义。

三、什么时候值得开启返回值校验

可以把选择拆成三个问题：返回值是否跨越了团队或进程边界，函数实现是否来自插件或不稳定依赖，测试是否需要把契约错误尽早暴露。只要其中一项很重要，返回校验通常更有价值；如果函数位于高频内循环，先测量装饰器带来的成本，再决定是否把校验放在边界层而不是每次调用都做。

异步函数也遵循同一原则：装饰器包住的是协程函数的调用契约，返回值校验应放在实际结果可用的边界上。若返回的是流、生成器或大型对象，不要只因为有类型注解就默认打开；先确认 Pydantic 能表达你真正想检查的结构。

四、接入前的四项检查

• 先确认要保护的是“结构”，还是答案内容、权限和业务状态；后者要用业务逻辑补充。
• 给返回模型写清必填字段、可选字段和数值约束，避免只写一个宽泛的 dict。
• 为成功转换、缺字段和非法类型各准备一个测试，确认异常发生在函数出口。
• 对高频函数比较开启前后的耗时和分配，再决定在边界统一校验还是逐次校验。

相关问题

只写返回类型注解，为什么没有自动校验？

因为 validate_call 的默认职责是参数校验。返回值校验是可选行为，需要显式传入 validate_return=True。

开启后会不会检查答案是否正确？

不会。它检查模型结构和字段规则；语义正确性、权限和业务状态仍需要单独的业务判断。

返回值校验适合所有函数吗？

不适合。边界函数通常值得开启，稳定的高频内循环应先做性能测量，再选择校验位置。