在Pydantic中使用不同名称环境变量的参数传递问题

问题场景 #

我需要定义一个pydantic.BaseModel类，要求node字段的默认值来自环境变量ENV_NODE_POOL，同时支持直接传递node参数赋值。但遇到两个问题：

1. 使用Field(alias="env_node_pool")时，不传参数能正常读取环境变量，但直接传node参数会触发校验错误。
2. 尝试用AliasChoices支持多别名时，环境变量的默认值又无法生效，不传参数时会报错字段缺失。

错误代码与报错信息 #

错误写法1：仅设置alias

from pydantic import Field, BaseModel
from pydantic_settings import SettingsConfigDict

class WorkflowRun(BaseModel):
    id: str
    name: str
    node: str = Field(alias="env_node_pool")
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        env_ignore_empty=True,
    )

# 执行失败
WorkflowRun(**{"id": "1", "name": "test", "node": "test"})
# 执行成功
WorkflowRun(**{"id": "1", "name": "test", "env_node_pool": "test"})

报错信息：

ValidationError: 1 validation error for WorkflowRun
env_node_pool
  Field required [type=missing, input_value={'id': '1', 'name': 'test', 'node': 'test'}, input_type=dict]

错误写法2：使用AliasChoices但未处理默认值

from pydantic import Field, BaseModel, AliasChoices
from pydantic_settings import SettingsConfigDict

class WorkflowRun(BaseModel):
    id: str
    name: str
    node: str = Field(validation_alias=AliasChoices('node', 'ENV_NODE_POOL'))
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        env_ignore_empty=True,
        populate_by_name=True,
    )

# 执行失败，无法读取环境变量默认值
WorkflowRun(**{"id": "1", "name": "test"})

报错信息：

pydantic_core._pydantic_core.ValidationError: 1 validation error for WorkflowRun
node
  Field required [type=missing, input_value={'id': '1', 'name': 'test'}, input_type=dict]

解决方案 #

方案一：使用BaseSettings（推荐） #

BaseSettings是pydantic_settings提供的专门处理环境变量的基类，能自动读取环境变量，同时结合AliasChoices支持多别名传参。

from pydantic import Field, AliasChoices
from pydantic_settings import BaseSettings, SettingsConfigDict

class WorkflowRun(BaseSettings):
    id: str
    name: str
    node: str = Field(
        validation_alias=AliasChoices("node", "ENV_NODE_POOL"),
    )
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        env_ignore_empty=True,
        populate_by_name=True,
    )

# 测试用例均正常执行
WorkflowRun(**{"id": "1", "name": "test", "node": "test"})
WorkflowRun(**{"id": "1", "name": "test", "ENV_NODE_POOL": "test"})
WorkflowRun(**{"id": "1", "name": "test"})  # 自动读取环境变量ENV_NODE_POOL的值

方案二：在BaseModel中手动处理默认值 #

如果必须使用BaseModel，可以通过default参数手动从环境变量获取默认值，同时用AliasChoices支持多别名传参。

from pydantic import Field, BaseModel, AliasChoices
from pydantic_settings import SettingsConfigDict
import os

class WorkflowRun(BaseModel):
    id: str
    name: str
    node: str = Field(
        default=os.getenv("ENV_NODE_POOL"),
        validation_alias=AliasChoices("node", "ENV_NODE_POOL"),
    )
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        env_ignore_empty=True,
        populate_by_name=True,
    )

# 测试用例均正常执行
WorkflowRun(**{"id": "1", "name": "test", "node": "test"})
WorkflowRun(**{"id": "1", "name": "test", "ENV_NODE_POOL": "test"})
WorkflowRun(**{"id": "1", "name": "test"})  # 使用环境变量的默认值

问题原因说明 #

1. 错误写法1中，alias参数会将env_node_pool设置为字段的唯一输入键，原字段名node会被Pydantic忽略，因此传node时会被判定为缺少env_node_pool字段。
2. 错误写法2中，AliasChoices仅支持多别名校验，但BaseModel本身不会自动读取环境变量填充默认值，必须手动通过default参数指定环境变量来源。

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