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();
}