pydantic_settings的before模式字段验证器未正常执行问题

你遇到的核心问题是：Pydantic Settings加载.env/环境变量时，会先尝试将原始字符串值转换为字段声明的目标类型，这一步发生在field_validator(mode='before')执行之前。原生Pydantic无法将"380, 90, 380"这类字符串直接解析为Tuple[int, int, int]，所以在验证器触发前就抛出了SettingsError，导致你的自定义解析逻辑根本没机会运行。

推荐两种简洁的修复方式，都能让自定义解析逻辑在类型转换前执行：

方式一：使用Annotated + BeforeValidator #

通过Annotated给字段附加前置解析逻辑，确保字符串先被转换成三元组，再进行类型验证：

from pydantic_settings import BaseSettings
from pydantic import Field, BeforeValidator
from typing import Tuple, Annotated

def parse_int_tuple(v) -> tuple[int, int, int]:
    # 仅当输入是字符串时执行解析
    if isinstance(v, str):
        parts = [x.strip() for x in v.split(',')]
        assert len(parts) == 3, "必须提供3个整数，用逗号分隔"
        return tuple(int(part) for part in parts)
    # 非字符串输入（比如默认值的元组）直接返回
    return v

class JobSettings(BaseSettings):
    wp_generate_funnel_box: bool = Field(True)
    # 用Annotated包裹字段类型，添加前置解析器
    wp_funnel_box_dims_mm: Annotated[Tuple[int, int, int], BeforeValidator(parse_int_tuple)] = Field((380, 90, 380))

    model_config = {
        "env_file": ".env",
        "env_file_encoding": "utf-8",
        "extra": "ignore",
    }

方式二：自定义可解析字符串的三元组类型 #

如果需要在多个地方复用这个类型，可以自定义一个支持字符串解析的元组子类：

from pydantic_settings import BaseSettings
from pydantic import Field, GetCoreSchemaHandler
from pydantic_core import core_schema
from typing import Any, Tuple

class IntTuple3(Tuple[int, int, int]):
    @classmethod
    def __get_pydantic_core_schema__(cls, source_type: Any, handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
        # 定义支持字符串或直接三元组输入的核心Schema
        return core_schema.no_info_wrap_validator_function(
            cls.validate,
            core_schema.union_schema([
                core_schema.str_schema(),
                core_schema.tuple_schema([core_schema.int_schema()]*3)
            ])
        )
    
    @classmethod
    def validate(cls, v: Any) -> Tuple[int, int, int]:
        if isinstance(v, str):
            parts = [x.strip() for x in v.split(',')]
            if len(parts) != 3:
                raise ValueError("必须是3个整数组成的字符串，用逗号分隔")
            return tuple(int(part) for part in parts)
        elif isinstance(v, tuple) and len(v) == 3 and all(isinstance(x, int) for x in v):
            return v
        raise ValueError(f"无法将{repr(v)}转换为3元整数组")

class JobSettings(BaseSettings):
    wp_generate_funnel_box: bool = Field(True)
    # 直接使用自定义类型作为字段类型
    wp_funnel_box_dims_mm: IntTuple3 = Field((380, 90, 380))

    model_config = {
        "env_file": ".env",
        "env_file_encoding": "utf-8",
        "extra": "ignore",
    }

两种方式都能正确解析.env中的wp_funnel_box_dims_mm="380, 90, 380"，同时保留默认值的正常使用。如果输入不符合格式（比如只有2个数字），会抛出明确的错误提示。

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