MyBatis 3
用户指南
帮助我们把文档做得更好…
如果你发现了本文档的遗漏之处，或者丢失 MyBatis 特性的说明时，那么最好的方法就
是了解一下这个遗漏之处然后把它记录下来。
我们在 wiki 接收公共的文档贡献：
http://code.google.com/p/mybatis/wiki/Welcome
你也是本文档的最佳作者，其他用户也会来阅读它的。
关于翻译
MyBatis 3 的用户指南翻译由南磊完成，若对翻译质量有任何意见和建议，请联系
nanlei1987@gmail.com，愿和大家共同提高，共同进步。
从文档中复制代码的警告
对，这不是一个法律上的警告，但是它可以帮助你保持清醒的认识。从美
学上来讲，现代的文字处理工具在制作可读性强和格式良好的文本上做了大
量的工作。然而，它们也往往会由于插入特殊字符而完全破坏代码示例，有
时看起来和你想要的是一模一样的。“引号"和连字符就是一个很好的例子-在
IDE 环境或文本编辑器中，左边的那个符号就不会正常起作用，至少不会是你
想要的那个效果。
阅读本文档，就要享受它，希望它能对你有帮助。当遇到代码段示例的时
候，可以寻找示例和下载（包括单元测试等），或是来自网站和邮件列表的
示例。
目录
什么是 MyBatis？............................................................................................................. 5
入门................................................................................................................................. 5
从 XML 中构建 SqlSessionFactory .............................................................................. 5
不使用 XML 构建 SqlSessionFactory........................................................................... 6
从 SqlSessionFactory 中获取 SqlSession....................................................................... 6
探究已映射的 SQL 语句 ............................................................................................ 7
命名空间的一点注释 .......................................................................................... 8
范围和生命周期 ........................................................................................................ 8
SqlSessionFactoryBuilder ..................................................................................... 8
SqlSessionFactory................................................................................................ 9
SqlSession .......................................................................................................... 9
Mapper 实例 ....................................................................................................... 9
XML 映射配置文件 ........................................................................................................ 10
properties................................................................................................................. 10
Settings ....................................................................................................................11
typeAliases .............................................................................................................. 12
typeHandlers ............................................................................................................ 13
objectFactory ........................................................................................................... 14
plugins .................................................................................................................... 15
environments............................................................................................................ 16
transactionManager ............................................................................................ 17
dataSsource....................................................................................................... 17
mappers ................................................................................................................... 19
SQL 映射的 XML 文件 ................................................................................................... 19
select....................................................................................................................... 20
insert，update，delete .............................................................................................. 21
sql........................................................................................................................... 23
Parameters ............................................................................................................... 24
resultMap ................................................................................................................ 25
高级结果映射................................................................................................... 27
id，result.......................................................................................................... 29
支持的 JDBC 类型 ............................................................................................ 30
构造方法.......................................................................................................... 30
关联................................................................................................................. 31
集合................................................................................................................. 34
鉴别器 ............................................................................................................. 36
缓存........................................................................................................................ 38
使用自定义缓存 ............................................................................................... 38
参照缓存................................................................................................................. 39
动态 SQL ................................................................................................................ 39
if ..................................................................................................................... 40
choose, when, otherwise ..................................................................................... 40
trim, where, set .................................................................................................. 41
foreach ............................................................................................................. 43
Java API ......................................................................................................................... 43
应用目录结构.......................................................................................................... 43
SqlSessions .............................................................................................................. 44
SqlSessionFactoryBuilder ................................................................................... 44
SqlSessionFactory.............................................................................................. 46
SqlSession ........................................................................................................ 47
SelectBuilder..................................................................................................... 53
SqlBuilder ........................................................................................................ 56
什么是 MyBatis？
MyBatis 是支持普通 SQL 查询，存储过程和高级映射的优秀持久层框架。MyBatis 消除
了几乎所有的 JDBC 代码和参数的手工设置以及结果集的检索。MyBatis 使用简单的 XML
或注解用于配置和原始映射，将接口和 Java 的 POJOs（Plan Old Java Objects，普通的 Java
对象）映射成数据库中的记录。
入门
每一个 MyBatis 的 应 用 程 序 都 以 一 个 SqlSessionFactory 对 象 的 实 例 为 核 心 。
SqlSessionFactory 对 象 的 实 例 可 以 通 过 SqlSessionFactoryBuilder 对 象 来 获 得 。
SqlSessionFactoryBuilder 对象可以从 XML 配置文件，或从 Configuration 类的习惯准备的实
例中构建 SqlSessionFactory 对象。
从 XML 中构建 SqlSessionFactory
从 XML 文件中构建 SqlSessionFactory 的实例非常简单。这里建议你使用类路径下的资
源文件来配置，但是你可以使用任意的 Reader 实例，这个实例包括由文字形式的文件路径
或 URL 形式的文件路径 file://来创建。MyBatis 包含了一些工具类，称作为资源，这些工具
类包含一些方法，这些方法使得从类路径或其他位置加载资源文件更加简单。
String resource = "org/mybatis/example/Configuration.xml";
Reader reader = Resources.getResourceAsReader(resource);
sqlMapper = new SqlSessionFactoryBuilder().build(reader);
XML 配置文件包含对 MyBatis 系统的核心设置，包含获取数据库连接实例的数据源和
决定事务范围和控制的事务管理器。关于 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>
