Spring Boot 通过 FTL 模板动态生成图片（HTML 生成图片 imgBase64）

一、背景与问题

在现代 Web 应用中，动态生成图片的需求非常普遍。例如：

个性化证书生成（姓名、日期、印章等动态字段）
报告生成（表格、图表、文字排版）
图标生成（基于用户输入的样式参数）

传统方案通常采用以下模式：

前端生成静态图片（如 PNG/SVG）
后端生成静态图片（如使用 Java 的 BufferedImage API）
使用图形库生成动态图片（如使用 JavaFX 或 Apache PDFBox）

但这些方案都存在局限性：

静态图片无法动态渲染字段
图形库需要复杂坐标计算
跨平台兼容性差

本文提出的解决方案是：通过 Thymeleaf 模板引擎动态生成 HTML，利用 HTML5 Canvas 实现图片渲染，最终输出为 base64 编码的图片数据。这种方法具有以下优势：

动态渲染能力（支持任意文本/样式）
前端开发友好（直接使用 HTML/CSS）
跨平台兼容（支持所有现代浏览器）
可复用性（模板可被前端直接调用）

二、基本原理

整个流程分为四个核心步骤：

1. 模板渲染

使用 Thymeleaf 模板引擎，将动态数据插入到 HTML 模板中，生成完整的 HTML 内容。

2. HTML 转换

通过 jsoup 或 Jsoup 等库将 HTML 转换为 DOM 结构，便于后续操作。

3. Canvas 渲染

利用 HTML5 Canvas API 将 HTML 内容绘制到画布上，生成图片数据。

4. Base64 编码

将 Canvas 生成的图片数据编码为 base64 字符串，最终返回给客户端。

技术流程图

三、环境准备

1. 依赖配置

<!-- Spring Boot Starter Web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Thymeleaf 模板引擎 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

<!-- HTML 解析库 -->
<dependency>
    <groupId>org.jsoup</groupId>
    <artifactId>jsoup</artifactId>
    <version>1.16.1</version>
</dependency>

<!-- 前端资源 -->
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>bootstrap</artifactId>
    <version>5.3.2</version>
</dependency>

2. 项目结构

src
├── main
│   ├── java
│   │   └── com.example.demo
│   │       └── controller
│   │           └── ImageController.java
│   └── resources
│       ├── templates
│       │   └── image.html
│       └── static
│           └── css
│               └── style.css

四、核心实现

1. 模板渲染（Thymeleaf）

// ImageController.java
@GetMapping("/generate")
public String generateImage(@RequestParam String text, Model model) {
    model.addAttribute("content", text);
    return "image";
}

<!-- resources/templates/image.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Image Generator</title>
    <link rel="stylesheet" href="/css/style.css">
</head>
<body>
    <div id="container">
        <h1 th:text="${content}">Default Text</h1>
        <img id="output" />
    </div>
</body>
</html>

2. HTML 转换与 Canvas 渲染

// ImageService.java
public class ImageService {
    public String generateImageFromTemplate(String htmlContent) {
        // 使用 Jsoup 解析 HTML
        Document doc = Jsoup.parse(htmlContent);
        
        // 创建 Canvas 元素
        Element canvas = doc.createElement("canvas");
        doc.body().appendChild(canvas);
        
        // 使用 Jsoup 的 JS 引擎执行渲染
        ScriptEngine engine = new ScriptEngineManager().getEngineByName("js");
        engine.put("doc", doc);
        engine.eval("""
            (function() {
                var canvas = document.getElementById('output');
                var ctx = canvas.getContext('2d');
                var text = document.getElementById('content').innerText;
                ctx.font = '36px Arial';
                ctx.fillText(text, 50, 100);
                return canvas.toDataURL();
            })()
        """);
        
        return engine.get("result");
    }
}

3. 基于 Canvas 的图片生成

// ImageGenerator.java
public class ImageGenerator {
    public String generateImage(String htmlContent) {
        // 1. 渲染 HTML 模板
        String renderedHtml = ThymeleafTemplateEngine.render(htmlContent);
        
        // 2. 转换 HTML 为 Canvas
        String canvasDataUrl = ImageService.generateImageFromTemplate(renderedHtml);
        
        // 3. 返回 base64 编码的图片数据
        return canvasDataUrl;
    }
}

五、完整案例

1. 动态证书生成系统

1.1 前端模板（`resources/templates/certificate.html`）

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Certificate</title>
    <style>
        body {
            font-family: 'Arial', sans-serif;
            background-color: #f5f5f5;
        }
        .certificate {
            width: 800px;
            height: 500px;
            border: 2px solid #000;
            padding: 20px;
            background: white;
        }
        .header {
            text-align: center;
            font-size: 36px;
            font-weight: bold;
            color: #333;
        }
        .content {
            margin-top: 50px;
            text-align: center;
            font-size: 24px;
            color: #000;
        }
        .footer {
            margin-top: 30px;
            text-align: center;
            font-size: 16px;
            color: #666;
        }
    </style>
</head>
<body>
    <div class="certificate">
        <div class="header" id="header">Certified</div>
        <div class="content" id="content" th:text="${content}">Default Content</div>
        <div class="footer" id="footer">Issued on: <span id="date"></span></div>
    </div>
</body>
</html>

1.2 后端控制器（`ImageController.java`）

@RestController
@RequestMapping("/certificates")
public class CertificateController {
    @Autowired
    private ImageGenerator imageGenerator;
    
    @GetMapping("/generate")
    public ResponseEntity<String> generateCertificate(
            @RequestParam String content, 
            @RequestParam String date) {
        
        // 1. 构建模板数据
        Map<String, Object> model = new HashMap<>();
        model.put("content", content);
        model.put("date", date);
        
        // 2. 渲染模板
        String htmlContent = ThymeleafTemplateEngine.render("certificate", model);
        
        // 3. 生成图片
        String imageBase64 = imageGenerator.generateImage(htmlContent);
        
        // 4. 返回结果
        return ResponseEntity.ok()
                .header("Content-Type", "image/png")
                .body("data:image/png;base64," + imageBase64);
    }
}

1.3 前端调用示例（JavaScript）

// frontend.js
async function generateCertificate() {
    const content = document.getElementById('content').value;
    const date = document.getElementById('date').value;
    
    const response = await fetch(`/certificates/generate?content=${encodeURIComponent(content)}&date=${encodeURIComponent(date)}`);
    const blob = await response.blob();
    
    // 创建图片对象
    const imageUrl = URL.createObjectURL(blob);
    const img = document.createElement('img');
    img.src = imageUrl;
    document.body.appendChild(img);
}

六、源码解析

1. Thymeleaf 模板渲染机制

Thymeleaf 使用 TemplateEngine 接口进行模板渲染，其核心流程包括：

加载模板（TemplateLoader）
解析模板（TemplateParser）
编译模板（TemplateEngine）
执行模板（TemplateModel）

关键代码：

public String render(String templateName, Map<String, Object> model) {
    TemplateEngine engine = new TemplateEngine();
    Template template = engine.getTemplate(templateName);
    return template.process(model);
}

2. Canvas 渲染原理

HTML5 Canvas 的核心 API 包括：

ctx.fillText(text, x, y)：绘制文本
ctx.drawImage(img, dx, dy)：绘制图像
canvas.toDataURL()：获取图片数据

需要注意的细节：

文字渲染需要考虑字体、字号、对齐方式
图像绘制需要考虑尺寸、位置、透明度
生成的 base64 编码包含 MIME 类型信息

七、进阶使用

1. 复杂布局支持

使用 CSS Flexbox 布局实现多行文本：

.container {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    height: 100%;
}

2. 动态样式生成

通过模板参数控制样式：

<style>
    .text {
        font-size: th:|{fontSize}|px;
        color: th:|{color}|;
    }
</style>

3. 多图层渲染

支持叠加多层图片：

ctx.drawImage(background, 0, 0);
ctx.drawImage(front, 0, 0);

八、性能与工程实践

1. 性能优化方案

优化策略	说明
缓存策略	对重复内容进行缓存，避免重复渲染
异步处理	使用 `@Async` 注解进行异步生成
资源压缩	使用 `Gzip` 压缩 base64 数据
资源预加载	预加载常用样式和字体

2. 异常处理机制

@ExceptionHandler
public ResponseEntity<String> handleException(Exception e) {
    log.error("Image generation failed: ", e);
    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body("Error generating image: " + e.getMessage());
}

3. 安全防护措施

输入过滤：使用 Jsoup 清洗 HTML 内容
XSS 防护：对特殊字符进行转义
限制大小：设置最大渲染尺寸
防止注入：禁用 JavaScript 执行

九、常见问题与踩坑

1. 常见错误及解决方案

问题	原因	解决方案
生成的图片为空	Canvas 未正确初始化	确保 HTML 中包含 `<canvas>` 元素
文字显示异常	字体未正确加载	使用系统字体或 Web 字体
base64 编码错误	未正确处理 MIME 类型	确保 `canvas.toDataURL()` 包含 `image/png`
渲染性能差	复杂 DOM 结构	简化 HTML 结构，避免不必要的元素

2. 常见陷阱

内存溢出：大量生成图片时未进行资源回收
跨域问题：静态资源未正确配置 CORS
样式丢失：未正确加载 CSS 文件
安全漏洞：未对用户输入进行过滤

十、最佳实践

1. 开发规范

模板文件应使用 .html 后缀
静态资源应放在 static 目录下
生成的 base64 应包含完整的 MIME 类型
对关键字段进行校验和过滤

2. 推荐方案

场景	推荐方案
简单文本生成	直接使用 `canvas.fillText()`
复杂布局	使用 CSS 布局 + JavaScript 渲染
大量生成	使用缓存 + 异步处理
安全要求高	加密内容 + 防注入处理

3. 工程实践

使用 @Component 管理模板引擎
使用 @Configuration 配置资源路径
使用 @Service 管理生成逻辑
使用 @Controller 处理 HTTP 请求

十一、总结

通过 Thymeleaf 模板引擎动态生成图片，结合 HTML5 Canvas 技术，可以实现灵活、高效的图片生成方案。这种方法特别适合需要动态渲染文本和样式的应用场景，如证书生成、个性化报告等。

需要注意的是，这种方法在处理复杂图形时可能存在性能瓶颈，且需要特别注意安全性问题。在实际开发中，应根据具体需求选择合适的方案，并做好性能优化和安全防护。

通过本文的深入解析，我们不仅了解了技术实现原理，还掌握了实际开发中需要规避的陷阱和最佳实践。希望这些经验能够帮助开发者在实际项目中更好地应用这一技术。