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地址：https://github.com/apache/freemarker

工作原理

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

image

二、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

效果如下：

image

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

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;
}

最终的效果是：

image
2.1.4.2 “?html”语法解析

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

  • < 替换为 &lt;
  • > 替换为 &gt;
  • & 替换为 &amp;
  • " 替换为 &quot;
2.1.4.3 noescape使用

HTML代码：

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

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;
}

最终效果：

image

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直接使用${}打印，会报模板错误，效果如下：

image

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}

输出：

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

更多的字符串内建函数：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

三、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
配置项 类型 默认值 建议值 说明
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属性的名称

更多配置：

# 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/ 就可看到如下效果：

image

四、参考资料

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

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

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 204,293评论 6赞 478
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 85,604评论 2赞 381
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 150,958评论 0赞 337
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,729评论 1赞 277
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,719评论 5赞 366
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,630评论 1赞 281
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 38,000评论 3赞 397
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,665评论 0赞 258
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 40,909评论 1赞 299
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,646评论 2赞 321
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,726评论 1赞 330
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,400评论 4赞 321
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 38,986评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,959评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,197评论 1赞 260
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 44,996评论 2赞 349
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,481评论 2赞 342

推荐阅读更多精彩内容