JSON 转 Python Dataclass

即时从 JSON 生成 Python dataclass,支持 @dataclass、Pydantic v2 BaseModel 和 TypedDict,处理嵌套对象、数组、可选字段和自定义根类名。免费,在浏览器中运行。

  • 在浏览器中处理
  • 工具不会把输入上传到 ZeroTool 服务器
  • 免费 · 无需注册
留空时使用 Root。修改名称后,等待 300 毫秒自动生成。
模式 选择 @dataclass、Pydantic v2 或 TypedDict,切换后立即重新生成。
用含嵌套对象、数组和 null 的示例替换 JSON,并按当前设置立即生成。
清空 JSON、输出和状态,保留根名和所选模式。在工具内按 Ctrl/⌘+L 还会清空根名。
输入合法 JSON,不能带注释或末尾逗号。停止输入 300 毫秒后自动生成;JSON 无效时会清空输出并显示错误。
Python 输出
复制当前显示的完整 Python 输出。输出为空时不复制。
将当前完整输出保存为 .py 文件。文件名使用小写根名,ASCII 字母、数字和下划线以外的字符替换为下划线。输出为空时不下载。

输入 JSON 或载入示例以生成 Python。

示例、说明与常见问题 带实际输出的示例、与同类工具的差别,以及常见问题。

类型映射

  • 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、根类名称和模式与上一次记录时相同时不再记录。