Pydantic中Optional类型下Field约束未触发问题

问题现象 #

定义BaseModel子类时，使用Optional包裹带Field约束的Annotated类型，约束验证未按预期触发，非法值可被成功设置。例如传入f1=-1时，未抛出ValidationError，但去掉Optional的属性（如f2）能正常触发验证。

复现代码如下：

from typing import Annotated, Optional, List
from pydantic import Field, BaseModel, ValidationError
import pytest

class MyClass(BaseModel):
    # 失效的写法：Field约束未生效
    f1: Optional[Annotated[float | List[float], Field(ge=0)]] = None
    # 正常生效的写法
    f2: Annotated[float | List[float], Field(ge=0)] = None
    # 验证基础类型同样存在该问题
    f3: Optional[Annotated[float, Field(ge=0)]] = None

def test_valid_input():
    myclass = MyClass(f1=1, f2=1)
    assert myclass.f1 == myclass.f2 == 1

def test_invalid_input_successful_validation():
    # f2非法值触发验证，符合预期
    with pytest.raises(ValidationError):
        MyClass(f1=1, f2=-1)

def test_invalid_input_failing_validation():
    # 预期f1非法值触发验证，但实际未触发
    with pytest.raises(ValidationError):
        MyClass(f1=-1, f2=1)
    # 实际myclass.f1 == -1

使用版本：python3.11.2、pytest7.2.0、pydantic==1.10.2

原因分析 #

在Pydantic 1.x版本中，Annotated的元数据（如Field约束）需要直接作为目标类型的标注。当Annotated被Optional（本质是Union[type, None]）包裹时，Pydantic无法正确识别并应用Annotated内部的Field约束，导致验证规则被忽略。

解决方案 #

有两种可行的解决方式：

方案1：将Optional放入Annotated内部 #

调整类型标注顺序，把Optional移到Annotated内部，让Field约束直接关联到包含None的联合类型：

class MyClass(BaseModel):
    # 修改后的生效写法
    f1: Annotated[Optional[float | List[float]], Field(ge=0)] = None
    f2: Annotated[float | List[float], Field(ge=0)] = None
    f3: Annotated[Optional[float], Field(ge=0)] = None

此时再运行test_invalid_input_failing_validation，非法值会正常触发ValidationError。

方案2：升级到Pydantic 2.x #

Pydantic 2.x对Annotated和Union/Optional的类型处理逻辑进行了优化，原有的Optional[Annotated[...]]写法可以正常触发约束验证。如果项目允许升级，直接升级Pydantic版本即可解决问题。

内容的提问来源于stack exchange，提问作者hunny14