Freemarker模板引擎速查

Apache Freemarker是JVM平台上一个比较流行的通用模板引擎，适合用于生成网页、 邮件、 配置文件等代码。

简介

在Web开发中，我们经常需要动态生成网页（HTML文件）以便在响应中包含与请求有关的信息（如用户名、 搜索结果）。这时我们有两种方法：

• 硬编码代码生成的规则。例如："亲爱的"+user.getName()+"上午好"。这种方法对于生成简单的文本时可能比较方便，但当规模变大后就容易失控，而且用于生成HTML或SQL代码时往往成为注入攻击的温床。
• 套用模板。例如：java.text.MessageFormat.format("亲爱的{0}上午好",user.getName())。这里"亲爱的{0}上午好"就是一个模板，而user.getName()则是模型，这种方法体现了MVC（模型-视图-控制器）模式的原则，有利于分离关注点并容许专门人员分别负责展现什么和怎么展示，提高了可维护性。当然java.text.MessageFormat的模板语言表达力对于许多用途而言太弱，但freemarker之类的模板引擎克服了这个局限性。JVM平台上其它通用模板引擎包括：
  • Apache Velocity
  • Thymeleaf
  • StringTemplate

为了使用freemarker，首先我们需要加入对freemarker库的依赖，例如使用Maven的话在pom.xml中加入：

<dependency>
	<groupId>org.freemarker</groupId>
	<artifactId>freemarker</artifactId>
	<version>2.3.28</version>
</dependency>

然后我们编写一个简单的模板src/main/resources/com/github/chungkwong/template/example.ftl：

亲爱的${name}上午好

接着我们演示如何在java程序src/main/java/com/github/chungkwong/template/Main.java中使用上述模板：

package com.github.chungkwong.template;
import freemarker.template.*;
import java.io.*;
import java.util.*;
public class Main{
	public static void main(String[] args) throws IOException,TemplateException{
		//创建配置类，配置类应尽可能重用，不必再创建以提高性能
		Configuration configuration=new Configuration(Configuration.getVersion());
		//设置模板所在目录，另外可改为
		// setDirectoryForTemplateLoading(File)
		// setClassLoaderForTemplateLoading(ClassLoader, String)
		configuration.setClassForTemplateLoading(Main.class,"");
		//取得模板  
		Template template=configuration.getTemplate("example.ftl");
		//准备模型
		Map<String,Object> model=new HashMap<>();
		model.put("name","陈大文");
		//套用模板并把结果输出到一个流
		template.process(model,new OutputStreamWriter(System.out));
	}
}

运行上述程序应该得到输出亲爱的陈大文上午好。

模型

模型在内部表示为TemplateModel子类型的对象。幸运的是，freemarker.template.DefaultObjectWrapper的TemplateModel handleUnknownType(final Object obj) throws TemplateModelException方法通常能把Java模型对象自动转换为内部对象，我们很少要清晰区分内部对象。不过如果有兴趣也可以通过TemplateModel的子接口了解其类型系统：

• AdapterTemplateModel包装动态类型语言的对象
• TemplateBooleanModel对应于布尔值
• TemplateCollectionModel对应于集合，它的子接口TemplateCollectionModelEx支持查询元素数
• TemplateDateModel对应于日期和/或时间
• TemplateDirectiveModel对应于模板可使用的指令，在需要自定义指令时可覆盖方法void execute(Environment env,Map params, TemplateModel[] loopVars,TemplateDirectiveBody body) throws TemplateException, IOException
• TemplateHashModel对应于哈希表，它的子接口TemplateHashModelEx和TemplateHashModelEx2提供迭代键值对的方法
• TemplateMarkupOutputModel对于于不应再转义就能输出的代码
• TemplateMethodModel对应于模板可调用的方法，它的子接口TemplateMethodModelEx要求实参以TemplateModel而非String传入方法由TemplateModel exec(List args) throws TemplateModelException给出的自定义方法
• TemplateModelWithAPISupport
• TemplateNodeModel对应于XML文档中的结点，它的子接口TemplateNodeModelEx支持查找相邻兄弟结点
• TemplateNumberModel对应于数值
• TemplateScalarModel对应于字符串
• TemplateSequenceModel对应于序列
• WrapperTemplateModel包装其它Java对象

模板

语法

模板中形如<#-- 注释内容 -->的是注释（注释内容中不能含-->），会被忽略。注意注释也可以出现在表达式或指令中。

模板中其余部分由以下构造连接而成：

引用

作用域

和其它语言一样，较局部变量会屏蔽较全局的同名变量。从内而外依次为：

1. Environment 中变量：
   1. 循环创建在循环变量集合
   2. 宏中宏参数或由local指令创建的局部变量集合
   3. 由assign指令创建的当前的命名空间中
   4. 由global指令创建的变量集合中，它们在所有命名空间可见
2. 传递给process方法的模型对象中变量
3. 在 Configuration 对象的共享变量

特殊变量

指令

其中可设置的属性有：

表达式

Freemarker的表达式如下构成：

• 常量
  • 字符串由'或"包围，其中可用\转义，引号前加r可禁用转义和插值
  • 数值格式如123.45
  • 布尔值：true或false
  • 序列形如[元素,...,元素]
  • 哈希表形如{字符串键表达式:值表达式, ...}
• 括号表达式(表达式)可用于控制求值顺序
• 引用
  • 变量的值：变量名
  • 哈希表中的值： 表.键、 表["键"]
  • 序列中元素：序列[索引]
  • 序列中子序列：序列[范围]
  • 字符串中字符：字符串[索引]
  • 字符串中子字符串：字符串[范围]
  • 默认值：表达式!默认值表达式
  • 默认值为空序列/字符串/哈希表：表达式!
  • 变量存在性：表达式??
  • 方法调用：方法表达式(参数表达式,...)
  • 内置函数：表达式?函数
  • 内置函数：表达式?函数(参数表达式,...)
• 前缀运算符
  • 正：+表达式
  • 负：-表达式
  • 否定：!表达式
• 积性数值运算符
  • 积：数值表达式*数值表达式
  • 商：数值表达式/数值表达式
  • 余：数值表达式%数值表达式
• 和性数值运算符
  • 和：数值表达式+数值表达式
  • 字符串/序列/哈希表连接：表达式+表达式
  • 差：数值表达式-数值表达式
• 范围表达式
  • start..end表示一个范围（包含start和end）
  • start..<end或start..!end表示一个范围（包含start但不包含end）
  • start..*length表示从start开始长度为length绝对值的范围
  • start..表示从start开始的无穷序列
• 关系表达式
  • 小于检测：表达式<表达式或表达式 lt 表达式
  • 小于等于检测：表达式<=表达式或表达式 lte 表达式
  • 大于检测：表达式>表达式或表达式 gt 表达式
  • 大于等于检测：表达式>=表达式或表达式 gte 表达式
• 相等性表达式
  • 相等检测：表达式==表达式或表达式=表达式
  • 不等检测：表达式!=表达式
• 逻辑与：表达式&&表达式
• 逻辑与：表达式||表达式

内置函数

以下简单介绍各内置函数的用途：

其中标志可以为：

配置

Configuration对象有一些配置选项，可用以下方法设置（另外可用对应的get、 is或unset方法读取或撤销）：

结语

由于模板语言过于强大，应该在控制器做的事情在模板中也能完成（图灵完备），因此仅仅使用模板语言并不意味着完全把视图和控制器隔离。为了保证可维护性，必须始终明确什么事情是业务逻辑而什么是视图。