Java架构师之旅（二十九 附录《MyBatis3 用户指南》中文版）

夜光序言：

 

岁月波光粼粼，赋予爱与生命，唯有生活不能被他人代替，只会有寂寞相随~~

 

 

 

 

 

正文：

MyBatis 3

2010.08.01  翻译的一个版本，虽难比较老了，但是有一些基础还是值得学习，毕竟是中文版

 

Contents

MyBatis是什么? 6

准备开始 6

从XML中创建 SqlSessionFactory 实例 6

如何不使用XML来创建SqlSessionFactory 7

从SqlSessionFactory 获取SqlSession 7

探索映射SQL语句 8

关于命名空间 9

作用域和生命周期 10

Mapper XML配置 11

properties元素 12

Settings元素 13

typeAliases元素 14

typeHandlers元素 15

objectFactory元素 16

Plugins元素 17

Environments元素 18

事务管理器 20

dataSource元素 21

Mappers元素 23

SQL 映射 XML 文件 23

Select元素 24

Insert、 update、 delete元素 25

Sql元素 28

参数（Parameters） 28

resultMap元素 30

高级结果映射 32

id, result元素 34

支持的JDBC类型 35

Constructor元素 35

Association元素 36

Collection元素 40

Discriminator元素 42

Cache元素 43

cache-ref元素 46

动态SQL（Dynamic SQL） 46

if元素 46

choose, when, otherwise元素 47

trim, where, set元素 48

Foreach元素 50

Java API 52

目录结构 52

SqlSessions 53

SqlSessionFactoryBuilder 53

SqlSessionFactory 55

SqlSession 57

SelectBuilder 64

SqlBuilder 67

结束语 69

附录1 对象模型 70

附录2创建数据库 73

附录3 MyBatis实例 77

 简单select 77

 update，delete，insert 84

 自动生成主键 85

 处理NULL值 87

 使用接口映射类 88

 使用Constructor元素 90

 使用Association元素 92

 使用Collection元素 100

附录4 XML中的特殊字符 104

 

 

 

MyBatis是什么?

MyBatis是一款一流的支持自定义SQL、存储过程和高级映射的持久化框架。MyBatis几乎消除了所有的JDBC代码，也基本不需要手工去设置参数和获取检索结果。MyBatis能够使用简单的 XML格式或者注解进行来配置，能够映射基本数据元素、Map接口和POJOs（普通java对象）到数据库中的记录。

准备开始

所有的MyBatis应用都以SqlSessionFactory实例为中心。SqlSessionFactory实例通过 SqlSessionFactoryBuilder来获得，SqlSessionFactoryBuilder能够从XML配置文件或者通过自定义编写的配置类（Configuration class），来创建一个SqlSessionFactory实例。

从XML中创建 SqlSessionFactory 实例

从XML中创建SqlSessionFactory实例非常简单。建议您使用类资源路径（classpath

resource）来加载配置文件，但是您也能够使用任何方式，包括文本文件路径或者以file:// 开头URL的方式。MyBatis包括一个叫做Resources的工具类（utility class），其中包含了一系列方法，使之能简单地从classpath或其它地方加载配置文件。

String resource = "org/mybatis/example/Configuration.xml"; Reader reader = Resources.getResourceAsReader(resource); sqlMapper = new SqlSessionFactoryBuilder().build(reader);

XML配置文件包含MyBatis框架的核心设置，包括获取数据库连接的DataSource实例，和包括决定事务作用域范围和控制的事务管理等。您将能够在后面的章节中找到详细的XML配置，在这里我们先展示一个简单的例子：

PUBLIC "-//mybatis.org//DTD Config 3.0//EN"

"http://mybatis.org/dtd/mybatis-3-config.dtd">

虽然XML配置文件中还有很多其它的配置细节，但是，上面的示例显示了最重要的部分。注意XML配置文件的头部，会使用DTD验证文档来验证该XML配置文件。body部分的environment 元素，包含了事务管理和连接池配置。Mappers元素指定了映射配置文件--包含SQL语句和映射定义的XML文件。

如何不使用XML来创建SqlSessionFactory

如果您喜欢直接通过java代码而不是通过XML创建配置选项，或者想创建您自己的配置生成器。MyBatis提供了一个完整的配置类（Configuration class），它提供了与XML文件相同的配置选项。

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

请注意，这种方式下的配置添加一个映射类（mapper class）。映射类是包含SQL映射注解

的Java类，从而避免了使用XML。但是，由于注解的一些局限性以及MyBatis映射的复杂性， XML仍然是一些高级的映射功能（如嵌套连接映射，Nested Join Mapping）所必须的方式。基于这个原因，如果存在XML文件，MyBatis自动寻找并加载这个XML文件。在这种情况下， BlogMapper.xml将会被类路径下名称为BlogMapper.class的类加载。详述请见后面章节。

从SqlSessionFactory 获取SqlSession

现在您已经创建了一个SqlSessionFactory（指上面的sqlMapper），正如它名字暗示那样，

您可以通过它来创建一个SqlSession 实例。SqlSession包含了所有执行数据库SQL语句的方法。您能够直接地通过SqlSession实例执行映射SQL语句。例如：

SqlSession session = sqlMapper.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 class）是怎样执行的。映射SQL

语句是一个很大的主题，该主题将可能占据本文档的大部分内容。但是，为了让您看到它是怎样运行的，这里举两个例子。

在上面的例子中，映射语句已经在XML配置文件或注解中定义。让我们首先来看看XML配置文件，所有MyBatis提供的功能特性都可以通过基于XML映射配置文件配置来实现。如果您以前使用过MyBatis，对此就会很熟悉。但许多改进使XML映射文件变得更简洁清晰。下面是一个基于XML映射配置的例子，满足上述SqlSession的调用。

PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"

"http://mybatis.org/dtd/mybatis-3-mapper.dtd">

select * from Blog where id = #{id}

这个简单的例子看起来有不少的开销，但它确实非常地轻巧，只要您喜欢，您可以在一个映射XML文件中定义许多映射语句。虽然会有一些XML头部和DOCTYPE声明，但该文件余下的部分是自解（self explanatory，可理解为不加解释就能明白）的。它定义了映射语句的名称

“selectBlog”，在命名空间“org.mybatis.example.BlogMapper”，允许您通过指定完整类名

“org.mybatis.example.BlogMapper”来访问上面的例子：

Blog blog = (Blog) session.selectOne(

"org.mybatis.example.BlogMapper.selectBlog", 101);

这非常类似java中通过完整类名来调用方法，而这样做是有原因的。这个名称可以直接映射

到一个具在相同命名空间的映射类，这个映射类有一个方法的名称、参数及返回类型都与select 映射语句相匹配。正如您前面看到的，这使您很简单地调用映射类里的方法，下面是另外的一个例子：

BlogMapper mapper = session.getMapper(BlogMapper.class);

Blog blog = mapper.selectBlog(101);

第二种方法有很多好处。第一，它不依赖于字符串，所以更安全。第二，如果您的IDE有自动完成功能，您可以利用这功能很快导航到您的映射SQL语句。第三，您不需要关注返回类型，不需要进行强制转换，因为使用BlogMapper 接口已经限定了返回类型，它会安全地返回。

关于命名空间

命名空间:在以前的版本中是可选的、复杂的且没多大用处。但在这个版本中，命名空间是必须的，并且不仅仅是简单地使用完整类名来隔离区分语句。 正如您看到的那样，命名空间能够进行接口绑定，即使您认为现在不会使用到它，但您应该按照这些准则来做。一旦使用了命名空间并且放入适当的java包命名空间中将会使您的代码清晰，并提高MyBatis的长期可用性。 名称解析: 为了减少大量地输入， MyBatis对所有的配置元素，包括statements、result maps、 caches等使用下面的名称解析规则: 完整类名 ：(例如: “com.mypackage.MyMapper.selectAllThings”)可用来直接查找并使用。 短名称： (例如: “selectAllThings”)可用来引用明确的实体对象。但是，如果出现有两个或更多（例如“com.foo.selectAllThings和com.bar.selectAllThings”）实体对象，您将收到一个错误报告（短名称含糊不清），因此，这时就必须使用完整类名。

对映射类还有一个更好的方法,就像前面的BlogMapper。它们的映射语句不需要完全在XML 中配置。相反，它们可以使用Java注解。例如上面的XML配置可以替换为：

package org.mybatis.example;

public interface BlogMapper {

@Select("SELECT * FROM blog WHERE id = #{id}")

Blog selectBlog(int id);

}

对简单的映射语句，使用注解可以显得非常地清晰。但是java注解本身的局限难于应付更复杂的语句。如果您准备要做某些复杂的事情，最好使用XML文件来配置映射语句。这将由您和您的项目小组来确定哪种方式是适合的，以一致的方式来定义映射语句是非常重要的。也就是说，您不会被限于仅用一种方式。您能够非常容易地从基于注解的映射语句移植到

XML配置文件中，反之亦然。

作用域和生命周期

理解到目前为止所讨论的类的作用域和生命周期是非常重要的。如果使用不当可导致严重的并发性问题。

SqlSessionFactoryBuilder

这个类可以在任何时候被实例化、使用和销毁。一旦您创造了SqlSessionFactory就不需要再保留它了。所以SqlSessionFactoryBuilder实例的最好的作用域是方法体内（即一个本地方法变量）。您能重用SqlSessionFactoryBuilder创建多个SqlSessionFactory实例，但最好不要把时间、资源放在解析XML文件上，而是要从中解放出来做最重要事情。

SqlSessionFactory

一旦创建，SqlSessionFactory将会存在于您的应用程序整个运行生命周期中。很少或根本没有理由去销毁它或重新创建它。最佳实践是不要在一个应用中多次创建SqlSessionFactory。这样做会被视为“没品味”。所是SqlSessionFactory最好的作用域范围是一个应用的生命周期范围。这可以由多种方式来实现，最简单的方式是使用Singleton模式或静态Singleton模式。但这不是被广泛接受的最佳做法，相反，您可能更愿意使用像Google Guice 或Spring的依赖注入方式。这些框架允许您创造一个管理器，用于管理SqlSessionFactory的生命周期。

SqlSession

每个线程都有一个SqlSession实例，SqlSession实例是不被共享的，并且不是线程安全的。因此最好的作用域是request或者method。决不要用一个静态字段或者一个类的实例字段来保存SqlSession实例引用。也不要用任何一个管理作用域，如Servlet框架中的HttpSession，来保存SqlSession的引用。如果您正在用一个WEB框架，可以把SqlSession的作用域看作类似于HTTP的请求范围。也就是说，在收到一个HTTP请求，您可以打开一个SqlSession，当您把 response返回时，就可以把SqlSession关闭。关闭会话是非常重要的，您应该要确保会话在一个finally块中被关闭。

SqlSession session = sqlSessionFactory.openSession(); try {

// do work

} finally {

session.close();

}

在您的代码里都使用这一模式将保证所有的数据库资源被正确地关闭（假如您没有把您自己

的数据库连接传递给MyBatis管理，这就对MyBatis表明您希望自己管理连接）。

Mapper实例

Mappers是创建来绑定映射语句的接口，该Mapper实例是从SqlSession得到的。因此，所有mapper实例的作用域跟创建它的SqlSession一样。但是，mapper实例最好的作用域是 method，也就是它们应该在方法内被调用，使用完即被销毁。并且mapper实例不用显式地被关闭。虽然把mapper实例保持在一个request范围（与SqlSession相似）不会产生太大的问题，但是您可能会发现，在这个层次上管理太多资源可能会失控。保持简单，就是让Mappers保持在一个方法内。下面的例子演示了这种做法。

SqlSession session = sqlSessionFactory.openSession(); try {

BlogMapper mapper = session.getMapper(BlogMapper.class);

// do work

} finally {

session.close();

}

Mapper XML配置

MyBatis的XML配置文件包含了设置和影响MyBatis行为的属性。XML配置文件的层次结构如下：

• configuration o properties o settings o typeAliases o typeHandlers o objectFactory o plugins o environments

environment

• transactionManager
• dataSource

o mappers

properties元素

它们都是外部化，可替代的属性。可以配置在一个典型的Java属性文件中，或者通过

properties元素的子元素进行配置。例如：

在整个配置文件中，这些属性能够被可动态替换（即使用占位符）的属性值引用，例如：

示例中的username和password将会被替换为配置在properties元素中的相应值。driver

和 url属性则会被config.properties文件中的相应值替换。这里提供了大量的配置选项。这些属性也可以传递给sqlSessionFactoryBuilder.build()方法。例如：

SqlSessionFactory factory = sqlSessionFactoryBuilder.build(reader, props);

// ... or ...

SqlSessionFactory factory = sqlSessionFactoryBuilder.build(reader, environment, props);

如果一个属性存在于多个地方，MyBatis将使用下面的顺序加载：

• 首先读入properties元素主体中指定的属性。
• 然后会加载类路径或者properties元素中指定的url的资源文件属性。它会覆盖前面已经读入的重复属性。
• 通过方法参数来传递的属性将最后读取(即通过sqlSessionFactoryBuilder.build)，同样也会覆盖从properties元素指定的和resource/url指定的重复属性。

因此最优先的属性是通过方法参数来传递的属性，然后是通过resource/url配置的属性，最后是在MyBatis的Mapper配置文件中，properties元素主体中指定的属性。

Settings元素

Setting元素下是些非常重要的设置选项，用于设置和改变MyBatis运行中的行为。下面的表格列出了Setting元素支持的属性、默认值及其功能。

设置选项	描述	可用值	默认值
cacheEnabled	全局性地启用或禁用所有在mapper 配置文件中配置的缓存。	true | false	true
lazyLoadingEnabled	全局性地启用或禁用延迟加载。当禁用时，所有关联的配置都会立即加载。	true | false	true
aggressiveLazyLoading	当启用后，一个有延迟加载属性的对象的任何一个延迟属性被加载时，该对象的所有的属性都会被加载。否则，所有属性都是按需加载。	true | false	true
multipleResultSetsEnabled	允许或禁止从单一的语句返回多个结果集（需要驱动程序兼容）。	true | false	true
useColumnLabel	使用列的标签而不是列的名称。在这方面，不同的驱动程序可能有不同的实现。参考驱动程序的文档或者进行测试来确定您所使用的驱动程的行为	true | false	true
useGeneratedKeys	允许JDBC 自动生成主键。需要驱动程序兼容。如果设置为true则会强行自动生成主键，然而有些则不会自动生成主键（驱动程序不兼容），但依旧会工作（如Derby）。	true | false	False
autoMappingBehavior	指定MyBatis是否以及如何自动将列映射到字段/属性。 PARTIAL: 只是自动映射简单、非嵌套的结果集。 FULL: 将会自动映射任何复杂的（嵌套或非嵌套）的结果集。	NONE, PARTIAL, FULL	PARTIAL
defaultExecutorType	配置默认的执行器（executor）。 SIMPLE ：简单的执行器。 REUSE ：重用prepared statements的执行器。 BATCH：重用statements并且进行批量更新的执行器。	SIMPLE REUSE BATCH	SIMPLE
defaultStatementTimeout	设置查询数据库超时时间。	任何正整数	Not Set (null)

一个Settings元素完整的配置例子如下：

typeAliases元素

别名是一个较短的Java类型的名称。这只是与XML配置文件相关联，减少输入多余的完整类

名。例如：

在这个配置中，您就可以在想要使用"domain.blog.Blog"的地方使用别名“Blog”了。

对常用的java类型，已经内置了一些别名支持。这些别名都是不区分大小写的。注意java 的基本数据类型，它们进行了特别处理，加了“_”前缀。

别名	对应的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结果集中取得值时，就会使用TypeHandler来处理数据库类型与java类型之间转换。下表描述了默认的TypeHandlers。

Type Handler	Java Types	JDBC Types
BooleanTypeHandler	Boolean, boolean	任何兼容的 BOOLEAN
ByteTypeHandler	Byte, byte	任何兼容的NUMERIC 或		BYTE
ShortTypeHandler	Short, short	任何兼容的NUMERIC或		SHORT INTEGER
IntegerTypeHandler	Integer, int	任何兼容的NUMERIC或		INTEGER
LongTypeHandler	Long, long	任何兼容的NUMERIC	或	LONG INTEGER
FloatTypeHandler	Float, float	任何兼容的NUMERIC	或	FLOAT
DoubleTypeHandler	Double, double	任何兼容的NUMERIC	或	DOUBLE
BigDecimalTypeHandler	BigDecimal	任何兼容的NUMERIC	或	DECIMAL
StringTypeHandler	String	CHAR, VARCHAR
ClobTypeHandler	String	CLOB, LONGVARCHAR
NStringTypeHandler	String	NVARCHAR, NCHAR
NClobTypeHandler	String	NCLOB
ByteArrayTypeHandler	byte[]	任何兼容的byte stream type
BlobTypeHandler	byte[]	BLOB, LONGVARBINARY
DateTypeHandler	Date (java.util)	TIMESTAMP
DateOnlyTypeHandler	Date (java.util)	DATE
TimeOnlyTypeHandler	Date (java.util)	TIME
SqlTimestampTypeHandler	Timestamp (java.sql)	TIMESTAMP
SqlDateTypeHadler	Date (java.sql)	DATE
SqlTimeTypeHandler	Time (java.sql)	TIME
ObjectTypeHandler	Any	OTHER, or unspecified
EnumTypeHandler	Enumeration Type	VARCHAR –任何与string兼容的类型，储存的是编码而不是索引。

您能够重写类型处理器（type handlers），或者创建您自己的类型处理器去处理没有被支持

的或非标准的类型。要做到这一点，只要实现TypeHandler接口(org.mybatis.type)，并且将您的TypeHandler类映射到java类型和可选的JDBC类型即可。例如：

// ExampleTypeHandler.java

public class ExampleTypeHandler implements TypeHandler {

public void setParameter(

PreparedStatement ps, int i, Object parameter, JdbcType jdbcType) throws SQLException { ps.setString(i, (String) parameter);

}

public Object getResult(

ResultSet rs, String columnName) throws SQLException {

return rs.getString(columnName);

}

public Object getResult(

CallableStatement cs, int columnIndex) throws SQLException {

return cs.getString(columnIndex);

}

}

// MapperConfig.xml

使用上面的TypeHandler将会重写已经存在的用来处理java的String属性、VARCHAR参数

和结果集的类型处理器。注意，MyBatis并不会通过数据库的元数据来确认类型，所以您必须指定它的一个类型处理器，用于将VARCHAR字段的参数和结果映射到正确的类型上。这是因为 MyBatis在语句的执行之前都不知道它要处理的数据类型是什么。

objectFactory元素

MyBatis每次创建一个结果对象实例都会使用ObjectFactory实例。使用默认的 ObjectFactory与使用默认的构造函数（或含参数的构造函数）来实例化目标类没什么差别。如果您想重写ObjectFactory来改变其默认行为，那您能通过创造您自己的ObjectFactory来做到。看下面的例子：

// ExampleObjectFactory.java

public class ExampleObjectFactory extends DefaultObjectFactory {

public Object create(Class type) {

return super.create(type);

}

public Object create(

Class type,

List constructorArgTypes,

List