一文掌握MyBatis的动态SQL使用与原理

来源 | OSCHINA 社区

作者 | 华为云开发者联盟

摘要：使用动态 SQL 并非一件易事，但借助可用于任何 SQL 映射语句中的强大的动态 SQL 语言，MyBatis 显著地提升了这一特性的易用性。

本文分享自华为云社区《MyBatis 详解 - 动态 SQL 使用与原理》，作者：龙哥手记 。 动态 SQL 是 MyBatis 的强大特性之一。如果你使用过 JDBC 或其它类似的框架，你应该能理解根据不同条件拼接 SQL 语句有多痛苦，例如拼接时要确保不能忘记添加必要的空格，还要注意去掉列表最后一个列名的逗号。利用动态 SQL，可以彻底摆脱这种痛苦。 使用动态 SQL 并非一件易事，但借助可用于任何 SQL 映射语句中的强大的动态 SQL 语言，MyBatis 显著地提升了这一特性的易用性。 如果你之前用过 JSTL 或任何基于类 XML 语言的文本处理器，你对动态 SQL 元素可能会感觉似曾相识。在 MyBatis 之前的版本中，需要花时间了解大量的元素。借助功能强大的基于 OGNL 的表达式，MyBatis 3 替换了之前的大部分元素，大大精简了元素种类，现在要学习的元素种类比原来的一半还要少。

if

choose (when, otherwise)

trim (where, set)

foreach

if

使用动态 SQL 最常见情景是根据条件包含 where 子句的一部分。比如：

  SELECT * FROM BLOG
  WHERE state = ‘ACTIVE’
 
    AND title like #{title}
 

 

这条语句提供了可选的查找文本功能。如果不传入 “title”，那么所有处于 “ACTIVE” 状态的 BLOG 都会返回；如果传入了 “title” 参数，那么就会对 “title” 一列进行模糊查找并返回对应的 BLOG 结果（细心的读者可能会发现，“title” 的参数值需要包含查找掩码或通配符字符）。

如果希望通过 “title” 和 “author” 两个参数进行可选搜索该怎么办呢？首先，我想先将语句名称修改成更名副其实的名称；接下来，只需要加入另一个条件即可。

 

  SELECT * FROM BLOG WHERE state = ‘ACTIVE’
 
    AND title like #{title}
 
 
    AND author_name like #{author.name}
 

 

choose、when、otherwise

有时候，我们不想使用所有的条件，而只是想从多个条件中选择一个使用。针对这种情况，MyBatis 提供了 choose 元素，它有点像 Java 中的 switch 语句。

还是上面的例子，但是策略变为：传入了 “title” 就按 “title” 查找，传入了 “author” 就按 “author” 查找的情形。若两者都没有传入，就返回标记为 featured 的 BLOG（这可能是管理员认为，与其返回大量的无意义随机 Blog，还不如返回一些由管理员挑选的 Blog）。

 

  SELECT * FROM BLOG WHERE state = ‘ACTIVE’
 
 
      AND title like #{title}
 
 
      AND author_name like #{author.name}
 
 
      AND featured = 1
 
 

 

trim、where、set

前面几个例子已经合宜地解决了一个臭名昭著的动态 SQL 问题。现在回到之前的 “if” 示例，这次我们将 “state = ‘ACTIVE’” 设置成动态条件，看看会发生什么。

 

  SELECT * FROM BLOG
  WHERE
 
    state = #{state}
 
 
    AND title like #{title}
 
 
    AND author_name like #{author.name}
 

 

如果没有匹配的条件会怎么样？最终这条 SQL 会变成这样：

 

SELECT * FROM BLOG
WHERE

 

这会导致查询失败。如果匹配的只是第二个条件又会怎样？这条 SQL 会是这样:

 

SELECT * FROM BLOG
WHERE
AND title like ‘someTitle’

 

这个查询也会失败。这个问题不能简单地用条件元素来解决。这个问题是如此的难以解决，以至于解决过的人不会再想碰到这种问题。

MyBatis 有一个简单且适合大多数场景的解决办法。而在其他场景中，可以对其进行自定义以符合需求。而这，只需要一处简单的改动：

 

  SELECT * FROM BLOG
 
 
         state = #{state}
 
 
        AND title like #{title}
 
 
        AND author_name like #{author.name}
 
 

 

where 元素只会在子元素返回任何内容的情况下才插入 “WHERE” 子句。而且，若子句的开头为 “AND” 或 “OR”，where 元素也会将它们去除。

如果 where 元素与你期望的不太一样，你也可以通过自定义 trim 元素来定制 where 元素的功能。比如，和 where 元素等价的自定义 trim 元素为：

 

  ...

 

prefixOverrides 属性会忽略通过管道符分隔的文本序列（注意此例中的空格是必要的）。上述例子会移除所有 prefixOverrides 属性中指定的内容，并且插入 prefix 属性中指定的内容。

用于动态更新语句的类似解决方案叫做 set。set 元素可以用于动态包含需要更新的列，忽略其它不更新的列。比如：

 

  update Author
 
 username=#{username},
 password=#{password},
 email=#{email},
 bio=#{bio}
 
  where id=#{id}

 

这个例子中，set 元素会动态地在行首插入 SET 关键字，并会删掉额外的逗号（这些逗号是在使用条件语句给列赋值时引入的）。

来看看与 set 元素等价的自定义 trim 元素吧：

 

  ...

 

注意，我们覆盖了后缀值设置，并且自定义了前缀值。

foreach

动态 SQL 的另一个常见使用场景是对集合进行遍历（尤其是在构建 IN 条件语句的时候）。比如：

 

  SELECT *
  FROM POST P
  WHERE ID in
 
        #{item}
 

 

foreach 元素的功能非常强大，它允许你指定一个集合，声明可以在元素体内使用的集合项（item）和索引（index）变量。它也允许你指定开头与结尾的字符串以及集合项迭代之间的分隔符。这个元素也不会错误地添加多余的分隔符，看它多智能！

提示：你可以将任何可迭代对象（如 List、Set 等）、Map 对象或者数组对象作为集合参数传递给 foreach。当使用可迭代对象或者数组时，index 是当前迭代的序号，item 的值是本次迭代获取到的元素。当使用 Map 对象（或者 Map.Entry 对象的集合）时，index 是键，item 是值。

至此，我们已经完成了与 XML 配置及映射文件相关的讨论。下一章将详细探讨 Java API，以便你能充分利用已经创建的映射配置。

script

要在带注解的映射器接口类中使用动态 SQL，可以使用 script 元素。比如:

 

 @Update({""})
 void updateAuthorValues(Author author);

 

bind

bind 元素允许你在 OGNL 表达式以外创建一个变量，并将其绑定到当前的上下文。比如：

 

 
  SELECT * FROM BLOG
  WHERE title LIKE #{pattern}

 

多数据库支持

如果配置了 databaseIdProvider，你就可以在动态代码中使用名为 “_databaseId” 的变量来为不同的数据库构建特定的语句。比如下面的例子：

 

 
 
      select seq_users.nextval from dual
 
 
      select nextval for seq_users from sysibm.sysdummy1"
 
 
  insert into users values (#{id}, #{name})

 

动态 SQL 中的插入脚本语言

MyBatis 从 3.2 版本开始支持插入脚本语言，这允许你插入一种语言驱动，并基于这种语言来编写动态 SQL 查询语句。

可以通过实现以下接口来插入一种语言：

 

public interface LanguageDriver {
 ParameterHandler createParameterHandler(MappedStatement mappedStatement, Object parameterObject, BoundSql boundSql);
 SqlSource createSqlSource(Configuration configuration, XNode script, Class parameterType);
 SqlSource createSqlSource(Configuration configuration, String script, Class parameterType);
}

 

实现自定义语言驱动后，你就可以在 mybatis-config.xml 文件中将它设置为默认语言：

 

 

或者，你也可以使用 lang 属性为特定的语句指定语言：

 

  SELECT * FROM BLOG

 

或者，在你的 mapper 接口上添加 @Lang 注解：

 

public interface Mapper {
 @Lang(MyLanguageDriver.class)
 @Select("SELECT * FROM BLOG")
 List selectBlog();
}

 

提示：可以使用 Apache Velocity 作为动态语言，更多细节请参考 MyBatis-Velocity 项目。

你前面看到的所有 xml 标签都由默认 MyBatis 语言提供，而它由语言驱动 org.apache.ibatis.scripting.xmltags.XmlLanguageDriver（别名为 xml）所提供。

动态 SQL 解析原理

我们在使用 mybatis 的时候，会在 xml 中编写 sql 语句。比如这段动态 sql 代码：

 

    UPDATE users
 
 
            name = #{name}
 
 
            , age = #{age}
 
 
            , birthday = #{birthday}
 
 
    where id = ${id}

 

mybatis 底层是如何构造这段 sql 的？下面带着这个疑问，我们一步一步分析。

关于动态 SQL 的接口和类

SqlNode 接口，简单理解就是 xml 中的每个标签，比如上述 sql 的 update,trim,if 标签：

 

public interface SqlNode {
 boolean apply(DynamicContext context);
}

 

SqlSource Sql 源接口，代表从 xml 文件或注解映射的 sql 内容，主要就是用于创建 BoundSql，有实现类 DynamicSqlSource (动态 Sql 源)，StaticSqlSource (静态 Sql 源) 等：

 

public interface SqlSource {
 BoundSql getBoundSql(Object parameterObject);
}

 

BoundSql 类，封装 mybatis 最终产生 sql 的类，包括 sql 语句，参数，参数源数据等参数：

XNode，一个 Dom API 中的 Node 接口的扩展类：

BaseBuilder 接口及其实现类 (属性，方法省略了，大家有兴趣的自己看), 这些 Builder 的作用就是用于构造 sql：

下面我们简单分析下其中 4 个 Builder：

XMLConfigBuilder：解析 mybatis 中 configLocation 属性中的全局 xml 文件，内部会使用 XMLMapperBuilder 解析各个 xml 文件。

XMLMapperBuilder：遍历 mybatis 中 mapperLocations 属性中的 xml 文件中每个节点的 Builder，比如 user.xml，内部会使用 XMLStatementBuilder 处理 xml 中的每个节点。

XMLStatementBuilder：解析 xml 文件中各个节点，比如 select,insert,update,delete 节点，内部会使用 XMLScriptBuilder 处理节点的 sql 部分，遍历产生的数据会丢到 Configuration 的 mappedStatements 中。

XMLScriptBuilder：解析 xml 中各个节点 sql 部分的 Builder。

LanguageDriver 接口及其实现类 (属性，方法省略了，大家有兴趣的自己看)，该接口主要的作用就是构造 sql:

简单分析下 XMLLanguageDriver (处理 xml 中的 sql，RawLanguageDriver 处理静态 sql)：XMLLanguageDriver 内部会使用 XMLScriptBuilder 解析 xml 中的 sql 部分。

源码分析走起

Spring 与 Mybatis 整合的时候需要配置 SqlSessionFactoryBean，该配置会加入数据源和 mybatis xml 配置文件路径等信息：

 

 

我们就分析这一段配置背后的细节：

SqlSessionFactoryBean 实现了 Spring 的 InitializingBean 接口，InitializingBean 接口的 afterPropertiesSet 方法中会调用 buildSqlSessionFactory 方法 该方法内部会使用 XMLConfigBuilder 解析属性 configLocation 中配置的路径，还会使用 XMLMapperBuilder 属性解析 mapperLocations 属性中的各个 xml 文件。部分源码如下：

由于 XMLConfigBuilder 内部也是使用 XMLMapperBuilder，我们就看看 XMLMapperBuilder 的解析细节：

我们关注一下，增删改查节点的解析：

XMLStatementBuilder 的解析：

默认会使用 XMLLanguageDriver 创建 SqlSource（Configuration 构造函数中设置）。

XMLLanguageDriver 创建 SqlSource：

XMLScriptBuilder 解析 sql：

得到 SqlSource 之后，会放到 Configuration 中，有了 SqlSource，就能拿 BoundSql 了，BoundSql 可以得到最终的 sql。

实例分析

以下面的 xml 解析大概说下 parseDynamicTags 的解析过程：

 

    UPDATE users
 
 
            name = #{name}
 
 
            , age = #{age}
 
 
            , birthday = #{birthday}
 
 
    where id = ${id}

 

parseDynamicTags 方法的返回值是一个 List，也就是一个 Sql 节点集合。SqlNode 本文一开始已经介绍，分析完解析过程之后会说一下各个 SqlNode 类型的作用。

首先根据 update 节点 (Node) 得到所有的子节点，分别是 3 个子节点：

文本节点 UPDATE users

trim 子节点 ...

文本节点 where id = #

遍历各个子节点：

如果节点类型是文本或者 CDATA，构造一个 TextSqlNode 或 StaticTextSqlNode；

如果节点类型是元素，说明该 update 节点是个动态 sql，然后会使用 NodeHandler 处理各个类型的子节点。这里的 NodeHandler 是 XMLScriptBuilder 的一个内部接口，其实现类包括 TrimHandler、WhereHandler、SetHandler、IfHandler、ChooseHandler 等。看类名也就明白了这个 Handler 的作用，比如我们分析的 trim 节点，对应的是 TrimHandler；if 节点，对应的是 IfHandler... 这里子节点 trim 被 TrimHandler 处理，TrimHandler 内部也使用 parseDynamicTags 方法解析节点。

遇到子节点是元素的话，重复以上步骤：

trim 子节点内部有 7 个子节点，分别是文本节点、if 节点、是文本节点、if 节点、是文本节点、if 节点、文本节点。文本节点跟之前一样处理，if 节点使用 IfHandler 处理。遍历步骤如上所示，下面我们看下几个 Handler 的实现细节。

IfHandler 处理方法也是使用 parseDynamicTags 方法，然后加上 if 标签必要的属性：

 

private class IfHandler implements NodeHandler {
 public void handleNode(XNode nodeToHandle, List targetContents) {
 List contents = parseDynamicTags(nodeToHandle);
 MixedSqlNode mixedSqlNode = new MixedSqlNode(contents);
 String test = nodeToHandle.getStringAttribute("test");
 IfSqlNode ifSqlNode = new IfSqlNode(mixedSqlNode, test);
 targetContents.add(ifSqlNode);
 }
}

 

TrimHandler 处理方法也是使用 parseDynamicTags 方法，然后加上 trim 标签必要的属性：

 

private class TrimHandler implements NodeHandler {
 public void handleNode(XNode nodeToHandle, List targetContents) {
 List contents = parseDynamicTags(nodeToHandle);
 MixedSqlNode mixedSqlNode = new MixedSqlNode(contents);
 String prefix = nodeToHandle.getStringAttribute("prefix");
 String prefixOverrides = nodeToHandle.getStringAttribute("prefixOverrides");
 String suffix = nodeToHandle.getStringAttribute("suffix");
 String suffixOverrides = nodeToHandle.getStringAttribute("suffixOverrides");
 TrimSqlNode trim = new TrimSqlNode(configuration, mixedSqlNode, prefix, prefixOverrides, suffix, suffixOverrides);
 targetContents.add(trim);
 }
}

 

以上 update 方法最终通过 parseDynamicTags 方法得到的 SqlNode 集合如下：

trim 节点：

由于这个 update 方法是个动态节点，因此构造出了 DynamicSqlSource。DynamicSqlSource 内部就可以构造 sql 了:

DynamicSqlSource 内部的 SqlNode 属性是一个 MixedSqlNode。然后我们看看各个 SqlNode 实现类的 apply 方法。下面分析一下各个 SqlNode 实现类的 apply 方法实现：

MixedSqlNode：MixedSqlNode 会遍历调用内部各个 sqlNode 的 apply 方法。

 

public boolean apply(DynamicContext context) {
 for (SqlNode sqlNode : contents) {
 sqlNode.apply(context);
 }
 return true;
}

 

StaticTextSqlNode：直接 append sql 文本。

 

public boolean apply(DynamicContext context) {
 context.appendSql(text);
 return true;
}

 

IfSqlNode：这里的 evaluator 是一个 ExpressionEvaluator 类型的实例，内部使用了 OGNL 处理表达式逻辑。

 

public boolean apply(DynamicContext context) {
 if (evaluator.evaluateBoolean(test, context.getBindings())) {
 contents.apply(context);
 return true;
 }
 return false;
}

 

TrimSqlNode：

 

public boolean apply(DynamicContext context) {
 FilteredDynamicContext filteredDynamicContext = new FilteredDynamicContext(context);
 boolean result = contents.apply(filteredDynamicContext);
 filteredDynamicContext.applyAll();
 return result;
}
public void applyAll() {
 sqlBuffer = new StringBuilder(sqlBuffer.toString().trim());
 String trimmedUppercaseSql = sqlBuffer.toString().toUpperCase(Locale.ENGLISH);
 if (trimmedUppercaseSql.length() > 0) {
 applyPrefix(sqlBuffer, trimmedUppercaseSql);
 applySuffix(sqlBuffer, trimmedUppercaseSql);
 }
 delegate.appendSql(sqlBuffer.toString());
}
private void applyPrefix(StringBuilder sql, String trimmedUppercaseSql) {
 if (!prefixApplied) {
 prefixApplied = true;
 if (prefixesToOverride != null) {
 for (String toRemove : prefixesToOverride) {
 if (trimmedUppercaseSql.startsWith(toRemove)) {
 sql.delete(0, toRemove.trim().length());
 break;
 }
 }
 }
 if (prefix != null) {
 sql.insert(0, " ");
 sql.insert(0, prefix);
 }
 }
}

 

TrimSqlNode 的 apply 方法也是调用属性 contents (一般都是 MixedSqlNode) 的 apply 方法，按照实例也就是 7 个 SqlNode，都是 StaticTextSqlNode 和 IfSqlNode。最后会使用 FilteredDynamicContext 过滤掉 prefix 和 suffix。

 

　　审核编辑：汤梓红