mybatis-入门

安装

要使用 MyBatis， 只需将 mybatis-x.x.x.jar 文件置于 classpath 中便可。

若是使用 Maven 来构建项目，则需将下面的 dependency 代码置于 pom.xml 文件中：

<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis</artifactId>
  <version>x.x.x</version>
</dependency>

从 XML 中构建 SqlSessionFactory

每一个基于 MyBatis 的应用都是以一个 SqlSessionFactory 的实例为中心的。SqlSessionFactory 的实例能够经过 SqlSessionFactoryBuilder 得到。而 SqlSessionFactoryBuilder 则能够从 XML 配置文件或一个预先定制的 Configuration 的实例构建出 SqlSessionFactory 的实例。

从 XML 文件中构建 SqlSessionFactory 的实例很是简单，建议使用类路径下的资源文件进行配置。可是也可使用任意的输入流(InputStream)实例，包括字符串形式的文件路径或者 file:// 的 URL 形式的文件路径来配置。MyBatis 包含一个名叫 Resources 的工具类，它包含一些实用方法，可以使从 classpath 或其余位置加载资源文件更加容易。

String resource = "org/mybatis/example/mybatis-config.xml";
InputStream inputStream = Resources.getResourceAsStream(resource);
sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

XML 配置文件（configuration XML）中包含了对 MyBatis 系统的核心设置，包含获取数据库链接实例的数据源（DataSource）和决定事务范围和控制方式的事务管理器（TransactionManager）。XML 配置文件的详细内容后面再探讨，这里先给出一个简单的示例：

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
  PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
  "http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
  <environments default="development">
    <environment id="development">
      <transactionManager type="JDBC"/>
      <dataSource type="POOLED">
        <property name="driver" value="${driver}"/>
        <property name="url" value="${url}"/>
        <property name="username" value="${username}"/>
        <property name="password" value="${password}"/>
      </dataSource>
    </environment>
  </environments>
  <mappers>
    <mapper resource="org/mybatis/example/BlogMapper.xml"/>
  </mappers>
</configuration>

固然，还有不少能够在XML 文件中进行配置，上面的示例指出的则是最关键的部分。要注意 XML 头部的声明，用来验证 XML 文档正确性。environment 元素体中包含了事务管理和链接池的配置。mappers 元素则是包含一组 mapper 映射器（这些 mapper 的 XML 文件包含了 SQL 代码和映射定义信息）。

不使用 XML 构建 SqlSessionFactory

若是你更愿意直接从 Java 程序而不是 XML 文件中建立 configuration，或者建立你本身的 configuration 构建器，MyBatis 也提供了完整的配置类，提供全部和 XML 文件相同功能的配置项。

DataSource dataSource = BlogDataSourceFactory.getBlogDataSource();
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);

注意该例中，configuration 添加了一个映射器类（mapper class）。映射器类是 Java 类，它们包含 SQL 映射语句的注解从而避免了 XML 文件的依赖。不过，因为 Java 注解的一些限制加之某些 MyBatis 映射的复杂性，XML 映射对于大多数高级映射（好比：嵌套 Join 映射）来讲仍然是必须的。有鉴于此，若是存在一个对等的 XML 配置文件的话，MyBatis 会自动查找并加载它（这种状况下， BlogMapper.xml 将会基于类路径和 BlogMapper.class 的类名被加载进来）。具体细节稍后讨论。

从 SqlSessionFactory 中获取 SqlSession

既然有了 SqlSessionFactory ，顾名思义，咱们就能够从中得到 SqlSession 的实例了。SqlSession 彻底包含了面向数据库执行 SQL 命令所需的全部方法。你能够经过 SqlSession 实例来直接执行已映射的 SQL 语句。例如：

SqlSession session = sqlSessionFactory.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 到底执行了什么操做，而 SQL 语句映射是个至关大的话题，可能会占去文档的大部分篇幅。不过为了让你可以了解个大概，这里会给出几个例子。

在上面提到的两个例子中，一个语句应该是经过 XML 定义，而另一个则是经过注解定义。先看 XML 定义这个，事实上 MyBatis 提供的所有特性能够利用基于 XML 的映射语言来实现，这使得 MyBatis 在过去的数年间得以流行。若是你之前用过 MyBatis，这个概念应该会比较熟悉。不过 XML 映射文件已经有了不少的改进，随着文档的进行会愈发清晰。这里给出一个基于 XML 映射语句的示例，它应该能够知足上述示例中 SqlSession 的调用。

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
  PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
  "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="org.mybatis.example.BlogMapper">
  <select id="selectBlog" resultType="Blog">
    select * from Blog where id = #{id}
  </select>
</mapper>

对于简单语句来讲，注解使代码显得更加简洁，然而 Java 注解对于稍微复杂的语句就会力不从心而且会显得更加混乱。所以，若是你须要作很复杂的事情，那么最好使用 XML 来映射语句。

选择何种方式以及映射语句的定义的一致性对你来讲有多重要这些彻底取决于你和你的团队。换句话说，永远不要拘泥于一种方式，你能够很轻松的在基于注解和 XML 的语句映射方式间自由移植和切换。

范围（Scope）和生命周期

理解咱们目前已经讨论过的不一样范围和生命周期类是相当重要的，由于错误的使用会致使很是严重的并发问题。

提示 对象生命周期和依赖注入框架

依赖注入框架能够建立线程安全的、基于事务的 SqlSession 和映射器（mapper）并将它们直接注入到你的 bean 中，所以能够直接忽略它们的生命周期。若是对如何经过依赖注入框架来使用 MyBatis 感兴趣能够研究一下 MyBatis-Spring 或 MyBatis-Guice 两个子项目。

SqlSessionFactoryBuilder

这个类能够被实例化、使用和丢弃，一旦建立了 SqlSessionFactory，就再也不须要它了。所以 SqlSessionFactoryBuilder 实例的最佳范围是方法范围（也就是局部方法变量）。你能够重用 SqlSessionFactoryBuilder 来建立多个 SqlSessionFactory 实例，可是最好仍是不要让其一直存在以保证全部的 XML 解析资源开放给更重要的事情。

SqlSessionFactory

SqlSessionFactory 一旦被建立就应该在应用的运行期间一直存在，没有任何理由对它进行清除或重建。使用 SqlSessionFactory 的最佳实践是在应用运行期间不要重复建立屡次，屡次重建 SqlSessionFactory 被视为一种代码“坏味道（bad smell）”。所以 SqlSessionFactory 的最佳范围是应用范围。有不少方法能够作到，最简单的就是使用单例模式或者静态单例模式。

SqlSession

每一个线程都应该有它本身的 SqlSession 实例。SqlSession 的实例不是线程安全的，所以是不能被共享的，因此它的最佳的范围是请求或方法范围。绝对不能将 SqlSession 实例的引用放在一个类的静态域，甚至一个类的实例变量也不行。也毫不能将 SqlSession 实例的引用放在任何类型的管理范围中，好比 Serlvet 架构中的 HttpSession。若是你如今正在使用一种 Web 框架，要考虑 SqlSession 放在一个和 HTTP 请求对象类似的范围中。换句话说，每次收到的 HTTP 请求，就能够打开一个 SqlSession，返回一个响应，就关闭它。这个关闭操做是很重要的，你应该把这个关闭操做放到 finally 块中以确保每次都能执行关闭。下面的示例就是一个确保 SqlSession 关闭的标准模式：

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

在你的全部的代码中一致性地使用这种模式来保证全部数据库资源都能被正确地关闭。

映射器实例（Mapper Instances）

映射器是建立用来绑定映射语句的接口。映射器接口的实例是从 SqlSession 中得到的。所以从技术层面讲，映射器实例的最大范围是和 SqlSession 相同的，由于它们都是从 SqlSession 里被请求的。尽管如此，映射器实例的最佳范围是方法范围。也就是说，映射器实例应该在调用它们的方法中被请求，用过以后便可废弃。并不须要显式地关闭映射器实例，尽管在整个请求范围（request scope）保持映射器实例也不会有什么问题，可是很快你会发现，像 SqlSession 同样，在这个范围上管理太多的资源的话会难于控制。因此要保持简单，最好把映射器放在方法范围（method scope）内。下面的示例就展现了这个实践：

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