UD5工具箱
常见问题解答
Dataclass（Python 3.7+）是可变的数据容器，通过 @dataclass 装饰器自动生成 __init__、__repr__、__eq__ 等方法，支持字段默认值、字段验证和 __post_init__ 钩子。它本质上是一个类，可以在上面定义业务方法。适合需要对数据进行操作、验证或转换的场景。
TypedDict（Python 3.8+）是轻量级的类型标注机制，定义的类型在运行时就是普通 dict，没有任何额外的类开销。它主要用于为字典提供精确的类型提示，与 mypy 等类型检查器配合良好。适合 API 响应处理、JSON 解析等纯数据传递场景。
选择建议：如果需要方法、验证或复杂逻辑，选 Dataclass；如果只需要类型安全的字典，选 TypedDict。
工具遍历 JSON 中所有键值对进行类型推断：整数值推断为 int，浮点值推断为 float，字符串值推断为 str，布尔值推断为 bool，null 值推断为 Optional[T]。对于数组：空数组推断为 List[Any]；同类型元素推断为 List[T]（如全为字符串则为 List[str]）；混合类型使用 Union 标注。
对于数组中的对象：工具会合并所有对象的键集合，只在部分对象中出现的字段自动标记为 Optional[T]，默认值设为 None。这确保了生成的类型定义能兼容数组中所有可能的对象结构。
生成的代码完全基于 Python 标准库，无需安装任何第三方包。Dataclass 模式依赖 from dataclasses import dataclass, field（Python 3.7+ 内置）；TypedDict 模式依赖 from typing import TypedDict（Python 3.8+ 内置）。复制代码到 .py 文件后即可直接运行。
如果启用了「使用 __future__ annotations」选项，代码顶部会添加 from __future__ import annotations 声明，这同样需要 Python 3.7+。建议在使用前确认 Python 版本满足最低要求。
当 JSON 数组中包含多个对象，且某个字段不是在所有对象中都出现时，该字段会被标记为 Optional[T]，默认值为 None。例如：[{"a":1}, {"a":2, "b":3}] 中，字段 b 只在第二个对象中出现，生成的类型为 b: Optional[int] = None。
这是最安全的推断策略，确保类型定义能兼容数组中的所有对象。如果手动移除 Optional 标注，当遇到缺少该字段的对象时会引发 KeyError 或 TypeError。建议保留 Optional 标注，并在业务逻辑中处理 None 值的情况。
如果 JSON 根节点是数组（如 [{"id":1}, {"id":2}]），工具会自动生成元素类型的类定义，并添加类型别名。Dataclass 模式生成元素 Dataclass + RootType = List[ElementDataclass] 别名，同时提供 from_dict_list 和 to_dict_list 函数支持批量转换。TypedDict 模式生成元素 TypedDict + RootType = List[ElementTypedDict] 别名。
这种处理方式使得列表数据也能获得完整的类型标注支持，开发者可以像处理单个对象一样处理整个列表。
类型推断基于提供的 JSON 样本，存在以下局限：空数组无法推断元素类型，默认使用 List[Any]，建议手动补充类型；如果样本中某字段值单一（如总是同一个字符串），会被推断为 str 而非字面量类型；无法区分 int 和 float 的语义差异（如金额字段建议手动改为 Decimal）；无法识别日期格式字符串，统一推断为 str。
建议将生成的代码作为起点，根据实际业务需求微调类型标注。例如将 ID 字段改为 str（某些系统使用字符串 ID），将金额字段改为 decimal.Decimal 等。
支持。在 JSON 输入框上方有「根类名称」输入框，可以自定义生成的主类名称。默认名称为 RootModel，修改后生成的主类会使用新名称。嵌套对象的类名仍然根据字段名自动生成（如字段名为 user_info 则类名为 UserInfo）。
生成的 Dataclass 代码与 Pydantic 模型的结构相似但不完全兼容。Pydantic 使用 BaseModel 而非 dataclass，且字段验证语法不同。但生成的类型定义和 from_dict/to_dict 逻辑可以作为编写 Pydantic 模型的参考。如果需要 Pydantic 兼容的代码，可以将 Dataclass 代码中的 @dataclass 装饰器替换为 BaseModel 继承，并调整字段定义语法。
不会。所有 JSON 解析和代码生成逻辑均在浏览器本地执行，数据不会离开用户的浏览器环境。工具不使用任何后端 API，不存储、不传输、不记录用户的 JSON 数据。这确保了敏感数据（如 API 密钥、用户信息等）的隐私安全。