SpringBoot动态图片获取缩略图方案

<!-- springweb核心依赖 -->
<dependency>
    <groupid>org.springframework.boot</groupid>
    <artifactid>spring-boot-starter-web</artifactid>
</dependency>
<!-- hutool工具类（io、读图兜底、字符串处理） -->
<dependency>
    <groupid>cn.hutool</groupid>
    <artifactid>hutool-all</artifactid>
    <version>5.7.16</version>
</dependency>
<!-- 通用工具类 -->
<dependency>
    <groupid>org.apache.commons.lang3</groupid>
    <artifactid>commons-lang3</artifactid>
    <version>3.20.0</version>
</dependency>
<!-- 核心缩略引擎 -->
<dependency>
      <groupid>net.coobird</groupid>
      <artifactid>thumbnailator</artifactid>
      <version>0.4.20</version>
</dependency>

import com.zhang.interceptor.thumbnailinterceptor;
import org.springframework.context.annotation.configuration;
import org.springframework.web.servlet.config.annotation.corsregistry;
import org.springframework.web.servlet.config.annotation.interceptorregistry;
import org.springframework.web.servlet.config.annotation.resourcehandlerregistry;
import org.springframework.web.servlet.config.annotation.webmvcconfigurationsupport;

/**
 * webmvc全局配置类
 * 1. 注册动态图片缩略拦截器，精准拦截业务图片路径
 * 2. 全覆盖本地静态资源映射
 * 3. 自定义业务文件磁盘路径映射，适配缩略图功能
 * 4. 全局跨域配置、资源缓存规范配置
 * @author z
 */
@configuration
public class webmvcconfig extends webmvcconfigurationsupport {

    /** 业务文件请求路径前缀（与拦截器保持统一） */
    private static final string business_file_pattern = "/businessfile/**";
    /** 本地业务文件磁盘路径 */
    private static final string business_file_local_path = "file:e:\\project_files\\file\\businessfile\\";

    /**
     * 注册缩略图拦截器
     * 精准拦截业务图片路径，零侵入其他静态资源
     */
    @override
    protected void addinterceptors(interceptorregistry registry) {
        registry.addinterceptor(new thumbnailinterceptor())
                .addpathpatterns(business_file_pattern)
                // 可根据业务扩展排除路径
                .excludepathpatterns();
    }

    /**
     * 全局静态资源映射
     * 整合系统默认静态资源路径 + 业务磁盘文件路径
     * 规范缓存策略，避免缩略图缓存冲突
     */
    @override
    protected void addresourcehandlers(resourcehandlerregistry registry) {
        // 系统通用静态资源映射（页面、js、css等）
        registry.addresourcehandler("/**")
                .addresourcelocations("classpath:/web-inf/")
                .addresourcelocations("classpath:/meta-inf/resources/")
                .addresourcelocations("classpath:/resources/")
                .addresourcelocations("classpath:/static/")
                .addresourcelocations("classpath:/public/")
                .addresourcelocations("classpath:/test/")
                // 静态资源短缓存，实时更新
                .setcacheperiod(60);

        // 业务图片文件专属映射（对接缩略拦截器核心路径）
        registry.addresourcehandler(business_file_pattern)
                .addresourcelocations(business_file_local_path.replace("\\", "/"))
                .setcacheperiod(0);
    }

    /**
     * 全局跨域配置
     * 适配前后端分离项目，解决图片跨域访问问题
     */
    @override
    protected void addcorsmappings(corsregistry registry) {
        registry.addmapping("/**")
                .allowcredentials(true)
                .allowedorigins("*")
                .allowedheaders("*")
                .allowedmethods("get", "post", "put", "delete", "options")
                .maxage(3600);
    }
}

import cn.hutool.core.io.ioutil;
import cn.hutool.core.util.strutil;
import cn.hutool.core.img.imgutil;
import lombok.getter;
import net.coobird.thumbnailator.thumbnails;
import org.apache.commons.lang3.stringutils;
import org.slf4j.logger;
import org.slf4j.loggerfactory;
import org.springframework.lang.nonnull;
import org.springframework.lang.nullable;
import org.springframework.stereotype.component;
import org.springframework.web.servlet.handlerinterceptor;
import org.springframework.web.servlet.modelandview;

import javax.imageio.imageio;
import javax.servlet.servletcontext;
import javax.servlet.http.httpservletrequest;
import javax.servlet.http.httpservletresponse;
import java.awt.graphics2d;
import java.awt.renderinghints;
import java.awt.color;
import java.awt.alphacomposite;
import java.awt.image.bufferedimage;
import java.awt.image.colormodel;
import java.awt.image.componentcolormodel;
import java.io.bufferedinputstream;
import java.io.file;
import java.io.inputstream;
import java.io.outputstream;
import java.io.fileoutputstream;
import java.io.ioexception;
import java.net.urldecoder;
import java.nio.charset.standardcharsets;
import java.nio.file.files;
import java.nio.file.path;
import java.nio.file.paths;
import java.text.simpledateformat;
import java.time.zoneid;
import java.time.zoneddatetime;
import java.time.format.datetimeformatter;
import java.util.date;
import java.util.locale;
import java.util.map;
import java.util.arraylist;
import java.util.linkedhashmap;
import java.util.collections;
import java.util.comparator;
import java.util.list;
import java.util.timezone;
import java.util.concurrent.concurrenthashmap;

/**
 * 图片缩略图动态生成拦截器
 * 核心优化：路径防越权、lru缓存、cmyk色彩修复、流隔离零泄漏、双读图兜底、安全响应头、线程安全时间
 * 业务逻辑：无w/h参数返回原图，带参数实时生成缩略图，无临时文件落地
 * 安全特性：魔数校验、参数多层防御、目录遍历拦截、大小限流、画布限流
 * 性能特性：零内存泄漏、零io冗余、高并发缓存稳定、低cpu占用
 *
 * @author z
 */
@component
public class thumbnailinterceptor implements handlerinterceptor {

    private static final logger logger = loggerfactory.getlogger(thumbnailinterceptor.class);

    /** 上传路径前缀 */
    private static final string local_file_prefix = "businessfile";
    /** 【单位：秒】图片缓存有效期 365天 */
    private static final long max_cache_second = 31536000l;
    /** 文件魔数读取字节长度 */
    private static final int magic_header_read_len = 16;
    /** 单张图片最大限制10mb，防止堆内存溢出 */
    private static final long max_image_byte_size = 10 * 1024 * 1024l;
    /** 缩略图宽高上限，避免超大画布渲染阻塞 */
    private static final int max_thumb_size = 1200;
    /** 缩略图生成方案开关：true=thumbnails工具，false=原生graphics2d */
    private static final boolean use_thumbnails_tool = true;
    /** mime类型缓存最大容量，lru淘汰 */
    private static final int mime_cache_max_size = 256;

    /**
     * lru同步缓存：请求路径 -> mime类型
     * linkedhashmap重写淘汰规则，超容量移除最久未访问key
     */
    private static final map<string, string> mime_cache =
            collections.synchronizedmap(new linkedhashmap<string, string>(mime_cache_max_size, 0.75f, true) {
                @override
                protected boolean removeeldestentry(map.entry<string, string> eldest) {
                    return size() > mime_cache_max_size;
                }
            });
    /** mime缓存读写同步锁，保证原子操作 */
    private static final object cache_lock = new object();
    /** 线程安全gmt时间格式化器，用于expires响应头 */
    private static final datetimeformatter gmt_formatter = datetimeformatter
            .ofpattern("eee, dd mmm yyyy hh:mm:ss zzz", locale.us)
            .withzone(zoneid.of("gmt"));

    /** 上传文件根路径，懒加载全局单例 */
    private static string upload_root = null;
    /** 根路径初始化标记，避免重复异常打印 */
    private static boolean init_root_flag = false;

    /**
     * 图片魔数映射：文件头部十六进制魔数 -> 图片后缀
     * 支持jpg/png/bmp三种主流图片
     */
    public static final map<string, string> img_type_map = new concurrenthashmap<>();
    /**
     * 魔数排序列表：按魔数字符长度倒序，长魔数优先匹配，避免短前缀误判
     */
    public static final list<map.entry<string, string>> sorted_magic_list;

    static {
        // 初始化图片魔数
        img_type_map.put("ffd8ff", "jpg");
        img_type_map.put("ffd8", "jpeg");
        img_type_map.put("89504e47", "png");
        img_type_map.put("424d228c010000000000", "bmp");
        img_type_map.put("424d8240090000000000", "bmp");
        img_type_map.put("424d8e1b030000000000", "bmp");
        img_type_map.put("424d", "bmp");

        // 按魔数字符长度倒序排序
        sorted_magic_list = new arraylist<>(img_type_map.entryset());
        sorted_magic_list.sort(comparator.comparingint(e -> -e.getkey().length()));

        // 加载全局imageio解码器，解决部分环境图片读取失败
        imageio.scanforplugins();
    }

    // ====================== 前置拦截入口 ======================
    /**
     * 请求前置拦截核心逻辑
     * 1. 初始化上传根路径
     * 2. 路径解码、非法路径拦截、文件存在/大小校验
     * 3. 参数w/h合法性校验（支持单参数自适应缩放）
     * 4. 文件魔数校验，拦截伪造后缀文件
     * 5. cmyk图片自动转rgb
     * 6. 生成缩略图写入响应流；异常重置缓冲区返回原图
     */
    @override
    public boolean prehandle(@nonnull httpservletrequest request, @nonnull httpservletresponse response,
                             @nullable object handler) throws exception {

        // 懒加载上传根路径
        inituploadroot();

        // 未配置上传根路径，直接放行不处理缩略
        if (strutil.isblank(upload_root)) {
            return true;
        }

        string requesturl;
        try {
            // url解码处理中文文件名
            requesturl = urldecoder.decode(request.getservletpath(), standardcharsets.utf_8.name());
        } catch (illegalargumentexception e) {
            logger.warn("url路径解码失败，非法字符", e);
            return true;
        }

        if (logger.isdebugenabled()) {
            logger.debug("进入缩略拦截器，请求路径：{}", requesturl);
        }

        // 空路径直接放行
        if (stringutils.isblank(requesturl)) {
            return true;
        }

        // 非图片后缀请求直接放行
        if (!isimagerequest(requesturl)) {
            return true;
        }

        // 先写入缓存相关响应头
        setimagecacheheader(request, response, requesturl);

        string widthparam = request.getparameter("w");
        string heightparam = request.getparameter("h");
        // 无缩放尺寸参数，返回原图
        if (stringutils.isblank(widthparam) && stringutils.isblank(heightparam)) {
            if (logger.isdebugenabled()) {
                logger.debug("无w/h缩放参数，直接返回原图，路径url：{}", requesturl);
            }
            return true;
        }

        // 防御：超长参数字符串，避免大数解析溢出
        if ((widthparam != null && widthparam.length() > 10) || (heightparam != null && heightparam.length() > 10)) {
            logger.warn("宽高参数字符串过长，非法参数 w={},h={}", widthparam, heightparam);
            return true;
        }

        boolean widthvalid = true;
        boolean heightvalid = true;

        // 宽度参数非空，校验合法性
        if (stringutils.isnotblank(widthparam)) {
            try {
                int w = integer.parseint(widthparam);
                if (w < 1 || w > max_thumb_size) {
                    widthvalid = false;
                }
            } catch (numberformatexception e) {
                widthvalid = false;
            }
        }

        // 高度参数非空，校验合法性
        if (stringutils.isnotblank(heightparam)) {
            try {
                int h = integer.parseint(heightparam);
                if (h < 1 || h > max_thumb_size) {
                    heightvalid = false;
                }
            } catch (numberformatexception e) {
                heightvalid = false;
            }
        }

        // 任意参数非法，直接返回原图
        if (!widthvalid || !heightvalid) {
            logger.warn("宽高参数不合法，超出范围[1,{}] w={},h={}", max_thumb_size, widthparam, heightparam);
            return true;
        }

        // 解析目标宽高，空参数默认0（用于自适应计算）
        int targetwidth = stringutils.isnotblank(widthparam) ? integer.parseint(widthparam) : 0;
        int targetheight = stringutils.isnotblank(heightparam) ? integer.parseint(heightparam) : 0;

        // 宽高均为0无缩放意义，返回原图
        if (targetwidth <= 0 && targetheight <= 0) {
            return true;
        }

        // 限制最大值，不限制最小值（保留0用于自适应）
        targetwidth = math.min(targetwidth, max_thumb_size);
        targetheight = math.min(targetheight, max_thumb_size);

        // 路径安全校验：拦截../目录遍历
        string subpath = requesturl.replace(local_file_prefix, "");
        if (subpath.contains("..")) {
            logger.warn("路径包含非法上级跳转字符，拒绝处理 url:{}", requesturl);
            return true;
        }
        path fullfilepath = paths.get(upload_root, subpath).normalize();
        path rootpath = paths.get(upload_root).normalize();
        // 校验文件路径严格在上传根目录内，防止越权访问
        if (!fullfilepath.startswith(rootpath)) {
            logger.warn("文件路径越出上传根目录，拒绝处理 url:{}", requesturl);
            return true;
        }

        file sourceimagefile = fullfilepath.tofile();
        string imagelocalpath = fullfilepath.tostring();

        // 文件不存在/非普通文件直接放行
        if (!sourceimagefile.exists() || !sourceimagefile.isfile()) {
            logger.warn("目标图片文件不存在或非文件，路径：{}", imagelocalpath);
            return true;
        }

        // 超大文件拦截，防止oom
        long filelen = sourceimagefile.length();
        if (filelen > max_image_byte_size) {
            logger.warn("图片超出10mb上限，直接返回原图 path={}", imagelocalpath);
            return true;
        }
        // 空文件拦截
        if (filelen == 0) {
            logger.warn("图片文件为空，返回原图 path={}", imagelocalpath);
            return true;
        }

        // try-with-resources 自动关闭响应输出流，避免句柄泄漏
        try (outputstream outstream = response.getoutputstream()) {
            string realimgsuffix;
            // 独立流读取魔数，不消耗原图数据流
            try (inputstream magicis = new bufferedinputstream(files.newinputstream(sourceimagefile.topath()))) {
                magicresult magicresult = getfilemagicsuffix(magicis);
                realimgsuffix = magicresult.getsuffix();
            }

            // 魔数不匹配，判定为伪造后缀文件，返回原图
            if (strutil.isblank(realimgsuffix) || isnotimagesuffix(realimgsuffix)) {
                logger.info("魔数校验非合法图片，返回原图 url:{}", requesturl);
                return true;
            }

            bufferedimage originalimage = null;
            // 优先imageio读取原图
            try (inputstream imgis = new bufferedinputstream(files.newinputstream(sourceimagefile.topath()))) {
                originalimage = imageio.read(imgis);
            }

            // imageio读取失败，使用hutool兜底读取
            if (originalimage == null) {
                try (inputstream imgis2 = new bufferedinputstream(files.newinputstream(sourceimagefile.topath()))) {
                    originalimage = imgutil.read(imgis2);
                } catch (exception e) {
                    logger.error("兜底读取图片失败 path={}", imagelocalpath, e);
                    return true;
                }
            }

            // 双读取方案均失败，判定为损坏文件
            if (originalimage == null) {
                logger.error("图片读取失败，文件损坏或格式不支持 path={}", imagelocalpath);
                return true;
            }

            // cmyk四通道jpg自动转为rgb，避免色彩失真
            if ("jpg".equals(realimgsuffix) || "jpeg".equals(realimgsuffix)) {
                colormodel cm = originalimage.getcolormodel();
                if (cm instanceof componentcolormodel && cm.getnumcolorcomponents() == 4) {
                    bufferedimage rgbimg = new bufferedimage(originalimage.getwidth(), originalimage.getheight(), bufferedimage.type_3byte_bgr);
                    graphics2d g = rgbimg.creategraphics();
                    g.setcomposite(alphacomposite.src);
                    g.drawimage(originalimage, 0, 0, null);
                    g.dispose();
                    originalimage.flush();
                    originalimage = rgbimg;
                }
            }

            // 计算等比例缩放后的实际宽高，禁止放大原图
            int finalw = calcscalewidth(targetwidth, targetheight, originalimage);
            int finalh = calcscaleheight(targetwidth, targetheight, originalimage);
            finalw = math.min(finalw, originalimage.getwidth());
            finalh = math.min(finalh, originalimage.getheight());

            boolean thumbrenderok = true;
            try {
                // 匹配原图后缀输出格式
                string outputformat = "png";
                if ("jpg".equals(realimgsuffix) || "jpeg".equals(realimgsuffix)) {
                    outputformat = "jpg";
                }
                // 选择缩略生成器
                if (use_thumbnails_tool) {
                    generatethumbbythumbnails(originalimage, finalw, finalh, outstream, outputformat);
                } else {
                    generatethumbbygraphics2d(originalimage, finalw, finalh, outstream, outputformat);
                }
                outstream.flush();
            } catch (exception e) {
                thumbrenderok = false;
                logger.error("缩略图渲染生成异常", e);
            } finally {
                originalimage.flush();
            }
            // 渲染失败：清空缓冲区，重写缓存头，返回原图
            if (!thumbrenderok) {
                response.resetbuffer();
                setimagecacheheader(request, response, requesturl);
                return true;
            }
        } catch (exception e) {
            logger.error("响应流读写异常", e);
            return true;
        }

        // 缩略图正常输出，拦截后续静态资源处理
        logger.info("缩略图完成，输出正常！");
        return false;
    }

    /** 后置拦截器，无业务逻辑 */
    @override
    public void posthandle(@nonnull httpservletrequest request, @nonnull httpservletresponse response,
                           @nullable object handler, modelandview modelandview) {
    }

    /** 请求完成回调，无业务逻辑 */
    @override
    public void aftercompletion(@nonnull httpservletrequest request, @nonnull httpservletresponse response,
                                @nullable object handler, @nullable exception ex) {
    }

    // ====================== 缓存响应头 ======================
    /**
     * 设置图片缓存、安全响应头
     * cache-control长缓存、xss防护、csp限制图片加载源
     */
    private void setimagecacheheader(httpservletrequest request, httpservletresponse response, string requesturl) {
        response.setheader("cache-control", "public, max-age=" + max_cache_second);
        // 防止浏览器mime嗅探xss
        response.setheader("x-content-type-options", "nosniff");
        // csp：仅允许本站+内联base64图片，禁止外部图片加载
        response.setheader("content-security-policy", "default-src 'self'; img-src 'self' data:;");

        // 生成gmt标准过期时间
        string gmtexpirestr;
        try {
            zoneddatetime expiretime = zoneddatetime.now().plusseconds(max_cache_second);
            gmtexpirestr = gmt_formatter.format(expiretime);
        } catch (exception e) {
            // 格式化器异常降级使用simpledateformat兜底
            simpledateformat sdfgmt = new simpledateformat("eee, dd mmm yyyy hh:mm:ss zzz", locale.us);
            sdfgmt.settimezone(timezone.gettimezone("gmt"));
            gmtexpirestr = sdfgmt.format(new date(system.currenttimemillis() + max_cache_second * 1000));
        }

        response.setheader("expires", gmtexpirestr);
        response.setcharacterencoding(standardcharsets.utf_8.name());

        // 缓存mime类型，减少重复获取
        string mime;
        synchronized (cache_lock) {
            mime = mime_cache.get(requesturl);
            if (mime == null) {
                string tempmime = null;
                servletcontext context = request.getservletcontext();
                if (context != null) {
                    tempmime = context.getmimetype(requesturl);
                }
                mime = strutil.isblank(tempmime) ? "image/png" : tempmime;
                mime_cache.put(requesturl, mime);
            }
        }
        response.setcontenttype(mime);
    }

    // ====================== 请求路径判断 ======================
    /** 判断请求路径是否为图片后缀 */
    private boolean isimagerequest(string requesturl) {
        string lowerurl = requesturl.tolowercase();
        string[] splitarr = lowerurl.split("[?#]");
        string purepath = splitarr.length > 0 ? splitarr[0] : "";
        return purepath.endswith(".jpg")
                || purepath.endswith(".jpeg")
                || purepath.endswith(".png")
                || purepath.endswith(".bmp");
    }

    /** 魔数匹配返回结果 */
    @getter
    public static class magicresult {
        private string suffix;
        magicresult(string suffix) {
            this.suffix = suffix;
        }
    }

    // ====================== 魔数工具（兼容不支持mark的流） ======================
    /**
     * 读取文件头部16字节魔数，识别真实图片格式
     * mark/reset 重置流指针，不消耗原始文件流数据
     */
    public static magicresult getfilemagicsuffix(inputstream in) {
        try {
            // 标记流起始位置，读取后回滚
            if (in.marksupported()) {
                in.mark(magic_header_read_len);
            }
            // 读取最多16字节
            byte[] temp = ioutil.readbytes(in, magic_header_read_len);
            // 固定16字节数组，不足补0，避免短文件匹配失效
            byte[] headerbytes = new byte[magic_header_read_len];
            // 复制有效数据，不足部分补0
            system.arraycopy(temp, 0, headerbytes, 0, temp.length);
            // 可回退流则重置指针
            if (in.marksupported()) {
                in.reset();
            }
            string hex = bytearraytoupperhex(headerbytes);
            string suffix = matchmagicmap(hex);
            return new magicresult(suffix);
        } catch (exception e) {
            logger.error("读取文件魔数io异常", e);
            return new magicresult(null);
        }
    }

    /** byte数组转大写十六进制字符串，单字节补0 */
    private static string bytearraytoupperhex(@nullable byte[] bytes) {
        if (bytes == null || bytes.length == 0) {
            return "";
        }
        stringbuilder sb = new stringbuilder();
        for (byte b : bytes) {
            int val = b & 0xff;
            string hex = integer.tohexstring(val);
            if (hex.length() == 1) {
                sb.append('0');
            }
            sb.append(hex);
        }
        return sb.tostring().touppercase();
    }

    /**
     * 魔数匹配逻辑
     * 长魔数优先，严格校验魔数字长，杜绝短前缀误匹配
     */
    private static string matchmagicmap(string filestreamhexhead) {
        if (logger.isdebugenabled()) {
            logger.debug("文件魔数字符串：{}", filestreamhexhead);
        }
        for (map.entry<string, string> entry : sorted_magic_list) {
            string magickey = entry.getkey();
            // 优化：改为完整等长匹配，杜绝前缀误匹配
            if (filestreamhexhead.startswith(magickey) && magickey.length() <= filestreamhexhead.length()) {
                return entry.getvalue();
            }
        }
        return null;
    }

    /** 忽略大小写前缀匹配工具 */
    public static boolean startwithignorecase(@nullable charsequence str, @nullable charsequence prefix) {
        if (str == null && prefix == null) {
            return true;
        }
        if (str == null || prefix == null) {
            return false;
        }
        string strlow = str.tostring().tolowercase();
        string prelow = prefix.tostring().tolowercase();
        return strlow.startswith(prelow);
    }

    /** 判断【是否为合法图片】后缀 */
    public static boolean isimagesuffix(string type) {
        return strutil.equalsanyignorecase(type, "jpg", "jpeg", "png", "bmp");
    }

    /** 判断【是否为不合法图片】后缀 */
    public static boolean isnotimagesuffix(string type) {
        return !isimagesuffix(type);
    }

    // ====================== 等比例缩放计算 ======================
    /** 计算等比例缩放目标宽度，原图不放大 */
    private static int calcscalewidth(int targetw, int targeth, @nonnull bufferedimage source) {
        if (source == null) {
            logger.error("原图bufferedimage为空");
            return targetw;
        }
        int w = source.getwidth();
        int h = source.getheight();
        // 防除零异常
        if (w <= 0 || h <= 0) {
            return targetw > 0 ? targetw : targeth;
        }
        double scale = (double) w / h;
        return targetw > 0 ? targetw : (int) math.floor(targeth * scale);
    }

    /** 计算等比例缩放目标高度，原图不放大 */
    private static int calcscaleheight(int targetw, int targeth, @nonnull bufferedimage source) {
        if (source == null) {
            logger.error("原图bufferedimage为空");
            return targeth;
        }
        int w = source.getwidth();
        int h = source.getheight();
        if (w <= 0 || h <= 0) {
            return targeth > 0 ? targeth : targetw;
        }
        double scale = (double) w / h;
        return targeth > 0 ? targeth : (int) math.floor(targetw / scale);
    }

    // ====================== 两套缩略图生成（新增输出格式参数，修复jpg透明黑底） ======================
    /** thumbnails工具生成缩略图 */
    private static void generatethumbbythumbnails(bufferedimage originalimage, int w, int h, outputstream out, string format) throws ioexception {
        int imagetype = "png".equals(format) ? bufferedimage.type_int_argb : bufferedimage.type_3byte_bgr;
        thumbnails.of(originalimage)
                .imagetype(imagetype)
                .size(w, h)
                .keepaspectratio(true)
                .outputquality(0.85)
                .outputformat(format)
                .tooutputstream(out);
    }

    /** 原生graphics2d绘制缩略图，无第三方依赖 */
    private static void generatethumbbygraphics2d(bufferedimage originalimage, int w, int h, outputstream out, string format) throws ioexception {
        int imagetype = "png".equals(format) ? bufferedimage.type_int_argb : bufferedimage.type_3byte_bgr;
        bufferedimage thumbnail = new bufferedimage(w, h, imagetype);
        graphics2d g2d = null;
        try {
            g2d = thumbnail.creategraphics();
            // 抗锯齿、高清插值缩放
            g2d.setrenderinghint(renderinghints.key_antialiasing, renderinghints.value_antialias_on);
            g2d.setrenderinghint(renderinghints.key_interpolation, renderinghints.value_interpolation_bilinear);
            // png透明、jpg白底
            if ("png".equals(format)) {
                g2d.setbackground(new color(0, 0, 0, 0));
            } else {
                g2d.setbackground(color.white);
            }
            g2d.clearrect(0, 0, w, h);
            g2d.drawimage(originalimage, 0, 0, w, h, null);
            imageio.write(thumbnail, format, out);
        } finally {
            if (g2d != null) {
                g2d.dispose();
            }
            thumbnail.flush();
        }
    }

    /**
     * 懒加载上传根路径，全局仅初始化一次
     * 从spring配置类读取上传根目录，读取失败置为空
     */
    private static void inituploadroot() {
        if (init_root_flag) {
            return;
        }
        init_root_flag = true;
        try {
            // 【生产适配】此处可替换为yml配置读取，解耦硬编码
            upload_root = "e:\\project_files\\test-project\\file\\";
        } catch (exception e) {
            logger.error("初始化上传根路径失败，缩略功能关闭", e);
            upload_root = "";
        }
    }


    // ====================== 本地测试main ======================
    public static void main(string[] args) {
        // 本地测试强制覆盖上传根路径，跳过spring上下文获取
        upload_root = "e:\\project_files\\test-project\\file\\";
        init_root_flag = true;

        try {
            string mockuploadroot = "e:\\project_files\\test-project\\file\\";
            string testrequesturl = "/businessfile/123123.png";
            string widthparam = "400";
            string heightparam = "300";
            string outdir = "e:\\project_files\\test-project\\file\\businessfile" + file.separator;

            // main 内部替换这段路径代码
            string subpath = testrequesturl.replace(local_file_prefix, "");
            // 去掉开头斜杠
            subpath = subpath.startswith("/") ? subpath.substring(1) : subpath;
            path fullfilepath = paths.get(mockuploadroot, subpath);
            // windows 手动拼接
            string fullpathstr = mockuploadroot + file.separator + subpath.replace("/", file.separator);
            file sourceimg = new file(fullpathstr);
            system.out.println("文件是否存在：" + sourceimg.exists());
            system.out.println("是否为文件：" + sourceimg.isfile());
            system.out.println("文件大小 byte：" + sourceimg.length());
            testsingleread(sourceimg);

            if (!sourceimg.exists() || !sourceimg.isfile()) {
                logger.error("【测试失败】原图不存在 path={}", fullfilepath);
                return;
            }
            system.out.println("浏览器地址：" + testrequesturl);
            system.out.println("本地文件：" + fullfilepath);

            if (stringutils.isblank(widthparam) && stringutils.isblank(heightparam)) {
                system.out.println("无缩放参数，模拟详情页，不生成缩略图");
                return;
            }

            int targetwidth, targetheight;
            try {
                targetwidth = stringutils.isnotblank(widthparam) ? integer.parseint(widthparam) : 0;
                targetheight = stringutils.isnotblank(heightparam) ? integer.parseint(heightparam) : 0;
                // 新增二次校验
                if(targetwidth < 1 || targetwidth > max_thumb_size || targetheight < 1 || targetheight > max_thumb_size){
                    logger.warn("宽高数值超出范围 1~{} w={},h={}",max_thumb_size,widthparam,heightparam);
                    return;
                }
            } catch (numberformatexception e) {
                system.out.println("宽高参数非法，终止测试");
                return;
            }
            if (targetwidth <= 0 && targetheight <= 0) {
                system.out.println("宽高无缩放需求，终止测试");
                return;
            }
            targetwidth = math.min(math.max(targetwidth, 1), max_thumb_size);
            targetheight = math.min(math.max(targetheight, 1), max_thumb_size);

            bufferedimage originalimage;
            magicresult magicresult;
            // 独立流读取魔数，不污染图片读取流
            try (inputstream magicis = new bufferedinputstream(files.newinputstream(sourceimg.topath()))) {
                magicresult = getfilemagicsuffix(magicis);
            }
            system.out.println("魔数识别类型：" + magicresult.getsuffix());
            if (strutil.isblank(magicresult.getsuffix()) || isnotimagesuffix(magicresult.getsuffix())) {
                system.out.println("非图片文件，终止测试");
                return;
            }
            // 全新流从头读取完整图片
            try (inputstream imgis = new bufferedinputstream(files.newinputstream(sourceimg.topath()))) {
                originalimage = imageio.read(imgis);
            }
            // imageio读取失败，新开流使用hutool
            if (null == originalimage) {
                try (inputstream imgis2 = new bufferedinputstream(files.newinputstream(sourceimg.topath()))) {
                    originalimage = imgutil.read(imgis2);
                }
            }

            if (null == originalimage) {
                system.out.println("图片读取失败，文件损坏");
                return;
            }
            system.out.printf("原图尺寸：%d × %d%n", originalimage.getwidth(), originalimage.getheight());

            int finalw = calcscalewidth(targetwidth, targetheight, originalimage);
            int finalh = calcscaleheight(targetwidth, targetheight, originalimage);
            finalw = math.min(finalw, originalimage.getwidth());
            finalh = math.min(finalh, originalimage.getheight());
            system.out.printf("缩略图尺寸：%d × %d%n", finalw, finalh);

            file dir = new file(outdir);
            if (!dir.exists()) {
                dir.mkdirs();
            }

            string fmt = "jpg".equals(magicresult.getsuffix()) || "jpeg".equals(magicresult.getsuffix()) ? "jpg" : "png";
            file out1 = new file(outdir + "thumb_test_方案一_thumbnails." + fmt);
            try (outputstream outstream1 = new fileoutputstream(out1)) {
                generatethumbbythumbnails(originalimage, finalw, finalh, outstream1, fmt);
            }
            system.out.println("【方案一】生成完成：" + out1.getabsolutepath());

            file out2 = new file(outdir + "thumb_test_方案二_graphics2d." + fmt);
            try (outputstream outstream2 = new fileoutputstream(out2)) {
                generatethumbbygraphics2d(originalimage, finalw, finalh, outstream2, out2, fmt);
            }
            system.out.println("【方案二】生成完成：" + out2.getabsolutepath());

            originalimage.flush();
            system.out.println("测试完成，线上推荐use_thumbnails_tool=true");
        } catch (exception e) {
            logger.error("main测试异常", e);
        }
    }

    @suppresswarnings("unused")
    private static void testsingleread(file file) {
        system.out.println("===== hutool 单独读取测试 =====");
        try (inputstream is = files.newinputstream(file.topath())) {
            bufferedimage img = imgutil.read(is);
            system.out.println("读取成功，图片宽：" + img.getwidth() + " 高：" + img.getheight());
        } catch (exception e) {
            e.printstacktrace();
        }
    }
}