SpringBoot实战（三十九）集成 FreeMarker
目录
- 一、什么是 FreeMarker？
- 1.1 FreeMarker 模板组成部分
- 1.2 FreeMarker 与 Web 容器无关
- 二、FreeMarker 有什么优点？
- 三、SpringBoot 集成
- 3.1 Maven依赖
- 3.2 编写模板
- 3.3 配置属性
- 3.4 定义 Controller
- 3.5 全局配置
- 官网地址：https://freemarker.apache.org/
- 中文文档：http://freemarker.foofun.cn/index.html
一、什么是 FreeMarker？
FreeMarker 是一款 模板引擎工具：即一种基于模板和要改变的数据，用来生成输出文本（如：HTML网页、电子邮件、配置文件、源代码等）的通用工具。它不是面向最终用户的，而是 一个Java类库，是一款程序员可以嵌入它们所开发产品的组件。
（FreeMarker 是免费的。）
FTL(FreeMarker Template Language) 为 模板编写语言。它是简单、专用的语言，不是像 PHP 那样成熟的编程语言。那就意味着要准备数据在真实编程语言中来现实，比如数据库查询和业务运算，之后模板现实已经准备好的数据。在模板中，你可以专注于如何展现数据，而在模板之外可以专注于要展示什么数据。
1.1 FreeMarker 模板组成部分
FreeMarker 模板文件主要由以下 4个部分组成：
- 文本：直接输出的部分；
- 注视：使用
<#-- ... -->格式做注释，里面内容不会输出； - 插值：即
${...}或#{...}格式的部分，类似于占位符，将使用数据模型中的部分替代输出。 - FTL指令：即 FreeMarker 指令，全称是：FreeMarker Template Language，和 HTML 标记类似，但名字前加
#予以区分，不会输出。
下面是一个 FreeMarker 模板的例子，包含了以上所说的 4个部分：
<html>
<head>
<title>Welcome to FreeMarker 中文官网</title><br>
</head>
<body>
<#-- 注释部分 -->
<#-- 下面使用插值 -->
<h1>Welcome ${user} !</h1><br>
<p>We have these animals:<br>
<u1>
<#-- 使用FTL指令 -->
<#list animals as being><br> <li>${being.name} for ${being.price} Euros<br>
<#list>
<u1>
</body>
</html>
1.2 FreeMarker 与 Web 容器无关
FreeMarker 与 Web 容器无关，即在 Web 运行时，它并不知道 Servlet 或 HTTP，故此 FreeMarker 不仅可以用作表现层的实现技术，而且还可以用于生成 XML、JSP 或 Java 等各种文本文件。
在 Java Web 领域，FreeMarker 时应用广泛的模板引擎，主要用于 MVC 中的 view 层，生成 html 展示数据给客户端，可以完全替代 JSP。
总之，FreeMarker 是一个模板引擎，一个基于模板生成文本输出的通用工具，使用纯 Java 编写，模板中没有业务逻辑，外部 Java 程序通过数据库操作等生成数据传入模板（template）中，然后输出页面。它能够生成各种文本：HTML、XML、RTF、Java 源代码等等，而且不需要 Servlet 环境，并且可以从任何源载入模板，如本地文件、数据库等等。
二、FreeMarker 有什么优点？
FreeMarker 的诞生是为了取代 JSP。 虽然 JSP 功能强大，可以写 Java 代码实现复杂的逻辑处理，但是页面会有大量业务逻辑，不利于维护和阅读，更不利于前后台分工，容易破坏 MVC 结构，所以舍弃 JSP，选择使用 FreeMarker 是大势所趋。当前很多企业使用 FreeMarker 取代 JSP，FreeMarker 有众多的优点，如下所示：
（1）很好地分离表现层和业务逻辑。
- JSP 功能很强大，它可以在前台编写业务逻辑代码，但这也带来了一个很大的弊端——页面内容杂乱，可读性差，这将会大大增加后期的维护难度。
- 而 FreeMarker 职责明确，功能专注，仅仅负责页面的展示，从而去掉了繁琐的逻辑代码。FreeMarker 的原理就是：模板+数据模型=输出，模板只负责数据在页面中的表现，不涉及任何的逻辑代码，而所有的逻辑都是由数据模型来处理的。用户最终看到的输出是模板和数据模型合并后创建的。
（2）提高开发效率。
- 众所周知，JSP 在第一次执行的时候需要转换成 Servlet 类，之后的每次修改都要编译和转换。这样就造成了每次修改都需要等待编译的事件，效率低下。
- 而 FreeMarker 模板技术并不存在编译和转换问题，所以就不会存在上述问题。相比而言，使用 FreeMarker 可以提高一定的开发效率。
（3）明确分工。
- JSP 页面前后端的代码写到了一起，耦合度很高，前端开发需要熟悉后台环境，需要去调试，而后台开发人员需要去做不熟悉的前端界面设计。对两者而言，交替性的工作需要花费一定的学习成本，效率低下。
- 而使用 FreeMarker 后，前后端完全分离，大家各干各的，互不影响。
（4）简单易用，功能强大。
- FreeMarker 支持 JSP 标签，宏定义比 JSP Tag 方便，同时内置了大量常用功能，比如 html 过滤，日期金额格式化等等。FreeMarker 代码十分简洁，上手快，使用非常方便。
三、SpringBoot 集成
FreeMarker 没有其他的任何依赖，仅仅依赖 Java 自身。
3.1 Maven依赖
在 pom.xml 添加 spring-boot-starter-web 和 spring-boot-starter-freemarker 依赖。
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId>
</dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-freemarker</artifactId>
</dependency>
3.2 编写模板
根据 Spring Boot 约定，模板文件应该放在 src/main/resources 目录下的 tepmlates 目录中。
其中，index.ftl 内容如下：
<!DOCTYPE html>
<html><head><meta charset="UTF-8"><title>Freemarker</title></head><body>Hello ${title}!</body>
</html>
如上，模板知识简单地输出了 Model 中的 title 属性。
3.3 配置属性
Spring Boot 中提供了很多 FreeMarker 的属性配置，可用于在 application.yml 或 application.properties 中定制 FreeMarker 配置，这些属性都以 spring.freemarker 开头。
常用配置如下：
spring:freemarker:# 启用 freemarker 模板enabled: true# 是否缓存cache: false# Content Typecontent-type: text/html# 编码charset: utf-8# 模板后缀suffix: .ftl# 引用 request 的属性名称request-context-attribute: request# 是否暴露 request 域中的属性expose-request-attributes: false# 是否暴露session域中的属性expose-session-attributes: false# request 域中的属性是否可以覆盖 controller 的 model 的同名项。默认 false，如果发生同名属性覆盖的情况会抛出异常allow-request-override: true# session 域中的属性是否可以覆盖 controller 的 model 的同名项。默认 false，如果发生同名属性覆盖的情况会抛出异常allow-session-override: true# 暴露官方提供的宏expose-spring-macro-helpers: true# 启动时检查模板位置是否有效check-template-location: true# 优先加载文件系统的模板prefer-file-system-access: true# 模板所在位置（目录）template-loader-path:- classpath:/templates/settings:datetime_format: yyyy-MM-dd HH:mm:ss # date 输出格式化template_update_delay: 30m # 模板引擎刷新时间default_encoding: utf-8 # 默认编码
完整的配置信息，可参阅 官方文档。
spring.freemarker.expose-spring-macro-helpers 设置为 true 可以暴露 Spring 官方提供的宏。这些宏提供了国际化、表单绑定等等功能。
这些宏定义在 spring-webmvc 模块的 /org/spring/freemark/web/servlet/view/freemarker/spring.ftl 文件中。你可以在模板中使用 #import 指令导入、使用，如下所示：
<#import "/spring.ftl" as spring/>
注意：“/spring.ftl” 必须以 “/” 开头，否则会抛异常：
Caused by: freemarker.template.TemplateNotFoundException: Template not found for name "index/spring.ftl".
The name was interpreted by this TemplateLoader: MultiTemplateLoader(loader1 = FileTemplateLoader(baseDir="C:\eclipse\eclipse-jee-2023-09-R-win32-x86_64\app\springdoc-demo\target\classes\templates", canonicalBasePath="C:\eclipse\eclipse-jee-2023-09-R-win32-x86_64\app\springdoc-demo\target\classes\templates\"), loader2 = ClassTemplateLoader(resourceLoaderClass=org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer, basePackagePath="" /* relatively to resourceLoaderClass pkg */)).at freemarker.template.Configuration.getTemplate(Configuration.java:2957) ~[freemarker-2.3.32.jar:2.3.32]at freemarker.core.Environment.getTemplateForInclusion(Environment.java:3062) ~[freemarker-2.3.32.jar:2.3.32]at freemarker.core.Environment.getTemplateForInclusion(Environment.java:3024) ~[freemarker-2.3.32.jar:2.3.32]at freemarker.core.Environment.getTemplateForImporting(Environment.java:3186) ~[freemarker-2.3.32.jar:2.3.32]at freemarker.core.Environment.importLib(Environment.java:3171) ~[freemarker-2.3.32.jar:2.3.32]at freemarker.core.Environment.importLib(Environment.java:3135) ~[freemarker-2.3.32.jar:2.3.32]at freemarker.core.LibraryLoad.accept(LibraryLoad.java:65) ~[freemarker-2.3.32.jar:2.3.32]... 55 common frames omitted
spring.freemarker.template-loader-path 是一个数组，支持定义多个模板目录。不仅支持 classpath 目录，也支持本地目录，如：file:${user.dir}/templates/。
3.4 定义 Controller
创建 IndexController，返回 ModelAndView，渲染主页模板视图，代码如下：
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.ModelAndView;@RestController
@RequestMapping("/index")
public class IndexController {@GetMapping("/getIndex")public ModelAndView index() {ModelAndView modelAndView = new ModelAndView("index/index");// 添加 title 属性到 ModelmodelAndView.addObject("title", "FreeMarker");return modelAndView;}
}
在 ModelAndView 对象的构造函数中指定要渲染的视图（模板），不需要添加 .ftl 后缀，因为已经同意在配置文件中定义了。
启动应用，访问地址：http://localhost:8080/index/getIndex
响应如下：
由上可见，成功地渲染了 index.ftl，输出了 Model 中的 title 属性。
3.5 全局配置
有时候，你可能需要对模板进行深层次的定制，如：设置自定义函数、定义全局变量等。
那么你可以在任意 Bean 中通过 IOC 注入：freemarker.template.Configuration 对象，进行自定义设置。
import freemarker.template.TemplateModelException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;import javax.annotation.PostConstruct;@Configuration
public class MyFreeMarkerConfiguration {// 注入 Configuration@Autowiredprivate freemarker.template.Configuration configuration;@PostConstructpublic void configuration() throws TemplateModelException {// 添加全局变量this.configuration.setSharedVariable("app", "Spring Boot");}
}
调整 index.ftl 内容，增加 ${app}，如下所示：
<!DOCTYPE html>
<html><head><meta charset="UTF-8"><title>Freemarker</title></head><body>Hello ${title}! The app is ${app}.</body>
</html>
启动应用，页面如下所示：
可以看到，MyFreeMarkerConfiguration 中的全局配置已正常生效。
整理完毕，完结撒花～🌻
参考地址：
1.FreeMarker简介，http://www.freemarker.cn/archives/165.html
2.Spring Boot 整合 Freemarker 模板引擎，https://springdoc.cn/springboot-freemarker/