Class JsonStrings

java.lang.Object
cloud.opencode.base.json.util.JsonStrings
public final class JsonStrings extends Object
JSON Strings - String-level JSON Utilities JSON 字符串 - 字符串级 JSON 工具类

Provides low-level string manipulation utilities for JSON processing, including escaping, unescaping, validation, minification, and pretty-printing. These operations work directly on JSON strings without building a tree model.

提供用于 JSON 处理的低级字符串操作工具， 包括转义、反转义、验证、压缩和格式化。 这些操作直接在 JSON 字符串上工作，不构建树模型。

Features | 主要功能:

  • RFC 8259 compliant string escaping and unescaping - 符合 RFC 8259 的字符串转义和反转义
  • Fast JSON validation without tree construction - 快速 JSON 验证，无需构建树
  • Whitespace removal (minification) - 空白移除（压缩）
  • Pretty-printing with configurable indentation - 可配置缩进的格式化

Usage Examples | 使用示例:

// Escape a string for use inside a JSON value
String escaped = JsonStrings.escape("Hello\nWorld");
// Result: Hello\nWorld

// Unescape a JSON string value
String unescaped = JsonStrings.unescape("Hello\\nWorld");
// Result: Hello\nWorld

// Validate JSON
boolean valid = JsonStrings.isValid("{\"key\":\"value\"}"); // true

// Minify JSON
String minified = JsonStrings.minify("{ \"a\" : 1 }");
// Result: {"a":1}

// Pretty-print JSON
String pretty = JsonStrings.prettyPrint("{\"a\":1,\"b\":[1,2]}");

Performance | 性能:

  • All operations are single-pass with O(n) complexity - 所有操作都是单遍 O(n) 复杂度
  • No intermediate tree or object construction - 无中间树或对象构建
  • StringBuilder-based output for minimal allocation - 基于 StringBuilder 的输出，最小化分配

Security | 安全性:

  • Thread-safe: Yes (stateless utility) - 线程安全: 是（无状态工具类）
  • Input validation prevents injection - 输入验证防止注入
  • Depth limit in validation/pretty-print prevents stack overflow - 验证/格式化中的深度限制防止栈溢出
Since:
JDK 25, opencode-base-json V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • escape

      public static String escape(String value)
      Escapes a string value for use inside a JSON string (RFC 8259). 转义字符串值以在 JSON 字符串中使用 (RFC 8259)。

      Escape rules:

      • " → \"
      • \ → \\
      • U+0008 → \b
      • U+000C → \f
      • U+000A → \n
      • U+000D → \r
      • U+0009 → \t
      • Other control chars (U+0000-U+001F) are escaped as unicode escapes
      • / is NOT escaped (optional per RFC 8259)
      Parameters:
      value - the string to escape - 要转义的字符串
      Returns:
      the escaped string (without surrounding quotes) - 转义后的字符串（不含外围引号）
      Throws:
      OpenJsonProcessingException - if value is null - 如果值为 null

    • unescape

      public static String unescape(String value)
      Unescapes a JSON string value (reverse of escape). 反转义 JSON 字符串值（escape 的逆操作）。

      Handles all JSON escape sequences including unicode escapes and surrogate pairs.

      处理所有 JSON 转义序列，包括 Unicode 转义和代理对。

      Parameters:
      value - the escaped string to unescape (without surrounding quotes) - 要反转义的字符串（不含外围引号）
      Returns:
      the unescaped string - 反转义后的字符串
      Throws:
      OpenJsonProcessingException - if value is null or contains invalid escape sequences - 如果值为 null 或包含无效的转义序列

    • isValid

      public static boolean isValid(String json)
      Validates whether the input is valid JSON per RFC 8259. 验证输入是否为有效的 RFC 8259 JSON。

      Uses a simple state machine parser without building a tree. Returns false for null, empty, or blank input.

      使用简单的状态机解析器，不构建树。 对于 null、空或空白输入返回 false。

      Parameters:
      json - the string to validate - 要验证的字符串
      Returns:
      true if the input is valid JSON - 如果输入是有效的 JSON 则返回 true

    • minify

      public static String minify(String json)
      Removes all unnecessary whitespace from a JSON string. 移除 JSON 字符串中所有不必要的空白。

      Parses the JSON and re-serializes it without whitespace. Throws an exception if the input is not valid JSON.

      解析 JSON 并重新序列化，不带空白。 如果输入不是有效的 JSON，则抛出异常。

      Parameters:
      json - the JSON string to minify - 要压缩的 JSON 字符串
      Returns:
      the minified JSON string - 压缩后的 JSON 字符串
      Throws:
      OpenJsonProcessingException - if the input is null or invalid JSON - 如果输入为 null 或无效的 JSON

    • prettyPrint

      public static String prettyPrint(String json)
      Pretty-prints a JSON string with 2-space indentation. 使用 2 空格缩进格式化 JSON 字符串。
      Parameters:
      json - the JSON string to format - 要格式化的 JSON 字符串
      Returns:
      the formatted JSON string - 格式化后的 JSON 字符串
      Throws:
      OpenJsonProcessingException - if the input is null or invalid JSON - 如果输入为 null 或无效的 JSON

    • prettyPrint

      public static String prettyPrint(String json, String indent)
      Pretty-prints a JSON string with the specified indentation. 使用指定缩进格式化 JSON 字符串。
      Parameters:
      json - the JSON string to format - 要格式化的 JSON 字符串
      indent - the indentation string (e.g., " " or "\t") - 缩进字符串
      Returns:
      the formatted JSON string - 格式化后的 JSON 字符串
      Throws:
      OpenJsonProcessingException - if the input is null or invalid JSON - 如果输入为 null 或无效的 JSON