Spring Boot 模板引擎FreeMarker集成

一、FreeMaker介绍

FreeMarker是一款免费的Java模板引擎，是一种基于模板和数据生成文本（HMLT、电子邮件、配置文件、源代码等）的工具，它不是面向最终用户的，而是一款程序员使用的组件。
FreeMarker最初设计是用来在MVC模式的Web开发中生成HTML页面的，所以没有绑定Servlet或任意Web相关的东西上，所以它可以运行在非Web应用环境中。
发展史
FreeMarker第一版在1999年未就发布了，2002年初使用JavaCC（Java Compiler Compiler是一个用Java开发的语法分析生成器）重写了FreeMarker的核心代码，2015年FreeMarker代码迁移到了Apache下。
GitHub地址：github.com/apache/free…
工作原理
FreeMarker模板存储在服务器上，当有用户访问的时候，FreeMarker会查询出相应的数据，替换模板中的标签，生成最终的HTML返回给用户，如下图：

在这里插入图片描述

二、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，示例如下：

<#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

效果如下：
在这里插入图片描述
对空白不敏感的格式，移除空白行还是挺有用的功能。

2.1.4 escape, noescape 转义，不转义

2.1.4.1 escape使用

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

上面的代码，类似于：

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

Java代码：

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

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代码：

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

最终效果：
在这里插入图片描述

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直接使用${}打印，会报模板错误(你可以自己试一下)，
最终效果如下：
在这里插入图片描述

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 or 2
</#if>

2.1.8 import 引入模板

语法：

<#import path as hash>

示例如下
freemarkerFooter.ftl 关键代码如下：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
this is footer.ftl<#assign copy="冯雪超的博客">
</body>
</html>

freemarker.ftl 关键代码如下：

<#import "freemarkerFooter.ftl" as footer>
${footer.copy}

最终输出内容：
在这里插入图片描述

2.1.9 include 嵌入模板

语法：

<#include path>

示例如下
freemarkerFooterooter.ftl 代码如下：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
this is footer.ftl<#assign copy="冯雪超的博客">
</body>
</html>

freemarker.ftl 关键代码如下：

<#include "freemarkerFooter.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}

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

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
更多的字符串内建函数：http://freemarker.foofun.cn/ref_builtins.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

三、Spring Boot 集成

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

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

3.2.3 编写HTML代码

freemarker.ftl

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>冯雪超的博客</title>
</head>
<body>


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

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

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

<div>
    <#compress>
  1 2  3   4    5


  test only

  I said, test only</#compress>

    1 2  3   4    5


    test only

    I said, test only
</div>

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

    <div>
    ${firstName?html}
    ${lastName?html}
    </div>
</div>

<div>
    <#function sum x y z>
        <#return x+y+z>
    </#function>

${sum(5,5,5)}

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

<div>
<#global name1="fxc1" name2="fxc2">
    <#global name3>
  capture this
    </#global>
    <br>
${name1}<br>
${name2}<br>
${name3}<br>
</div>

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

<div>
    <#import "freemarkerFooter.ftl" as footer>
${footer.copy}
</div>

<div>
    <#include "freemarkerFooter.ftl">
</div>

<div>
    <#list 1..3 as n>
        ${n}
    <#if n==2>
        <#break>
    </#if>
    </#list>
</div>
<dvi>
    <#list 1..3 as n>
        ${n}
<#sep>,</#sep>
    </#list>
</dvi>
<div>
    <#list 1..3 as n>
        ${n}
    <#if !n_has_next>
    最后一项
    </#if>
    </#list>
</div>

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

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

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

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

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

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

<div>
${1.23569?string.percent}${1.23569?string["0.##"]}${1.23569?string["0.###"]}
</div>

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

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

FreemarkerFooter.ftl

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>
this is footer.ftl<#assign copy="冯雪超的博客">
</body>
</html>

3.2.4 编写Java代码

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

package com.littlefxc.blog.controller;

import lombok.Data;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

import java.util.Arrays;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

/**
 * @author fengxuechao
 */
@Controller
public class IndexController {


    @RequestMapping("/")
    public ModelAndView index(ModelAndView modelAndView) {
        modelAndView.setViewName("index");
        modelAndView.addObject("names", Arrays.asList("小王", "小明", "小红"));
        Goods goods = new Goods();
        goods.setName("iMac");
        goods.setPrice("￥20000");
        goods.setCreateTime(new Date());
        modelAndView.addObject("goods", goods);
        return modelAndView;
    }

    @Data
    public static class Goods{
        private String name;

        private String price;

        private Date createTime;
    }

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

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

3.2.5 运行

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

四、参考资料

FreeMarker官方文档：freemarker.apache.org/
FreeMarker翻译的中文网站：freemarker.foofun.cn/toc.html