ThumbnailUtil 图片压缩工具类
📦 包路径：
top.csaf.img.ThumbnailUtil🔗 所属模块：
zutil-img
ThumbnailUtil 是基于开源库 Thumbnailator (coobird) 的二次封装工具类。
它专注于指定文件大小的图片压缩场景，通过递归调整压缩质量（Quality），力求在保持尽可能高清晰度的前提下，将图片体积压缩到指定阈值（KB）以下。同时，该工具会将输出格式统一标准化为 JPG。
✨ 核心特性
- 指定大小压缩：支持设置目标文件的最大体积（单位 KB），工具会自动尝试压缩直到满足要求。
- 智能递归：内置递归压缩算法。如果一次压缩未达标，会重复压缩；若当前质量参数已达极限，会自动降低质量参数（步长 0.1）继续尝试，直到满足大小或质量无法再降。
- 自动转 JPG：为了获得更好的压缩比，输出文件会自动转换为
.jpg格式（若原路径后缀不是 jpg/jpeg，会自动修改）。
🚀 常用方法概览
1. 指定大小压缩 (Compress)
将图片压缩到指定大小（KB）以内。
| 方法名 | 描述 |
|---|---|
compress(source, target, size) | 使用默认初始质量 (0.9) 进行压缩。 |
compress(source, target, size, quality) | 自定义初始压缩质量进行压缩。 |
参数说明：
| 参数名 | 类型 | 描述 |
|---|---|---|
sourcePath | String | 源图片文件路径。 |
targetPath | String | 目标图片文件路径。注意：若后缀不是 .jpg 或 .jpeg，会自动修改为 .jpg。 |
targetSize | long | 期望的最大文件大小，单位 KB。 |
recursiveQuality | Double | (可选) 初始压缩质量（0 < q < 1）。默认为 0.9。 |
返回值：
long：压缩成功后的文件大小（字节 Bytes）。-1：压缩失败或发生异常。
逻辑细节：
- 校验：检查路径是否为空、源文件是否存在、目标大小是否合法。
- 转码：首先以初始质量将图片转换为 JPG 格式。
- 递归检查：
- 若当前文件大小 <= 目标大小，返回当前大小。
- 若文件大小 > 目标大小：
- 继续以当前质量压缩。
- 若压缩后大小无变化（进入瓶颈），则将质量降低
0.1后重试。 - 直到满足大小要求或质量降为 0。
示例代码：
// 1. 简单压缩：将 source.png 压缩到 200KB 以内，保存为 target.jpg
// 默认初始质量 0.9
long size1 = ThumbnailUtil.compress("docs/img/source.png", "docs/img/target.jpg", 200L);
// 2. 自定义质量压缩：初始质量 0.8
// 如果 target.png 后缀不是 jpg，会自动改为 target.jpg
long size2 = ThumbnailUtil.compress("docs/img/source.png", "docs/img/target.png", 500L, 0.8);
if (size1 != -1) {
System.out.println("压缩成功，文件大小：" + size1 + " 字节");
}
⚠️ 注意事项
- JPG 转换：该工具类强制将输出格式转为 JPG，因为 JPG 在有损压缩方面表现较好，适合控制文件体积。输入路径中的透明通道（如 PNG）可能会变黑或丢失。
- 性能开销：由于采用递归压缩（可能进行多次 IO 操作和图片处理），在处理超大图片或极小目标体积时可能会消耗较多时间。
- 依赖：本项目依赖
net.coobird:thumbnailator库。