这个转换器把 JSON 结构转换成 Pydantic v2 的 BaseModel 类,或标准库的 @dataclass 代码。字段名会按 Python 风格改写成 snake_case,每个嵌套对象都有自己的类。
定义 FastAPI 的请求和响应 schema、给用 requests 或 httpx 获取的数据加上类型提示,或者整理那些靠字符串 key 在 dict 里层层翻找的 ETL 和爬虫脚本时,都可以用它。
类型名 中输入顶层模型的名称(例如 Forecast)。风格 中,需要校验和别名时选 Pydantic (v2),想要无依赖的模型时选 dataclass。models.py 之类的模块中。风格和类型名会保存在 URL 中。{
"city": "Seoul",
"updatedAt": "2024-05-01T09:00:00+09:00",
"current": { "temp": 18.5, "humidity": 40 },
"hourly": [
{ "hour": 10, "temp": 19, "rain_mm": 0 },
{ "hour": 11, "temp": 20.5, "rain_mm": 0.4, "alert": "shower" }
]
}from __future__ import annotations
from pydantic import BaseModel, ConfigDict, Field
class Hourly(BaseModel):
hour: int
temp: float
rain_mm: float
alert: str | None = None
class Current(BaseModel):
temp: float
humidity: int
class Forecast(BaseModel):
model_config = ConfigDict(populate_by_name=True)
city: str
updated_at: str = Field(alias="updatedAt")
current: Current
hourly: list[Hourly]
updatedAt 变成 updated_at 字段,并通过 Field(alias="updatedAt") 与原始 key 对应。在 hourly 中,temp 混有整数和小数,所以变成 float;只在第二项中出现的 alert 是 str | None = None。类按子类在前的顺序输出。
Field(alias=...),model_config = ConfigDict(populate_by_name=True) 让你也能用 Python 名称赋值。= None 字段之前,以避免 TypeError: non-default argument follows default argument;原始 key 以 # JSON: "updatedAt" 注释的形式保留。str、int、float、bool、list[...],混合类型的值为 Any。null 的字段变成 X | None = None。class、from、type 等 Python 关键字会加上后缀下划线(class_)。from __future__ import annotations,类之间可以互相引用而不受顺序限制。Root = list[RootItem] 这样的别名。根据与前端约定好的 JSON 生成 BaseModel,用在 response_model= 中或作为接口参数,OpenAPI 文档也会自动随之更新。
把调用包在 Forecast.model_validate(resp.json()) 中,当服务商改变某个字段的类型时,ValidationError 会准确指出出问题的字段路径。
把 data["current"]["temp"] 改成 forecast.current.temp,就能获得编辑器补全,mypy 或 pyright 也能检查代码。
@dataclass 不会把嵌套的 dict 转换成对象。执行 Forecast(**data) 后,current 仍然是 dict;如果需要嵌套转换,请使用 Pydantic 或 dacite 之类的辅助库。updatedAt)序列化回去,请调用 model_dump(by_alias=True) 或 model_dump_json(by_alias=True)。str | None 语法,所以 Pydantic 模型要求 Python 3.10 或更高版本。str。在 Pydantic 中,只要把注解改成 datetime 就能解析 ISO 8601 值。class Config、parse_obj)。populate_by_name=True 有什么用?默认情况下,带别名的字段只接受别名(updatedAt)作为输入。开启这个设置后,也可以写 Forecast(updated_at=...),在测试中很方便。
Optional[str]。str | None 和 Optional[str] 含义相同。如果需要兼容 Python 3.9,请从 typing 导入 Optional 并替换注解。
支持的风格是 Pydantic v2 和 dataclass。如果需要 TypedDict 或 @attrs.define 类,dataclass 的字段列表可以直接搬过去。
不会。Python 名称与原始 key 相同时,不会输出 Field(alias=...) 或 ConfigDict,得到的是 rain_mm: float 这样简单的行。