Class JsonFlattener

java.lang.Object
cloud.opencode.base.json.util.JsonFlattener
public final class JsonFlattener extends Object
JSON Flattener - Converts nested JSON to flat dot-notation key-value maps and back. JSON 扁平化工具 - 将嵌套 JSON 转换为扁平的点分隔键值映射，并支持反向操作。

This utility flattens a nested JsonNode tree into a single-level map where keys represent the full path to each leaf value. It also supports unflattening a flat map back into a nested tree structure.

此工具将嵌套的 JsonNode 树扁平化为单层映射，其中键表示每个叶值的完整路径。 同时支持将扁平映射反向还原为嵌套树结构。

Features | 主要功能:

  • Flatten nested JSON objects and arrays to dot-notation keys - 将嵌套 JSON 对象和数组扁平化为点分隔键
  • Configurable separator and array notation style - 可配置分隔符和数组表示法风格
  • Unflatten flat maps back to nested JSON trees - 将扁平映射反向还原为嵌套 JSON 树
  • Preserves empty objects, empty arrays, and null values - 保留空对象、空数组和 null 值
  • Depth guard against stack overflow - 深度保护防止栈溢出

Usage Examples | 使用示例:

// Flatten with default settings
JsonNode obj = JsonNode.object()
    .put("a", JsonNode.object().put("b", 1))
    .put("c", JsonNode.array().add(2).add(3));
Map<String, JsonNode> flat = JsonFlattener.flatten(obj);
// {"a.b": NumberNode(1), "c[0]": NumberNode(2), "c[1]": NumberNode(3)}

// Unflatten back to nested structure
JsonNode restored = JsonFlattener.unflatten(flat);

Performance | 性能:

  • O(n) time complexity where n is the total number of nodes - O(n) 时间复杂度，n 为节点总数
  • Stateless and thread-safe - 无状态且线程安全

Security | 安全性:

  • Thread-safe: Yes (stateless utility) - 线程安全: 是（无状态工具类）
  • Depth-limited to prevent stack overflow attacks - 深度限制以防止栈溢出攻击
Since:
JDK 25, opencode-base-json V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • flatten

      public static Map<String,JsonNode> flatten(JsonNode node)
      Flattens a JSON tree into a flat map using the default configuration. 使用默认配置将 JSON 树扁平化为平面映射。

      Uses "." as separator and bracket notation "[n]" for array indices.

      使用 "." 作为分隔符，"[n]" 作为数组索引表示法。

      Parameters:
      node - the JSON node to flatten - 要扁平化的 JSON 节点
      Returns:
      an ordered map of flattened key-value pairs - 扁平化键值对的有序映射
      Throws:
      OpenJsonProcessingException - if the node exceeds maximum depth - 如果节点超过最大深度
      NullPointerException - if node is null - 如果节点为 null

    • flatten

      public static Map<String,JsonNode> flatten(JsonNode node, String separator)
      Flattens a JSON tree into a flat map using a custom separator. 使用自定义分隔符将 JSON 树扁平化为平面映射。
      Parameters:
      node - the JSON node to flatten - 要扁平化的 JSON 节点
      separator - the key separator - 键分隔符
      Returns:
      an ordered map of flattened key-value pairs - 扁平化键值对的有序映射
      Throws:
      OpenJsonProcessingException - if the node exceeds maximum depth - 如果节点超过最大深度
      NullPointerException - if node or separator is null - 如果节点或分隔符为 null

    • flatten

      public static Map<String,JsonNode> flatten(JsonNode node, JsonFlattener.FlattenConfig config)
      Flattens a JSON tree into a flat map using the specified configuration. 使用指定配置将 JSON 树扁平化为平面映射。

      Object keys are joined with the separator. Array indices use bracket notation (e.g. "[0]") when bracketArrayNotation is true, otherwise dot notation (e.g. ".0").

      对象键使用分隔符连接。数组索引在 bracketArrayNotation 为 true 时 使用方括号表示法（如 "[0]"），否则使用点表示法（如 ".0"）。

      Parameters:
      node - the JSON node to flatten - 要扁平化的 JSON 节点
      config - the flatten configuration - 扁平化配置
      Returns:
      an ordered map of flattened key-value pairs - 扁平化键值对的有序映射
      Throws:
      OpenJsonProcessingException - if the node exceeds maximum depth - 如果节点超过最大深度
      NullPointerException - if node or config is null - 如果节点或配置为 null

    • unflatten

      public static JsonNode unflatten(Map<String,JsonNode> map)
      Unflattens a flat map back into a nested JSON tree using the default "." separator. 使用默认的 "." 分隔符将平面映射反向还原为嵌套 JSON 树。
      Parameters:
      map - the flat key-value map - 平面键值映射
      Returns:
      the nested JSON tree - 嵌套 JSON 树
      Throws:
      OpenJsonProcessingException - if the map contains conflicting keys - 如果映射包含冲突的键
      NullPointerException - if map is null - 如果映射为 null

    • unflatten

      public static JsonNode unflatten(Map<String,JsonNode> map, String separator)
      Unflattens a flat map back into a nested JSON tree using a custom separator. 使用自定义分隔符将平面映射反向还原为嵌套 JSON 树。
      Parameters:
      map - the flat key-value map - 平面键值映射
      separator - the key separator - 键分隔符
      Returns:
      the nested JSON tree - 嵌套 JSON 树
      Throws:
      OpenJsonProcessingException - if the map contains conflicting keys - 如果映射包含冲突的键
      NullPointerException - if map or separator is null - 如果映射或分隔符为 null