前言
OneBlog中使用到了springboot + freemarker的技术，同时项目里多个controller中都需要查询一个公有的数据集合，一般做法是直接在每个controller的方法中通过
model.addAttribute("xx",xx);的方式手动设置，但这样就有个明显的问题：重复代码。同一个实现需要在不同的controller方法中设置，除了重复代码外，还会给后期维护造成不必要的麻烦。在以往的jsp项目中，可以通过taglib实现自定义标签，那么，在freemarker中是否也可以实现这种功能呢？今天就尝试一下在freemarker中如何使用自定义标签。
TemplateDirectiveModel
在freemarker中实现自定义的标签，主要就是靠 TemplateDirectiveModel类。如字面意思：模板指令模型，主要就是用来扩展自定义的指令(和freemarker的宏类似，自定义标签也属于这个范畴)
1 public interface TemplateDirectiveModel extends TemplateModel {
2 void execute(Environment env, Map params, TemplateModel[] loopVars, TemplateDirectiveBody body) throws TemplateException, IOException;
3 }
TemplateDirectiveModel是一个接口，类中只有一个execute方法供使用者实现，而我们要做的就是通过实现execute方法，实现自定义标签的功能。当页面模板中使用自定义标签时，会自动调用该方法。
先来看一下execute方法的参数含义
env : 表示模板处理期间的运行时环境。该对象会存储模板创建的临时变量集、模板设置的值、对数据模型根的引用等等，通常用它来输出相关内容，如Writer out = env.getOut()。
params : 传递给自定义标签的参数(如果有的话)。其中map的key是自定义标签的参数名，value值是TemplateModel实例【1】。
loopVars : 循环替代变量 （未发现有什么用，希望知道的朋友能指教一二）
body : 表示自定义标签中嵌套的内容。说简单点就是自定义标签内的内容体。如果指令调用没有嵌套内容(例如，就像<@myDirective />或者<@myDirective>)，那么这个参数就会为空。
【1】：TemplateModel是一个接口类型，代表FreeMarker模板语言(FTL)数据类型的接口的公共超接口，即所有的数据类型都会被freemarker转成对应的TemplateModel。通常我们都使用TemplateScalarModel接口来替代它获取一个String 值，如TemplateScalarModel.getAsString();当然还有其它常用的替代接口，如TemplateNumberModel获取number等
类型 | FreeMarker接口 | FreeMarker实现 |
字符串 | TemplateScalarModel | SimpleScalar |
数值 | TemplateNumberModel | SimpleNumber |
日期 | TemplateDateModel | SimpleDate |
布尔 | TemplateBooleanModel | TemplateBooleanModel.TRUE |
哈希 | TemplateHashModel | SimpleHash |
序列 | TemplateSequenceModel | SimpleSequence |
集合 | TemplateCollectionModel | SimpleCollection |
节点 | TemplateNodeModel | NodeModel |
实现自定义标签
前面了解了 TemplateDirectiveModel的基本含义和用法，那么，接下来我们就以OneBlog中的例子来简单解释下如何实现自定义标签。
ps：为了方便阅读，本例只摘出了一部分关键代码，详细内容，请参考我的开源博客：https://gitee.com/yadong.zhang/DBlog
一、创建类实现TemplateDirectiveModel接口
1 @Component
2 public class CustomTagDirective implements TemplateDirectiveModel {
3 private static final String METHOD_KEY = "method";
4 @Autowired
5 private BizTagsService bizTagsService;
6
7 @Override
8 public void execute(Environment environment, Map map, TemplateModel[] templateModels, TemplateDirectiveBody templateDirectiveBody) throws TemplateException, IOException {
9 if (map.containsKey(METHOD_KEY)) {
10 DefaultObjectWrapperBuilder builder = new DefaultObjectWrapperBuilder(Configuration.VERSION_2_3_25);
11 String method = map.get(METHOD_KEY).toString();
12 switch (method) {
13 case "tagsList":
14 // 将数据对象转换成对应的TemplateModel
15 TemplateModel tm = builder.build().wrap(bizTagsService.listAll())
16 environment.setVariable("tagsList", tm);
17 break;
18 case other...
19 default:
20 break;
21 }
22 }
23 templateDirectiveBody.render(environment.getOut());
24 }
25 }
二、创建freemarker的配置类
1 @Configuration
2 public class FreeMarkerConfig {
3
4 @Autowired
5 protected freemarker.template.Configuration configuration;
6 @Autowired
7 protected CustomTags customTags;
8
9 /**
10 * 添加自定义标签
11 */
12 @PostConstruct
13 public void setSharedVariable() {
14 /*
15 * 向freemarker配置中添加共享变量;
16 * 它使用Configurable.getObjectWrapper()来包装值，因此在此之前设置对象包装器是很重要的。（即上一步的builder.build().wrap操作）
17 * 这种方法不是线程安全的;使用它的限制与那些修改设置值的限制相同。
18 * 如果使用这种配置从多个线程运行模板，那么附加的值应该是线程安全的。
19 */
20 configuration.setSharedVariable("zhydTag", customTags);
21 }
22 }
三、ftl模板中使用自定义标签
1 <div class="sidebar-module">
2 <h5 class="sidebar-title"><i class="fa fa-tags icon"></i><strong>文章标签</strong></h5>
3 <ul class="list-unstyled list-inline">
4 <@zhydTag method="tagsList" pageSize="10">
5 <#if tagsList?exists && (tagsList?size > 0)>
6 <#list tagsList as item>
7 <li class="tag-li">
8 <a class="btn btn-default btn-xs" href="${config.siteUrl}/tag/${item.id?c}" title="${item.name?if_exists}">
9 ${item.name?if_exists}
10 </a>
11 </li>
12 </#list>
13 </#if>
14 </@zhydTag>
15 </ul>
16 </div>
自定义标签的使用方法跟自定义宏(macro)用法一样，直接使用`<@标签名>${值}</@标签名>`即可。
注：ftl中通过@调用自定义标签时，后面可以跟任意参数，所有的参数都可以在execute方法的第二个参数(map)中获取，由此可以根据一个特定的属性开发一套特定的自定义标签，比如OneBlog中通过method参数判断调用不同的处理方式。
四、扩展FreeMarkerConfig
上面提到的自定义标签，都是通过 <@tagName>xxx</@tagName>方式调用的，那么针对我们系统中一些类环境变量的数据（全局的配置类属性等）如何像使用普通的el表达式一般直接通过${xx}获取呢？ 看代码：
1 @Configuration
2 public class FreeMarkerConfig {
3
4 @Autowired
5 protected freemarker.template.Configuration configuration;
6 @Autowired
7 private SysConfigService configService;
8
9 /**
10 * 添加自定义标签
11 */
12 @PostConstruct
13 public void setSharedVariable() {
14 try {
15 configuration.setSharedVariable("config", configService.get());
16 } catch (TemplateModelException e) {
17 e.printStackTrace();
18 }
19 }
20 }
如此而已，在使用的时候我们可以直接在页面上通过${config.siteName}调用config的参数即可。
五、可能遇到的问题
针对上面两种标签（ 类宏模式和 类el表达式模式），会有一个问题存在，如下图
在程序启动时会初始化FreemarkerConfig类（@PostConstruct），并且当且仅当程序启动时才会初始化一次。像 zhydTag这种自定义标签，因为是将整个自定义标签类（CustomTag）保存到了共享变量中，那么在使用自定义标签时，实际还是调用的相关接口获取数据库，当数据库发生变化时，也会同步更新到标签中；而像 config这种类el表达式的环境变量（如图，value的类型是一个StringModel），只会在程序初始化时加载一次，在后续调用标签时也只是调用的 SharedVariable中的config副本内容，并不会再次访问接口去数据库中获取数据。这样就造成了一个问题：当config表中的数据发生变化时，在前台通过${config.siteName}获取到的仍然是旧的数据。
六、解决问题
在OneBlog中，我是通过实现一个简单的AOP，去监控、对比config表的内容，当config表发生变化时，将新的config副本保存到freeamrker的 SharedVariable中。如下实现
1 /**
2 * 用于监控freemarker自定义标签中共享变量是否发生变化，发生变化时实时更新到内存中
3 *
4 * @author yadong.zhang (yadong.zhang0415(a)gmail.com)
5 * @version 2.0
6 * @date 2018/5/17 17:06
7 */
8 @Slf4j
9 @Component
10 @Aspect
11 @Order(1)
12 public class FreemarkerSharedVariableMonitorAspects {
13
14 private static volatile long configLastUpdateTime = 0L;
15 @Autowired
16 protected freemarker.template.Configuration configuration;
17 @Autowired
18 private SysConfigService configService;
19
20 @Pointcut(value = "@annotation(org.springframework.web.bind.annotation.GetMapping)" +
21 "|| @annotation(org.springframework.web.bind.annotation.RequestMapping)")
22 public void pointcut() {
23 // 切面切入点
24 }
25
26 @After("pointcut()")
27 public void after(JoinPoint joinPoint) {
28 Config config = configService.get();
29 if (null == config) {
30 log.error("config为空");
31 return;
32 }
33 Long updateTime = config.getUpdateTime().getTime();
34 if (updateTime == configLastUpdateTime) {
35 log.debug("config表未更新");
36 return;
37 }
38 log.debug("config表已更新，重新加载config到freemarker tag");
39 configLastUpdateTime = updateTime;
40 try {
41 configuration.setSharedVariable("config", config);
42 } catch (TemplateModelException e) {
43 e.printStackTrace();
44 }
45 }
46 }
当然， 虽然OneBlog中是使用的AOP方式解决问题，我们使用过滤器、拦截器也是一样的道理，
代码调优
上面介绍的编码实现方式，我们必须通过 switch...case去挨个判断实际的处理逻辑，在同一个标签类中有太多具体标签实现时，就显得比较笨重。因此，我们简单的优化一下代码，使它看起来不是那么糟糕并且易于扩展。
一、首先，分析代码，将公共模块提取出来。
TemplateDirectiveModel类的 execute方法是每个自定义标签类都必须实现的，并且每个自定义标签都是根据 method参数去使用具体的实现，这一块我们可以提成公共模块：
1 /**
2 * 所有自定义标签的父类，负责调用具体的子类方法
3 *
4 * @author yadong.zhang (yadong.zhang0415(a)gmail.com)
5 * @version 1.0
6 * @website https://www.zhyd.me
7 * @date 2018/9/18 16:19
8 * @since 1.8
9 */
10 public abstract class BaseTag implements TemplateDirectiveModel {
11
12 private String clazzPath = null;
13
14 public BaseTag(String targetClassPath) {
15 clazzPath = targetClassPath;
16 }
17
18 private String getMethod(Map params) {
19 return this.getParam(params, "method");
20 }
21
22 protected int getPageSize(Map params) {
23 int pageSize = 10;
24 String pageSizeStr = this.getParam(params, "pageSize");
25 if (!StringUtils.isEmpty(pageSizeStr)) {
26 pageSize = Integer.parseInt(pageSizeStr);
27 }
28 return pageSize;
29 }
30
31 private void verifyParameters(Map params) throws TemplateModelException {
32 String permission = this.getMethod(params);
33 if (permission == null || permission.length() == 0) {
34 throw new TemplateModelException("The 'name' tag attribute must be set.");
35 }
36 }
37
38 String getParam(Map params, String paramName) {
39 Object value = params.get(paramName);
40 return value instanceof SimpleScalar ? ((SimpleScalar) value).getAsString() : null;
41 }
42
43 private DefaultObjectWrapper getBuilder() {
44 return new DefaultObjectWrapperBuilder(Configuration.VERSION_2_3_25).build();
45 }
46
47 private TemplateModel getModel(Object o) throws TemplateModelException {
48 return this.getBuilder().wrap(o);
49 }
50
51
52 @Override
53 public void execute(Environment environment, Map map, TemplateModel[] templateModels, TemplateDirectiveBody templateDirectiveBody) throws TemplateException, IOException {
54 this.verifyParameters(map);
55 String funName = getMethod(map);
56 Method method = null;
57 try {
58 Class clazz = Class.forName(clazzPath);
59 method = clazz.getDeclaredMethod(funName, Map.class);
60 if (method != null) {
61 Object res = method.invoke(this, map);
62 environment.setVariable(funName, getModel(res));
63 }
64 } catch (NoSuchMethodException | IllegalAccessException | InvocationTargetException | ClassNotFoundException e) {
65 e.printStackTrace();
66 }
67 templateDirectiveBody.render(environment.getOut());
68 }
69
70 }
BaseTag作为所有自定义标签的父类，只需要接受一个参数：clazzPath，即子类的类路径（全类名），在实际的 execute方法中，只需要根据制定的 method，使用反射调用子类的相关方法即可。
二、优化后的标签类
1 /**
2 * 自定义的freemarker标签
3 *
4 * @author yadong.zhang (yadong.zhang0415(a)gmail.com)
5 * @version 1.0
6 * @website https://www.zhyd.me
7 * @date 2018/4/16 16:26
8 * @since 1.0
9 * @modify by zhyd 2018-09-20
10 * 调整实现，所有自定义标签只需继承BaseTag后通过构造函数将自定义标签类的className传递给父类即可。
11 * 增加标签时，只需要添加相关的方法即可，默认自定义标签的method就是自定义方法的函数名。
12 * 例如：<@zhydTag method="types" ...></@zhydTag>就对应 {{@link #types(Map)}}方法
13 */
14 @Component
15 public class CustomTags extends BaseTag {
16
17 @Autowired
18 private BizTypeService bizTypeService;
19
20 public CustomTags() {
21 super(CustomTags.class.getName());
22 }
23
24 public Object types(Map params) {
25 return bizTypeService.listTypeForMenu();
26 }
27
28 // 其他自定义标签的方法...
29 }
如上，所有自定义标签只需继承BaseTag后通过构造函数将自定义标签类的className传递给父类即可。增加标签时，只需要添加相关的方法即可，默认自定义标签的method就是自定义方法的函数名。
例如：<@zhydTag method="types" ...>就对应 CustomTags#types(Map)方法
如此一来，我们想扩展标签时，只需要添加相关的自定义方法即可，ftl中通过method指定调用哪个方法。
