Python · Pydantic API models
Pydantic camelCase ↔ snake_case aliases
Python model field 可維持 snake_case，而外部 JSON 採用另一種命名慣例。若 model 已擁有 schema，alias generator 通常比遞迴 dict 轉換更合適。
單一外部規則使用 alias_generator
from pydantic import BaseModel, ConfigDict
from pydantic.alias_generators import to_camel
class UserProfile(BaseModel):
model_config = ConfigDict(
alias_generator=to_camel,
validate_by_alias=True,
validate_by_name=True,
)
first_name: str
created_at: str
profile = UserProfile.model_validate({
"firstName": "Ada",
"createdAt": "2026-09-12",
})
print(profile.first_name)
print(profile.model_dump(by_alias=True))
# {'firstName': 'Ada', 'createdAt': '2026-09-12'}Pydantic 提供 to_camel 與 to_snake，並可用 model_dump(by_alias=True) 輸出外部名稱。
validation 與 serialization 不同時使用 AliasGenerator
from pydantic import AliasGenerator, BaseModel, ConfigDict
from pydantic.alias_generators import to_camel, to_snake
class UserProfile(BaseModel):
model_config = ConfigDict(
alias_generator=AliasGenerator(
validation_alias=to_camel,
serialization_alias=to_snake,
),
validate_by_alias=True,
)
first_name: str
created_at: str
profile = UserProfile.model_validate({
"firstName": "Ada",
"createdAt": "2026-09-12",
})
print(profile.model_dump(by_alias=True))
# {'first_name': 'Ada', 'created_at': '2026-09-12'}AliasGenerator 可分別設定 validation_alias 與 serialization_alias。
正式環境注意事項
- 明確 field alias 可能優先於產生的 alias，請記錄例外並測試。
- Pydantic 已驗證 payload 時優先使用 model alias；未建模 JSON 再考慮遞迴 dict 轉換。
- 要輸出外部 field name 時使用 model_dump(by_alias=True)。
- 把 naming policy 放在 model/serialization 邊界，不要讓外部 API casing 滲入 business logic。
線上測試 JSON 邊界
在實作前測試巢狀物件、陣列、排除鍵、stop paths、語意前綴、衝突與 key-only diff。
拖放 .json 檔案，或從裝置選取
檔案只會在瀏覽器中讀取。最大檔案大小：5 MB。
轉換後 JSON
{
"userProfile": {
"firstName": "Ada",
"createdAt": "2026-09-12"
}
}解析、檔案讀取、格式化與鍵名轉換都在瀏覽器本機執行。JSON 不會傳送到轉換伺服器。