个人英语学习作用，非专业翻译
引言
什么是MyBatis？
MyBatis第一个支持自定义SQL、存储过程、高级映射的持久层框架，他消除了几乎所有的JDBC代码和参数的手动设置和结果的检索。MyBatis可以使用简单的XML或者注解进行配置和原语映射，将接口和Java的POJO（Plain Old Java Object）对象映射到数据库记录。
入门
Installation安装
使用MyBatis你只需要引入 mybatis-xxx.jar文件到里的classpath中。
如果拟使用的maven，只需要引入以下依赖即可：
<dependency>
<groupId>org.mybatis</groupId>
<artifactId>mybatis</artifactId>
<version>x.x.x</version>
</dependency>
通过XML创建SqlSessionFactory
每个MyBatis程序都是以一个SqlSessionFactory实例为中心的，一个SqlSessionFactory实例可以通过使用SqlSessionFactoryBuilder.来获得。而 SqlSessionFactoryBuilder 则可以从 XML 配置文件或一个预先配置的 Configuration 实例来构建出 其实例。
从XML中创建一个SqlSessionFactory非常简单，建议你使用类路径下资源文件进行配置，但也可以使用任意的输入流（InputStream）实例，比如用文件路径字符串或 file:// URL 构造的输入流，MyBatis 包含一个名叫 Resources 的工具类，它包含一些实用方法，使得从类路径或其它位置加载资源文件更加容易。
String resource = "org/mybatis/example/mybatis-config.xml";
InputStream inputStream = Resources.getResourceAsStream(resource);
SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
XML配置文件包含了MyBatis的核心配置，包括用于获取数据库连接实例的数据源，以及事务管理器，用于确定事务的作用域和控制方式，详细配置下面会详细介绍，简单例子如下：
<?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），这些映射器的 XML 映射文件包含了 SQL 代码和映射定义信息。
不使用 XML 构建 SqlSessionFactory
如果你更喜欢直接从Java代码，而不是XML中创建配置，或者想要创建你自己的配置建造器，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);
注意上面例子创建了一个映射器类，映射器类是 Java 类，它们包含 SQL 映射注解从而避免依赖 XML 文件。不过，由于 Java 注解的一些限制以及某些 MyBatis 映射的复杂性，要使用大多数高级映射（比如：嵌套联合映射），仍然需要使用 XML 配置。有鉴于此，如果存在一个同名 XML 配置文件，MyBatis 会自动查找并加载它（在这个例子中，基于类路径和 BlogMapper.class 的类名，会加载 BlogMapper.xml）。具体细节稍后讨论。
从SqlSessionFactory中获取SqlSession
现在你已经创建了一个SqlSessionFactory，顾名思义，你可以获取一个SqlSession实例。SqlSession包含对数据库执行SQL命令所需的所有方法。你可以直接针对SqlSession实例执行映射的SQL语句。例如：
try (SqlSession session = sqlSessionFactory.openSession()) {
Blog blog = session.selectOne(
"org.mybatis.example.BlogMapper.selectBlog", 101);
}
这种方法是可行的，而且MyBatis以前版本的用户对此也很熟悉，现在有一种更清除的方法。使用和指定语句的参数和返回值相匹配的接口(例如BlogMapper.class)，现在你的代码不仅更清晰而且更加类型安全，还不用担心可能出错的字符串字面值以及强制类型转换。
try (SqlSession session = sqlSessionFactory.openSession()) {
BlogMapper mapper = session.getMapper(BlogMapper.class);
Blog blog = mapper.selectBlog(101);
}
让我们探究一下这里到底执行了什么。
探究已经映射的SQL语句
此时你可能已经想知道，SqlSession和Mapper到底执行了些什么。SQL语句映射是一个很广泛的话题，这个话题会占去文档的大部分篇幅。但是为了让你知道到底是什么在运行，这里给出了几个例子。
在上面两个例子中，一个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>
虽然对于这个简单的示例来说，我们似乎写了不少配置，但其实非常少。你可以在一个XML文件中定义很多的的映射语句，这样一来，XML 头部和文档类型声明部分就显得微不足道了。mapper文件的其余部分就很容易理解，它在命名空间 “org.mybatis.example.BlogMapper” 中定义了一个名为 “selectBlog” 的映射语句，这样你就可以用全限定名 “org.mybatis.example.BlogMapper.selectBlog” 来调用映射语句了，就像上面例子中那样：
Blog blog = session.selectOne(
"org.mybatis.example.BlogMapper.selectBlog", 101);
你可能会注意到，这与完全限定类名调用一个方法类似，这样的话，该命名就可以直接映射到在命名空间中同名的映射器类，并将已映射的 select 语句匹配到对应名称、参数和返回类型的方法。因此你就可以像上面那样，不费吹灰之力地在对应的映射器接口调用方法，就像下面这样：
BlogMapper mapper = session.getMapper(BlogMapper.class);
Blog blog = mapper.selectBlog(101);
第二种方法有很多优势，首先它不依赖于字符串字面值，会更安全一点；其次，如果你的 IDE 有代码补全功能，那么代码补全可以帮你快速选择到映射好的 SQL 语句。
作用域（Scope）和生命周期
理解我们之前讨论过的不同作用域和生命周期类别是至关重要的，因为错误的使用会导致非常严重的并发问题。
对象生命周期和依赖注入框架
依赖注入框架可以创建线程安全的、基于事务的 SqlSession 和映射器，并将它们直接注入到你的 bean 中，因此可以直接忽略它们的生命周期。 如果对如何通过依赖注入框架使用 MyBatis 感兴趣，可以研究一下 MyBatis-Spring 或 MyBatis-Guice 两个子项目。
SqlSessionFactoryBuilder
这个类可以被实例化、使用和丢弃，一旦创建了 SqlSessionFactory，就不再需要它了。 因此 SqlSessionFactoryBuilder 实例的最佳作用域是方法作用域（也就是局部方法变量）。 你可以重用 SqlSessionFactoryBuilder 来创建多个 SqlSessionFactory 实例，但最好还是不要一直保留着它，以保证所有的 XML 解析资源可以被释放给更重要的事情。
SqlSessionFactory
SqlSessionFactory 一旦被创建就应该在应用的运行期间一直存在，没有任何理由丢弃它或重新创建另一个实例。 **使用 SqlSessionFactory 的最佳实践是在应用运行期间不要重复创建多次，**多次重建 SqlSessionFactory 被视为一种代码“坏习惯”。因此 SqlSessionFactory 的最佳作用域是应用作用域。 有很多方法可以做到，最简单的就是使用单例模式或者静态单例模式。
SqlSession
每个线程都应该有它自己的 SqlSession 实例。SqlSession 的实例不是线程安全的，因此是不能被共享的，所以它的最佳的作用域是请求或方法作用域。 绝对不能将 SqlSession 实例的引用放在一个类的静态域，甚至一个类的实例变量也不行。 也绝不能将 SqlSession 实例的引用放在任何类型的托管作用域中，比如 Servlet 框架中的 HttpSession。 如果你现在正在使用一种 Web 框架，考虑将 SqlSession 放在一个和 HTTP 请求相似的作用域中。 换句话说，每次收到 HTTP 请求，就可以打开一个 SqlSession，返回一个响应后，就关闭它。 这个关闭操作很重要，为了确保每次都能执行关闭操作，你应该把这个关闭操作放到 finally 块中。 下面的示例就是一个确保 SqlSession 关闭的标准模式：
try (SqlSession session = sqlSessionFactory.openSession()) {
// 你的应用逻辑代码
}
在所有代码中都遵循这种使用模式，可以保证所有数据库资源都能被正确地关闭。
映射器实例
映射器是一些绑定映射语句的接口。映射器接口的实例是从 SqlSession 中获得的。虽然从技术层面上来讲，任何映射器实例的最大作用域与请求它们的 SqlSession 相同。但方法作用域才是映射器实例的最合适的作用域。 也就是说，映射器实例应该在调用它们的方法中被获取，使用完毕之后即可丢弃。 映射器实例并不需要被显式地关闭。尽管在整个请求作用域保留映射器实例不会有什么问题，但是你很快会发现，在这个作用域上管理太多像 SqlSession 的资源会让你忙不过来。 因此，最好将映射器放在方法作用域内。就像下面的例子一样：
try (SqlSession session = sqlSessionFactory.openSession()) {
BlogMapper mapper = session.getMapper(BlogMapper.class);
// 你的应用逻辑代码
}
XML配置
MyBatis的的配置文件包含了会对MyBatis行为产生巨大影响的设置和属性信息，
配置文档的顶层结构如下：
configuration
- properties（属性）
- settings（设置）
- typeAliases（类型别名）
- typeHandlers（类型处理器）
- objectFactory（对象工厂）
- plugins（插件）
- environments（多个环境配置）
- environment（一个环境）
- transactionManager（事务管理器）
- dataSource（数据源）
- environment（一个环境）
- databaseIdProvider（数据提供商）
- mappers（多个映射器）
properties
这些属性可以在外部定义，然后进行动态替换。可以通过典型的Java配置文件实现、或者通过properties的子元素进行实现，例如：
<properties resource="org/mybatis/example/config.properties">
<property name="username" value="dev_user"/>
<property name="password" value="F2Fa3!33TYyg"/>
</properties>
这些属性（属性文件中定义好的），可以在整个配置文件中用来替换需要被动态配置的值。
<dataSource type="POOLED">
<property name="driver" value="${driver}"/>
<property name="url" value="${url}"/>
<property name="username" value="${username}"/>
<property name="password" value="${password}"/>
</dataSource>
上面例子中的username和password被properties 元素中设置的值替换（第一个代码片段中定义的）。diver和url属性会config.properties 文件中对应的值替换。这样为配置提供了很多选项
也可以在 SqlSessionFactoryBuilder.build() 方法中传入属性值。例如：
SqlSessionFactory factory =
sqlSessionFactoryBuilder.build(reader, props);
// ... or ...
SqlSessionFactory factory =
new SqlSessionFactoryBuilder.build(reader, environment, props);
当一个属性被存在于上面多个地方时，MyBatis会通过以下顺序加载他们：
- 首先读取在 properties 元素体内指定的属性。
- 然后根据 properties 元素中的 resource 属性读取类路径下属性文件，或根据 url 属性指定的路径读取属性文件，并覆盖之前读取过的同名属性。
- 最后读取作为方法参数传递的属性，并覆盖之前读取过的同名属性。
因此，通过方法参数传递的属性具有最高优先级，resource/url 属性中指定的配置文件次之，最低优先级的则是 properties 元素中指定的属性。
从 MyBatis 3.4.2 开始，你可以为占位符指定一个默认值。例如：
<dataSource type="POOLED">
<!-- ... -->
<property name="username" value="${username:ut_user}"/> <!-- 如果属性 'username' 没有被配置，'username' 属性的值将为 'ut_user' -->
</dataSource>
上面这个特征默认关闭的，如果你给占位符指定了一个默认值，你还需要添加一个特定的属性来开启这个特性。例
<properties resource="org/mybatis/example/config.properties">
<!-- ... -->
<property name="org.apache.ibatis.parsing.PropertyParser.enable-default-value" value="true"/> <!--启用默认特征 Enable this feature -->
</properties>
【提示：】如果你在属性名中使用了
":"字符（如：db:username），或者在 SQL 映射中使用了 OGNL 表达式的三元运算符（如：${tableName != null ? tableName : 'global_constants'}），就需要设置特定的属性来修改分隔属性名和默认值的字符。
例如：
<properties resource="org/mybatis/example/config.properties">
<!-- ... -->
<property name="org.apache.ibatis.parsing.PropertyParser.default-value-separator" value="?:"/> <!-- 修改默认值的分隔符 -->
</properties>
<dataSource type="POOLED">
<!-- ... -->
<property name="username" value="${db:username?:ut_user}"/>
</dataSource>
settings
These are extremely important tweaks that modify the way that MyBatis behaves at runtime. The following table describes the settings, their meanings and their default values.
这是MyBatis中极为重要的1设置，会改变MyBatis在运行时行为。下表中描述了这些设置含义和 他们的默认值。
| 设置名 | 描述 | 有效值 | 默认值 |
|---|---|---|---|
| cacheEnabled | 全局性地开启或关闭所有映射器配置文件中已配置的任何缓存。 | true /false | true |
| lazyLoadingEnabled | 全局开启或关闭懒加载. 当关闭时所有关联的都会延迟加载， 在特定的关联关系中这个值可以被fetchType 属性覆盖掉. | true / false | false |
| aggressiveLazyLoading | 开启时，任一方法的调用都会加载该对象的所有延迟加载属性。 否则，每个延迟加载属性会按需加载（参考 lazyLoadTriggerMethods)。 | true /false | false (true in ≤3.4.1) |
| multipleResultSetsEnabled | 是否允许单个语句返回多结果集（需要数据库驱动支持）. | true /false | true |
| useColumnLabel | 使用列标签代替列名.在这方面不同的驱动有不同的表现. 具体可参考数据库驱动的相关文档，或通过对比测试来观察。 | true / false | true |
| useGeneratedKeys | 允许 JDBC 支持自动生成主键，需要数据库驱动支持（compatible 兼容--->支持）。如果设置为 true，将强制使用自动生成主键。尽管一些数据库驱动不支持此特性，但仍可正常工作（如 Derby）。 | true / false | False |
| autoMappingBehavior | 指定MyBatis是否以及怎样自动映射列到字段或属性. NONE 代表禁用自动映射. PARTIAL代表只会自动映射没有定义嵌套结果映射的字段. FULL会自动映射任何复杂的结果集（无论是否嵌套） | NONE, PARTIAL, FULL | PARTIAL |
| autoMappingUnknownColumnBehavior | 指定发现自动映射目标未知列（或未知属性类型）的行为。NONE: 不做任何反应WARNING: 输出警告日日志(org.apache.ibatis.session.AutoMappingUnknownColumnBehavior的日志等级必须设置为 WARN) FAILING: 映射失败 (抛出 SqlSessionException) | NONE, WARNING, FAILING | NONE |
| defaultExecutorType | 指定默认执行器. SIMPLE 执行器不做什么特别的事情. REUSE执行器会重用预处理语句. BATCH 执行器不仅重用预处理语句还会执行批量更新. | SIMPLE, REUSE ,BATCH | SIMPLE |
| defaultStatementTimeout | 设置数据库驱动等待数据库响应的时间（超时时间）. | 任意正整数 | Not Set (null) |
| defaultFetchSize | 为驱动的结果集设置一个建议值，用来控制结果集的获取数量，这个参数在查询设置中会被覆盖 | 任意正整数 | Not Set (null) |
| defaultResultSetType | 指定语句默认的滚动策略。（新增于 3.5.2) | FORWARD_ONLY ，SCROLL_SENSITIVE，SCROLL_INSENSITIVE ，DEFAULT(等同于未设置) | Not Set (null) |
| safeRowBoundsEnabled | 是否允许在嵌套语句中使用分页(RowBounds)，如果允许使用则设置为 false。 | true， false | False |
| safeResultHandlerEnabled | 是否允许在嵌套语句中使用结果处理器*(ResultHandler),如果允许使用则设置为 false。 | true, false | True |
| mapUnderscoreToCamelCase | 是否开启驼峰命名自动映射，即从经典数据库列名 A_COLUMN 映射到经典 Java 属性名 aColumn。 | true ,false | False |
| localCacheScope | MyBatis 利用本地缓存机制（Local Cache）防止循环引用和加速重复的嵌套查询。 默认值为 SESSION，会缓存一个会话中执行的所有查询。 若设置值为 STATEMENT，本地缓存将仅用于执行语句，对相同 SqlSession 的不同查询将不会进行缓存。 | SESSION ,STATEMENT | SESSION |
| jdbcTypeForNull | 当没有为参数指定特定的 JDBC 类型时，空值的默认 JDBC 类型。 某些数据库驱动需要指定列的 JDBC 类型，多数情况直接用一般类型即可，比如 NULL、VARCHAR 或 OTHER。 | JdbcType 常量，常用值：NULL、VARCHAR 或 OTHER。 | OTHER |
| lazyLoadTriggerMethods | 指定对象的哪些方法触发一次延迟加载。 | 用逗号分隔的方法列表。 | equals,clone,hashCode,toString |
| defaultScriptingLanguage | 指定动态 SQL 生成使用的默认脚本语言。 | 一个类型别名或全限定类名。 | org.apache.ibatis.scripting.xmltags.XMLLanguageDriver |
| defaultEnumTypeHandler | 指定 Enum 使用的默认 TypeHandler 。（新增于 3.4.5） | 一个类型别名或全限定类名。 | org.apache.ibatis.type.EnumTypeHandler |
| callSettersOnNulls | 指定当结果集中值为 null 的时候是否调用映射对象的 setter（map 对象时为 put）方法，这在依赖于 Map.keySet() 或 null 值进行初始化时比较有用。注意基本类型（int、boolean 等）是不能设置成 null 的。 | true ，false | false |
| returnInstanceForEmptyRow | 当返回行的所有列都是空时，MyBatis默认返回 null。 当开启这个设置时，MyBatis会返回一个空实例。 请注意，它也适用于嵌套的结果集（如集合或关联）。（新增于 3.4.2） | true ，false | false |
| logPrefix | 指定 MyBatis 增加到日志名称的前缀。 | 任何字符串 | 未设置 |
| logImpl | 指定 MyBatis 所用日志的具体实现，未指定时将自动查找。 | SLF4J | LOG4J |
| proxyFactory | 指定 Mybatis 创建可延迟加载对象所用到的代理工具。 | CGLIB，JAVASSIST | JAVASSIST （MyBatis 3.3 以上） |
| vfsImpl | 指定 VFS 的实现 自定义 VFS 的实现的类全限定名， | 用逗号分隔、 | 未设置 |
| configurationFactory | 指定一个提供 Configuration 实例的类。 这个被返回的 Configuration 实例用来加载被反序列化对象的延迟加载属性值。 这个类必须包含一个签名为static Configuration getConfiguration() 的方法。（新增于 3.2.3） | 一个类型别名或完全限定类名. | 未设置 |
一个配置完整的setting元素的配置如下所示：
<settings>
<setting name="cacheEnabled" value="true"/>
<setting name="lazyLoadingEnabled" value="true"/>
<setting name="multipleResultSetsEnabled" value="true"/>
<setting name="useColumnLabel" value="true"/>
<setting name="useGeneratedKeys" value="false"/>
<setting name="autoMappingBehavior" value="PARTIAL"/>
<setting name="autoMappingUnknownColumnBehavior" value="WARNING"/>
<setting name="defaultExecutorType" value="SIMPLE"/>
<setting name="defaultStatementTimeout" value="25"/>
<setting name="defaultFetchSize" value="100"/>
<setting name="safeRowBoundsEnabled" value="false"/>
<setting name="mapUnderscoreToCamelCase" value="false"/>
<setting name="localCacheScope" value="SESSION"/>
<setting name="jdbcTypeForNull" value="OTHER"/>
<setting name="lazyLoadTriggerMethods"
value="equals,clone,hashCode,toString"/>
</settings>
typeAliases（别名）
类型别名可为 Java 类型设置一个简写的名字。 它仅用于 XML 配置，意在降低冗余的全限定类名书写。
<typeAliases>
<typeAlias alias="Author" type="domain.blog.Author"/>
<typeAlias alias="Blog" type="domain.blog.Blog"/>
<typeAlias alias="Comment" type="domain.blog.Comment"/>
<typeAlias alias="Post" type="domain.blog.Post"/>
<typeAlias alias="Section" type="domain.blog.Section"/>
<typeAlias alias="Tag" type="domain.blog.Tag"/>
</typeAliases>
通过这个配置, Blog 可以在任何需要使用domain.blog.Blog 的地方使用。
也可以指定一个包名，MyBatis 会在包名下面搜索需要的 Java Bean，比如：
<typeAliases>
<package name="domain.blog"/>
</typeAliases>
Each bean found in domain.blog , if no annotation is found, will be registered as an alias using uncapitalized non-qualified class name of the bean. That is domain.blog.Author will be registered as author. If the @Alias annotation is found its value will be used as an alias. See the example below:
每一个在包 domain.blog 中的 Java Bean，在没有注解的情况下，会使用 Bean 的首字母小写的非限定类名来作为它的别名。 比如 domain.blog.Author 的别名为 author；若有注解，则别名为其注解值。见下面的例子：
@Alias("author")
public class Author {
...
}
下面是一些为常见的 Java 类型内建的类型别名。它们都是不区分大小写的，注意，为了应对原始类型的命名重复，采取了特殊的命名风格。
| 别名 | 映射类型 |
|---|---|
| _byte | byte |
| _long | long |
| _short | short |
| _int | int |
| _integer | int |
| _double | double |
| _float | float |
| _boolean | boolean |
| string | String |
| byte | Byte |
| long | Long |
| short | Short |
| int | Integer |
| integer | Integer |
| double | Double |
| float | Float |
| boolean | Boolean |
| date | Date |
| decimal | BigDecimal |
| bigdecimal | BigDecimal |
| object | Object |
| map | Map |
| hashmap | HashMap |
| list | List |
| arraylist | ArrayList |
| collection | Collection |
| iterator | Iterator |
typeHandlers(类型处理器)
MyBatis不管是在预处理语句（PreparedStatement ）中设置参数或者从结果集（ResultSet）中提取一个值时,都会用类型处理器将获取到的值以合适的方式转换成 Java 类型。
下表描述了一些默认的类型处理器。
NOTE 从3.4.5开始, MyBatis开始默认支持 JSR-310 (Date and Time API)
| Type Handle(类型处理器)r | Java Types | JDBC Types |
|---|---|---|
| BooleanTypeHandler | java.lang.Boolean, boolean | Any compatible BOOLEAN |
| ByteTypeHandler | java.lang.Byte, byte | Any compatible NUMERIC or BYTE |
| ShortTypeHandler | java.lang.Short, short | Any compatible NUMERIC or SMALLINT |
| IntegerTypeHandler | java.lang.Integer, int | Any compatible NUMERIC or INTEGER |
| LongTypeHandler | java.lang.Long, long | Any compatible NUMERIC or BIGINT |
| FloatTypeHandler | java.lang.Float, float | Any compatible NUMERIC or FLOAT |
| DoubleTypeHandler | java.lang.Double, double | Any compatible NUMERIC or DOUBLE |
| BigDecimalTypeHandler | java.math.BigDecimal | Any compatible NUMERIC or DECIMAL |
| StringTypeHandler | java.lang.String | CHAR, VARCHAR |
| ClobReaderTypeHandler | java.io.Reader | - |
| ClobTypeHandler、 java.lang.String | CLOB, LONGVARCHAR | |
| NStringTypeHandler | java.lang.String | NVARCHAR, NCHAR |
| NClobTypeHandler | java.lang.String | NCLOB |
| BlobInputStreamTypeHandler | java.io.InputStream | - |
| ByteArrayTypeHandler | byte[] | Any compatible byte stream type |
| BlobTypeHandler | byte[] | BLOB, LONGVARBINARY |
| DateTypeHandler | java.util.Date | TIMESTAMP |
| DateOnlyTypeHandler | java.util.Date | DATE |
| TimeOnlyTypeHandler | java.util.Date | TIME |
| SqlTimestampTypeHandler | java.sql.Timestamp | TIMESTAMP |
| SqlDateTypeHandler | java.sql.Date | DATE |
| SqlTimeTypeHandler | java.sql.Time | TIME |
| ObjectTypeHandler | Any OTHER, or | unspecified |
| EnumTypeHandler | Enumeration Type | VARCHAR any string compatible type, as the code is stored (not index). |
| EnumOrdinalTypeHandler | Enumeration Type | Any compatible NUMERIC or DOUBLE, as the position is stored (not the code itself). |
| SqlxmlTypeHandler | java.lang.String | SQLXML |
| InstantTypeHandler | java.time.Instant | TIMESTAMP |
| LocalDateTimeTypeHandler | java.time.LocalDateTime | TIMESTAMP |
| LocalDateTypeHandler | java.time.LocalDate | DATE |
| LocalTimeTypeHandler | java.time.LocalTime | TIME |
| OffsetDateTimeTypeHandler | java.time.OffsetDateTime | TIMESTAMP |
| OffsetTimeTypeHandler | java.time.OffsetTime | TIME |
| ZonedDateTimeTypeHandler | java.time.ZonedDateTime | TIMESTAMP |
| YearTypeHandler | java.time.Year | INTEGER |
| MonthTypeHandler | java.time.Month | INTEGER |
| YearMonthTypeHandler | java.time.YearMonth | VARCHAR or LONGVARCHAR |
| JapaneseDateTypeHandler | java.time.chrono.JapaneseDate | DATE |
你可以重写已有的类型处理器或创建你自己的类型处理器来处理不支持的或非标准的类型。 具体做法为：实现 org.apache.ibatis.type.TypeHandler 接口， 或继承一个很便利的类 org.apache.ibatis.type.BaseTypeHandler， 并且可以（可选地）将它映射到一个 JDBC 类型。比如：
// ExampleTypeHandler.java
@MappedJdbcTypes(JdbcType.VARCHAR)
public class ExampleTypeHandler extends BaseTypeHandler<String> {
@Override
public void setNonNullParameter(PreparedStatement ps, int i,
String parameter, JdbcType jdbcType) throws SQLException {
ps.setString(i, parameter);
}
@Override
public String getNullableResult(ResultSet rs, String columnName)
throws SQLException {
return rs.getString(columnName);
}
@Override
public String getNullableResult(ResultSet rs, int columnIndex)
throws SQLException {
return rs.getString(columnIndex);
}
@Override
public String getNullableResult(CallableStatement cs, int columnIndex)
throws SQLException {
return cs.getString(columnIndex);
}
}
<!-- mybatis-config.xml -->
<typeHandlers>
<typeHandler handler="org.mybatis.example.ExampleTypeHandler"/>
</typeHandlers>
使用上述的类型处理器将会覆盖已有的处理 Java String 类型的属性以及 VARCHAR 类型的参数和结果的类型处理器。 要注意 MyBatis 不会通过检测数据库元信息来决定使用哪种类型，所以你必须在参数和结果映射中指明字段是 VARCHAR 类型， 以使其能够绑定到正确的类型处理器上。这是因为 MyBatis 直到语句被执行时才清楚数据类型。
通过类型处理器的泛型，MyBatis 可以得知该类型处理器处理的 Java 类型，不过这种行为可以通过两种方法改变：
- 在类型处理器的配置元素（
typeHandler 元素）上增加一个javaType属性（比如：javaType="String"）； - 在类型处理器的类上增加一个
@MappedTypes注解指定与其关联的 Java 类型列表。 如果在javaType属性中也同时指定，则注解上的配置将被忽略。
可以通过两种方式来指定关联的 JDBC 类型：
- 在类型处理器的配置元素上增加一个
jdbcType属性（比如：jdbcType="VARCHAR"）； - 在类型处理器的类上增加一个
@MappedJdbcTypes注解指定与其关联的 JDBC 类型列表。 如果在jdbcType属性中也同时指定，则注解上的配置将被忽略。
当在 ResultMap 中决定使用哪种类型处理器时，此时 Java 类型是已知的（从结果类型中获得），但是 JDBC 类型是未知的。 因此 Mybatis 使用 javaType=[Java 类型], jdbcType=null 的组合来选择一个类型处理器。
这意味着使用 @MappedJdbcTypes 注解可以限制类型处理器的作用范围，并且可以确保，除非显式地设置，否则类型处理器在 ResultMap 中将不会生效。 如果希望能在 ResultMap 中隐式地使用类型处理器，那么设置 @MappedJdbcTypes 注解的 includeNullJdbcType=true 即可。 然而从 Mybatis 3.4.0 开始，如果某个 Java 类型只有一个注册的类型处理器，即使没有设置 includeNullJdbcType=true，那么这个类型处理器也会是 ResultMap 使用 Java 类型时的默认处理器。
最后，可以让 MyBatis 帮你查找类型处理器：
<!-- mybatis-config.xml -->
<typeHandlers>
<package name="org.mybatis.example"/>
</typeHandlers>
注意在使用自动发现功能的时候，只能通过注解方式来指定 JDBC 的类型。
你可以创建能够处理多个类的泛型类型处理器。为了使用泛型类型处理器， 需要增加一个接受该类的 class 作为参数的构造器，这样 MyBatis 会在构造一个类型处理器实例的时候传入一个具体的类。
//GenericTypeHandler.java
public class GenericTypeHandler<E extends MyObject> extends BaseTypeHandler<E> {
private Class<E> type;
public GenericTypeHandler(Class<E> type) {
if (type == null) throw new IllegalArgumentException("Type argument cannot be null");
this.type = type;
}
EnumTypeHandler 和 EnumOrdinalTypeHandler 都是泛型类型处理器，我们将会在接下来的部分详细探讨。
tweaks ↩︎
扫一扫
143
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
