/* * Copyright 2026 mingliqiye * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * ProjectName mingli-utils * ModuleName mingli-utils.main * CurrentFile JSONA.kt * LastUpdate 2026-02-26 14:14:18 * UpdateUser MingLiPro */ package com.mingliqiye.utils.json.api import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.module.kotlin.kotlinModule import com.mingliqiye.utils.json.api.base.JsonApi import com.mingliqiye.utils.json.api.type.JsonTypeReference import com.mingliqiye.utils.json.api.type.listType import com.mingliqiye.utils.json.converters.base.BaseJsonConverter import com.mingliqiye.utils.json.converters.base.getJsonConverter import java.io.File import java.io.InputStream import java.io.OutputStream import java.nio.file.Path /** * JSON工具类,提供静态方法访问JSON API功能 */ object JSONA { @JvmStatic private var jsonApi: JsonApi? = null /** * 获取JSON API实例 * * @return JSON API实例 * @throws NullPointerException 当JSON API未初始化时抛出异常 */ @Throws(NullPointerException::class) @JvmStatic fun getJsonApi(): JsonApi { if (jsonApi == null) { throw NullPointerException("jsonApi is null plase setJsonApi first") } return jsonApi!! } /** * 设置JSON API实例 * * @param jsa JSON API实例 */ @JvmStatic fun setJsonApi(jsa: JsonApi) { jsonApi = jsa } /** * 使用反射创建并设置指定类型的JSON API实例 * * @param T 继承自JsonApi的具体实现类 */ inline fun setJsonApi() { setJsonApi(T::class.java.getConstructor().newInstance() as JsonApi) } /** * 将JSON字符串解析为指定类型的对象 * * @param json 待解析的JSON字符串 * @param clazz 目标对象的Class类型 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parse(json: String, clazz: Class): T = getJsonApi().parse(json, clazz) /** * 将JSON字符串解析为指定泛型类型对象 * * @param json 待解析的JSON字符串 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic inline fun parse(json: String): T { return getJsonApi().parse(json, (object : JsonTypeReference() {})) } /** * 将字节数组形式的JSON解析为指定泛型类型对象 * * @param json 待解析的JSON字节数组 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic inline fun parse(json: ByteArray): T = getJsonApi().parse(json, object : JsonTypeReference() {}) /** * 将JSON字符串解析为指定泛型类型对象 * * @param json 待解析的JSON字符串 * @param type 目标对象的Type类型(支持泛型) * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parse(json: String, type: JsonTypeReference): T = getJsonApi().parse(json, type) /** * 将对象格式化为JSON字符串 * * @param obj 待格式化的对象 * @return 格式化后的JSON字符串 */ @JvmStatic fun format(obj: Any): String = getJsonApi().format(obj) /** * 从文件路径解析JSON为指定类型的对象 * * @param path 文件路径 * @param clazz 目标对象的Class类型 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parseFrom(path: String, clazz: Class): T = getJsonApi().parseFrom(path, clazz) /** * 从Path对象解析JSON为指定类型的对象 * * @param path Path对象 * @param clazz 目标对象的Class类型 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parseFrom(path: Path, clazz: Class): T = getJsonApi().parseFrom(path, clazz) /** * 从File对象解析JSON为指定类型的对象 * * @param file File对象 * @param clazz 目标对象的Class类型 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parseFrom(file: File, clazz: Class): T = getJsonApi().parseFrom(file, clazz) /** * 从InputStream解析JSON为指定类型的对象 * * @param inputStream InputStream对象 * @param clazz 目标对象的Class类型 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parseFrom(inputStream: InputStream, clazz: Class): T = getJsonApi().parseFrom(inputStream, clazz) /** * 从文件路径解析JSON为指定泛型类型对象 * * @param path 文件路径 * @param type 目标对象的Type类型(支持泛型) * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parseFrom(path: String, type: JsonTypeReference): T = getJsonApi().parseFrom(path, type) /** * 从Path对象解析JSON为指定泛型类型对象 * * @param path Path对象 * @param type 目标对象的Type类型(支持泛型) * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parseFrom(path: Path, type: JsonTypeReference): T = getJsonApi().parseFrom(path, type) /** * 从File对象解析JSON为指定泛型类型对象 * * @param file File对象 * @param type 目标对象的Type类型(支持泛型) * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parseFrom(file: File, type: JsonTypeReference): T = getJsonApi().parseFrom(file, type) /** * 从InputStream解析JSON为指定泛型类型对象 * * @param inputStream InputStream对象 * @param type 目标对象的Type类型(支持泛型) * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parseFrom(inputStream: InputStream, type: JsonTypeReference): T = getJsonApi().parseFrom(inputStream, type) /** * 将字节数组形式的JSON解析为指定类型的对象 * * @param json 待解析的JSON字节数组 * @param clazz 目标对象的Class类型 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parse(json: ByteArray, clazz: Class): T = getJsonApi().parse(json, clazz) /** * 将字节数组形式的JSON解析为指定泛型类型对象 * * @param json 待解析的JSON字节数组 * @param type 目标对象的Type类型(支持泛型) * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例 */ @JvmStatic fun parse(json: ByteArray, type: JsonTypeReference): T = getJsonApi().parse(json, type) /** * 将JSON字符串解析为指定类型的对象,解析失败时返回默认值 * * @param json 待解析的JSON字符串 * @param clazz 目标对象的Class类型 * @param defaultValue 解析失败时返回的默认值 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例或默认值 */ @JvmStatic fun parse(json: String, clazz: Class, defaultValue: T): T = getJsonApi().parse(json, clazz, defaultValue) /** * 将JSON字符串解析为指定泛型类型对象,解析失败时返回默认值 * * @param json 待解析的JSON字符串 * @param type 目标对象的Type类型(支持泛型) * @param defaultValue 解析失败时返回的默认值 * @param 泛型参数,表示目标对象的类型 * @return 解析后的对象实例或默认值 */ @JvmStatic fun parse( json: String, type: JsonTypeReference, defaultValue: T ): T = getJsonApi().parse(json, type, defaultValue) /** * 将对象格式化为美化格式的JSON字符串(带缩进和换行) * * @param obj 待格式化的对象 * @return 格式化后的美化JSON字符串 */ @JvmStatic fun formatPretty(obj: Any): String = getJsonApi().formatPretty(obj) /** * 将对象格式化为美化格式的JSON字节数组 * * @param obj 待格式化的对象 * @return 格式化后的美化JSON字节数组 */ @JvmStatic fun formatPrettyBytes(obj: Any): ByteArray = getJsonApi().formatPrettyBytes(obj) /** * 将对象格式化为美化格式的JSON字符串并写入文件 * * @param obj 待格式化的对象 * @param file 文件路径 */ @JvmStatic fun formatPretty(obj: Any, file: String) = getJsonApi().formatPretty(obj, file) /** * 将对象格式化为美化格式的JSON字符串并写入文件 * * @param obj 待格式化的对象 * @param file Path对象 */ @JvmStatic fun formatPretty(obj: Any, file: Path) = getJsonApi().formatPretty(obj, file) /** * 将对象格式化为美化格式的JSON字符串并写入文件 * * @param obj 待格式化的对象 * @param file File对象 */ @JvmStatic fun formatPretty(obj: Any, file: File) = getJsonApi().formatPretty(obj, file) /** * 将对象格式化为美化格式的JSON字符串并写入输出流 * * @param obj 待格式化的对象 * @param stream OutputStream对象 */ @JvmStatic fun formatPretty(obj: Any, stream: OutputStream) = getJsonApi().formatPretty(obj, stream) /** * 将对象格式化为JSON字节数组 * * @param obj 待格式化的对象 * @return 格式化后的JSON字节数组 */ @JvmStatic fun formatBytes(obj: Any): ByteArray = getJsonApi().formatBytes(obj) /** * 将对象格式化为JSON字符串并写入文件 * * @param obj 待格式化的对象 * @param file 文件路径 */ @JvmStatic fun format(obj: Any, file: String) = getJsonApi().format(obj, file) /** * 将对象格式化为JSON字符串并写入文件 * * @param obj 待格式化的对象 * @param file Path对象 */ @JvmStatic fun format(obj: Any, file: Path) = getJsonApi().format(obj, file) /** * 将对象格式化为JSON字符串并写入文件 * * @param obj 待格式化的对象 * @param file File对象 */ @JvmStatic fun format(obj: Any, file: File) = getJsonApi().format(obj, file) /** * 将对象格式化为JSON字符串并写入输出流 * * @param obj 待格式化的对象 * @param stream OutputStream对象 */ @JvmStatic fun format(obj: Any, stream: OutputStream) = getJsonApi().format(obj, stream) /** * 将JSON字符串解析为指定元素类型的List集合 * * @param json 待解析的JSON字符串 * @param elementType List中元素的类型 * @param 泛型参数,表示List中元素的类型 * @return 解析后的List集合 */ @JvmStatic fun parseList(json: String, elementType: Class): List = parse(json, listType(elementType)) /** * 将JSON字符串解析为指定元素类型的List集合 * * @param json 待解析的JSON字符串 * @param 泛型参数,表示List中元素的类型 * @return 解析后的List集合 */ @JvmStatic inline fun parseList(json: String): List = parse(json, listType(T::class.java)) /** * 将JSON字符串解析为指定键值类型的Map集合 * * @param json 待解析的JSON字符串 * @param keyType Map中键的类型 * @param valueType Map中值的类型 * @param 泛型参数,表示Map中键的类型 * @param 泛型参数,表示Map中值的类型 * @return 解析后的Map集合 */ @JvmStatic fun parseMap( json: String, keyType: Class, valueType: Class ): MutableMap = getJsonApi().parseMap(json, keyType, valueType) /** * 将JSON字符串解析为指定键值类型的Map集合 * * @param json 待解析的JSON字符串 * @param 泛型参数,表示Map中键的类型 * @param 泛型参数,表示Map中值的类型 * @return 解析后的Map集合 */ @JvmStatic inline fun parseMap( json: String ): MutableMap = getJsonApi().parseMap(json, K::class.java, V::class.java) /** * 验证字符串是否为有效的JSON格式 * * @param json 待验证的字符串 * @return 如果是有效的JSON格式返回true,否则返回false */ @JvmStatic fun isValidJson(json: String): Boolean = getJsonApi().isValidJson(json) /** * 将对象转换为JSON字节数组 * * @param object 待转换的对象 * @return 转换后的JSON字节数组 */ @JvmStatic fun toBytes(obj: Any): ByteArray = getJsonApi().toBytes(obj) /** * 将对象转换为美化格式的JSON字节数组 * * @param object 待转换的对象 * @return 转换后的美化格式JSON字节数组 */ @JvmStatic fun toBytesPretty(obj: Any): ByteArray = getJsonApi().toBytesPretty(obj) /** * 合并多个JSON字符串为一个JSON对象 * * @param jsons 待合并的JSON字符串数组 * @return 合并后的JSON字符串 */ @JvmStatic fun merge(vararg jsons: String): String = getJsonApi().merge(*jsons) /** * 获取JSON字符串中指定路径节点的值 * * @param json JSON字符串 * @param path 节点路径(如:"user.name") * @return 节点值的字符串表示 */ @JvmStatic fun getNodeValue(json: String, path: String): String? = getJsonApi().getNodeValue(json, path) /** * 更新JSON字符串中指定路径节点的值 * * @param json 原始JSON字符串 * @param path 节点路径(如:"user.name") * @param newValue 新的节点值 * @return 更新后的JSON字符串 */ @JvmStatic fun updateNodeValue(json: String, path: String, newValue: Any): String = getJsonApi().updateNodeValue(json, path, newValue) /** * 将源对象转换为目标类型的对象 * * @param T 源对象的类型 * @param D 目标对象的类型 * @param source 需要转换的源对象 * @param destinationClass 目标对象的Class类型 * @return 转换后的目标类型对象 */ @JvmStatic fun convert(source: Any, destinationClass: Class): D = getJsonApi().convert(source, destinationClass) /** * 使用内联函数和reified类型参数将源对象转换为目标类型的对象 * * @param T 源对象的类型 * @param D 目标对象的类型(通过reified类型参数推断) * @param source 需要转换的源对象 * @return 转换后的目标类型对象 */ @JvmStatic inline fun convert(source: Any): D = getJsonApi().convert(source, object : JsonTypeReference() {}) /** * 将源对象转换为目标类型的对象,使用JsonTypeReference指定目标类型 * * @param T 源对象的类型 * @param D 目标对象的类型 * @param source 需要转换的源对象 * @param destinationType 目标对象的JsonTypeReference类型引用 * @return 转换后的目标类型对象 */ @JvmStatic fun convert(source: Any, destinationType: JsonTypeReference): D = getJsonApi().convert(source, destinationType) /** * 添加JSON转换器到API中 * * @param c 需要添加的JSON转换器实例 */ @JvmStatic fun addJsonConverter(c: BaseJsonConverter<*, *>) = getJsonApi().addJsonConverter(c) /** * 使用反射创建并添加指定类型的JSON转换器到API中 * * @param T 继承自BaseJsonConverter的具体实现类 */ inline fun > addJsonConverter() = addJsonConverter(getJsonConverter()) inline fun String.parseJson() = parse(this) inline fun ByteArray.parseJson() = parse(this) inline fun InputStream.parseJson() = this.use { parse(readBytes()) } inline fun File.parseJson() = this.inputStream().parseJson() inline fun Path.parseJson() = this.toFile().inputStream().parseJson() fun Any.toJson() = format(this) @JvmStatic fun jacksonKotlinObjectMapper(): ObjectMapper = ObjectMapper().jacksonKotlinObjectMapper() @JvmStatic fun ObjectMapper.jacksonKotlinObjectMapper(): ObjectMapper = this.registerModule(kotlinModule()) }