JSON转Python Dataclass生成器

从JSON生成Python dataclass定义

加载示例
根类名称:

JSON输入

Python输出

本地运行 · 粘贴密钥安全无忧
Python dataclass将显示在这里…

什么是JSON转Python Dataclass转换?

JSON转Python dataclass转换是指将原始JSON对象转化为一组带有精确类型注解的Python dataclass定义。Python的dataclasses模块由PEP 557(Python 3.7)引入,能够根据带注解的类字段自动生成__init__、__repr__和__eq__方法。在处理JSON API、配置文件或消息队列时,dataclass可为数据提供类型化结构,编辑器和mypy等类型检查器能在开发阶段进行验证。

Python的json.loads()返回普通的dict和list,虽然可以使用,但缺乏类型信息:键名拼写错误会返回None而非抛出异常,编辑器也无法自动补全字段名。Dataclass通过将每个JSON键映射为具名的带类型字段来解决这一问题。嵌套JSON对象会生成独立的dataclass定义,数组变为List[T]注解,null值变为Optional[T]并默认值为None。

手动编写这些定义是机械性工作:读取JSON、根据值推断每个字段的类型、将camelCase或snake_case键转换为Python命名规范,并处理可空字段和混合类型数组等边界情况。转换器能在毫秒内完成所有这些工作。粘贴JSON,即可获得正确的dataclass代码。

为什么使用JSON转Python转换器?

手动将JSON结构转换为Python类定义,需要从示例数据中猜测类型、将必填字段排在可选字段之前,并在API变更时更新所有内容。转换器消除了这些繁琐操作。

即时生成dataclass
粘贴JSON,不到一秒即可获得带类型的Python dataclass定义。嵌套对象、列表和可选字段均自动处理。
🔒
隐私优先处理
转换完全在浏览器中通过JavaScript运行,JSON数据不会离开您的设备。API密钥、令牌和用户记录始终保持私密。
📝
正确的类型注解
每个生成的字段都包含从JSON值推断的Python类型注解:str、int、float、bool、List[T],以及null对应的Optional[T]。
📦
无需安装或注册
打开页面,粘贴JSON即可使用。无需Python环境,无需安装pip包,无需创建账号。

JSON转Python使用场景

REST API客户端开发
从API响应示例生成dataclass。粘贴第三方REST端点返回的JSON,即可获得可直接用于requests或httpx的类型安全Python类。
FastAPI请求/响应模型
从JSON负载结构出发生成dataclass定义,再将其转换为Pydantic模型,为FastAPI路由处理器提供自动验证功能。
数据管道Schema定义
为ETL管道定义带类型的记录结构。粘贴来自Kafka、RabbitMQ或SQS的示例JSON消息,生成描述预期数据结构的dataclass。
配置文件解析
将JSON配置文件转换为带类型的Python类。使用json.load()加载配置后,构建dataclass实例以获得编辑器自动补全和类型检查支持。
测试夹具生成
从示例JSON数据创建带类型的测试夹具。QA工程师可粘贴API响应快照,生成可用于pytest测试套件的dataclass定义。
学习Python类型注解
学员可粘贴任意JSON结构,观察Python如何用类型提示表示它。生成的代码展示了List、Optional、嵌套类和默认值的实际用法。

JSON与Python类型映射

每种JSON值类型对应一个特定的Python类型注解。下表展示转换器如何翻译每种JSON类型,包括typing模块语法(Python 3.7+)和Python 3.10起可用的内置语法。

JSON类型示例Python(typing)Python 3.10+
string"hello"strstr
number (integer)42intint
number (float)3.14floatfloat
booleantrueboolbool
nullnullOptional[str]str | None
object{"k": "v"}@dataclass classnested model
array of strings["a", "b"]List[str]list[str]
array of objects[{"id": 1}]List[Item]list[Item]
mixed array[1, "a"]List[Any]list[Any]

Dataclass装饰器参考

@dataclass装饰器接受多个参数,用于改变生成类的行为。本参考涵盖处理JSON派生数据时最常用的选项。

装饰器 / 字段行为适用场景
@dataclassGenerates __init__, __repr__, __eq__ from field annotationsStandard dataclasses
@dataclass(frozen=True)Makes instances immutable (hashable, no attribute reassignment)Config objects, dict keys
@dataclass(slots=True)Uses __slots__ for lower memory and faster attribute accessPython 3.10+, large datasets
@dataclass(kw_only=True)All fields require keyword arguments in __init__Python 3.10+, many fields
field(default_factory=list)Sets a mutable default without sharing state between instancesList/dict/set defaults

dataclass、Pydantic与TypedDict对比

Python有三种常用方式来定义JSON的带类型结构,各适用于不同场景。Dataclass是零依赖的标准库选项,Pydantic提供运行时验证,TypedDict在不创建新类的情况下为普通dict添加类型注解。

@dataclass
标准库(Python 3.7+),自动生成__init__、__repr__和__eq__。无运行时验证,可与mypy和dataclasses-json配合进行序列化。适用于由您控制输入的内部数据结构。
BaseModel (Pydantic)
第三方库,在运行时验证类型和约束,可通过model_validate_json()直接解析JSON。是FastAPI、配置管理以及任何接收不受信任输入代码的标准选择。
TypedDict
标准库(Python 3.8+),为普通dict添加类型提示,不生成__init__或其他方法,值仍通过dict方式访问。适用于需要类型检查但希望保留dict接口的场景,例如遗留代码库。

代码示例

以下示例展示如何在Python中使用生成的dataclass,如何通过JavaScript以编程方式生成,以及如何使用Pydantic和命令行工具等替代方案。

Python (dataclasses)
from dataclasses import dataclass
from typing import List, Optional
import json

@dataclass
class Address:
    street: str
    city: str
    zip: str

@dataclass
class User:
    id: int
    name: str
    email: str
    active: bool
    score: float
    address: Address
    tags: List[str]
    metadata: Optional[str] = None

raw = '{"id":1,"name":"Alice","email":"alice@example.com","active":true,"score":98.5,"address":{"street":"123 Main St","city":"Springfield","zip":"12345"},"tags":["admin","user"],"metadata":null}'
data = json.loads(raw)

# Reconstruct nested objects manually
addr = Address(**data["address"])
user = User(**{**data, "address": addr})
print(user.name)     # -> Alice
print(user.address)  # -> Address(street='123 Main St', city='Springfield', zip='12345')
JavaScript (generate Python from JSON)
// Minimal JSON-to-Python-dataclass generator in JS
function jsonToPython(obj, name = "Root") {
  const classes = [];
  function infer(val, fieldName) {
    if (val === null) return "Optional[str]";
    if (typeof val === "string") return "str";
    if (typeof val === "number") return Number.isInteger(val) ? "int" : "float";
    if (typeof val === "boolean") return "bool";
    if (Array.isArray(val)) {
      const first = val.find(v => v !== null);
      return first ? `List[${infer(first, fieldName + "Item")}]` : "List[Any]";
    }
    if (typeof val === "object") {
      const clsName = fieldName.charAt(0).toUpperCase() + fieldName.slice(1);
      build(val, clsName);
      return clsName;
    }
    return "Any";
  }
  function build(obj, cls) {
    const fields = Object.entries(obj).map(([k, v]) => `    ${k}: ${infer(v, k)}`);
    classes.push(`@dataclass\nclass ${cls}:\n${fields.join("\n")}`);
  }
  build(obj, name);
  return classes.join("\n\n");
}

const data = { id: 1, name: "Alice", scores: [98, 85] };
console.log(jsonToPython(data, "User"));
// @dataclass
// class User:
//     id: int
//     name: str
//     scores: List[int]
Python (Pydantic BaseModel alternative)
from pydantic import BaseModel
from typing import List, Optional

class Address(BaseModel):
    street: str
    city: str
    zip: str

class User(BaseModel):
    id: int
    name: str
    email: str
    active: bool
    score: float
    address: Address
    tags: List[str]
    metadata: Optional[str] = None

# Pydantic parses and validates JSON in one step
raw = '{"id":1,"name":"Alice","email":"alice@example.com","active":true,"score":98.5,"address":{"street":"123 Main St","city":"Springfield","zip":"12345"},"tags":["admin","user"],"metadata":null}'
user = User.model_validate_json(raw)
print(user.name)              # -> Alice
print(user.model_dump_json()) # -> re-serializes to JSON
CLI (datamodel-code-generator)
# Install the generator
pip install datamodel-code-generator

# Generate dataclasses from a JSON file
datamodel-codegen --input data.json --output models.py --output-model-type dataclasses.dataclass

# Generate Pydantic models instead
datamodel-codegen --input data.json --output models.py

# From a JSON string via stdin
echo '{"id": 1, "name": "Alice", "tags": ["admin"]}' | \
  datamodel-codegen --output-model-type dataclasses.dataclass
# Output:
# @dataclass
# class Model:
#     id: int
#     name: str
#     tags: List[str]

常见问题

Python dataclass与普通类有什么区别?
Dataclass使用@dataclass装饰器,根据字段注解自动生成__init__、__repr__和__eq__方法。普通类需要手动编写这些方法。当类主要用于存储数据时(JSON派生结构的典型场景),dataclass能显著减少样板代码。
能否直接将dataclass用于JSON序列化?
标准库的json模块默认无法序列化dataclass实例。可使用dataclasses.asdict()将dataclass转换为dict,再传给json.dumps()。如需更多控制,dataclasses-json库提供.to_json()和.from_json()方法,Pydantic模型则原生支持序列化。
转换器如何处理嵌套JSON对象?
每个嵌套对象都会生成独立的@dataclass定义。若JSON中名为"address"的字段包含"street"和"city",转换器会创建一个Address dataclass,并将父类中对应字段注解为address: Address。深度嵌套结构会按依赖顺序生成多个dataclass定义。
JSON字段为null时如何处理?
null字段注解为Optional[str](若能从上下文推断类型则使用相应类型),默认值为None。带默认值的字段必须位于必填字段之后,因此转换器将可选字段放在类定义的末尾。
dataclass与Pydantic模型处理JSON有何区别?
Dataclass属于标准库,不在运行时验证数据。Pydantic模型在运行时验证类型、执行约束,并可直接解析原始JSON字符串。若从外部来源接收JSON且需要拒绝格式错误的数据,Pydantic更为合适。对于信任输入的内部数据传递,dataclass更轻量且无外部依赖。
如何在Python dataclass中处理camelCase JSON键?
Python规范使用snake_case命名变量。转换器将"firstName"这样的camelCase键转换为first_name这样的snake_case字段。若需从JSON反序列化回来,可使用dataclasses-json库配合映射两种命名规范的配置,或编写自定义__post_init__方法。
此转换器支持Python 3.10+语法(如list[str]代替List[str])吗?
转换器生成typing模块导入(List、Optional),以保持与Python 3.7至3.12的最大兼容性。若项目目标为Python 3.10或更高版本,可安全地将List[str]替换为list[str],将Optional[str]替换为str | None。上方类型映射表展示了两种写法。