`hutool.json`¶

Module Contents¶

Classes¶

JSONUtil

JSON工具类，提供 JSON 的解析、序列化、校验、路径操作等功能。

Functions¶

_element_to_dict

递归将 XML Element 转为字典。

API¶

hutool.json._element_to_dict(element: xml.etree.ElementTree.Element)¶

递归将 XML Element 转为字典。

参数:: element – XML 元素
返回:: 转换后的字典或字符串

class hutool.json.JSONUtil¶

JSON工具类，提供 JSON 的解析、序列化、校验、路径操作等功能。

static create_obj() → dict¶

创建空JSON对象。

返回:: 空字典

static create_array() → list¶

创建空JSON数组。

返回:: 空列表

static parse_obj(json_str: str) → dict¶

解析JSON字符串为字典。

参数:: json_str – JSON字符串
返回:: 字典
抛出:: ValueError – JSON字符串不是对象类型时

static parse_array(json_str: str) → list¶

解析JSON字符串为列表。

参数:: json_str – JSON字符串
返回:: 列表
抛出:: ValueError – JSON字符串不是数组类型时

static parse(json_str: str)¶

解析JSON字符串，自动返回对应Python类型。

参数:: json_str – JSON字符串
返回:: 解析后的Python对象

static to_json_str(obj: Any, indent: Optional[int] = None) → str¶

对象转JSON字符串。

参数:

obj – 待序列化的对象
indent – 缩进空格数，None表示不缩进

返回:

JSON字符串

static to_json_pretty_str(obj: Any) → str¶

对象转格式化JSON字符串（缩进2空格）。

参数:: obj – 待序列化的对象
返回:: 格式化的JSON字符串

static to_bean(json_str: str, bean_class: Type)¶

JSON字符串转对象。

将JSON解析为字典后，通过 bean_class(**dict) 构造实例。如果 bean_class 提供了 from_dict 类方法，则优先调用。

参数:

json_str – JSON字符串
bean_class – 目标类型

返回:

目标类型的实例

static to_bean_list(json_str: str, element_class: Type) → list¶

JSON字符串转对象列表。

参数:

json_str – JSON字符串（数组格式）
element_class – 元素目标类型

返回:

对象列表

抛出:

ValueError – JSON字符串不是数组类型时

static from_bean(obj: Any) → str¶

对象转JSON字符串。

如果对象具有 to_dict 方法则先调用，否则直接序列化。

参数:: obj – 待序列化的对象
返回:: JSON字符串

static read_json(path: str, charset: str = 'utf-8')¶

读取JSON文件并解析。

参数:

path – 文件路径
charset – 文件编码

返回:

解析后的Python对象

static read_json_object(path: str, charset: str = 'utf-8') → dict¶

读取JSON文件为字典。

参数:

path – 文件路径
charset – 文件编码

返回:

字典

抛出:

ValueError – JSON文件内容不是对象类型时

static read_json_array(path: str, charset: str = 'utf-8') → list¶

读取JSON文件为列表。

参数:

path – 文件路径
charset – 文件编码

返回:

列表

抛出:

ValueError – JSON文件内容不是数组类型时

static write_json(path: str, obj: Any, charset: str = 'utf-8', indent: Optional[int] = None) → None¶

写入JSON文件。

参数:

path – 文件路径
obj – 待写入对象
charset – 文件编码
indent – 缩进空格数，None表示不缩进

static is_json(str_val: str) → bool¶

是否为有效JSON。

参数:: str_val – 待检查的字符串
返回:: 是否为有效JSON

static is_json_obj(str_val: str) → bool¶

是否为JSON对象。

参数:: str_val – 待检查的字符串
返回:: 是否为JSON对象

static is_json_array(str_val: str) → bool¶

是否为JSON数组。

参数:: str_val – 待检查的字符串
返回:: 是否为JSON数组

static format_json(json_str: str, indent: int = 2) → str¶

格式化JSON字符串。

参数:

json_str – JSON字符串
indent – 缩进空格数

返回:

格式化后的JSON字符串

static compress(json_str: str) → str¶

压缩JSON（去除所有空白）。

参数:: json_str – JSON字符串
返回:: 压缩后的JSON字符串

static _parse_path_keys(path: str) → List[Union[str, int]]¶

将路径字符串解析为键列表。

例如 'a.b[0].c' 解析为 ['a', 'b', 0, 'c']

参数:: path – 路径字符串
返回:: 键列表

static get_by_path(json_data: Any, path: str) → Any¶

按路径获取值

参数:

json_data – JSON数据（字典或列表）
path – 路径，如 ‘a.b.c’ 或 ‘a[0].b’

返回:

对应路径的值，路径不存在时返回 None

static put_by_path(json_data: Any, path: str, value: Any) → None¶

按路径设置值

参数:

json_data – JSON数据（字典或列表）
path – 路径，如 ‘a.b.c’ 或 ‘a[0].b’
value – 要设置的值

static map_dict_keys(func: Callable, obj: Any) → Any¶

递归映射 JSON 对象（字典）的所有键名。

对嵌套的字典和列表递归处理。

Examples:

map_dict_keys(str.upper, {"a": 1, "b": {"c": 2}})
-> {"A": 1, "B": {"C": 2}}

参数:

func – 键名映射函数
obj – JSON 对象（字典）或列表

返回:

映射后的新对象

static map_list_keys(func: Callable, lst: list) → list¶

递归映射列表中所有字典的键名。

参数:

func – 键名映射函数
lst – 列表

返回:

映射后的新列表

static convert_keys_to_camel(obj: Dict) → Dict¶

将 JSON 对象的所有键名从 snake_case 转为 camelCase。

Examples:

convert_keys_to_camel({"user_name": "Tom", "home_addr": {"zip_code": "100000"}})
-> {"userName": "Tom", "homeAddr": {"zipCode": "100000"}}

参数:: obj – 字典对象
返回:: 键名转换后的新字典

static convert_keys_to_snake(obj: Dict) → Dict¶

将 JSON 对象的所有键名从 camelCase 转为 snake_case。

Examples:

convert_keys_to_snake({"userName": "Tom", "homeAddr": {"zipCode": "100000"}})
-> {"user_name": "Tom", "home_addr": {"zip_code": "100000"}}

参数:: obj – 字典对象
返回:: 键名转换后的新字典

static quote(s: str) → str¶

用双引号包裹字符串并进行JSON转义

参数:: s – 原始字符串
返回:: JSON引号包裹的字符串

static escape(s: str) → str¶

JSON字符串转义

将特殊字符转为JSON转义序列。

参数:: s – 原始字符串
返回:: 转义后的字符串

static is_null(json_str: str) → bool¶

判断JSON字符串是否为null

参数:: json_str – JSON字符串
返回:: 是否为null

static xml_to_json(xml_str: str) → dict¶

XML字符串转JSON字典

简单的XML到字典转换。

参数:: xml_str – XML字符串
返回:: 转换后的字典

static to_json_bytes(obj: Any, charset: str = 'utf-8') → bytes¶

对象转JSON字节数组

参数:

obj – 待序列化对象
charset – 字符集

返回:

JSON字节数组

static wrap(obj: Any) → str¶

将对象包装为JSON字符串（to_json_str别名）

参数:: obj – 对象
返回:: JSON字符串

static get_str(json_data: dict, key: str, default: str = '') → str¶

从JSON对象获取字符串值

参数:

json_data – JSON字典
key – 键名
default – 默认值

返回:

字符串值

static get_int(json_data: dict, key: str, default: int = 0) → int¶

从JSON对象获取整数值

参数:

json_data – JSON字典
key – 键名
default – 默认值

返回:

整数值

static get_float(json_data: dict, key: str, default: float = 0.0) → float¶

从JSON对象获取浮点值

参数:

json_data – JSON字典
key – 键名
default – 默认值

返回:

浮点值

static get_bool(json_data: dict, key: str, default: bool = False) → bool¶

从JSON对象获取布尔值

参数:

json_data – JSON字典
key – 键名
default – 默认值

返回:

布尔值

static get_list(json_data: dict, key: str, default: Optional[list] = None) → list¶

从JSON对象获取列表值

参数:

json_data – JSON字典
key – 键名
default – 默认值

返回:

列表值

static parse_from_xml(xml_str: str) → dict¶

将 XML 字符串解析为字典。

参数:: xml_str – XML 字符串
返回:: 解析后的字典

static get_ordered_json(s: str) → str¶

获取排序键名后的 JSON 字符串（用于比较）。

参数:: s – JSON 字符串
返回:: 排序键名后的 JSON 字符串

static json_equal(s1: str, s2: str) → bool¶

比较两个 JSON 是否语义相等（忽略键顺序）。

参数:

s1 – JSON 字符串 1
s2 – JSON 字符串 2

返回:

是否相等

static json_keys_equal(s1: str, s2: str) → bool¶

比较两个 JSON 的键集合是否相等（仅对象类型）。

参数:

s1 – JSON 字符串 1
s2 – JSON 字符串 2

返回:

键集合是否相等

hutool.json¶

Module Contents¶

Classes¶

Functions¶

API¶

`hutool.json`¶