Spring Boot 最佳实践（三）模板引擎FreeMarker集成

刺骨的言语ヽ痛彻心扉 2023-10-17 23:55 144阅读 0赞

### 一、FreeMaker介绍 ###

FreeMarker是一款免费的Java模板引擎，是一种基于模板和数据生成文本（HMLT、电子邮件、配置文件、源代码等）的工具，它不是面向最终用户的，而是一款程序员使用的组件。

FreeMarker最初设计是用来在MVC模式的Web开发中生成HTML页面的，所以没有绑定Servlet或任意Web相关的东西上，所以它可以运行在非Web应用环境中。

#### 发展史 ####

FreeMarker第一版在1999年未就发布了，2002年初使用JavaCC（Java Compiler Compiler是一个用Java开发的语法分析生成器）重写了FreeMarker的核心代码，2015年FreeMarker代码迁移到了Apache下。

GitHub地址：[https://github.com/apache/freemarker][https_github.com_apache_freemarker]

#### 工作原理 ####

FreeMarker模板存储在服务器上，当有用户访问的时候，FreeMarker会查询出相应的数据，替换模板中的标签，生成最终的HTML返回给用户，如下图：

![springboot-freemarker-process3.png][]

### 二、FreeMarker基础使用 ###

基础使用分为3部分，这3部分组成了FreeMarker：

*  指令
 *  表达式

指令是FreeMarker用来识别转换的特殊标签，表达式是标签里具体的语法实现，其他部分是一些不好分类的模板。

#### 2.1 指令 ####

使用FTL（freemarker template language）标签来调用指令。

指令速览：

*  assign
 *  attempt, recover
 *  compress
 *  escape, noescape
 *  flush
 *  ftl
 *  function, return
 *  global
 *  if, else, elseif
 *  import
 *  include
 *  list, else, items, sep, break
 *  local
 *  macro, nested, return
 *  noparse
 *  nt
 *  setting
 *  stop
 *  switch, case, default, break
 *  t, lt, rt
 *  visit, recurse, fallback
 *  用户自定义标签

下来我们分别来看每个指令对应具体使用。

##### 2.1.1 assign 代码声明 #####

assign 分为变量和代码片段声明两种。

###### 2.1.1.1 变量声明 ######

可以是单变量声明，或多变量声明，下面是多变量声明的示例：

<#assign name="adam" age=18 "sex"="man">
    ${name} - ${age} - ${"sex"}

单个变量的话，只写一个就可以了。

###### 2.1.1.2 代码片段声明 ######

<#assign code>
        <#list ["java","golang"] as c>
            ${c}
        </#list>
    </#assign>
    ${code}

其中 `${code}` 是用来执行方法的，如果不调用话，代码片段不会执行。

##### 2.1.2 attempt, recover 异常指令 #####

attempt（尝试）, recover（恢复）指令类似于程序的try catch，示例如下：

`html <#attempt> i am ${name} <#recover> error name </#attempt>`

如果有变量“name”就会正常显示，显示“i am xxx”，如果没有变量就会显示“error name”。

##### 2.1.3 compress 压缩代码移除空白行 #####

<#compress>
      1 2  3   4    5
    
    
      test only
    
      I said, test only
    </#compress>
    
    1 2  3   4    5
    
    
    test only
    
    I said, test only

效果如下：

![springboot-freemarker-compress.png][]

对空白不敏感的格式，移除空白行还是挺有用的功能。

##### 2.1.4 escape, noescape 转义，不转义 #####

###### 2.1.4.1 escape使用 ######

<#escape x as x?html>
        ${firstName}
        ${lastName}
    </#escape>

上面的代码，类似于：

${firstName?html}
    ${lastName?html}

Java代码：

@RequestMapping("/")
    public ModelAndView index() {
      ModelAndView modelAndView = new ModelAndView("/index");
      modelAndView.addObject("firstName", "<span style='color:red'>firstName</span>");
      modelAndView.addObject("lastName", "lastName");
      return modelAndView;
    }

最终的效果是：

![springboot-freemarker-escape.png][]

###### 2.1.4.2 “?html”语法解析 ######

单问号后面跟的是操作函数，类似于Java中的方法名，html属于内建函数的一个，表示字符串会按照HTML标记输出，字符替换规则如下：

*  `<` 替换为 `<`
 *  `>` 替换为 `>`
 *  `&` 替换为 `&`
 *  `"` 替换为 `"`

###### 2.1.4.3 noescape使用 ######

HTML代码：

<#escape x as x?html>
        <#noescape>
            ${firstName}
        </#noescape>
        ${lastName}
    </#escape>

Java代码：

最终效果：

![springboot-freemarker-noescape.png_1][]

##### 2.1.5 function, return 方法声明 #####

代码格式：

<#function name param1 param2 ... paramN>
      ...
      <#return returnValue>
      ...
    </#function>

*  name 为方法名称
 *  param1, param2,paramN 方法传递过来的参数，可以有无限个参数，或者没有任何参数
 *  return 方法返回的值，可以出现在function的任何位置和出现任意次数

示例代码如下：

<#function sum x y z>
        <#return x+y+z>
    </#function>
    
    ${sum(5,5,5)}

注意：function如果没有return是没有意义的，相当于返回null，而function之中信息是不会打印到页面的，示例如下：

<#function wantToPrint>
        这里的信息是显示不了的
    </#function>
    
    <#if wantToPrint()??>
        Message:${wantToPrint()}
    </#if>

“??”用于判断值是否是null，如果为null是不执行的。如果不判null直接使用$\{\}打印，会报模板错误，效果如下：

![springboot-freemarker-function.png][]

##### 2.1.6 global 全局代码声明 #####

语法如下:

<#global name=value>
    或
    <#global name1=value1 name2=value2 ... nameN=valueN>
    或
    <#global name>
      capture this
    </#global>

global使用和assign用法类似，只不过global声明是全局的，所有的命名空间都是可见的。

##### 2.1.7 if elseif else 条件判断 #####

语法如下：

<#if condition>
      ...
    <#elseif condition2>
      ...
    <#elseif condition3>
      ...
    ...
    <#else>
      ...
    </#if>

示例如下：

<#assign x=1 >
    <#if x==1>
        x is 1
    <#elseif x==2>
        x is 2
    <#else>
        x is not 1
    </#if>

##### 2.1.8 import 引入模板 #####

语法： `<#import path as hash>`

示例如下

footer.ftl 代码如下：

<html>
    <head>
        <title>王磊的博客</title>
    </head>
    <body>
    this is footer.ftl
    <#assign copy="来自 王磊的博客">
    </body>
    </html>

index.ftl 代码如下：

<html>
    <head>
        <title>王磊的博客</title>
    </head>
    <body>
    <#import "footer.ftl" as footer>
    ${footer.copy}
    </body>
    </html>

最终输出内容：

来自 王磊的博客

##### 2.1.9 include 嵌入模板 #####

语法： `<#include path>`

示例如下

footer.ftl 代码如下：

<html>
    <head>
        <title>王磊的博客</title>
    </head>
    <body>
    this is footer.ftl
    <#assign copy="来自 王磊的博客">
    </body>
    </html>

index.ftl 代码如下：

<html>
    <head>
        <title>王磊的博客</title>
    </head>
    <body>
    <#include "footer.ftl">
    </body>
    </html>

最终内容如下：

this is footer.ftl

##### 2.1.10 list, else, items, sep, break 循环 #####

###### 2.1.10.1 正常循环 ######

输出1-3的数字，如果等于2跳出循环，代码如下：

<#list 1..3 as n>
        ${n}
        <#if n==2>
            <#break>
        </#if>
    </#list>

注意：“1..3”等于\[1,2,3\]。

结果： `1 2`

###### 2.1.10.2 使用items输出 ######

示例如下：

<#list 1..3>
    <ul>
    <#items as n>
        <li>${n}</li>
    </#items>
    </ul>
    </#list>

###### 2.1.10.3 sep 使用 ######

跳过最后一项

<#list 1..3 as n>
        ${n}
        <#sep>,</#sep>
    </#list>

最终结果：`1 , 2 , 3`

###### 2.1.10.4 数组最后一项 ######

代码如下：

<#list 1..3 as n>
        ${n}
        <#if !n_has_next>
        最后一项
        </#if>
    </#list>

使用“变量\_has\_next”判断是否还有下一个选项，来找到最后一项，最终的结果：`1 2 3 最后一项`

##### 2.1.11 macro 宏 #####

宏：是一个变量名的代码片段，例如：

<#macro sayhi name>
        Hello, ${name}
    </#macro>
    
    <@sayhi "Adam" />

相当于声明了一个名称为“sayhi”有一个参数“name”的宏，使用自定义标签“@”调用宏。

输出的结果： `Hello, Adam`

##### 2.1.12 switch, case, defalut, break 多条件判断 #####

示例代码如下：

<#assign animal="dog" >
    <#switch animal>
        <#case "pig">
            This is pig
            <#break>
        <#case "dog">
            This is dog
            <#break>
        <#default>
                This is Aaimal
    </#switch>

##### 2.1.13 扩展知识 #####

指令自动忽略空格特性

FreeMarker会忽略FTL标签中的空白标记，所以可以直接写：

<#list ["老王","老李","老张"]
        as
                p>
        ${
        p}
    </#list>

即使是这个格式也是没有任何问题的，FreeMarker会正常解析。

#### 2.2 表达式 ####

##### 2.2.1 字符串拼接 #####

字符拼接代码：

<#assign name="ABCDEFG">
    ${"Hello, ${name}"}

结果：`Hello, ABCDEFG`

##### 2.2.2 算术运算 #####

###### 2.2.2.1 算术符 ######

算术符有五种：

*  \+
 *  \-
 *  \*
 *  /
 *  % 求余（求模）

示例代码：

${100 - 10 * 20}

输出：

-100

###### 2.2.2.2 数值转换 ######

${1.999?int}

输出：

**注意：数值转换不会进行四舍五入，会舍弃小数点之后的。**

##### 2.2.3 内建函数（重点） #####

内建函数：相当于我们Java类里面的内置方法，非常常用，常用的内建函数有：时间内建函数、字符内建函数、数字内建函数等。

###### 2.2.3.1 单个问号和两个问号的使用和区别 ######

单问号：在FreeMarker中用单个问号，来调用内建函数，比如： `${"admin"?length}` 查看字符串“admin”的字符长度，其中length就是字符串的内建函数。

双引号：表示用于判断值是否为null，比如：

<#if admin??>
        Admin is not null
    </#if>

###### 2.2.3.2 字符串内建函数 ######

###### 2.2.3.2.1 是否包含判断 ######

使用contains判断，代码示例：

<#if "admin"?contains("min")>
       min
    <#else >
    not min
    </#if>

输出：

min

###### 2.2.3.2.2 大小写转换 ######

示例代码：

<#assign name="Adam">
    ${name?uncap_first} 
    ${name?upper_case}
    ${name?cap_first}
    ${name?lower_case}

输出：

adam ADAM Adam adam

更多的字符串内建函数：[https://freemarker.apache.org/docs/ref\_builtins\_string.html][https_freemarker.apache.org_docs_ref_builtins_string.html]

###### 2.2.3.3 数字内建函数 ######

示例代码：

${
       1.23569?string.percent}
    ${
       1.23569?string["0.##"]}
    ${
       1.23569?string["0.###"]}

输出：

124% 1.24 1.236

**注意：**

*  使用string.percent计算百分比，会自动四舍五入。
 *  使用“?string\[“0.\#\#”\]”可以自定义取小数点后几位，会自动四舍五入。

###### 2.2.3.4 时间内建函数 ######

###### 2.2.3.4.1 时间戳转换为任何时间格式 ######

代码：

<#assign timestamp=1534414202000>
    ${timestamp?number_to_datetime?string["yyyy/MM/dd HH:mm"]}

输出：

2018/08/16 18:10

###### 2.2.3.4.2 时间格式化 ######

示例代码：

<#assign nowTime = .now>
    ${
        nowTime} <br />
    ${
        nowTime?string["yyyy/MM/dd HH:mm"]} <br />

输出：

2018-8-16 18:33:50 
    2018/08/16 18:33

更多内建方法：[https://freemarker.apache.org/docs/ref\_builtins.html][https_freemarker.apache.org_docs_ref_builtins.html]

### 三、Spring Boot 集成 ###

#### 3.1 集成环境 ####

*  Spring Boot 2.0.4
 *  FreeMaker 2.3.28
 *  JDK 8
 *  Windows 10
 *  IDEA 2018.2.1

#### 3.2 集成步骤 ####

##### 3.2.1 pom.xml 添加FreeMaker依赖 #####

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

##### 3.2.2 application.properties 配置模板 #####

主要配置，如下：

## Freemarker 配置
    spring.freemarker.template-loader-path=classpath:/templates/
    spring.freemarker.cache=false
    spring.freemarker.charset=UTF-8
    spring.freemarker.check-template-location=true
    spring.freemarker.content-type=text/html
    spring.freemarker.expose-request-attributes=false
    spring.freemarker.expose-session-attributes=false
    spring.freemarker.request-context-attribute=request
    spring.freemarker.suffix=.ftl

<table> 
 <thead> 
  <tr> 
   <th align="left">配置项</th> 
   <th align="center">类型</th> 
   <th align="center">默认值</th> 
   <th align="center">建议值</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">spring.freemarker.template-loader-path</td> 
   <td align="center">String</td> 
   <td align="center">classpath:/templates/</td> 
   <td align="center">默认</td> 
   <td align="left">模版存放路径</td> 
  </tr> 
  <tr> 
   <td align="left">spring.freemarker.cache</td> 
   <td align="center">bool</td> 
   <td align="center">true</td> 
   <td align="center">默认</td> 
   <td align="left">是否开启缓存，生成环境建议开启</td> 
  </tr> 
  <tr> 
   <td align="left">spring.freemarker.charset</td> 
   <td align="center">String</td> 
   <td align="center">-</td> 
   <td align="center">UTF-8</td> 
   <td align="left">编码</td> 
  </tr> 
  <tr> 
   <td align="left">spring.freemarker.content-type</td> 
   <td align="center">String</td> 
   <td align="center">text/html</td> 
   <td align="center">text/html</td> 
   <td align="left">content-type类型</td> 
  </tr> 
  <tr> 
   <td align="left">spring.freemarker.suffix</td> 
   <td align="center">String</td> 
   <td align="center">.ftl</td> 
   <td align="center">.ftl</td> 
   <td align="left">模板后缀</td> 
  </tr> 
  <tr> 
   <td align="left">spring.freemarker.expose-request-attributes</td> 
   <td align="center">bool</td> 
   <td align="center">false</td> 
   <td align="center">false</td> 
   <td align="left">设定所有request的属性在merge到模板的时候，是否要都添加到model中</td> 
  </tr> 
  <tr> 
   <td align="left">spring.freemarker.expose-session-attributes</td> 
   <td align="center">bool</td> 
   <td align="center">false</td> 
   <td align="center">false</td> 
   <td align="left">设定所有HttpSession的属性在merge到模板的时候，是否要都添加到model中.</td> 
  </tr> 
  <tr> 
   <td align="left">spring.freemarker.request-context-attribute</td> 
   <td align="center">String</td> 
   <td align="center">-</td> 
   <td align="center">request</td> 
   <td align="left">RequestContext属性的名称</td> 
  </tr> 
 </tbody> 
</table>

更多配置：

# FREEMARKER (FreeMarkerProperties)
    spring.freemarker.allow-request-override=false # Whether HttpServletRequest attributes are allowed to override (hide) controller generated model attributes of the same name.
    spring.freemarker.allow-session-override=false # Whether HttpSession attributes are allowed to override (hide) controller generated model attributes of the same name.
    spring.freemarker.cache=false # Whether to enable template caching.
    spring.freemarker.charset=UTF-8 # Template encoding.
    spring.freemarker.check-template-location=true # Whether to check that the templates location exists.
    spring.freemarker.content-type=text/html # Content-Type value.
    spring.freemarker.enabled=true # Whether to enable MVC view resolution for this technology.
    spring.freemarker.expose-request-attributes=false # Whether all request attributes should be added to the model prior to merging with the template.
    spring.freemarker.expose-session-attributes=false # Whether all HttpSession attributes should be added to the model prior to merging with the template.
    spring.freemarker.expose-spring-macro-helpers=true # Whether to expose a RequestContext for use by Spring's macro library, under the name "springMacroRequestContext".
    spring.freemarker.prefer-file-system-access=true # Whether to prefer file system access for template loading. File system access enables hot detection of template changes.
    spring.freemarker.prefix= # Prefix that gets prepended to view names when building a URL.
    spring.freemarker.request-context-attribute= # Name of the RequestContext attribute for all views.
    spring.freemarker.settings.*= # Well-known FreeMarker keys which are passed to FreeMarker's Configuration.
    spring.freemarker.suffix=.ftl # Suffix that gets appended to view names when building a URL.
    spring.freemarker.template-loader-path=classpath:/templates/ # Comma-separated list of template paths.
    spring.freemarker.view-names= # White list of view names that can be resolved.

##### 3.2.3 编写HTML代码 #####

<html>
    <head>
        <title>王磊的博客</title>
    </head>
    <body>
    <div>
        Hello,${name}
    </div>
    </body>
    </html>

##### 3.2.4 编写Java代码 #####

新建index.java文件，Application.java（入口文件）代码不便，index.java代码如下：

import org.springframework.stereotype.Controller;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.servlet.ModelAndView;
    
    @Controller
    @RequestMapping("/")
    public class Index {
        
        @RequestMapping("/")
        public ModelAndView index() {
            ModelAndView modelAndView = new ModelAndView("/index");
            modelAndView.addObject("name", "老王");
            return modelAndView;
        }
    }

关键代码解读：

1.  @Controller注解：标识自己为控制器，只需要配置@RequestMapping之后，就可以把用户URL映射到控制器；
2.  使用ModelAndView对象，指定视图名&添加视图对象。

##### 3.2.5 运行 #####

执行上面4个步骤之后，就可以运行这个Java项目了，如果是IDEA使用默认快捷键“Shift + F10”启动调试，在页面访问：[http://localhost:8080/][http_localhost_8080] 就可看到如下效果：

![springboot-freemarker-helloworld2.png][]

### 四、参考资料 ###

FreeMarker官方文档：[https://freemarker.apache.org/][https_freemarker.apache.org]

FreeMarker翻译的中文网站：[http://freemarker.foofun.cn/toc.html][http_freemarker.foofun.cn_toc.html]

[https_github.com_apache_freemarker]: https://github.com/apache/freemarker
[springboot-freemarker-process3.png]: http://icdn.apigo.cn/blog/springboot-freemarker-process3.png
[springboot-freemarker-compress.png]: http://icdn.apigo.cn/blog/springboot-freemarker-compress.png
[springboot-freemarker-escape.png]: http://icdn.apigo.cn/blog/springboot-freemarker-escape.png
[springboot-freemarker-noescape.png_1]: http://icdn.apigo.cn/blog/springboot-freemarker-noescape.png?1
[springboot-freemarker-function.png]: http://icdn.apigo.cn/blog/springboot-freemarker-function.png
[https_freemarker.apache.org_docs_ref_builtins_string.html]: https://freemarker.apache.org/docs/ref_builtins_string.html
[https_freemarker.apache.org_docs_ref_builtins.html]: https://freemarker.apache.org/docs/ref_builtins.html
[http_localhost_8080]: http://localhost:8080/
[springboot-freemarker-helloworld2.png]: http://icdn.apigo.cn/blog/springboot-freemarker-helloworld2.png
[https_freemarker.apache.org]: https://freemarker.apache.org/
[http_freemarker.foofun.cn_toc.html]: http://freemarker.foofun.cn/toc.html