Class OpenJson

java.lang.Object
cloud.opencode.base.json.OpenJson
public final class OpenJson extends Object
OpenJson - Unified JSON Processing Facade OpenJson - 统一 JSON 处理门面

This is the main entry point for all JSON operations in the OpenCode JSON library. It provides a unified API that delegates to pluggable JSON provider implementations (Jackson, Gson, Fastjson2, etc.).

这是 OpenCode JSON 库中所有 JSON 操作的主入口点。 它提供统一的 API，委托给可插拔的 JSON 提供者实现（Jackson、Gson、Fastjson2 等）。

Features | 特性:

  • Serialization/Deserialization - 序列化/反序列化
  • Tree Model (JsonNode) - 树模型
  • Streaming API - 流式 API
  • JSONPath & JSON Pointer - JSONPath 和 JSON Pointer
  • JSON Patch & Merge Patch - JSON Patch 和 Merge Patch
  • JSON Schema Validation - JSON Schema 验证
  • Custom Type Adapters - 自定义类型适配器
  • Security Features - 安全特性

Basic Usage | 基本用法:

// Serialize to JSON
String json = OpenJson.toJson(user);

// Deserialize from JSON
User user = OpenJson.fromJson(json, User.class);

// Parse to tree
JsonNode node = OpenJson.parse(json);

// Query with JSONPath
List<JsonNode> results = OpenJson.select(node, "$.users[*].name");

// Custom configuration
OpenJson json = OpenJson.withConfig(config);

Features | 主要功能:

  • Unified facade for all JSON operations - 所有JSON操作的统一门面
  • Pluggable provider architecture (Jackson, Gson, Fastjson2) - 可插拔提供者架构
  • Static and instance API support - 支持静态和实例API

Usage Examples | 使用示例:

// See class-level documentation for usage
// 参见类级文档了解用法

Security | 安全性:

  • Thread-safe: Yes (immutable) - 线程安全: 是（不可变）
  • Null-safe: Partial (validates inputs) - 空值安全: 部分（验证输入）
Since:
JDK 25, opencode-base-json V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • withConfig

      public static OpenJson withConfig(JsonConfig config)
      Creates a new OpenJson instance with the specified configuration. 使用指定配置创建新的 OpenJson 实例。
      Parameters:
      config - the configuration - 配置
      Returns:
      the OpenJson instance - OpenJson 实例

    • withProvider

      public static OpenJson withProvider(String providerName)
      Creates a new OpenJson instance with the specified provider. 使用指定提供者创建新的 OpenJson 实例。
      Parameters:
      providerName - the provider name (e.g., "jackson", "gson") - 提供者名称
      Returns:
      the OpenJson instance - OpenJson 实例

    • withConfigAndProvider

      public static OpenJson withConfigAndProvider(JsonConfig config, String providerName)
      Creates a new OpenJson instance with configuration and provider. 使用配置和提供者创建新的 OpenJson 实例。
      Parameters:
      config - the configuration - 配置
      providerName - the provider name - 提供者名称
      Returns:
      the OpenJson instance - OpenJson 实例

    • toJson

      public static String toJson(Object obj)
      Serializes an object to JSON string. 将对象序列化为 JSON 字符串。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      Returns:
      the JSON string - JSON 字符串

    • toJsonBytes

      public static byte[] toJsonBytes(Object obj)
      Serializes an object to JSON bytes. 将对象序列化为 JSON 字节数组。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      Returns:
      the JSON bytes - JSON 字节数组

    • toJson

      public static void toJson(Object obj, OutputStream output)
      Serializes an object to an OutputStream. 将对象序列化到输出流。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      output - the output stream - 输出流

    • toJson

      public static void toJson(Object obj, Writer writer)
      Serializes an object to a Writer. 将对象序列化到 Writer。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      writer - the writer - Writer

    • toPrettyJson

      public static String toPrettyJson(Object obj)
      Serializes an object to pretty-printed JSON. 将对象序列化为美化的 JSON。
      Parameters:
      obj - the object to serialize - 要序列化的对象
      Returns:
      the pretty JSON string - 美化的 JSON 字符串

    • fromJson

      public static <T> T fromJson(String json, Class<T> clazz)
      Deserializes JSON string to an object. 将 JSON 字符串反序列化为对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON string - JSON 字符串
      clazz - the target class - 目标类
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      public static <T> T fromJson(String json, TypeReference<T> typeReference)
      Deserializes JSON string using TypeReference. 使用 TypeReference 反序列化 JSON 字符串。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON string - JSON 字符串
      typeReference - the type reference - 类型引用
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      public static <T> T fromJson(byte[] json, Class<T> clazz)
      Deserializes JSON bytes to an object. 将 JSON 字节数组反序列化为对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON bytes - JSON 字节数组
      clazz - the target class - 目标类
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      public static <T> T fromJson(byte[] json, TypeReference<T> typeReference)
      Deserializes JSON bytes using TypeReference. 使用 TypeReference 反序列化 JSON 字节数组。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON bytes - JSON 字节数组
      typeReference - the type reference - 类型引用
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      public static <T> T fromJson(InputStream input, Class<T> clazz)
      Deserializes from InputStream. 从输入流反序列化。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      input - the input stream - 输入流
      clazz - the target class - 目标类
      Returns:
      the deserialized object - 反序列化的对象

    • fromJson

      public static <T> T fromJson(Reader reader, Class<T> clazz)
      Deserializes from Reader. 从 Reader 反序列化。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      reader - the reader - Reader
      clazz - the target class - 目标类
      Returns:
      the deserialized object - 反序列化的对象

    • fromJsonArray

      public static <T> List<T> fromJsonArray(String json, Class<T> elementType)
      Deserializes JSON array to List. 将 JSON 数组反序列化为 List。
      Type Parameters:
      T - the element type - 元素类型
      Parameters:
      json - the JSON string - JSON 字符串
      elementType - the element type - 元素类型
      Returns:
      the list - 列表

    • fromJsonMap

      public static <K,V> Map<K,V> fromJsonMap(String json, Class<K> keyType, Class<V> valueType)
      Deserializes JSON object to Map. 将 JSON 对象反序列化为 Map。
      Type Parameters:
      K - the key type - 键类型
      V - the value type - 值类型
      Parameters:
      json - the JSON string - JSON 字符串
      keyType - the key type - 键类型
      valueType - the value type - 值类型
      Returns:
      the map - Map

    • parse

      public static JsonNode parse(String json)
      Parses JSON string to JsonNode tree. 将 JSON 字符串解析为 JsonNode 树。
      Parameters:
      json - the JSON string - JSON 字符串
      Returns:
      the root node - 根节点

    • parse

      public static JsonNode parse(byte[] json)
      Parses JSON bytes to JsonNode tree. 将 JSON 字节数组解析为 JsonNode 树。
      Parameters:
      json - the JSON bytes - JSON 字节数组
      Returns:
      the root node - 根节点

    • toTree

      public static JsonNode toTree(Object obj)
      Converts object to JsonNode tree. 将对象转换为 JsonNode 树。
      Parameters:
      obj - the object - 对象
      Returns:
      the JSON node - JSON 节点

    • treeToValue

      public static <T> T treeToValue(JsonNode node, Class<T> clazz)
      Converts JsonNode to object. 将 JsonNode 转换为对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      node - the JSON node - JSON 节点
      clazz - the target class - 目标类
      Returns:
      the object - 对象

    • at

      public static JsonNode at(JsonNode node, String pointer)
      Evaluates a JSON Pointer against a node. 对节点求值 JSON Pointer。
      Parameters:
      node - the JSON node - JSON 节点
      pointer - the JSON Pointer string - JSON Pointer 字符串
      Returns:
      the value at the pointer location - 指针位置的值

    • select

      public static List<JsonNode> select(JsonNode node, String path)
      Selects nodes using JSONPath. 使用 JSONPath 选择节点。
      Parameters:
      node - the JSON node - JSON 节点
      path - the JSONPath expression - JSONPath 表达式
      Returns:
      matching nodes - 匹配的节点

    • selectFirst

      public static JsonNode selectFirst(JsonNode node, String path)
      Selects first matching node using JSONPath. 使用 JSONPath 选择第一个匹配的节点。
      Parameters:
      node - the JSON node - JSON 节点
      path - the JSONPath expression - JSONPath 表达式
      Returns:
      the first match, or null - 第一个匹配，或 null

    • diff

      public static JsonDiff.DiffResult diff(JsonNode source, JsonNode target)
      Computes diff between two JSON documents. 计算两个 JSON 文档之间的差异。
      Parameters:
      source - the source document - 源文档
      target - the target document - 目标文档
      Returns:
      the diff result - 差异结果

    • patch

      public static JsonNode patch(JsonNode target, JsonPatch patch)
      Applies a JSON Patch to a document. 将 JSON Patch 应用于文档。
      Parameters:
      target - the target document - 目标文档
      patch - the patch - 补丁
      Returns:
      the patched document - 打补丁后的文档

    • mergePatch

      public static JsonNode mergePatch(JsonNode target, JsonNode patch)
      Applies a JSON Merge Patch to a document. 将 JSON Merge Patch 应用于文档。
      Parameters:
      target - the target document - 目标文档
      patch - the merge patch document - 合并补丁文档
      Returns:
      the merged document - 合并后的文档

    • validate

      public static JsonSchemaValidator.ValidationResult validate(JsonNode data, JsonNode schema)
      Validates JSON against a schema. 根据 schema 验证 JSON。
      Parameters:
      data - the data to validate - 要验证的数据
      schema - the JSON Schema - JSON Schema
      Returns:
      the validation result - 验证结果

    • validateOrThrow

      public static void validateOrThrow(JsonNode data, JsonNode schema)
      Validates and throws if invalid. 验证，如果无效则抛出异常。
      Parameters:
      data - the data to validate - 要验证的数据
      schema - the JSON Schema - JSON Schema

    • isValid

      public static boolean isValid(String json)
      Checks whether the given string is valid JSON. 检查给定字符串是否为合法 JSON。
      Parameters:
      json - the string to check - 要检查的字符串
      Returns:
      true if valid JSON - 如果是合法 JSON 则返回 true

    • minify

      public static String minify(String json)
      Minifies a JSON string by removing unnecessary whitespace. 通过移除不必要的空白来压缩 JSON 字符串。
      Parameters:
      json - the JSON string - JSON 字符串
      Returns:
      the minified JSON - 压缩后的 JSON

    • prettyPrint

      public static String prettyPrint(String json)
      Pretty-prints a JSON string with standard 2-space indentation. 使用标准 2 空格缩进美化 JSON 字符串。
      Parameters:
      json - the JSON string - JSON 字符串
      Returns:
      the formatted JSON - 格式化后的 JSON

    • structuralEquals

      public static boolean structuralEquals(JsonNode a, JsonNode b)
      Compares two JSON nodes for structural equality (ignoring object key order). 比较两个 JSON 节点的结构相等性（忽略对象键顺序）。
      Parameters:
      a - the first node - 第一个节点
      b - the second node - 第二个节点
      Returns:
      true if structurally equal - 如果结构相等则返回 true

    • flatten

      public static Map<String,JsonNode> flatten(JsonNode node)
      Flattens a nested JSON node into a flat key-value map using dot notation. 使用点号分隔将嵌套 JSON 节点扁平化为键值对 Map。
      Parameters:
      node - the JSON node to flatten - 要扁平化的 JSON 节点
      Returns:
      the flattened map - 扁平化后的 Map

    • unflatten

      public static JsonNode unflatten(Map<String,JsonNode> map)
      Restores a flattened map back to a nested JSON node. 将扁平化的 Map 还原为嵌套 JSON 节点。
      Parameters:
      map - the flattened map - 扁平化的 Map
      Returns:
      the nested JSON node - 嵌套的 JSON 节点

    • canonicalize

      public static String canonicalize(JsonNode node)
      Produces RFC 8785 canonical JSON output for the given node. 为给定节点生成 RFC 8785 规范化 JSON 输出。
      Parameters:
      node - the JSON node - JSON 节点
      Returns:
      the canonical JSON string - 规范化 JSON 字符串

    • truncate

      public static String truncate(String json, int maxLength)
      Truncates a JSON string to the specified maximum length for logging. 将 JSON 字符串截断到指定最大长度，用于日志记录。
      Parameters:
      json - the JSON string - JSON 字符串
      maxLength - the maximum length - 最大长度
      Returns:
      the truncated JSON - 截断后的 JSON

    • createReader

      public static JsonReader createReader(InputStream input)
      Creates a JsonReader for an InputStream. 为输入流创建 JsonReader。
      Parameters:
      input - the input stream - 输入流
      Returns:
      the JSON reader - JSON 读取器

    • createReader

      public static JsonReader createReader(Reader reader)
      Creates a JsonReader for a Reader. 为 Reader 创建 JsonReader。
      Parameters:
      reader - the reader - Reader
      Returns:
      the JSON reader - JSON 读取器

    • createWriter

      public static JsonWriter createWriter(OutputStream output)
      Creates a JsonWriter for an OutputStream. 为输出流创建 JsonWriter。
      Parameters:
      output - the output stream - 输出流
      Returns:
      the JSON writer - JSON 写入器

    • createWriter

      public static JsonWriter createWriter(Writer writer)
      Creates a JsonWriter for a Writer. 为 Writer 创建 JsonWriter。
      Parameters:
      writer - the writer - Writer
      Returns:
      the JSON writer - JSON 写入器

    • serialize

      public String serialize(Object obj)
      Serializes an object to JSON string. 将对象序列化为 JSON 字符串。
      Parameters:
      obj - the object - 对象
      Returns:
      the JSON string - JSON 字符串

    • serializeToBytes

      public byte[] serializeToBytes(Object obj)
      Serializes an object to JSON bytes. 将对象序列化为 JSON 字节数组。
      Parameters:
      obj - the object - 对象
      Returns:
      the JSON bytes - JSON 字节数组

    • serialize

      public void serialize(Object obj, OutputStream output)
      Serializes an object to an OutputStream. 将对象序列化到输出流。
      Parameters:
      obj - the object - 对象
      output - the output stream - 输出流

    • serialize

      public void serialize(Object obj, Writer writer)
      Serializes an object to a Writer. 将对象序列化到 Writer。
      Parameters:
      obj - the object - 对象
      writer - the writer - Writer

    • deserialize

      public <T> T deserialize(String json, Class<T> clazz)
      Deserializes JSON to an object. 将 JSON 反序列化为对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON string - JSON 字符串
      clazz - the target class - 目标类
      Returns:
      the object - 对象

    • deserialize

      public <T> T deserialize(String json, TypeReference<T> typeReference)
      Deserializes JSON using TypeReference. 使用 TypeReference 反序列化 JSON。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON string - JSON 字符串
      typeReference - the type reference - 类型引用
      Returns:
      the object - 对象

    • deserialize

      public <T> T deserialize(byte[] json, Class<T> clazz)
      Deserializes JSON bytes. 反序列化 JSON 字节数组。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON bytes - JSON 字节数组
      clazz - the target class - 目标类
      Returns:
      the object - 对象

    • deserialize

      public <T> T deserialize(byte[] json, TypeReference<T> typeReference)
      Deserializes JSON bytes using TypeReference. 使用 TypeReference 反序列化 JSON 字节数组。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      json - the JSON bytes - JSON 字节数组
      typeReference - the type reference - 类型引用
      Returns:
      the object - 对象

    • deserialize

      public <T> T deserialize(InputStream input, Class<T> clazz)
      Deserializes from InputStream. 从输入流反序列化。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      input - the input stream - 输入流
      clazz - the target class - 目标类
      Returns:
      the object - 对象

    • deserialize

      public <T> T deserialize(Reader reader, Class<T> clazz)
      Deserializes from Reader. 从 Reader 反序列化。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      reader - the reader - Reader
      clazz - the target class - 目标类
      Returns:
      the object - 对象

    • deserializeArray

      public <T> List<T> deserializeArray(String json, Class<T> elementType)
      Deserializes JSON array to List. 将 JSON 数组反序列化为 List。
      Type Parameters:
      T - the element type - 元素类型
      Parameters:
      json - the JSON string - JSON 字符串
      elementType - the element type - 元素类型
      Returns:
      the list - 列表

    • deserializeMap

      public <K,V> Map<K,V> deserializeMap(String json, Class<K> keyType, Class<V> valueType)
      Deserializes JSON object to Map. 将 JSON 对象反序列化为 Map。
      Type Parameters:
      K - the key type - 键类型
      V - the value type - 值类型
      Parameters:
      json - the JSON string - JSON 字符串
      keyType - the key type - 键类型
      valueType - the value type - 值类型
      Returns:
      the map - Map

    • parseTree

      public JsonNode parseTree(String json)
      Parses JSON to tree. 将 JSON 解析为树。
      Parameters:
      json - the JSON string - JSON 字符串
      Returns:
      the root node - 根节点

    • parseTree

      public JsonNode parseTree(byte[] json)
      Parses JSON bytes to tree. 将 JSON 字节数组解析为树。
      Parameters:
      json - the JSON bytes - JSON 字节数组
      Returns:
      the root node - 根节点

    • valueToTree

      public JsonNode valueToTree(Object obj)
      Converts object to tree. 将对象转换为树。
      Parameters:
      obj - the object - 对象
      Returns:
      the JSON node - JSON 节点

    • treeToObject

      public <T> T treeToObject(JsonNode node, Class<T> clazz)
      Converts tree to object. 将树转换为对象。
      Type Parameters:
      T - the target type - 目标类型
      Parameters:
      node - the JSON node - JSON 节点
      clazz - the target class - 目标类
      Returns:
      the object - 对象

    • registerModule

      public OpenJson registerModule(JsonModule module)
      Registers a JSON module with this instance. 向此实例注册 JSON 模块。

      The module's JsonModule.setupModule(JsonModule.SetupContext) method is called immediately to register all components.

      模块的 JsonModule.setupModule(JsonModule.SetupContext) 方法会被立即调用以注册所有组件。

      Parameters:
      module - the module to register - 要注册的模块
      Returns:
      this instance for chaining - 此实例，用于链式调用

    • addMixin

      public OpenJson addMixin(Class<?> target, Class<?> mixin)
      Adds a mixin annotation class for a target type. 为目标类型添加混入注解类。
      Parameters:
      target - the target class - 目标类
      mixin - the mixin class containing annotations - 包含注解的混入类
      Returns:
      this instance for chaining - 此实例，用于链式调用

    • setPropertyFilter

      public OpenJson setPropertyFilter(String filterId, PropertyFilter filter)
      Registers a named property filter. 注册命名属性过滤器。
      Parameters:
      filterId - the filter identifier - 过滤器标识符
      filter - the property filter - 属性过滤器
      Returns:
      this instance for chaining - 此实例，用于链式调用

    • getMixinSource

      public MixinSource getMixinSource()
      Returns the mixin source. 返回混入源。
      Returns:
      the mixin source - 混入源

    • getPropertyFilter

      public PropertyFilter getPropertyFilter(String filterId)
      Returns the property filter for the given ID. 返回给定 ID 的属性过滤器。
      Parameters:
      filterId - the filter identifier - 过滤器标识符
      Returns:
      the filter, or null if not found - 过滤器，如果未找到则返回 null

    • getModules

      public List<JsonModule> getModules()
      Returns the registered modules. 返回注册的模块。
      Returns:
      unmodifiable list of modules - 不可修改的模块列表

    • getConfig

      public JsonConfig getConfig()
      Returns the configuration. 返回配置。
      Returns:
      the config - 配置

    • getProvider

      public JsonProvider getProvider()
      Returns the provider. 返回提供者。
      Returns:
      the provider - 提供者