Mybatis Guide

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

下面按照步骤创建一个基于Maven购建的Mybatis实例。

(1) 创建Maven工程及pom.xml

 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.mytest</groupId>
     <artifactId>mybatistest</artifactId>
     <version>0.0.1-SNAPSHOT</version>
     <packaging>pom</packaging>

     <dependencies>
         <!-- Mybatis Core -->
         <dependency>
             <groupId>org.mybatis</groupId>
             <artifactId>mybatis</artifactId>
             <version>3.4.5</version>
         </dependency>
         <!-- Sybase JDBC driver(请根据需要换成相应DB的JDBC driver) -->
         <dependency>
             <groupId>com.sybase</groupId>
             <artifactId>jconn4</artifactId>
             <version>7.07</version>
         </dependency>
     </dependencies>

     <build>
         <pluginManagement>
             <plugins>
                 <plugin>
                     <groupId>org.apache.maven.plugins</groupId>
                     <artifactId>maven-compiler-plugin</artifactId>
                     <configuration>
                         <source>${java-version}</source>
                         <target>${java-version}</target>
                     </configuration>
                 </plugin>
             </plugins>
         </pluginManagement>
     </build>
     <properties>
         <java-version>1.8</java-version>
     </properties>
 </project>

(2) 创建Mybatis的Configuration XML文件mybatis-config.xml。其中包含MyBatis的Setting设置，typeAliases，typeHandlers，数据源及映射关系等。

 <?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>
     <!--MyBatis的Setting设置，它们会改变 MyBatis的运行时行为。 -->
     <settings>
         <!-- 该配置影响的所有映射器中配置的缓存的全局开关[default:true] -->
         <setting name="cacheEnabled" value="true" />
         <!-- 延迟加载的全局开关。当开启时，所有关联对象都会延迟加载[default:false] -->
         <setting name="lazyLoadingEnabled" value="true" />
         <!-- 是否允许单一语句返回多结果集（需要兼容驱动）[default:true] -->
         <setting name="multipleResultSetsEnabled" value="true" />
         <!-- 使用列标签代替列名[default:true] -->
         <setting name="useColumnLabel" value="true" />
         <!-- 允许JDBC支持自动生成主键，需要驱动兼容[default:false] -->
         <setting name="useGeneratedKeys" value="false" />
         <!-- 指定MyBatis应如何自动映射列到字段或属性。NONE表示取消自动映射； PARTIAL只会自动映射没有定义嵌套结果集映射的结果集。FULL会自动映射任意复杂的结果集（无论是否嵌套）[default:PARTIAL] -->
         <setting name="autoMappingBehavior" value="PARTIAL" />
         <!-- 指定发现自动映射目标未知列（或者未知属性类型）的行为。NONE不做任何反应； WARNING输出提醒日志('org.apache.ibatis.session.AutoMappingUnknownColumnBehavior'的日志等级必须设置为WARN)； -->
         <!-- FAILING映射失败 (抛出 SqlSessionException)[default:NONE] -->
         <setting name="autoMappingUnknownColumnBehavior" value="WARNING" />
         <!-- 配置默认的执行器。SIMPLE就是普通的执行器；REUSE执行器会重用预处理语句（prepared statements）；
             BATCH执行器将重用语句并执行批量更新[default:SIMPLE] -->
         <setting name="defaultExecutorType" value="SIMPLE" />
         <!-- 设置超时时间，它决定驱动等待数据库响应的秒数 -->
         <setting name="defaultStatementTimeout" value="25" />
         <!-- 为驱动的结果集获取数量（fetchSize）设置一个提示值。此参数只可以在查询设置中被覆盖 -->
         <setting name="defaultFetchSize" value="100" />
         <!-- 允许在嵌套语句中使用分页（RowBounds）。如果允许使用则设置为false[default:false] -->
         <setting name="safeRowBoundsEnabled" value="false" />
         <!-- 是否开启自动驼峰命名规则（camel case）映射[default:false] -->
         <setting name="mapUnderscoreToCamelCase" value="false" />
         <!-- MyBatis利用本地缓存机制（Local Cache）防止循环引用（circular references）和加速重复嵌套查询。 -->
         <!-- 默认值为SESSION，这种情况下会缓存一个会话中执行的所有查询。 若设置值为STATEMENT，本地会话仅用在语句执行上，对相同SqlSession的不同调用将不会共享数据 -->
         <setting name="localCacheScope" value="SESSION" />
         <!-- 当没有为参数提供特定的JDBC类型时，为空值指定JDBC类型。 某些驱动需要指定列的JDBC类型，多数情况直接用一般类型即可，比如NULL、VARCHAR或OTHER[default:OTHER] -->
         <setting name="jdbcTypeForNull" value="OTHER" />
         <!-- 指定哪个对象的方法触发一次延迟加载。[default:equals,clone,hashCode,toString] -->
         <setting name="lazyLoadTriggerMethods" value="equals,clone,hashCode,toString" />
     </settings>

     <!-- 类型别名是为Java类型设置一个短的名字。它只和XML配置有关，存在的意义仅在于用来减少类完全限定名的冗余。 -->
     <typeAliases>
         <!-- <package name="com.xx.xxx" /> -->
     </typeAliases>

     <!-- 无论是MyBatis在预处理语句（PreparedStatement）中设置一个参数时，还是从结果集中取出一个值时， 都会用类型处理器将获取的值以合适的方式转换成Java类型。下面方式可以自定义。 -->
     <typeHandlers>
         <!-- <package name="com.xx.xxx.typehandler" /> -->
     </typeHandlers>

     <!--设置数据源 -->
     <environments default="development">
         <environment id="development">
             <transactionManager type="JDBC" />
             <dataSource type="POOLED">
                 <property name="driver" value="com.sybase.jdbc4.jdbc.SybDriver" /> <!-- Sybase JDBC driver name(请根据需要换成相应DB的JDBC driver) -->
                 <property name="url" value="*****" />
                 <property name="username" value="*****" />
                 <property name="password" value="*****" />
             </dataSource>
         </environment>
     </environments>
     <!--设置映射关系 -->
     <mappers>
         <!-- <mapper resource="xxx/xxx.xml" /> -->
     </mappers>
 </configuration>

(3) 创建SqlSessionFactoryBuilder，SqlSessionFactory，SqlSession。(与Hibernate类似)

SqlSessionFactoryBuilder：这个类可以被实例化、使用和丢弃，一旦创建了SqlSessionFactory，就不再需要它了。因此SqlSessionFactoryBuilder实例的最佳作用域是方法作用域（也就是局部方法变量）。你可以重用SqlSessionFactoryBuilder来创建多个 SqlSessionFactory实例，但是最好还是不要让其一直存在以保证所有的XML解析资源开放给更重要的事情。

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

SqlSession：每个线程都应该有它自己的SqlSession实例。SqlSession的实例不是线程安全的，因此是不能被共享的，所以它的最佳的作用域是请求或方法作用域。绝对不能将SqlSession实例的引用放在一个类的静态域，甚至一个类的实例变量也不行。也绝不能将 SqlSession实例的引用放在任何类型的管理作用域中，比如Servlet架构中的HttpSession。如果你现在正在使用一种Web框架，要考虑SqlSession放在一个和 HTTP 请求对象相似的作用域中。换句话说，每次收到的HTTP请求，就可以打开一个SqlSession，返回一个响应，就关闭它。这个关闭操作是很重要的，你应该把这个关闭操作放到finally块中以确保每次都能执行关闭。

下面是一个SqlSessionFactoryBuilder创建单例的SqlSessionFactory的例子：

 import org.apache.ibatis.io.Resources;
 import org.apache.ibatis.session.SqlSessionFactory;
 import org.apache.ibatis.session.SqlSessionFactoryBuilder;

 import java.io.IOException;
 import java.io.InputStream;

 public class MybatisTestSessionFactory {

     private static SqlSessionFactory instance;

     private MybatisTestSessionFactory() {
     }

     public static synchronized SqlSessionFactory getSqlSessionFactoryInstance() {
         return instance == null ? getSessionFactory() : instance;
     }

     private static SqlSessionFactory getSessionFactory() {
         String resource = "mybatis-config.xml";
         InputStream inputStream = null;
         try {
             inputStream = Resources.getResourceAsStream(resource);
         } catch (IOException e) {
             e.printStackTrace();
         }
         SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
         return sqlSessionFactory;
     }
 }

下面是创建SqlSession实例的例子：

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