v 5.2.6
This commit is contained in:
@@ -16,120 +16,142 @@
|
||||
* ProjectName mingli-utils
|
||||
* ModuleName mingli-utils.main
|
||||
* CurrentFile ResourceUtils.kt
|
||||
* LastUpdate 2026-02-05 11:09:16
|
||||
* LastUpdate 2026-05-23 10:28:28
|
||||
* UpdateUser MingLiPro
|
||||
*/
|
||||
package com.mingliqiye.utils.resource
|
||||
|
||||
import java.io.IOException
|
||||
import com.mingliqiye.utils.exception.NotFoundResourceException
|
||||
import java.nio.charset.Charset
|
||||
|
||||
/**
|
||||
* 工具类,用于从类路径中加载资源文件。
|
||||
*/
|
||||
object ResourceUtils {
|
||||
|
||||
|
||||
/**
|
||||
* 从默认类路径中加载指定名称的资源文件,并以字节数组形式返回。
|
||||
* 从类路径中读取资源文件并返回字节数组(使用 reified 类型参数)
|
||||
*
|
||||
* @param resourceName 资源文件的名称(相对于类路径根目录)。
|
||||
* @return 资源文件的内容作为字节数组。
|
||||
* @throws IOException 如果资源未找到或读取失败时抛出。
|
||||
* 这是一个内联扩展函数,利用 reified 关键字在编译时获取具体类型 T 的 Class 对象
|
||||
*
|
||||
* @param T 用于获取 ClassLoader 的类型参数(通常传入调用方的类)
|
||||
* @param path 资源文件的路径(相对于 T 所在的包,或以 / 开头的绝对路径)
|
||||
* @return 资源的字节数组
|
||||
* @throws NotFoundResourceException 当资源不存在时抛出
|
||||
*
|
||||
* 使用示例:
|
||||
* ```kotlin
|
||||
* // 在当前类的包下查找 config.json
|
||||
* val data = getResourceAsByteArray<MyClass>("config.json")
|
||||
*
|
||||
* // 使用绝对路径(从 classpath 根目录)
|
||||
* val data = getResourceAsByteArray<MyClass>("/assets/config.json")
|
||||
* ```
|
||||
*/
|
||||
@JvmStatic
|
||||
@Throws(IOException::class)
|
||||
fun getResource(resourceName: String): ByteArray {
|
||||
return getResource(resourceName, ResourceUtils::class.java)
|
||||
inline fun <reified T> getResourceAsByteArray(path: String): ByteArray {
|
||||
// 将 reified T 的 KClass 转换为 Java 的 Class 对象,传递给重载方法
|
||||
return getResourceAsByteArray(path, T::class.java)
|
||||
}
|
||||
|
||||
/**
|
||||
* 从指定类的类路径中加载指定名称的资源文件,并以字节数组形式返回。
|
||||
* 从类路径中读取资源文件并返回字符串(使用 reified 类型参数)
|
||||
*
|
||||
* @param resourceName 资源文件的名称(相对于类路径根目录)。
|
||||
* @param clazz 用于定位资源的类。
|
||||
* @return 资源文件的内容作为字节数组。
|
||||
* @throws IOException 如果资源未找到或读取失败时抛出。
|
||||
* @param T 用于获取 ClassLoader 的类型参数
|
||||
* @param resource 资源文件路径
|
||||
* @param charset 字符编码,默认为系统默认字符集
|
||||
* @return 资源文件的字符串内容
|
||||
* @throws NotFoundResourceException 当资源不存在时抛出
|
||||
*
|
||||
* 使用示例:
|
||||
* ```kotlin
|
||||
* // 读取文本文件,使用默认编码
|
||||
* val content = getResourceAsString<MyClass>("data.txt")
|
||||
*
|
||||
* // 指定 UTF-8 编码
|
||||
* val content = getResourceAsString<MyClass>("data.txt", Charsets.UTF_8)
|
||||
* ```
|
||||
*/
|
||||
@JvmStatic
|
||||
@Throws(IOException::class)
|
||||
fun getResource(resourceName: String, clazz: Class<*>): ByteArray {
|
||||
return clazz.getResourceAsStream(resourceName)?.use {
|
||||
it.readBytes()
|
||||
} ?: throw IOException("Resource not found: $resourceName")
|
||||
inline fun <reified T> getResourceAsString(
|
||||
resource: String,
|
||||
charset: Charset = Charset.defaultCharset(),
|
||||
): String {
|
||||
// 将 reified T 的 Class 对象传递给重载方法
|
||||
return getResourceAsString(resource, charset, T::class.java)
|
||||
}
|
||||
|
||||
/**
|
||||
* 从默认类路径中加载指定名称的资源文件,并以字符串形式返回。
|
||||
* 从类路径中读取资源文件并返回字符串(Java 友好重载版本)
|
||||
*
|
||||
* @param resourceName 资源文件的名称(相对于类路径根目录)。
|
||||
* @return 资源文件的内容作为字符串(使用UTF-8编码)。
|
||||
* @throws IOException 如果资源未找到或读取失败时抛出。
|
||||
* 此方法标记为 @JvmStatic,使其可以在 Java 代码中以静态方法形式调用
|
||||
*
|
||||
* @param path 资源文件路径
|
||||
* @param charset 字符编码
|
||||
* @param clazz 用于获取 ClassLoader 的参考类
|
||||
* @return 资源文件的字符串内容
|
||||
* @throws NotFoundResourceException 当资源不存在时抛出
|
||||
*
|
||||
* Java 调用示例:
|
||||
* ```java
|
||||
* // 在 Java 中调用
|
||||
* String content = YourClass.getResourceAsString("config.json", StandardCharsets.UTF_8, MyClass.class);
|
||||
* ```
|
||||
*/
|
||||
@JvmStatic
|
||||
@Throws(IOException::class)
|
||||
fun getStringResource(resourceName: String): String {
|
||||
return getStringResource(resourceName, ResourceUtils::class.java)
|
||||
fun getResourceAsString(path: String, charset: Charset, clazz: Class<*>): String {
|
||||
// 先读取为字节数组,再按指定字符集解码为字符串
|
||||
return String(getResourceAsByteArray(path, clazz), charset)
|
||||
}
|
||||
|
||||
/**
|
||||
* 从指定类的类路径中加载指定名称的资源文件,并以字符串形式返回。
|
||||
* 从类路径中读取资源文件并返回字符串(使用默认字符集,Java 友好重载)
|
||||
*
|
||||
* @param resourceName 资源文件的名称(相对于类路径根目录)。
|
||||
* @param clazz 用于定位资源的类。
|
||||
* @return 资源文件的内容作为字符串(使用UTF-8编码)。
|
||||
* @throws IOException 如果资源未找到或读取失败时抛出。
|
||||
* @param path 资源文件路径
|
||||
* @param clazz 用于获取 ClassLoader 的参考类
|
||||
* @return 资源文件的字符串内容
|
||||
* @throws NotFoundResourceException 当资源不存在时抛出
|
||||
*/
|
||||
@JvmStatic
|
||||
@Throws(IOException::class)
|
||||
fun getStringResource(resourceName: String, clazz: Class<*>): String {
|
||||
return clazz.getResourceAsStream(resourceName)?.use {
|
||||
it.readBytes().toString(charset = Charsets.UTF_8)
|
||||
} ?: throw IOException("Resource not found: $resourceName")
|
||||
fun getResourceAsString(path: String, clazz: Class<*>): String {
|
||||
// 委托给上面的方法,使用系统默认字符集
|
||||
return getResourceAsString(path, Charset.defaultCharset(), clazz)
|
||||
}
|
||||
|
||||
/**
|
||||
* 从调用者的类路径中加载指定名称的资源文件,并以字符串形式返回。
|
||||
* 从类路径中读取资源文件并返回字节数组(核心实现方法)
|
||||
*
|
||||
* @param resourceName 资源文件的名称(相对于类路径根目录)。
|
||||
* @return 资源文件的内容作为字符串(使用UTF-8编码)。
|
||||
* @throws IOException 如果资源未找到或读取失败时抛出。
|
||||
* 这是所有方法的核心实现,负责实际的资源查找和读取工作
|
||||
*
|
||||
* @param path 资源文件路径
|
||||
* - 如果以 "/" 开头:表示从 classpath 根目录查找
|
||||
* - 如果不以 "/" 开头:表示相对于 clazz 所在包的路径
|
||||
* @param clazz 参考类,用于确定相对路径的基准包
|
||||
* @return 资源的完整字节数组(使用 readAllBytes() 一次性读取)
|
||||
* @throws NotFoundResourceException 当资源文件不存在时抛出,错误信息会显示完整的查找路径
|
||||
*
|
||||
* 资源查找规则说明:
|
||||
* 1. 如果 path = "config.properties" 且 clazz = com.example.MyClass
|
||||
* 实际查找路径:/com/example/config.properties
|
||||
*
|
||||
* 2. 如果 path = "/config.properties"
|
||||
* 实际查找路径:/config.properties(classpath 根目录)
|
||||
*
|
||||
* 异常消息示例:
|
||||
* - 找不到文件时抛出:"/com/example/config.properties is not found"
|
||||
*/
|
||||
@JvmStatic
|
||||
@Throws(IOException::class)
|
||||
fun getStringResourceCallers(resourceName: String): String {
|
||||
return getStringResource(resourceName, getCallerClass())
|
||||
}
|
||||
fun getResourceAsByteArray(path: String, clazz: Class<*>): ByteArray {
|
||||
// 尝试从类路径中获取资源的输入流
|
||||
val stream = clazz.getResourceAsStream(path)
|
||||
?: throw NotFoundResourceException(
|
||||
// 构建详细的错误信息:显示实际查找的完整路径
|
||||
// 如果 path 不以 "/" 开头,则拼接类的包路径(将包名中的点替换为斜杠)
|
||||
(if (!path.startsWith("/"))
|
||||
"/${clazz.packageName.replace(".", "/")}/$path" // 相对路径:相对于 clazz 的包
|
||||
else
|
||||
path // 绝对路径:直接使用原路径
|
||||
) + " is not found" // 添加 " is not found" 后缀
|
||||
)
|
||||
|
||||
/**
|
||||
* 从调用者的类路径中加载指定名称的资源文件,并以字节数组形式返回。
|
||||
*
|
||||
* @param resourceName 资源文件的名称(相对于类路径根目录)。
|
||||
* @return 资源文件的内容作为字节数组。
|
||||
* @throws IOException 如果资源未找到或读取失败时抛出。
|
||||
*/
|
||||
@JvmStatic
|
||||
@Throws(IOException::class)
|
||||
fun getResourceCallers(resourceName: String): ByteArray {
|
||||
return getResource(resourceName, getCallerClass())
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取当前调用栈中第一个非ResourceUtils类的调用者类。
|
||||
*
|
||||
* @return 调用者类对象;如果未找到则返回ResourceUtils类本身。
|
||||
*/
|
||||
private fun getCallerClass(): Class<*> {
|
||||
val stackTrace = Thread.currentThread().stackTrace
|
||||
for (i in 2 until stackTrace.size) {
|
||||
val className = stackTrace[i].className
|
||||
try {
|
||||
val clazz = Class.forName(className)
|
||||
if (clazz != ResourceUtils::class.java) {
|
||||
return clazz
|
||||
}
|
||||
} catch (e: ClassNotFoundException) {
|
||||
continue
|
||||
}
|
||||
}
|
||||
return ResourceUtils::class.java
|
||||
// 读取输入流中的所有字节并返回
|
||||
// Kotlin 的扩展函数,等同于 Java 9+ 的 InputStream.readAllBytes()
|
||||
return stream.readAllBytes()
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user