改造Velocity模板引擎让$[!]{}输出默认进行html转义，并增加$#{}语法支持不转义输出

摘要: Velocity为我们提供了EscapeHtmlReference event handler用于在引用变量值输出之前进行HTML转义处理，但是这个HTML转义功能需要通过eventhandler.escape.html.match=//配置指定变量前缀来进行，特别对于有的变量需要转义，有的变量不需要转义的情况下非常的不方便，深受之苦；因此我决定改造扩展Velocity的语法：让 $[!]{ param } 默认转义输出，增加 $#{ param } 语法支持原样输出。

一直以来在项目中使用Apache Velocity模板引擎作为视图层输出，为了解决XSS漏洞，需要对输出到页面的内容进行HTML转义，我一般采用2种方式实现：

使用过滤器 Filter，在其中进行 HttpServletRequestWrapper 的 getParameter( )等方法重载，在底层进行HTML转义，然后页面直接输出；
这种方式很轻松很直接，业务代码不需要修改就完成了所有的转义工作；但是也带来了问题：修改了用户的原始输入数据，如果需要用到用户的原始输入数据，又得反转义回去，很麻烦。

在页面上使用 velocity-tools 的 $esc.html( ) 进行手工转义：$esc.html($task.content)；
这种方式工作量比较大，需要在转义的变量上增加 $esc.html()，很容易遗漏。

那有没有别的方法来解决呢？

后来我发现 Velocity 为我们提供了EscapeHtmlReference event handler 用于在引用变量值输出之前进行HTML转义处理，但是这个HTML转义功能需要通过eventhandler.escape.html.match=//配置指定变量前缀来进行，特别对于有的变量需要转义，有的变量不需要转义的情况下非常的不方便；在用了一段时间后，感觉很麻烦，污染变量命名，不爽；

正巧这段时间也使用了 artTemplate.js 的前端模板引擎，发现这个模板引擎提供了2种变量输出方式：<%= param %> 和 <%== param %>，其中 <%= param %> 是默认的常用输出方式（会对变量值中的HTML字符进行转义输出），<%== param %> 则是原样输出（不进行任何转义）；感觉这样的方式非常的好，即满足了大部分的转义输出，也满足了小部分的非转义输出，而且不用对业务代码进行修改，而是由模板引擎提供不同的输出方法。

那能否修改 Velocity 的语法，也支持一种非转义输出呢？这样不就完美解决这个问题了吗？

$[ ! ][ { ] param [ } ] 是 Velocity 的默认引用定义和输出语法，为了自定义的语法简单易用，想采用 $#{ ... } 语法格式，这样和原来的语法只有一个字的差别：! -> #

// 默认转义输出
$task.content
${task.content}
$!task.content
$!{task.content}

// 原样不转义输出
$#task.content
$#{task.content}

于是我开始研究 Velocity 的语法解析代码，Velocity 采用 AST 语法树进行模板的语法解析的，所有的语法定义在 Parser.jjt 文件中，然后使用JAVACC 编译Parser.jjt文件生成语法解析代码（ASTAddNode，ASTEQNode, ASTReference, ASTSetDirective等等），$[ ! ][ { ] ... [ } ] 语法Velocity定义为 Reference，因此 ASTReference.java 就是用来处理 Reference 的。

在 Parser.jjt 文件的 730 行定义了这样的语法配置：

<DOLLARBANG: ("\\")* "$" ("\\")* "!">

这段语法是用来支持 $! 的，如果我把最后的 "!" 变成 ("!"|"#") 不就支持 $# 了嘛，呵呵，修改之（当然其它的语法定义也必须都看一遍）：

<DOLLARBANG: ("\\")* "$" ("\\")* ("!"|"#")>

发现在 ASTReference.java 文件的 getRoot() 方法中进行了 $! 和 $!{ 的处理：

if (t.image.startsWith("$!")) {
referenceType = QUIET_REFERENCE;

/*
*  only if we aren't escaped do we want to null the output
*/

if (!escaped) nullString = "";

if (t.image.startsWith("$!{")) {
/*
*  ex : $!{provider.Title}
*/
return t.next.image;
} else {
/*
*  ex : $!provider.Title
*/
return t.image.substring(2);
}
}

在有了上面的了解后，修改Velocity的Reference 语法规则就简单了，迅速修改 Parser.jjt 文件，然后使用 JAVACC（我使用javacc-eclipse插件） 编译Parser.jjt，生成了和Velocity src 下源码一样的AST代码结构，由于我修改的仅仅是 Reference 的语法，因此生成的代码文件中我只保留了 ParserTokenManager.java 文件（用于替换src的该文件，这个文件代码很多，又没有发现可以上传附件的地方，因此代码就不贴出了），其它的文件使用原始 src 下的文件（注意：原始src下的AST文件大部分被后期手工修改完善，因此不能完全使用新编译生成的AST代码文件）。

同时对原始的 ASTReference.java 的 getRoot() 方法中的代码进行扩充，支持 $# 的处理：

if (t.image.startsWith("$!") || t.image.startsWith("$#")) {
referenceType = QUIET_REFERENCE;

/*
*  only if we aren't escaped do we want to null the output
*/

if (!escaped) nullString = "";

if (t.image.startsWith("$!{") || t.image.startsWith("$#{"))
{
/*
*  ex : $!{provider.Title} OR $#{provider.Title}
*/

return t.next.image;
}
else
{
/*
*  ex : $!provider.Title OR $#provider.Title
*/

return t.image.substring(2);
}
}

然后测试，一切OK，这样 Velocity 就多了一个语法：$#[ { ] ... [ } ] 支持。

哦，还没完呢，呵呵，此时 $#{} 仅仅和 $!{} 一样，下面开始对这2个命令进行处理：$!{} -- 转义输出， $#{} -- 不转义输出：

为了不修改原始核心代码，方便扩展，这里采用扩展 Velocity 提供的 ReferenceInsertionEventHandler 接口实现进行（类似EscapeHtmlReference），直接上代码和配置：

import org.apache.velocity.app.event.ReferenceInsertionEventHandler;
import org.apache.velocity.runtime.RuntimeServices;
import org.apache.velocity.util.RuntimeServicesAware;

/**
* HTML转义输出
*/
public class VelocityEscapeHtmlOutput
implements ReferenceInsertionEventHandler, RuntimeServicesAware
{
private RuntimeServices rs = null;

public Object referenceInsert(String reference, Object value)
{
// 呵呵，这里... 凡是以 $#开头的reference，其值直接返回(^_^)
if(reference.startsWith("$#")) {
return value;
}
// 其它默认转义
return escapeHtml(value);
}

public void setRuntimeServices(RuntimeServices rs)
{
this.rs = rs;
}

protected RuntimeServices getRuntimeServices()
{
return this.rs;
}

/**
* 转义HTML字符串
* @param str
* @return
*/
private static Object escapeHtml(Object value)
{
if(value == null)
{
return null;
}

if(!(value instanceof String))
{
return value;
}

String str = value.toString();
StringBuilder sb = new StringBuilder(str.length() + 30);

for(int i = 0, len = str.length(); i < len; i++)
{
char c = str.charAt(i);
// 去除不可见字符
if((int)c < 32)
{
continue;
}

switch(c)
{
case '<':
sb.append("<");
break;
case '>':
sb.append(">");
break;
case '&':
sb.append("&");
break;
case '"':
sb.append(""");
break;
case '\'':
sb.append("'");
break;
default:
sb.append(c);
break;
}
}

str = null;

return sb.toString();
}
}

Velocity 提供的EventHandler接口需要在 velocity.properties中进行配置才能生效：

eventhandler.referenceinsertion.class = com.xxx.VelocityEscapeHtmlOutput

到此为止，就完成了对 Velocity 的 Reference 语法改造了！尽情享用吧！