mybatis学习整理（用户手册）（完整的全面学习）

MyBatis 是什么?

MyBatis 是一款一流的支持自定义SQL、存储过程和高级映射的持久化框架。MyBatis 几乎消除了所有的JDBC 代码，也基本不需要手工去设置参数和获取检索结果。MyBatis 能够使用简单的XML 格式或者注解进行来配置，能够映射基本数据元素、Map 接口和POJOs（普通java 对象）到数据库中的记录。

准备开始

所有的MyBatis 应用都以SqlSessionFactory 实例为中心。SqlSessionFactory 实例通过SqlSessionFactoryBuilder 来获得，SqlSessionFactoryBuilder 能够从XML 配置文件或者通过自定义编写的配置类（Configuration class），来创建一个SqlSessionFactory 实例。

从XML 中创建SqlSessionFactory 实例

从XML 中创建SqlSessionFactory 实例非常简单。建议您使用类资源路径（classpathresource）来加载配置文件，但是您也能够使用任何方式，包括文本文件路径或者以file:// 开头URL 的方式。MyBatis 包括一个叫做Resources 的工具类（utility class），其中包含了一系列方法，使之能简单地从classpath 或其它地方加载配置文件。
String resource = "org/mybatis/example/Configuration.xml";
Reader reader = Resources.getResourceAsReader(resource);
sqlMapper = new SqlSessionFactoryBuilder().build(reader);
XML 配置文件包含MyBatis 框架的核心设置，包括获取数据库连接的DataSource 实例，和包括决定事务作用域范围和控制的事务管理等。您将能够在后面的章节中找到详细的XML 配置，在这里我们先展示一个简单的例子：

虽然XML 配置文件中还有很多其它的配置细节，但是，上面的示例显示了最重要的部分。注意XML 配置文件的头部，会使用DTD 验证文档来验证该XML 配置文件。body 部分的environment元素，包含了事务管理和连接池配置。Mappers 元素指定了映射配置文件--包含SQL 语句和映射定义的XML 文件。

如何不使用XML 来创建SqlSessionFactory

如果您喜欢直接通过java 代码而不是通过XML 创建配置选项，或者想创建您自己的配置生成器。MyBatis 提供了一个完整的配置类（Configuration class），它提供了与XML 文件相同的配置选项。

TransactionFactory transactionFactory = new JdbcTransactionFactory();
Environment environment =new Environment("development", transactionFactory, dataSource);
Configuration configuration = new Configuration(environment);
configuration.addMapper(BlogMapper.class);
SqlSessionFactory sqlSessionFactory =new SqlSessionFactoryBuilder().build(configuration);

请注意，这种方式下的配置添加一个映射类（mapper class）。映射类是包含SQL 映射注解的Java 类，从而避免了使用XML。但是，由于注解的一些局限性以及MyBatis 映射的复杂性，XML 仍然是一些高级的映射功能（如嵌套连接映射，Nested Join Mapping）所必须的方式。基于这个原因，如果存在XML 文件，MyBatis 自动寻找并加载这个XML 文件。在这种情况下，BlogMapper.xml 将会被类路径下名称为BlogMapper.class 的类加载。详述请见后面章节。

从SqlSessionFactory 获取SqlSession

现在您已经创建了一个SqlSessionFactory（指上面的sqlMapper），正如它名字暗示那样，您可以通过它来创建一个SqlSession 实例。SqlSession 包含了所有执行数据库SQL 语句的方法。您能够直接地通过SqlSession 实例执行映射SQL 语句。例如：

SqlSession session = sqlMapper.openSession();
try {
Blog blog = (Blog) session.selectOne(
"org.mybatis.example.BlogMapper.selectBlog", 101);
} finally {
session.close();
}

虽然这种方法很有效，MyBatis 以前版本的用户对此也可能很熟悉，但现在有一个更简便的方式，那就是对给定的映射语句，使用一个正确描述参数与返回值的接口（如
BlogMapper.class），您就能更清晰地执行类型安全的代码，从而避免错误和异常。如：

SqlSession session = sqlSessionFactory.openSession();
try {
BlogMapper mapper = session.getMapper(BlogMapper.class);
Blog blog = mapper.selectBlog(101);
} finally {
session.close();
}

现在，让我们一起探索它们究竟是如何执行的。

探索映射SQL 语句

此时，您可能想知道SqlSession 或者映射器类（Mapper class）是怎样执行的。映射SQL语句是一个很大的主题，该主题将可能占据本文档的大部分内容。但是，为了让您看到它是怎样运行的，这里举两个例子。
在上面的例子中，映射语句已经在XML 配置文件或注解中定义。让我们首先来看看XML 配置文件，所有MyBatis 提供的功能特性都可以通过基于XML 映射配置文件配置来实现。如果您以前使用过MyBatis，对此就会很熟悉。但许多改进使XML 映射文件变得更简洁清晰。下面是一个基于XML 映射配置的例子，满足上述SqlSession 的调用。

select * from Blog where id = #{id}

这个简单的例子看起来有不少的开销，但它确实非常地轻巧，只要您喜欢，您可以在一个映射XML 文件中定义许多映射语句。虽然会有一些XML 头部和DOCTYPE 声明，但该文件余下的部分是自解（self explanatory，可理解为不加解释就能明白）的。它定义了映射语句的名称“selectBlog”，在命名空间“org.mybatis.example.BlogMapper”，允许您通过指定完整类名“org.mybatis.example.BlogMapper”来访问上面的例子：

Blog blog = (Blog) session.selectOne(
"org.mybatis.example.BlogMapper.selectBlog", 101);

这非常类似java 中通过完整类名来调用方法，而这样做是有原因的。这个名称可以直接映射到一个具在相同命名空间的映射类，这个映射类有一个方法的名称、参数及返回类型都与select映射语句相匹配。正如您前面看到的，这使您很简单地调用映射类里的方法，下面是另外的一个例子：

BlogMapper mapper = session.getMapper(BlogMapper.class);
Blog blog = mapper.selectBlog(101);

第二种方法有很多好处。第一，它不依赖于字符串，所以更安全。第二，如果您的IDE 有自动完成功能，您可以利用这功能很快导航到您的映射SQL 语句。第三，您不需要关注返回类型，不需要进行强制转换，因为使用BlogMapper 接口已经限定了返回类型，它会安全地返回。

关于命名空间

命名空间:在以前的版本中是可选的、复杂的且没多大用处。但在这个版本中，命名空间是必须的，并且不仅仅是简单地使用完整类名来隔离区分语句。
正如您看到的那样，命名空间能够进行接口绑定，即使您认为现在不会使用到它，但您应该按照这些准则来做。一旦使用了命名空间并且放入适当的java 包命名空间中将会使您的代码清晰，并提高MyBatis 的长期可用性。
名称解析: 为了减少大量地输入， MyBatis 对所有的配置元素，包括statements、resultmaps、caches 等使用下面的名称解析规则:
• 完整类名：(例如: “com.mypackage.MyMapper.selectAllThings”)可用来直接查找并使用。
• 短名称： (例如: “selectAllThings”)可用来引用明确的实体对象。但是，如果出现有两个或更多（例如“com.foo.selectAllThings 和com.bar.selectAllThings”）实体对象，您将收到一个错误报告（短名称含糊不清），因此，这时就必须使用完整类名。

对映射类还有一个更好的方法,就像前面的BlogMapper。它们的映射语句不需要完全在XML中配置。相反，它们可以使用Java 注解。例如上面的XML 配置可以替换为：

package org.mybatis.example;
public interface BlogMapper {
@Select("SELECT * FROM blog WHERE id = #{id}")
Blog selectBlog(int id);
}

对简单的映射语句，使用注解可以显得非常地清晰。但是java 注解本身的局限难于应付更复杂的语句。如果您准备要做某些复杂的事情，最好使用XML 文件来配置映射语句。
这将由您和您的项目小组来确定哪种方式是适合的，以一致的方式来定义映射语句是非常重要的。也就是说，您不会被限于仅用一种方式。您能够非常容易地从基于注解的映射语句移植到XML 配置文件中，反之亦然。

作用域和生命周期

理解到目前为止所讨论的类的作用域和生命周期是非常重要的。如果使用不当可导致严重的并发性问题。

SqlSessionFactoryBuilder

这个类可以在任何时候被实例化、使用和销毁。一旦您创造了SqlSessionFactory 就不需要再保留它了。所以SqlSessionFactoryBuilder 实例的最好的作用域是方法体内（即一个本地方法变量）。您能重用SqlSessionFactoryBuilder 创建多个SqlSessionFactory 实例，但最好不要把时间、资源放在解析XML 文件上，而是要从中解放出来做最重要事情。

SqlSessionFactory

一旦创建，SqlSessionFactory 将会存在于您的应用程序整个运行生命周期中。很少或根本没有理由去销毁它或重新创建它。最佳实践是不要在一个应用中多次创建SqlSessionFactory。这样做会被视为“没品味”。所是SqlSessionFactory 最好的作用域范围是一个应用的生命周期范围。这可以由多种方式来实现，最简单的方式是使用Singleton 模式或静态Singleton 模式。
但这不是被广泛接受的最佳做法，相反，您可能更愿意使用像Google Guice 或Spring 的依赖注入方式。这些框架允许您创造一个管理器，用于管理SqlSessionFactory 的生命周期。

SqlSession

每个线程都有一个SqlSession 实例，SqlSession 实例是不被共享的，并且不是线程安全的。因此最好的作用域是request 或者method。决不要用一个静态字段或者一个类的实例字段来保存SqlSession 实例引用。也不要用任何一个管理作用域，如Servlet 框架中的HttpSession，来保存SqlSession 的引用。如果您正在用一个WEB 框架，可以把SqlSession 的作用域看作类似于HTTP 的请求范围。也就是说，在收到一个HTTP 请求，您可以打开一个SqlSession，当您把response 返回时，就可以把SqlSession 关闭。关闭会话是非常重要的，您应该要确保会话在一个finally 块中被关闭。

SqlSession session = sqlSessionFactory.openSession();
try {
// do work
} finally {
session.close();
}

在您的代码里都使用这一模式将保证所有的数据库资源被正确地关闭（假如您没有把您自己的数据库连接传递给MyBatis 管理，这就对MyBatis 表明您希望自己管理连接）。

Mapper 实例

Mappers 是创建来绑定映射语句的接口，该Mapper 实例是从SqlSession 得到的。因此，所有mapper 实例的作用域跟创建它的SqlSession 一样。但是，mapper 实例最好的作用域是method，也就是它们应该在方法内被调用，使用完即被销毁。并且mapper 实例不用显式地被关闭。虽然把mapper 实例保持在一个request 范围（与SqlSession 相似）不会产生太大的问题，但是您可能会发现，在这个层次上管理太多资源可能会失控。保持简单，就是让Mappers 保持在一个方法内。下面的例子演示了这种做法。

SqlSession session = sqlSessionFactory.openSession();
try {
BlogMapper mapper = session.getMapper(BlogMapper.class);
// do work
} finally {
session.close();
}

Mapper XML 配置

MyBatis 的XML 配置文件包含了设置和影响MyBatis 行为的属性。XML 配置文件的层次结构如下：
• configuration
o properties
o settings
o typeAliases
o typeHandlers
o objectFactory
o plugins
o environments
 environment
• transactionManager
• dataSource
o mappers

properties 元素

它们都是外部化，可替代的属性。可以配置在一个典型的Java 属性文件中，或者通过properties 元素的子元素进行配置。例如：

在整个配置文件中，这些属性能够被可动态替换（即使用占位符）的属性值引用，例如：

示例中的username 和password 将会被替换为配置在properties 元素中的相应值。driver和url 属性则会被config.properties 文件中的相应值替换。这里提供了大量的配置选项。这些属性也可以传递给sqlSessionFactoryBuilder.build()方法。例如：

SqlSessionFactory factory =sqlSessionFactoryBuilder.build(reader, props);
// ... or ...
SqlSessionFactory factory =sqlSessionFactoryBuilder.build(reader, environment, props);

如果一个属性存在于多个地方，MyBatis 将使用下面的顺序加载：

• 首先读入properties 元素主体中指定的属性。
• 然后会加载类路径或者properties 元素中指定的url 的资源文件属性。它会覆盖前面已经读入的重复属性。
• 通过方法参数来传递的属性将最后读取(即通过sqlSessionFactoryBuilder.build)，同样也会覆盖从properties 元素指定的和resource/url 指定的重复属性。
因此最优先的属性是通过方法参数来传递的属性，然后是通过resource/url 配置的属性，最后是在MyBatis 的Mapper 配置文件中，properties 元素主体中指定的属性。

Settings 元素

Setting 元素下是些非常重要的设置选项，用于设置和改变MyBatis 运行中的行为。下面的表格列出了Setting 元素支持的属性、默认值及其功能。

一个Settings 元素完整的配置例子如下：

typeAliases 元素

别名是一个较短的Java 类型的名称。这只是与XML 配置文件相关联，减少输入多余的完整类名。例如：

在这个配置中，您就可以在想要使用"domain.blog.Blog"的地方使用别名“Blog”了。对常用的java 类型，已经内置了一些别名支持。这些别名都是不区分大小写的。注意java
的基本数据类型，它们进行了特别处理，加了“_”前缀。
别名对应的java 类型

_byte byte _long long _short short_int int _integer int_double double _float float_boolean boolean string StringByte Byte Long Longshort Short Int Integerinteger Integer double DoubleFloat Float boolean BooleanDate Date decimal BigDecimal

typeHandlers 元素

每当MyBatis 设置参数到PreparedStatement 或者从ResultSet 结果集中取得值时，就会使用TypeHandler 来处理数据库类型与java 类型之间转换。下表描述了默认的TypeHandlers。

您能够重写类型处理器（type handlers），或者创建您自己的类型处理器去处理没有被支持的或非标准的类型。要做到这一点，只要实现TypeHandler 接口(org.mybatis.type)，并且将您的TypeHandler 类映射到java 类型和可选的JDBC 类型即可。例如：
// ExampleTypeHandler.java

public class ExampleTypeHandler implements TypeHandler {
public void setParameter(
PreparedStatement ps, int i, Object parameter, JdbcType jdbcType)
throws SQLException {
ps.setString(i, (String) parameter);
}
public Object getResult(
ResultSet rs, String columnName)
throws SQLException {
return rs.getString(columnName);
}
public Object getResult(
CallableStatement cs, int columnIndex)
throws SQLException {
return cs.getString(columnIndex);
}
}

// MapperConfig.xml

使用上面的TypeHandler 将会重写已经存在的用来处理java 的String 属性、VARCHAR 参数和结果集的类型处理器。注意，MyBatis 并不会通过数据库的元数据来确认类型，所以您必须指定它的一个类型处理器，用于将VARCHAR 字段的参数和结果映射到正确的类型上。这是因为MyBatis 在语句的执行之前都不知道它要处理的数据类型是什么。

objectFactory 元素

MyBatis 每次创建一个结果对象实例都会使用ObjectFactory 实例。使用默认的ObjectFactory 与使用默认的构造函数（或含参数的构造函数）来实例化目标类没什么差别。如
果您想重写ObjectFactory 来改变其默认行为，那您能通过创造您自己的ObjectFactory 来做到。看下面的例子：
// ExampleObjectFactory.java

public class ExampleObjectFactory extends DefaultObjectFactory {
public Object create(Class type) {
return super.create(type);
}
public Object create(
MyBatis 3 - User Guide
17
Class type,
List constructorArgTypes,
List