This commit is contained in:
2026-06-21 10:41:28 +08:00
parent e00f8ad7a1
commit 60ec0e2883
38 changed files with 23987 additions and 614 deletions
@@ -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()
}
}