TDD两小时实现自定义表达式模板解析器

为什么要重新造一个车轮？

很多情况下，用户需要按其自定义模板动态生成邮件、PDF。开源组件中，有两类较贴合需求的产品系列：

模板渲染引擎，如FreeMarker, Velocity虽然强大异常，但是过于灵活，不利于按需裁减出自己想要的少量语法；
纯字符串模板引擎，要么取数据不够动态(需要提前预知有哪些变量)，或者是语法冗长(函数调用来实现动态扩展)不利于非IT人士编写。

那么有没有一款产品，既简洁可控，又易于扩展呢？

其实自己实现一个够用的模板解析器，也是很简单的事情，下面分享一款我两小时在融创地产HR项目中实现的模板解析器。

本实现没有任何外部依赖，很容易移植到其它语言，比如用javascript实现甚至更简单。

用户场景

用户的原始需求：

亲爱的XXX先生/女士
  你好！欢迎加入XXX公司，你的部门是XXX，岗位职级XXX
  …
  人事部 HR XXX先生/女士

模板设计：

亲爱的${uid|userInfo|prop:name}${uid|userInfo|prop:gender|genderName}
  你好！欢迎加入 一天一个小目标 公司，你的部门是${uid|department|prop:name}，岗位职级${uid|position|prop:name}
  …
  人事部 HR ${my|prop:name}${my|prop:gender|genderName}

语法(静态语法)

"${}":需要值替换的表达式，包含在"${"与"}"之间；
"|": 顺序串联单个表达式的多个函数调用，前一调用的值会作为后一调用的第一参数；
":": 若调用有额外参数，则追加在":"之后；
",": 若额外参数不止一个，则以","分隔。

函数说明(可扩展及控制部分)

uid: 获取当前调用的目标用户id
userInfo: 根据用户id获取用户信息
prop:name: 获取对象的"name"属性
prop:gender: 获取对象的"gender"属性
genderName: 获取性别的中文名
department: 根据用户id获取所在部门信息
position: 根据用户id获取其岗位信息
my: 获取session中当前登录的用户信息

Tips: 此处是为了可读性使用了相对完整的单词。实际为了简洁，我们采用了单个到两个字母表示每个函数(如:"P:name"="prop:name","GN"="genderName")，然后在前端文本编辑器下方给用户一张函数表去定制模板，实践证明在语法、函数不多的情况下，对非IT人士整个模板的简洁比部分内容的可读性更重要

实现过程

代码库 https://gitee.com/chentao106/SimpleExpressionInterpreter 通过提交记录完整展示了实现过程，整体只需要五步，即可实现一个面向非IT人士的自定义表达式模板解析器：

第一步创建代码框架及测试用例

先创建我们的解析器类，及其最重要的方法eval，即模板求值：

//SimpleExpressionInterpreter.java
public class SimpleExpressionInterpreter {
  public String eval(String template) {
    return null;
  }
}

测试驱动开发，当然要先编写测试用例：

//SimpleExpressionInterpreterTester.java
import org.junit.Assert;
import org.junit.Test;

public class SimpleExpressionInterpreterTester {
  static final String template = "亲爱的${uid|userInfo|prop:name}${uid|userInfo|prop:gender|genderName}\n" +
      "  你好！欢迎加入不存在公司，你的部门是${uid|department|prop:name}，岗位职级${uid|position|prop:name}…\n" +
      "  人事部 HR ${my|prop:name}${my|prop:gender|genderName}\n";
  static final String value = "亲爱的李四女士\n" +
      "  你好！欢迎加入不存在公司，你的部门是互联网行销部，岗位职级产品经理T1…\n" +
      "  人事部 HR 张三先生\n";

  private SimpleExpressionInterpreter testObj = new SimpleExpressionInterpreter();

  @Test
  public void testEval() {
    Assert.assertEquals(value, testObj.eval(template));
  }
}

此时，测试用例当然是执行不通过的，我们想办法让测试先通过，才好进行下一步，同时定义一下我们的语法关键字：

//SimpleExpressionInterpreter.java
public class SimpleExpressionInterpreter {
  protected String expressionStart = "${";
  protected String expressionEnd = "}";
  protected String invocationSplit = "|";
  protected String methodNameSplit = ":";
  protected String parameterSplit = ",";
  protected char escape = '\\';

  public String eval(String template) {
    return "亲爱的李四女士\n" +
        "  你好！欢迎加入不存在公司，你的部门是互联网行销部，岗位职级产品经理T1…\n" +
        "  人事部 HR 张三先生\n";
  }
}

运行测试用例，保证通过

第二步提取字符器模板中的表达式

修改SimpleExpressionInterpreter.java文件，在其中增加

  //SimpleExpressionInterpreter.java
  List<String> findExpressions(String template) {
    return null;
  }

增加测试用例

  //SimpleExpressionInterpreterTester.java
  @Test
  public void testFindExpressions() {
    Assert.assertEquals(Collections.EMPTY_LIST, testObj.findExpressions("{a}"));
    Assert.assertEquals(Collections.singletonList("${a}"), testObj.findExpressions("${a}"));
    Assert.assertEquals(Collections.singletonList("${a}"), testObj.findExpressions("\\$${a}"));
    Assert.assertEquals(Arrays.asList("${a}", "${b}"), testObj.findExpressions("${a}${b}"));
    Assert.assertEquals(Arrays.asList("${a}", "${b}"), testObj.findExpressions("Hello ${a}, world${b}"));
    Assert.assertEquals(Collections.singletonList("${a\\}${b}"), testObj.findExpressions("${a\\}${b}"));
    Assert.assertEquals(Collections.EMPTY_LIST, testObj.findExpressions("${a\\}${b"));
    Assert.assertEquals(Arrays.asList("${uid|userInfo|prop:name}", "${uid|userInfo|prop:gender|genderName}",
        "${uid|department|prop:name}", "${uid|position|prop:name}",
        "${my|prop:name}", "${my|prop:gender|genderName}"), testObj.findExpressions(template));
  }

为确保测试通过，修改SimpleExpressionInterpreter.java：

  //SimpleExpressionInterpreter.java
  int nextDivider(String template, String divider, int fromIndex) {
    int pos;
    int from = fromIndex;
    do {
      pos = template.indexOf(divider, from);
      if (pos == 0) return pos;
      if (pos > 0 && template.charAt(pos - 1) != escape) return pos;
      from = pos + 1;
    } while (pos >= 0);
    return -1;
  }

  List<String> findExpressions(String template) {
    List<String> expressions = new LinkedList<>();
    int fromIndex = 0;
    String expression;
    do {
      int beginIndex = nextDivider(template, expressionStart, fromIndex);
      if (beginIndex < 0) break;
      int endIndex = nextDivider(template, expressionEnd, beginIndex + expressionStart.length());
      if (endIndex < 0) break;
      expression = template.substring(beginIndex, endIndex + expressionEnd.length());
      expressions.add(expression);
      fromIndex = endIndex + expressionEnd.length();
    } while (true);
    return expressions;
  }

为了重用表达式前缀和后缀的查找代码，我们提取了公共函数nextDivider，我们也可以给它增加测试用例：

  //SimpleExpressionInterpreterTester.java
  @Test
  public void testNextDivider() {
    Assert.assertEquals(-1, testObj.nextDivider("{a}", testObj.expressionStart, 0));
    Assert.assertEquals(0, testObj.nextDivider("${a}", testObj.expressionStart, 0));
    Assert.assertEquals(2, testObj.nextDivider("\\$${a}", testObj.expressionStart, 0));
    Assert.assertEquals(4, testObj.nextDivider("${a}${b}", testObj.expressionStart, 1));
    Assert.assertEquals(3, testObj.nextDivider("${a}${b}", testObj.expressionEnd, 1));
    Assert.assertEquals(8, testObj.nextDivider("${a\\}${b}", testObj.expressionEnd, 1));
    Assert.assertEquals(-1, testObj.nextDivider("${a\\}${b", testObj.expressionEnd, 1));
  }

运行测试用例，保证通过

第三步解析表达式调用链

调用必须先用一个实体来表示：

//Invocation.java
import java.util.Arrays;

public class Invocation {
  private String method;
  private String[] extraParams;

  public Invocation(String method, String... extraParams) {
    this.method = method;
    this.extraParams = extraParams;
  }

  public Invocation(String method) {
    this(method, null);
  }

  public String getMethod() {
    return method;
  }

  public String[] getExtraParams() {
    return extraParams;
  }

  @Override
  public int hashCode() {
    return method.hashCode() + (extraParams == null ? 0 : Arrays.hashCode(extraParams));
  }

  @Override
  public boolean equals(Object obj) {
    if (obj == null) return false;
    if (!this.getClass().isInstance(obj)) return false;
    if (this.hashCode() != obj.hashCode()) return false;
    Invocation another = (Invocation) obj;
    return this.method.equals(another.method) && Arrays.equals(this.extraParams, another.extraParams);
  }

  @Override
  public String toString() {
    return extraParams == null || extraParams.length == 0 ? method : String.format("%s:%s", method, String.join(",", extraParams));
  }
}

增加解析调用链的函数声明：

//SimpleExpressionInterpreter.java
  List<Invocation> parseInvocations(String expression) {
    return null;
  }

增加测试用例：

//SimpleExpressionInterpreterTester.java
  @Test
  public void testParseInvocations() {
    Assert.assertEquals(Collections.EMPTY_LIST, testObj.parseInvocations(""));
    Assert.assertEquals(Collections.singletonList(new Invocation("a")), testObj.parseInvocations("${a}"));
    Assert.assertEquals(Arrays.asList(new Invocation("a"), new Invocation("b"), new Invocation("c")), testObj.parseInvocations("${a|b|c}"));
    Assert.assertEquals(Arrays.asList(new Invocation("uid"), new Invocation("userInfo"),
        new Invocation("prop", "name")), testObj.parseInvocations("${uid|userInfo|prop:name}"));
  }

为了通过测试，修改SimpleExpressionInterpreter.java：

//SimpleExpressionInterpreter.java
  List<Invocation> parseInvocations(String expression) {
    if (expression == null || expression.length() < expressionStart.length() + expressionEnd.length()) return Collections.emptyList();
    String statement = expression.substring(expressionStart.length(), expression.length() - expressionEnd.length());
    String[] phrases = split(statement, invocationSplit);
    List<Invocation> invocations = new ArrayList<>(phrases.length);
    for (String phrase : phrases) {
      invocations.add(parseInvocation(phrase));
    }
    return invocations;
  }

  private Invocation parseInvocation(String phrase) {
    int methodNameEndIndex = phrase.indexOf(methodNameSplit);
    if (methodNameEndIndex > 0) {
      String method = phrase.substring(0, methodNameEndIndex);
      String parameterStr = phrase.substring(methodNameEndIndex + methodNameSplit.length());
      String[] parameters = parameterStr.split(parameterSplit);
      return new Invocation(method, parameters);
    } else {
      return new Invocation(phrase);
    }
  }

  String[] split(String text, String delimiter) {
    if (text == null) return null;
    if (delimiter == null || delimiter.length() == 0) return new String[]{text};
    List<String> data = new ArrayList<>();
    int pos = 0;
    for (int from = 0; from >= 0; from = pos + delimiter.length()) {
      pos = text.indexOf(delimiter, from);
      if (pos >= 0) {
        data.add(text.substring(from, pos));
      } else {
        data.add(text.substring(from));
        break;
      }
    }
    return data.toArray(new String[0]);
  }

为了支持使用"|"串连表达式，我们重写了String的split函数(split使用正则表达式拆分，而"|"是正则表达式的关键字，不考虑语法可替换、可跨语言移植的情况下，可以直接转义"\|"+String.split)，我们也为它加上测试用例：

//SimpleExpressionInterpreterTester.java
  @Test
  public void testSplit() {
    Assert.assertNull(testObj.split(null, "|"));
    Assert.assertArrayEquals(new String[]{"a|b"}, testObj.split("a|b", null));
    Assert.assertArrayEquals(new String[]{"a|b"}, testObj.split("a|b", ""));
    Assert.assertArrayEquals(new String[]{"a", "b"}, testObj.split("a|b", "|"));
    Assert.assertArrayEquals(new String[]{"ab", "cd:ef,gh"}, testObj.split("ab|cd:ef,gh", "|"));
    Assert.assertArrayEquals(new String[]{"ab", "cd", "ef", "gh"}, testObj.split("ab,cd,ef,gh", ","));
  }

运行测试用例，保证通过

第四步实现表达式求值

到了最关键的表达式求值步骤，照旧我们还是先定义函数

//SimpleExpressionInterpreter.java
  String evalExpression(String expression) {
    return null;
  }

编写测试

//SimpleExpressionInterpreterTester.java
  @Test
  public void testEvalExpression() {
    Assert.assertEquals("李四", testObj.evalExpression("${uid|userInfo|prop:name}"));
    Assert.assertEquals("女士", testObj.evalExpression("${uid|userInfo|prop:gender|genderName}"));
    Assert.assertEquals("先生", testObj.evalExpression("${my|prop:gender|genderName}"));
    Assert.assertEquals("", testObj.evalExpression("${my1|prop:gender|genderName}"));
  }

如何实现表达式求值呢？首先我想到了javascript可以通过函数名来调用对象的方法，如果是java就要用到反射了。也就是说，我们可以把函数调用全部委托给另一个对象，我称作methodProvider，那么开始动手吧：

//SimpleExpressionInterpreter.java
  //增加成员变量，并通过注入一个methodProvider
  private final Object methodProvider;
  public SimpleExpressionInterpreter(Object methodProvider) {
    this.methodProvider = methodProvider;
  }

  //实现回调逻辑
  private Method findMethod(Class<?> clazz, String methodName) {
    for (Method m : clazz.getMethods()) {
      if (m.getName().equals(methodName)) {
        return m;
      }
    }
    return null;
  }

  private Object evalInvocations(List<Invocation> invocations) {
    boolean firstCall = true;
    Object result = null;
    try {
      for (Invocation invocation : invocations) {
        Method m = findMethod(methodProvider.getClass(), invocation.getMethod());
        if (m == null) return null;
        Object[] args;
        if (invocation.getExtraParams() != null) {
          args = new Object[invocation.getExtraParams().length + (firstCall ? 0 : 1)];
          if (!firstCall) args[0] = result;
          System.arraycopy(invocation.getExtraParams(), 0, args, firstCall ? 0 : 1, invocation.getExtraParams().length);
        } else {
          args = firstCall ? new Object[0] : new Object[]{result};
        }
        result = m.invoke(methodProvider, args);
        firstCall = false;
      }
    } catch (IllegalAccessException | InvocationTargetException e) {
      return null;
    }
    return result;
  }

  String evalExpression(String expression) {
    List<Invocation> invocations = parseInvocations(expression);
    Object result = evalInvocations(invocations);
    return result == null ? "" : result.toString();
  }

为了测试，我们要实现一个DemoMethodProvider，实际应用时，MethodProvider类就决定了你想向用户提供哪些可用函数：

//DemoMethodProvider.java
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class DemoMethodProvider {
  private Map<String, Object> callParameters;//模拟实时传入的参数
  private Map<String, Map<String, ?>> demoDB;//模拟数据库中的数据

  public DemoMethodProvider() {
    callParameters = new HashMap<>();
    Map<String, Object> my = new HashMap<>();
    my.put("id", 0);
    my.put("name", "张三");
    my.put("gender", 1);
    callParameters.put("my", my);
    callParameters.put("uid", 1);

    demoDB = new HashMap<>();
    Map<String, Object> you = new HashMap<>();
    you.put("id", 1);
    you.put("name", "李四");
    you.put("gender", 2);
    demoDB.put(String.format("user:%d", 1), you);
    Map<String, Object> yourDepartment = Collections.singletonMap("name", "互联网行销部");
    demoDB.put(String.format("user:%d:department", 1), yourDepartment);
    Map<String, Object> yourPosition = Collections.singletonMap("name", "产品经理T1");
    demoDB.put(String.format("user:%d:position", 1), yourPosition);
  }

  public Object uid() {
    return callParameters.get("uid");
  }

  public Object my() {
    return callParameters.get("my");
  }

  public Map<String, ?> userInfo(int uid) {
    return demoDB.get(String.format("user:%d", uid));
  }

  public Map<String, ?> department(int uid) {
    return demoDB.get(String.format("user:%d:department", uid));
  }

  public Map<String, ?> position(int uid) {
    return demoDB.get(String.format("user:%d:position", uid));
  }

  public Object prop(Map<String, ?> map, String propName) {
    return map.get(propName);
  }

  public String genderName(int gender) {
    switch (gender) {
      case 1:
        return "先生";
      case 2:
        return "女士";
      default:
        return "";
    }
  }
}

测试用例中创建SimpleExpressionInterpreter时注入DemoMethodProvider

//SimpleExpressionInterpreterTester.java
private SimpleExpressionInterpreter testObj = new SimpleExpressionInterpreter(new DemoMethodProvider());

运行测试用例，保证通过

第五步组装代码实现模板求值

第一步我们通过写死返回值，已经“实现”了固定模板的解析，当然这个“实现”是静态的，我们首先修改测试用例，暴露代码问题(当然更建议的是增加更多完整的模板->结果测试用例)：

//SimpleExpressionInterpreterTester.java
  @Test
  public void testEval() {
    Assert.assertEquals(value, testObj.eval(template));
    Assert.assertEquals(value + "...", testObj.eval(template + "..."));
    Assert.assertEquals("", testObj.eval(""));
    Assert.assertNull(testObj.eval(null));
  }

修改实现以保证测试通过：

//SimpleExpressionInterpreter.java
  public String eval(String template) {
    if (template == null || template.length() == 0) return template;
    String result = template;
    List<String> expressions = findExpressions(template);
    for (String expression : expressions) {
      String value = evalExpression(expression);
      result = result.replace(expression, value);
    }
    return result;
  }

上面的自定义表达式模板解析器虽然还有改进空间，但是在大部分情况下都已经够用了，这不就是测试驱动的高效之处吗? 到此，我们可以非常自信地说，我们快速实现了一个高质量、简洁够用的自定义表达式模板解析器，可以放心的使用到业务代码中去。

后续工作

作为一款组件，上面的自定义表达式模板解析器，还有一定的改良空间：

模板求值采用replace会涉及内存分配，可以在解析表达式的同时，把模板片段也解析出来，在求值后整体进行一次拼字符串操作；
解析器的创建可以引入Builder生成器，从而语法关键字可以实现运行时的动态指定；
对转义字符的支持——上面的实现实际已经支持了表达式之外的转义，即用户内容中有${关键字，但是没有处理表达式内的转义，即表达式包含}，但是基于这个表达式的初衷，大家自行决断吧！！