UD5工具箱
核心术语一览
| 术语 | 定义 | 与工具的关系 |
|---|---|---|
| Dataclass | Python 3.7 引入的装饰器语法，用于自动生成 __init__、__repr__、__eq__ 等方法的类。通过 @dataclass 装饰器标记，开发者只需定义字段和类型，无需手写样板代码。支持字段默认值、类型验证和方法定义。 | 工具的一种生成模式，输出带 @dataclass 装饰器的类定义 |
| TypedDict | Python 3.8 引入的类型标注机制，用于为字典类型定义精确的键值类型。运行时 TypedDict 就是普通 dict，没有额外开销。与 mypy 等类型检查器配合良好，适合 API 响应的类型标注。 | 工具的另一种生成模式，输出继承 TypedDict 的类定义 |
| Optional | typing 模块中的类型标注，表示一个值可以是指定类型或 None。Optional[T] 等价于 Union[T, None]，用于标注可能为空的字段。在 Python 3.10+ 中可以用 T | None 语法替代。 | 工具在检测到 null 值时自动使用 Optional 包装字段类型 |
| Union | typing 模块中的联合类型标注，表示一个值可以是多种类型之一。例如 Union[int, str] 表示字段值可以是整数或字符串。常用于处理混合类型数据。 | 当数组包含不同类型的元素时，工具生成 Union 类型标注 |
| from_dict | 类方法（classmethod），接收一个字典作为参数，递归地将字典及其嵌套结构转换为类实例。是实现 JSON 反序列化的关键方法，对应 JSON.parse 的 Python 等价操作。 | Dataclass 模式自动生成此方法，支持嵌套对象的递归转换 |
| to_dict | 实例方法，将对象及其所有嵌套结构转换为普通字典。是实现 JSON 序列化的关键方法，对应 JSON.stringify 的 Python 等价操作。转换后的字典可以直接传入 json.dumps()。 | Dataclass 模式自动生成此方法，递归处理嵌套对象 |
| 类型推断 | 编译器或工具根据上下文信息自动确定变量或表达式的类型，无需开发者显式标注。在本工具中，类型推断基于 JSON 字段的实际值：整数推断为 int，字符串推断为 str，布尔值推断为 bool 等。 | 工具的核心功能，自动分析 JSON 结构并推断每个字段的 Python 类型 |
| __future__.annotations | Python 3.7 引入的模块级声明，将所有类型标注延迟为字符串求值（PEP 563）。解决了前向引用问题，允许在类定义中引用尚未定义的类型。Python 3.10+ 默认启用此行为。 | 可选配置项，启用后在生成的代码顶部添加该声明 |
| 字段默认值 | Dataclass 中字段的默认值，在实例化时如果未提供该字段则使用默认值。对于 Optional 字段，默认值通常设为 None。非 Optional 字段如果需要默认值，必须放在所有必填字段之后。 | 工具自动为 Optional 字段设置 None 默认值，确保实例化时不会报错 |
| 类型别名 | 使用赋值语句为复杂类型创建一个简短的名称。例如 RootType = List[UserData] 将列表类型命名为 RootType，使代码更易读。在根节点为数组的场景中尤为有用。 | 当 JSON 根节点是数组时，工具生成 RootType 类型别名 |
补充说明
Dataclass vs TypedDict 选择指南
如果需要在数据对象上定义方法、进行字段验证或使用 __post_init__ 钩子，选择 Dataclass；如果只需要轻量级的类型标注、运行时就是普通 dict，选择 TypedDict。对于纯数据传递和 API 响应处理，TypedDict 更为高效。
Python 版本兼容性
Dataclass 模式需要 Python 3.7+，TypedDict 模式需要 Python 3.8+。使用 __future__.annotations 选项需要 Python 3.7+。生成的代码不依赖任何第三方库，仅使用 Python 标准库中的 dataclasses 和 typing 模块。