巡检照片与工单附件：jquick-pdf 图片嵌入的业务实战

巡检照片与工单附件jquick-pdf 图片嵌入的业务实战引入商品合同、巡检单和理赔报告常要把照片放进 PDF。真正的难点不是写一个image标签而是处理路径、尺寸、失败重试、临时文件和不可信 URL。本文以“巡检报告封面照片”为例讨论这类业务的资源治理照片从哪来、怎么落到磁盘、什么时候删、批量导出时内存如何控制。模板侧只使用已验证的本地图片标签网络图片在进入模板之前就被转换为受控本地文件。核心讲解现场照片的业务约束巡检、工单类照片有三个特点数量多一次巡检可能十几张、单张体积大手机原图常见数 MB、来源是用户设备且文件名不可信。它们直接决定三件事必须设置像素与字节上限必须支持批量且低内存地导出必须有失败兜底不能让一张坏图拖垮整单导出。依赖与运行基线JDK 8、Maven 3.6文档层核心依赖如下dependencygroupIdio.github.paohaijiao/groupIdartifactIdjquick-pdfx/artifactIdversion4.0.0/version/dependency按需追加jquick-pdf-font、jquick-pdf-svg、jquick-pdf-data、jquick-pdf-css。把img.png放到项目工作目录或改用绝对路径。完整示例ImageReportDemoimportcom.github.paohaijiao.executor.JQuickPdfFactory;// 导入工厂importjava.nio.file.Files;// 导入文件工具importjava.nio.file.Paths;// 导入路径工具publicclassImageReportDemo{// 声明类publicstaticvoidmain(String[]args)throwsException{// 声明入口StringimagePathsrc/main/resources/image/img.png;// 受控图片路径Stringtemplatepdfbody// 建立文档骨架h1巡检报告/h1// 报告标题p设备编号EQ-1001/p// 业务字段image src\imagePath\ style\width:200px;height:150px\/image// 嵌入照片p现场照片已归档/p// 说明文字/body/pdf;// 结束模板byte[]pdfnewJQuickPdfFactory().executeContent(template);// 执行渲染Files.write(Paths.get(image-report.pdf),pdf);// 写出 PDF}}模板与步骤拆解先确认文件存在并使用规范路径分隔符。用pdfbody建立文档骨架。文本节点使用单引号变量才使用${name}。image的src指向受控文件width、height控制版面。执行executeContent得到byte[]并写出。网络图片的流程是HTTP 客户端设置连接与读取超时校验 HTTPS、响应码、Content-Type 与大小下载至服务端随机命名的临时文件模板引用该文件导出完成后删除。安全校验的具体清单见上一篇“资源接入与安全边界”本篇不重复。关键细节Windows 路径写法与转义相对路径相对于进程工作目录不一定是源码目录生产环境建议使用绝对路径。反斜杠在 Java 字符串里要写成\\在模板属性里也容易出错统一使用/更省事例如D:/pdf/image.png。路径拼接不要用字符串相加把用户输入直接拼进去避免路径穿越文件名由服务端生成。临时文件生命周期与清理下载的图片写入隔离的临时目录文件名使用 UUID 或内容哈希。用 try/finally 或框架的资源钩子在导出结束后删除异常路径同样要清理。同一批次共用的图片如同一设备的多份报告只落地一次批次内复用批末统一清理。图片缓存策略以业务图片 ID 或内容 SHA-256 作为缓存键命中则跳过下载直接复用本地文件。缓存需要 TTL 与容量上限避免无限增长缓存区与临时区分离互不干扰。缓存失效要有明确触发条件图片 ID 变更、TTL 到期、容量淘汰否则旧图会长期占据磁盘。缓存命中率直接影响批量导出的耗时巡检类业务通常能命中同一设备的多份报告。下载超时与像素上限连接超时、读取超时都要设置批量下载要限制并发避免连接池与线程被打满。只校验字节大小不够还要限制像素尺寸。一个 4000×3000 的位图解码为位图数据约 4000×3000×4 字节接近 46MB手机原图很常见所以解码内存必须单独设上限。超限图片降级为缩略图或占位图保证报告本身能正常产出。批量图片导出的内存控制executeContent返回byte[]会整体驻留内存图片越多越大峰值越高。批量导出的典型骨架是逐张处理、立即落盘PathtempDirFiles.createTempDirectory(jquick-batch-);// 批次级隔离目录try{for(inti0;iphotoIds.size();i){// 逐张处理避免整批驻留内存PathphotoresolvePhoto(photoIds.get(i),tempDir);// 命中缓存则复用否则下载到临时目录Stringtemplatepdfbodyh1巡检报告/h1image src\photo// 单张模板\ style\width:200px;height:150px\/image/body/pdf;// 控制版面尺寸byte[]pdfnewJQuickPdfFactory().executeContent(template);// 生成单份 PDFFiles.write(Paths.get(report-i.pdf),pdf);// 立即落盘尽快释放if((i1)%100){cleanupFinished(tempDir);}// 每 10 张清理已用完的临时图片}}finally{deleteRecursively(tempDir);// 正常与异常路径都要清理}resolvePhoto、cleanupFinished、deleteRecursively属于应用层辅助方法不依赖任何模板能力。要点是分批、及时落盘、控制单页图片数量必要时用areaBreak让每页图片数可预期。实战说明验证步骤把img.png放到工作目录或用绝对路径改写imagePath。运行示例确认输出image-report.pdf的封面显示 200×150 的照片与上下文字。把imagePath改成不存在的文件确认业务层给出明确错误而不是产出无照片的报告。用 10 张以上照片做一次批量导出观察峰值内存并检查临时目录在结束后是否被清空。结果预期单张报告中按指定尺寸显示照片文字与图片顺序与模板一致。批量各批次文件均生成成功临时目录在批次结束后为空峰值内存随批次规模线性可控。失败样本坏图被替换为占位图或使该批次明确失败不会生成缺图但报告成功的文件。并发多任务同时导出时各自使用独立临时目录互相不会覆盖文件。生产注意事项原图过大会显著增加 PDF 体积不能只看 CSS 尺寸定价要按原图像素与压缩质量设上限。网络图片存在 SSRF、重定向与恶意超大文件风险先按上一篇的校验清单过滤再进入模板。PNG 透明背景在不同阅读器中的视觉表现可能不同。并发导出时限制下载与 PDF 任务队列避免内存峰值叠加。巡检照片常带 EXIF 方向信息方向纠正属于应用层处理不在模板能力范围内。适用于商品主图、证件照、签章前置照片、质检留痕、巡检照片等场景。可进一步增加图片方向纠正、缩略图缓存与失败占位页这些属于应用层逻辑不是本文验证的模板能力。总结本文的关键结论图片 PDF 的稳定性来自资源治理——受控目录、确定性命名、缓存与清理、超时与像素上限、分批导出模板只负责版面。常见误区在模板里拼用户 URL、用 URL 原始文件名落地、只限字节不限像素、一次性把整批图片读进内存。把资源安全与版面渲染分层巡检、工单类照片报告才能稳定上线。本文只依赖 jquick-pdfx 4.0.0 已验证的 image 语法网络直读未获源码证实因此采用“下载后本地渲染”的替代方案。版本基线jquick-pdfx 4.0.0、JDK 8升级前请核对 README_zh.md 的版本对照表更多示例见 GitHub 仓库。