在对接外部接口或解析非 Python 命名风格的数据时，字段名映射是最常见的需求之一。比如后端返回的 JSON 中已经有键叫 user_name，而 Pydantic 模型希望用 username 这个属性名；或者模型字段叫 full_name，但数据源里的现有键是 name。Pydantic 提供了 alias 机制来处理这种差异。简单来说，alias 是字段在外部数据中的名称，而字段名是 Python 对象里的属性名。只要给 Field 设置 alias 参数，Pydantic 就会在验证时优先读取 alias 指定的键。不过如果只设置 alias，字段本身的名称默认不会参与解析，这可能会让已有的调用方式失效。下面通过几个具体例子说明如何让别名指向已有键，同时保留字段名可用。
alias 的双重身份：验证与序列化
在 Pydantic v1 中，Field 的 alias 参数主要影响验证阶段，用来决定从外部数据读取哪个键。序列化时是否使用别名则由 by_alias 参数单独控制。到了 Pydantic v2，alias 仍然是设置验证别名和序列化别名的快捷方式，但默认情况下调用 model_dump() 输出时仍然使用字段名，只有传入 by_alias=True 才会输出别名。这种设计让开发者可以在读取和写出之间做出选择。
下面是一个基础示例。模型内部使用 full_name 作为属性名，但外部数据中已经存在 name 这个键。通过 Field 的 alias 参数，可以直接把别名指向 name。
from pydantic import BaseModel, Field
class User(BaseModel):
full_name: str = Field(alias='name')
user = User(**{'name': '张三'})
print(user.full_name) # 张三
print(user.model_dump()) # {'full_name': '张三'}
print(user.model_dump(by_alias=True)) # {'name': '张三'}
可以看到，默认输出时以字段名 full_name 为准，需要显式指定 by_alias=True 才会转回外部的 name。如果项目只关心读取外部数据，这个基础用法已经足够。但它有一个明显的问题：当外部数据中同时存在 name 和 full_name，或者旧接口还在用 full_name 传值时，字段名不会被接受。
让字段名和别名同时可用：populate_by_name
只设置 alias 时，字段名会被视为外部输入中的未知字段。也就是说，如果外部数据里已经包含 full_name 这个键，Pydantic 也不会把它映射到 full_name 字段，因为它优先查找 alias 指定的 name。这种情况在模型升级或兼容多套数据源时非常容易造成验证失败。解决方式是在 model_config 中开启 populate_by_name。
from pydantic import BaseModel, Field, ConfigDict
class User(BaseModel):
model_config = ConfigDict(populate_by_name=True)
full_name: str = Field(alias='name')
# 以下两种写法都可以通过验证
print(User(**{'name': '张三'}).full_name)
print(User(**{'full_name': '李四'}).full_name)
这个配置对应 v1 中的 allow_population_by_field_name。v1 中需要在模型的 Config 类里设置，而 v2 统一放进了 model_config。迁移时不要忘记这一点，否则老数据里如果使用字段名而不是别名，验证会直接报错。对于已经存在的字段键，比如外部 JSON 中既有 name 又有 full_name，populate_by_name 允许两者都进入，但最好在数据源头控制不要同时传两个键，以免出现歧义。
populate_by_name 的另一个好处是可以在不破坏内部命名习惯的前提下兼容多种外部键。比如模型内部坚持使用 username，而数据源分别返回 user_name 和 username，只需要给字段设置 alias 为 user_name，同时开启 populate_by_name，两个键就都能被接受。这样迁移过程会更平滑。
拆分 validation_alias 与 serialization_alias
在 Pydantic v2 中，Field 支持 validation_alias 和 serialization_alias 两个独立参数。validation_alias 只负责读取外部数据，serialization_alias 只负责输出别名。这种拆分让读取和写出可以指向不同的键。例如外部系统给的是 user_name，但希望模型输出时转成 login_name，可以这样定义。
from pydantic import BaseModel, Field
class Account(BaseModel):
username: str = Field(
validation_alias='user_name',
serialization_alias='login_name'
)
data = {'user_name': 'alice'}
account = Account(**data)
print(account.username) # alice
print(account.model_dump()) # {'username': 'alice'}
print(account.model_dump(by_alias=True)) # {'login_name': 'alice'}
如果只设置 alias，它同时影响两个方向；如果三个参数同时出现，Pydantic 会优先采用更具体的 validation_alias 或 serialization_alias。对于需要兼容旧字段名又不想在输出时改变键名的场景，只设置 validation_alias 并开启 populate_by_name 是更安全的做法。这样模型内部属性名保持不变，外部读取可以适配多种键，序列化时仍然用字段名输出。
需要注意的是，当 serialization_alias 未设置但 alias 存在时，model_dump(by_alias=True) 会使用 alias 作为输出键。这个行为可能不是所有项目都希望看到的。如果只想在验证阶段做映射，就应该忘记 alias 参数，只使用 validation_alias，并配合 populate_by_name 保留字段名输入能力。这样可以避免在输出阶段意外改变键名。
常见错误与迁移建议
从 v1 迁移到 v2 时，最常遇到的两个问题是 allow_population_by_field_name 被遗弃，以及 dict() 方法被 model_dump() 替代。v1 中的字段别名行为默认只影响验证，v2 中同样如此，但配置位置变了。迁移项目时，建议把 Config 类里的 allow_population_by_field_name 改成 model_config = ConfigDict(populate_by_name=True)，同时检查所有序列化调用是否仍然输出预期的键。
# Pydantic v1 写法
class UserV1(BaseModel):
full_name: str = Field(alias='name')
class Config:
allow_population_by_field_name = True
# Pydantic v2 写法
from pydantic import BaseModel, ConfigDict, Field
class UserV2(BaseModel):
model_config = ConfigDict(populate_by_name=True)
full_name: str = Field(alias='name')
另一个容易忽略的地方是别名与已有键完全相同时，字段名会被忽略。比如模型字段已经叫 username，外部键也叫 username，却又给字段设置了 alias='username'，这看起来多余，但在某些自动生成的场景中可能发生。如果只是想统一命名，不需要额外别名。只有在外部键与字段名不同时，alias 才有实际意义。
Pydantic 的验证顺序是先根据 alias 或 validation_alias 查找，再根据 populate_by_name 决定是否接受字段名。不要依赖异常消息中的键名来推断数据来源，定义模型时最好写清楚哪个键是标准入口，哪些键是兼容入口。这样后续维护时更容易判断哪些字段可以安全移除，也能避免因为优先级不清导致的验证结果不稳定。