Class JsonTruncator

java.lang.Object
cloud.opencode.base.json.util.JsonTruncator
public final class JsonTruncator extends Object
JSON Truncator - Truncates Large JSON for Logging JSON 截断器 - 截断大型 JSON 用于日志记录

Provides utilities to truncate large JSON structures for safe logging, debugging, and display purposes. Supports both string-level truncation (fast, may produce invalid JSON) and tree-level truncation (produces valid JSON with truncation markers).

提供截断大型 JSON 结构的工具，用于安全的日志记录、调试和显示。 支持字符串级截断（快速，可能产生无效 JSON）和树级截断 （产生带截断标记的有效 JSON）。

Features | 主要功能:

  • String-level truncation for quick logging - 字符串级截断用于快速日志记录
  • Tree-level truncation with configurable limits - 可配置限制的树级截断
  • Summary generation for node type and size - 节点类型和大小的摘要生成
  • Configurable via JsonTruncator.TruncateConfig record - 通过 TruncateConfig 记录配置

Usage Examples | 使用示例:

// String-level truncation
String result = JsonTruncator.truncate(longJson, 200);

// Tree-level truncation with default config
String result = JsonTruncator.truncate(node, TruncateConfig.DEFAULT);

// Tree-level truncation with custom config
TruncateConfig config = new TruncateConfig(512, 5, 50, 3, "...");
String result = JsonTruncator.truncate(node, config);

// Quick summary
String summary = JsonTruncator.summary(node); // "Object{5 properties}"

Performance | 性能:

  • String truncation is O(1) - no parsing - 字符串截断为 O(1)，无需解析
  • Tree truncation is O(n) bounded by config limits - 树截断为 O(n)，受配置限制约束

Security | 安全性:

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

  • Method Details

    • truncate

      public static String truncate(String json, int maxLength)
      Truncates a JSON string to the specified maximum length. 将 JSON 字符串截断到指定的最大长度。

      If the JSON string length is within maxLength, it is returned as-is. Otherwise, it is truncated at maxLength and the marker "...(truncated)" is appended. The result may not be valid JSON.

      如果 JSON 字符串长度在 maxLength 以内，则原样返回。 否则，在 maxLength 处截断并追加标记 "...(truncated)"。 结果可能不是有效 JSON。

      Parameters:
      json - the JSON string to truncate - 要截断的 JSON 字符串
      maxLength - the maximum length of the output - 输出的最大长度
      Returns:
      the truncated string - 截断后的字符串
      Throws:
      OpenJsonProcessingException - if maxLength is not positive - 如果 maxLength 不是正数

    • truncate

      public static String truncate(JsonNode node, JsonTruncator.TruncateConfig config)
      Truncates a JsonNode tree according to the specified configuration. 根据指定配置截断 JsonNode 树。

      Produces valid JSON with truncation markers as string values. Arrays are trimmed to maxArrayElements with a marker indicating remaining count. Strings are trimmed to maxStringLength with the truncation marker appended. Objects beyond maxDepth are replaced with a depth marker.

      生成带有截断标记字符串值的有效 JSON。 数组被截断到 maxArrayElements 项，带有剩余计数标记。 字符串被截断到 maxStringLength，附加截断标记。 超过 maxDepth 的对象被深度标记替换。

      Parameters:
      node - the JSON node to truncate - 要截断的 JSON 节点
      config - the truncation configuration - 截断配置
      Returns:
      the truncated JSON string - 截断后的 JSON 字符串
      Throws:
      OpenJsonProcessingException - if node or config is null - 如果节点或配置为 null

    • summary

      public static String summary(JsonNode node)
      Returns a brief summary of the node's type and size. 返回节点类型和大小的简要摘要。

      Examples:

      • Object{5 properties}
      • Array[100 elements]
      • String(50 chars)
      • Number(42)
      • Boolean(true)
      • null
      Parameters:
      node - the JSON node to summarize - 要摘要的 JSON 节点
      Returns:
      the summary string - 摘要字符串