JSON 转 Python Dataclass
即时从 JSON 生成 Python dataclass,支持 @dataclass、Pydantic v2 BaseModel 和 TypedDict,处理嵌套对象、数组、可选字段和自定义根类名。免费,在浏览器中运行。
- 在浏览器中处理
- 工具不会把输入上传到 ZeroTool 服务器
- 免费 · 无需注册
用微信扫描以下二维码即可分享
示例、说明与常见问题 带实际输出的示例、与同类工具的差别,以及常见问题。
类型映射
null→Optional[Any] = None- 字符串 →
str - 整数 →
int - 浮点数 →
float - 布尔值 →
bool - 数组 →
List[T] - 混合数组 →
List[Union[T1, T2]] - 嵌套对象 → 独立类
示例
给定如下 JSON:
{"user": {"first_name": "Alice", "age": 30}, "tags": ["admin"], "note": null}
@dataclass 模式下生成:
from dataclasses import dataclass
from typing import Any, List, Optional
@dataclass
class User:
first_name: str
age: int
@dataclass
class Root:
user: User
tags: List[str]
note: Optional[Any] = None
示例:嵌套对象与缺失的键
输入:
{"id": 7, "title": "Release notes", "author": {"name": "Alice", "email": null}, "tags": ["python", "json"], "score": 4.5, "comments": [{"user": "bob", "text": "nice"}, {"user": "carol"}]}
@dataclass 模式的输出:
from dataclasses import dataclass
from typing import Any, List, Optional
@dataclass
class Author:
name: str
email: Optional[Any] = None
@dataclass
class CommentsItem:
user: str
text: Optional[str] = None
@dataclass
class Root:
id: int
title: str
author: Author
tags: List[str]
score: float
comments: List[CommentsItem]
类的顺序保证每个类在被使用前已定义。第二条评论缺少 text,所以它是 Optional[str] = None。
dataclass、Pydantic 还是 TypedDict
三种模式描述的结构相同,运行时行为不同(Python 3.12、Pydantic 2.13 实测):
root = Root(**json.loads(raw))
type(root.author) # <class 'dict'>, not Author
root = Root.model_validate(json.loads(raw)) # Pydantic mode
root.comments[1] # CommentsItem(user='carol', text=None)
- @dataclass 不校验也不转换。
Root(**data)里的嵌套对象仍是普通 dict,类型不对也照样接受。数据可信时再用,或者自己转换嵌套字段。 - Pydantic 会校验类型并构造嵌套模型,适合处理你控制不了的 API 响应。
model_validate_json(raw)一步完成解析和校验。 - TypedDict 只给类型检查器描述 dict 的结构,运行时什么都不检查。所有键默认都是必需的,工具把只在部分元素里出现的键写成
NotRequired[...](PEP 655,Python 3.11+ 在typing中,更早版本用typing_extensions)。Optional[...]只表示值可以是None,键仍然必需。
示例:带缺失键的 TypedDict
两个商品:note 在第一个里为 null、在第二个里缺失,discount 只出现在第二个里(根类名 Product,TypedDict 模式):
[{"id": 1, "sku": "PEN-01", "price": 2, "note": null}, {"id": 2, "sku": "INK-07", "price": 1.5, "discount": 0.1}]
from typing import Any, NotRequired, Optional, TypedDict
class Product(TypedDict):
id: int
sku: str
price: float
note: NotRequired[Optional[Any]]
discount: NotRequired[float]
price 一个是 2、一个是 1.5,PEP 484 允许 int 当作 float 使用,所以字段是 float。运行时 Product.required_keys 为 {'id', 'sku', 'price'},optional_keys 为 {'note', 'discount'}(Python 3.12 实测)。
高德地理编码响应:同一个字段既是字符串又是数组
高德 Web 服务 API 的地理编码接口按 JSON 返回结果。返回参数说明写明 status 的值为 0 或 1(1 表示成功),并提示:「部分返回值当返回值存在时,将以字符串类型返回;当返回值不存在时,则以数组类型返回」(地理/逆地理编码)。下面按文档里的字段写了两条结果:第一条匹配到门牌号,第二条只匹配到区县,所以 street 和 number 是空数组。数值按上面那条说明都写成字符串,坐标为示意值(根类名 GeocodeResponse,Pydantic v2 模式):
{"status":"1","info":"OK","count":"2","geocodes":[{"formatted_address":"北京市朝阳区阜通东大街6号","province":"北京市","city":"北京市","district":"朝阳区","street":"阜通东大街","number":"6号","adcode":"110105","location":"116.483038,39.990633","level":"门牌号"},{"formatted_address":"浙江省杭州市西湖区","province":"浙江省","city":"杭州市","district":"西湖区","street":[],"number":[],"adcode":"330106","location":"120.130396,30.259242","level":"区县"}]}
from pydantic import BaseModel
from typing import Any, List, Union
class GeocodesItem(BaseModel):
formatted_address: str
province: str
city: str
district: str
street: Union[str, List[Any]]
number: Union[str, List[Any]]
adcode: str
location: str
level: str
class GeocodeResponse(BaseModel):
status: str
info: str
count: str
geocodes: List[GeocodesItem]
street和number在两条结果里分别是字符串和空数组,所以生成Union[str, List[Any]]。用这段代码的GeocodeResponse.model_validate()读入上面的 JSON,两条都能通过(工具测试用 Pydantic 实跑)。如果只拿第一条门牌级结果生成,字段会是str,之后遇到区县级结果时 Pydantic 会报校验错误。所以生成前要把不同匹配级别的结果放进同一个样本。status、count、adcode是字符串,生成的是str。判断成功要写resp.status == "1",写成== 1永远不成立。location是「经度,纬度」一个字符串,工具不会拆成两个数字,需要时自己split(",")。
限制
null会变成Optional[Any],请把Any换成真实类型。- 不能原样作字段名的键(
class等关键字、user-id和2fa这类非标识符、NFKC 会改变的键(如全角的name)、以__开头的键、与输出导入或用作类型的名字(str、Field)或生成的类同名的键;Pydantic 模式下还有以_或model_开头的键,如 MongoDB 的_id,以及json这类BaseModel属性名)会换成合法的字段名:@dataclass 模式在行尾用注释写出原键(用Root(**data)构造前要自己对应一下),Pydantic 模式加Field(alias=...),model_validate()照样按原键读取(model_dump()输出的是字段名,要还原原键请用model_dump(by_alias=True)),TypedDict 模式改用函数式写法TypedDict("Name", {...}),原键全部保留。工具的测试在 Python 3.12 和 3.14 下运行这三种输出并读回样例。 - 日期保持为
str;把类型改成datetime后,Pydantic 会解析 ISO 8601 字符串。 - 根节点是基础类型数组时不生成类。根数组里对象和其他值混在一起时,对象生成根类,整个数组在最后写成别名
RootArray = List[Union[...]](None表示 null 元素),Pydantic 里可以用TypeAdapter(RootArray)校验整个数组。 - 写成
10.0的数字到工具里已经是整数10(JavaScript 的JSON.parse不保留末尾的 0),所以生成price: int。之后 Pydantic 遇到10.5会报Input should be a valid integer, got a number with a fractional part。金额可能带小数时,请改成float,或者按分存成整数。 - 根类名称是合法的 Python 标识符时原样使用,否则转换:
order-item→OrderItem,数字开头的2fa→_2fa,关键字class→class_,开头的__改成一个_(嵌套类名以根类名开头,Python 会在类体里改写以两个下划线开头的名字),没有可用字符时用Root。 - 中文键名在类名里保留全部字符。类名不会和 JSON 里的键名相同(Pydantic 里带默认值的字段会遮住同名的类),所以会加上父级类名作前缀,见下例。
例如收货地址和发票地址(根类名 Order,@dataclass 模式):
{"收货地址": {"省": "浙江省", "市": "杭州市"}, "发票地址": {"抬头": "杭州示例科技有限公司"}}
from dataclasses import dataclass
@dataclass
class Order收货地址:
省: str
市: str
@dataclass
class Order发票地址:
抬头: str
@dataclass
class Order:
收货地址: Order收货地址
发票地址: Order发票地址
Python 3 允许非 ASCII 标识符,中文键名可以直接作字段名,这段代码能运行;两个地址结构不同,各自生成一个类,抬头 字段也会保留。想要英文类名时,可以把 Order收货地址、Order发票地址 改成 ShippingAddress、InvoiceInfo。
空数组与样本覆盖
空数组没有提供元素类型的依据,因此 {"tags": []} 会生成 tags: List[Any]。在同一输入数组中加入另一个含 {"tags": ["admin"]} 的对象,合并后的字段就变为 List[str]。生成器依据你提供的样本推断类型,无法推断所有样本中都未出现的字段。复制类定义前,请加入具有缺失键和 null 值的代表性对象。
FAQ
这个工具生成什么?
从 JSON 生成 Python 类定义,可选标准 @dataclass(stdlib)、Pydantic v2 BaseModel 或 TypedDict。嵌套对象会成为单独命名的类。
支持哪些输出模式?
三种模式:@dataclass(Python 标准库,默认)、Pydantic v2 BaseModel、TypedDict(Python 3.8+;用到 NotRequired 时需 3.11+ 或 typing_extensions)。
JSON 类型如何映射到 Python 类型?
string→str、整数→int、其他数字→float、boolean→bool、null→Optional[Any]、array→List[T](元素类型不一时为 List[Union[...]],空数组为 List[Any])、嵌套对象→独立类。写成 10.0 的数字会被读成整数 10,因此是 int。
字段什么时候会写成 Optional?
@dataclass 和 Pydantic 模式下,字段值在样本里为 null,或合并数组时在部分对象中缺失,就写成 Optional[T] = None,并排到必填字段之后。TypedDict 保留 JSON 里的键顺序:部分对象缺少的键写成 NotRequired[T],值为 null 的写成 Optional[T]。
嵌套对象如何处理?
每个嵌套对象生成一个类,类名取键名的 PascalCase;数组里的对象加后缀 Item(comments → CommentsItem)。类写在使用它的类之前。同一个键下字段相同的对象共用一个类;结构不同时加父级类名作前缀(b.meta → BMeta),再不行就加编号。非 ASCII 键名在类名里保留全部字符(PEP 3131),除根类名外,类名也不会与 JSON 键名、Python 关键字或输出里导入的名字相同。
我的数据会发送到服务器吗?
不会。JSON 和根类名称只在当前浏览器标签页里处理,不会发送出去,工具也不把它们存进浏览器存储。页面只在你改完输入并移开焦点、点击示例或切换模式时记录一条统计事件,内容只有工具名和动作(generate);JSON、根类名称和模式与上一次记录时相同时不再记录。