MyBatis中XML 映射文件中常见的标签说明

SQL 映射文件只有很少的几个顶级元素（按照应被定义的顺序列出）：

• cache ?C 对给定命名空间的缓存配置。
• cache-ref ?C 对其他命名空间缓存配置的引用。
• resultMap ?C 是最复杂也是最强大的元素，用来描述如何从数据库结果集中来加载对象。
• parameterMap ?C 已被废弃！老式风格的参数映射。更好的办法是使用内联参数，此元素可能在将来被移除。
• sql ?C 可被其他语句引用的可重用语句块。
• insert ?C 映射插入语句
• update ?C 映射更新语句
• delete ?C 映射删除语句
• select ?C 映射查询语句

select

<select id="selectPerson" parameterType="int" resultType="hashmap">
   SELECT * FROM PERSON WHERE ID = #{id}
 </select>

这个语句被称作 selectPerson，接受一个 int（或 Integer）类型的参数，并返回一个 HashMap 类型的对象，其中的键是列名，值便是结果行中的对应值。

注意参数符号：#{id}

这就告诉 MyBatis 创建一个预处理语句（PreparedStatement）参数，在 JDBC 中，这样的一个参数在 SQL 中会由一个“?”来标识，并被传递到一个新的预处理语句中，就像这样：

// 近似的 JDBC 代码，非 MyBatis 代码...
 String selectPerson = "SELECT * FROM PERSON WHERE ID=?";
 PreparedStatement ps = conn.prepareStatement(selectPerson);
 ps.setInt(1,id);
 <select
   id="selectPerson"
   parameterType="int"
   parameterMap="deprecated"
   resultType="hashmap"
   resultMap="personResultMap"
   flushCache="false"
   useCache="true"
   timeout="10"
   fetchSize="256"
   statementType="PREPARED"
   resultSetType="FORWARD_ONLY">

insert, update 和 delete

数据变更语句 insert，update 和 delete 的实现非常接近：

<insert
   id="insertAuthor"
   parameterType="domain.blog.Author"
   flushCache="true"
   statementType="PREPARED"
   keyProperty=""
   keyColumn=""
   useGeneratedKeys=""
   timeout="20">
 ​
 <update
   id="updateAuthor"
   parameterType="domain.blog.Author"
   flushCache="true"
   statementType="PREPARED"
   timeout="20">
 ​
 <delete
   id="deleteAuthor"
   parameterType="domain.blog.Author"
   flushCache="true"
   statementType="PREPARED"
   timeout="20">

生成主键

 <selectKey
   keyProperty="id"
   resultType="int"
   order="BEFORE"
   statementType="PREPARED">

 <selectKey resultType="java.lang.Long" order="AFTER" keyProperty="id">
   SELECT LAST_INSERT_ID() AS id
 </selectKey>

sql

这个元素可以被用来定义可重用的 SQL 代码段，这些 SQL 代码可以被包含在其他语句中。它可以（在加载的时候）被静态地设置参数。 在不同的包含语句中可以设置不同的值到参数占位符上。比如：

<sql id="userColumns"> ${alias}.id,${alias}.username,${alias}.password </sql>
 <select id="selectUsers" resultType="map">
   select
     <include refid="userColumns"><property name="alias" value="t1"/></include>,
     <include refid="userColumns"><property name="alias" value="t2"/></include>
   from some_table t1
     cross join some_table t2
 </select>

结果映射

resultMap 元素是 MyBatis 中最重要最强大的元素，在一些情形下允许你进行一些 JDBC 不支持的操作。实际上，在为一些比如连接的复杂语句编写映射代码的时候，一份 resultMap 能够代替实现同等功能的长达数千行的代码。ResultMap 的设计思想是，对于简单的语句根本不需要配置显式的结果映射，而对于复杂一点的语句只需要描述它们的关系就行了。

在JavaBean中定义一个有 3 个属性：id，username 和 hashedPassword的类，然后在mapper.xml中，这些属性会对应到 select 语句中的列名，这样的一个 JavaBean 可以被映射到 ResultSet，就像映射到 HashMap 一样简单。

<select id="selectUsers" resultType="com.someapp.model.User">
   select id, username, hashedPassword
   from some_table
   where id = #{id}
 </select>

像第三中的第三个例子，也可以定义外部resultMap，这也是解决列名不匹配的另外一种方式。

 <resultMap id="userResultMap" type="User">
   <id property="id" column="user_id" />
   <result property="username" column="user_name"/>
   <result property="password" column="hashed_password"/>
 </resultMap>
 ​
 <select id="selectUsers" resultMap="userResultMap">
   select user_id, user_name, hashed_password
   from some_table
   where id = #{id}
 </select>

结果映射（resultMap）

• constructor-用于在实例化类时，注入结果到构造方法中
• idArg - ID 参数；标记出作为 ID 的结果可以帮助提高整体性能
• arg - 将被注入到构造方法的一个普通结果
• id ?C 一个 ID 结果；标记出作为 ID 的结果可以帮助提高整体性能
• result ?C 注入到字段或 JavaBean 属性的普通结果
• association?C 一个复杂类型的关联；许多结果将包装成这种类型
• 嵌套结果映射 ?C 关联本身可以是一个 resultMap 元素，或者从别处引用一个
• collection?C 一个复杂类型的集合
• 嵌套结果映射 ?C 集合本身可以是一个 resultMap 元素，或者从别处引用一个
• discriminator?C 使用结果值来决定使用哪个resultMap
• case?C 基于某些值的结果映射
• 嵌套结果映射 ?C case 本身可以是一个 resultMap 元素，因此可以具有相同的结构和元素，或者从别处引用一个。

id & result

 <id property="id" column="post_id"/>
 <result property="subject" column="post_subject"/>

这些是结果映射最基本的内容。id 和 result 元素都将一个列的值映射到一个简单数据类型（String, int, double, Date 等）的属性或字段。

这两者之间的唯一不同是，id 元素表示的结果将是对象的标识属性，这会在比较对象实例时用到。 这样可以提高整体的性能，尤其是进行缓存和嵌套结果映射（也就是连接映射）的时候。

缓存

默认情况下，只启用了本地的会话缓存，它仅仅对一个会话中的数据进行缓存。 要启用全局的二级缓存，只需要在你的 SQL 映射文件中添加一行：<cache/>

基本上就是这样。这个简单语句的效果如下:

• 映射语句文件中的所有 select 语句的结果将会被缓存。
• 映射语句文件中的所有 insert、update 和 delete 语句会刷新缓存。
• 缓存会使用最近最少使用算法（LRU, Least Recently Used）算法来清除不需要的缓存。
• 缓存不会定时进行刷新（也就是说，没有刷新间隔）。
• 缓存会保存列表或对象（无论查询方法返回哪种）的 1024 个引用。
• 缓存会被视为读/写缓存，这意味着获取到的对象并不是共享的，可以安全地被调用者修改，而不干扰其他调用者或线程所做的潜在修改。

提示 缓存只作用于 cache 标签所在的映射文件中的语句。如果你混合使用 Java API 和 XML 映射文件，在共用接口中的语句将不会被默认缓存。你需要使用 @CacheNamespaceRef 注解指定缓存作用域。

这些属性可以通过 cache 元素的属性来修改。比如：

 <cache
   eviction="FIFO"
   flushInterval="60000"
   size="512"
   readOnly="true"/>

这个更高级的配置创建了一个 FIFO 缓存，每隔 60 秒刷新，最多可以存储结果对象或列表的 512 个引用，而且返回的对象被认为是只读的，因此对它们进行修改可能会在不同线程中的调用者产生冲突。

可用的清除策略有：

• LRU ?C 最近最少使用：移除最长时间不被使用的对象。
• FIFO ?C 先进先出：按对象进入缓存的顺序来移除它们。
• SOFT ?C 软引用：基于垃圾回收器状态和软引用规则移除对象。
• WEAK ?C 弱引用：更积极地基于垃圾收集器状态和弱引用规则移除对象。

默认的清除策略是 LRU。

flushInterval（刷新间隔）属性可以被设置为任意的正整数，设置的值应该是一个以毫秒为单位的合理时间量。 默认情况是不设置，也就是没有刷新间隔，缓存仅仅会在调用语句时刷新。

size（引用数目）属性可以被设置为任意正整数，要注意欲缓存对象的大小和运行环境中可用的内存资源。默认值是 1024。

readOnly（只读）属性可以被设置为 true 或 false。只读的缓存会给所有调用者返回缓存对象的相同实例。 因此这些对象不能被修改。这就提供了可观的性能提升。而可读写的缓存会（通过序列化）返回缓存对象的拷贝。 速度上会慢一些，但是更安全，因此默认值是 false。

提示 二级缓存是事务性的。这意味着，当 SqlSession 完成并提交时，或是完成并回滚，但没有执行 flushCache=true 的 insert/delete/update 语句时，缓存会获得更新。

使用自定义缓存

除了上述自定义缓存的方式，你也可以通过实现你自己的缓存，或为其他第三方缓存方案创建适配器，来完全覆盖缓存行为。

 <cache type="com.domain.something.MyCustomCache"/>

例子：

type 属性指定的类必须实现 org.mybatis.cache.Cache 接口，且提供一个接受 String 参数作为 id 的构造器。 这个接口是 MyBatis 框架中许多复杂的接口之一，但是行为却非常简单。

 public interface Cache {
   String getId();
   int getSize();
   void putObject(Object key, Object value);
   Object getObject(Object key);
   boolean hasKey(Object key);
   Object removeObject(Object key);
   void clear();
 }

动态SQL

• Mybatis 动态 SQL ，可以让我们在 XML 映射文件内，以 XML 标签的形式编写动态 SQL ，完成逻辑判断和动态拼接 SQL 的功能。
• Mybatis 提供了 9 种动态 SQL 标签：<if />、<choose />、<when />、<otherwise />、<trim />、<where />、<set />、<foreach />、<bind /> 。
• 其执行原理为，使用 OGNL 的表达式，从 SQL 参数对象中计算表达式的值，根据表达式的值动态拼接 SQL ，以此来完成动态 SQL 的功能。

if

动态 SQL 通常要做的事情是根据条件包含 where 子句的一部分。比如：

 <select id="findActiveBlogWithTitleLike"
      resultType="Blog">
   SELECT * FROM BLOG
   WHERE state = ‘ACTIVE'
   <if test="title != null">
     AND title like #{title}
   </if>
 </select>

这条语句提供了一种可选的查找文本功能。如果没有传入“title”，那么所有处于“ACTIVE”状态的BLOG都会返回；反之若传入了“title”，那么就会对“title”一列进行模糊查找并返回 BLOG 结果（“title”参数值是可以包含一些掩码或通配符的）。

通过“title”和“author”两个参数进行可选搜索:

 <select id="findActiveBlogLike"
      resultType="Blog">
   SELECT * FROM BLOG WHERE state = ‘ACTIVE'
   <if test="title != null">
     AND title like #{title}
   </if>
   <if test="author != null and author.name != null">
     AND author_name like #{author.name}
   </if>
 </select>

choose, when, otherwise

有时我们不想应用到所有的条件语句，而只想从中择其一项。针对这种情况，MyBatis 提供了 choose 元素，它有点像 Java 中的 switch 语句。

这次变为提供了“title”就按“title”查找，提供了“author”就按“author”查找的情形，若两者都没有提供，就返回所有符合条件的 BLOG（实际情况可能是由管理员按一定策略选出 BLOG 列表，而不是返回大量无意义的随机结果）。

 <select id="findActiveBlogLike"
      resultType="Blog">
   SELECT * FROM BLOG WHERE state = ‘ACTIVE'
   <choose>
     <when test="title != null">
       AND title like #{title}
     </when>
     <when test="author != null and author.name != null">
       AND author_name like #{author.name}
     </when>
     <otherwise>
       AND featured = 1
     </otherwise>
   </choose>
 </select>

trim, where, set

上面的几个例子，如果条件不满足的话，会拼凑成不成一条sql语句，导致无法查询，如：SELECT * FROM BLOG WHERE

 <select id="findActiveBlogLike"
      resultType="Blog">
   SELECT * FROM BLOG
   <where>
     <if test="state != null">
          state = #{state}
     </if>
     <if test="title != null">
         AND title like #{title}
     </if>
     <if test="author != null and author.name != null">
         AND author_name like #{author.name}
     </if>
   </where>
 </select>

where 元素只会在至少有一个子元素的条件返回 SQL 子句的情况下才去插入“WHERE”子句。而且，若语句的开头为“AND”或“OR”，where 元素也会将它们去除。

如果 where 元素没有按正常套路出牌，我们可以通过自定义 trim 元素来定制 where 元素的功能。比如，和 where 元素等价的自定义 trim 元素为：

 <trim prefix="WHERE" prefixOverrides="AND |OR ">
   ...
 </trim>

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

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

 <update id="updateAuthorIfNecessary">
   update Author
     <set>
       <if test="username != null">username=#{username},</if>
       <if test="password != null">password=#{password},</if>
       <if test="email != null">email=#{email},</if>
       <if test="bio != null">bio=#{bio}</if>
     </set>
   where id=#{id}
 </update>

这里，set 元素会动态前置 SET 关键字，同时也会删掉无关的逗号，因为用了条件语句之后很可能就会在生成的 SQL 语句的后面留下这些逗号。（译者注：因为用的是“if”元素，若最后一个“if”没有匹配上而前面的匹配上，SQL 语句的最后就会有一个逗号遗留）

若你对 set 元素等价的自定义 trim 元素的代码感兴趣，那这就是它的真面目：

 <trim prefix="SET" suffixOverrides=",">
   ...
 </trim>

注意这里我们删去的是后缀值，同时添加了前缀值。

foreach

动态 SQL 的另外一个常用的操作需求是对一个集合进行遍历，通常是在构建 IN 条件语句的时候。比如：

 <select id="selectPostIn" resultType="domain.blog.Post">
   SELECT *
   FROM POST P
   WHERE ID in
   <foreach item="item" index="index" collection="list"
       open="(" separator="," close=")">
         #{item}
   </foreach>
 </select>

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

注意

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

bind

bind 元素可以从 OGNL 表达式中创建一个变量并将其绑定到上下文。比如：

 <select id="selectBlogsLike" resultType="Blog">
   <bind name="pattern" value="'%' + _parameter.getTitle() + '%'" />
   SELECT * FROM BLOG
   WHERE title LIKE #{pattern}
 </select>