[Java实战]Spring Boot 整合 Freemarker (十一)

曼岛_

于 2025-05-11 14:55:55 发布

阅读量1k

点赞数 27

分类专栏： Java实战文章标签： java spring boot 开发语言

本文链接：https://blog.csdn.net/qq_29709589/article/details/147873247

版权

Java实战专栏收录该内容

23 篇文章

订阅专栏

[Java实战]Spring Boot 整合 Freemarker (十一)

引言

Apache FreeMarker 作为一款高性能的模板引擎，凭借其简洁语法、卓越性能和灵活扩展性，在 Java Web 开发中占据重要地位。结合 Spring Boot 的自动化配置能力，开发者能快速构建动态页面、生成报表或定制代码。本文将系统讲解整合流程、实战技巧、性能优化方案，并针对企业级场景提供深度解决方案。

一、Freemarker 核心优势与适用场景

1. 为什么选择 Freemarker？

特性	说明
高性能	编译型模板引擎，执行效率优于传统 JSP
语法简洁	类似 Python 的直观语法，学习成本低
强类型支持	严格的类型检查，减少运行时错误
多场景适用	支持 HTML、XML、JSON、纯文本等多种输出格式

2. 与 Thymeleaf 对比

维度	Freemarker	Thymeleaf
模板类型	非自然模板（需渲染后查看）	自然模板（浏览器直接预览）
性能	更高（适合高并发场景）	中等
功能扩展	支持自定义指令、宏	依赖方言扩展
集成复杂度	简单	需额外配置布局方言

二、Spring Boot 整合 Freemarker 全流程

1. 环境准备

JDK 1.8+（推荐 LTS 版本）
Spring Boot 2.x（本文基于 2.1.8）
Maven/Gradle（本文使用 Maven）

2. 添加依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-freemarker</artifactId>
</dependency>

3. 基础配置（application.yml）

spring:
  freemarker:
    enabled: true                   # 启用 Freemarker
    template-loader-path: classpath:/templates/  # 模板路径
    suffix: .ftl                    # 模板文件后缀
    charset: UTF-8                  # 编码格式
    cache: false                    # 开发环境关闭缓存
    settings:                       # Freemarker 全局配置
      classic_compatible: true      # 兼容旧版本语法
      number_format: 0.##           # 数字格式化
      datetime_format: yyyy-MM-dd HH:mm:ss

三、Freemarker 实战案例

案例 1：基础数据渲染

Controller

@Controller
public class ProductController {
    @GetMapping("/product")
    public String productDetail(Model model) {
        Product product = new Product("iPhone 15", 7999.00, 100);
        model.addAttribute("product", product);
        model.addAttribute("discount", 0.15);
        return "product";
    }
}

模板（product.ftl）

<!DOCTYPE html>
<html>
<head>
    <title>商品详情</title>
</head>
<body>
    <h1>${product.name}</h1>
    <p>价格: ${product.price?string.currency}</p>
    <p>库存: 
        <#if product.stock &gt; 0>
            <span style="color: green;">有货</span>
        <#else>
            <span style="color: red;">缺货</span>
        </#if>
    </p>
    <p>折后价: ${(product.price * (1 - discount))?string.currency}</p>
</body>
</html>

在这里插入图片描述

案例 2：分页功能实现

分页工具类

public class Page<T> {
    private List<T> data;
    private int currentPage;
    private int totalPages;
    // Getter/Setter
}

分页模板（list.ftl）

<table>
    <#list page.data as item>
        <tr><td>${item.name}</td></tr>
    </#list>
</table>

<div class="pagination">
    <#if page.currentPage &gt; 1>
        <a href="/list?page=${page.currentPage - 1}">上一页</a>
    </#if>
    <span>${page.currentPage}/${page.totalPages}</span>
    <#if page.currentPage < page.totalPages>
        <a href="/list?page=${page.currentPage + 1}">下一页</a>
    </#if>
</div>

四、高阶技巧与性能优化

1. 自定义指令（实现数据脱敏）

public class MaskDirective implements TemplateDirectiveModel {
    @Override
    public void execute(Environment env, Map params, 
                        TemplateModel[] loopVars, 
                        TemplateDirectiveBody body) {
        String content = params.get("content").toString();
        int keepLength = Integer.parseInt(params.get("keep").toString());
        String masked = content.substring(0, keepLength) + "****";
        env.getOut().write(masked);
    }
}

注册指令

@Configuration
public class FreemarkerConfig {
    @Bean
    public FreeMarkerConfigurationFactoryBean getFreeMarkerConfiguration() {
        FreeMarkerConfigurationFactoryBean config = new FreeMarkerConfigurationFactoryBean();
        config.setTemplateLoaderPath("classpath:/templates");
        Map<String, Object> variables = new HashMap<>();
        variables.put("mask", new MaskDirective());
        config.setFreemarkerVariables(variables);
        return config;
    }
}

模板中使用

<p>手机号: <@mask content="13812345678" keep=3 /></p>

2. 性能优化策略

spring:
  freemarker:
    cache: true  # 生产环境开启缓存
    settings:
      template_update_delay: 3600  # 模板更新检查间隔（秒）
      localized_lookup: false      # 关闭本地化查找提升性能

3. 集成其他模板引擎（多引擎共存）

@Configuration
public class MultiTemplateConfig {
    @Bean
    public ViewResolver freeMarkerViewResolver() {
        FreeMarkerViewResolver resolver = new FreeMarkerViewResolver();
        resolver.setPrefix("");
        resolver.setSuffix(".ftl");
        resolver.setOrder(1);  # 优先级高于 Thymeleaf
        return resolver;
    }
}

五、常见问题与解决方案

1. 模板文件未找到（404）

检查点：
- 文件是否位于 src/main/resources/templates
- 模板名是否与 Controller 返回的视图名一致
- 文件后缀是否为 .ftl

2. 变量解析失败

错误示例：Expression product.name is undefined
解决：
- 确保 Controller 中通过 model.addAttribute() 添加变量
- 检查变量名拼写（Freemarker 区分大小写）
- 使用 ?? 判空：${product.name!''}

3. 静态资源加载问题

正确引用方式：

<link href="/css/style.css" rel="stylesheet">
<script src="/js/app.js"></script>

确保路径配置：静态资源位于 src/main/resources/static

六、企业级应用扩展

1. 生成 PDF/Word 文档

利用 Freemarker 模板生成 HTML，再通过 Flying Saucer 或 Apache POI 转换为 PDF/Word：

Configuration cfg = new Configuration(Configuration.VERSION_2_3_31);
Template template = cfg.getTemplate("report.ftl");
String html = FreeMarkerTemplateUtils.processTemplateIntoString(template, model);
// 转换为 PDF
ITextRenderer renderer = new ITextRenderer();
renderer.setDocumentFromString(html);
renderer.layout();
renderer.createPDF(outputStream);

2. 集群环境模板热更新

结合 Spring Cloud Config 或 Nacos 实现模板动态加载：

@Scheduled(fixedRate = 60000)  # 每分钟检查更新
public void reloadTemplate() {
    configuration.clearTemplateCache();
}

七、总结

通过 Spring Boot 整合 Freemarker，开发者能够快速构建高效、灵活的动态页面系统。关键点包括：

快速整合：依赖配置与基础语法
高阶扩展：自定义指令与多引擎共存
性能优化：缓存策略与集群方案
企业级应用：文档生成与动态更新

扩展思考：如何结合 Freemarker 与前端框架（如 React）实现服务端渲染（SSR）？欢迎评论区交流！

附录

希望本教程对您有帮助，请点赞❤️收藏⭐关注支持！欢迎在评论区留言交流技术细节！