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

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

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

  1. 使用过滤器 Filter,在其中进行 HttpServletRequestWrapper 的 getParameter( )等方法重载,在底层进行HTML转义,然后页面直接输出;

    这种方式很轻松很直接,业务代码不需要修改就完成了所有的转义工作;但是也带来了问题:修改了用户的原始输入数据,如果需要用到用户的原始输入数据,又得反转义回去,很麻烦。

  2. 在页面上使用 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("&#60;");
					break;
				case ‘>‘:
					sb.append("&#62;");
					break;
				case ‘&‘:
					sb.append("&#38;");
					break;
				case ‘"‘:
					sb.append("&#34;");
					break;
				case ‘\‘‘:
					sb.append("&#39;");
					break;
				case ‘/‘:
					sb.append("&#47;");
					break;
				default:
					sb.append(c);
					break;
			}
		}
		
		str = null;
		
		return sb.toString();
	}
}

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

eventhandler.referenceinsertion.class = com.xxx.VelocityEscapeHtmlOutput


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

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