mybatis学习教程-2-Mapper XML 配置

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
MyBatis 3 - User Guide
12
o
mappers
properties 元素
它们都是外部化，可替代的属性。可以配置在一个典型的 Java 属性文件中，或者通过
properties 元素的子元素进行配置。例如：
<properties resource="org/mybatis/example/config.properties">
<property name="username" value="dev_user"/>
<property name="password" value="F2Fa3!33TYyg"/>
</properties>
</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 元素中的相应值。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 元素主体中指定的属性。
MyBatis 3 - User Guide
13
Settings 元素
Setting 元素下是些非常重要的设置选项，用于设置和改变 MyBatis 运行中的行为。下面的
表格列出了Setting 元素支持的属性、默认值及其功能。
一个 Settings 元素完整的配置例子如下：
<settings>
<setting name="cacheEnabled" value="true"/>
<setting name="lazyLoadingEnabled" value="true"/>
设置选项
描述
可用值
默认值
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)
MyBatis 3 - User Guide
14
<setting name="multipleResultSetsEnabled" value="true"/>
<setting name="useColumnLabel" value="true"/>
<setting name="useGeneratedKeys" value="false"/>
<setting name="enhancementEnabled" value="false"/>
<setting name="defaultExecutorType" value="SIMPLE"/>
<setting name="defaultStatementTimeout" value="25000"/>
</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>
在这个配置中，您就可以在想要使用"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
MyBatis 3 - User Guide
15
typeHandlers 元素
每当 MyBatis 设置参数到 PreparedStatement 或者从 ResultSet 结果集中取得值时，就会使
用 TypeHandler 来处理数据库类型与 java 类型之间转换。下表描述了默认的 TypeHandlers。
bigdecimal
BigDecimal
object
Object
Map
Map
hashmap
HashMap
List
List
arraylist
ArrayList
collection
Collection
iterator
Iterator
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 兼容的类型，储存
的是编码而不是索引。
MyBatis 3 - User Guide
16
您能够重写类型处理器（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
<typeHandlers>
<typeHandler javaType="String" jdbcType="VARCHAR"
handler="org.mybatis.example.ExampleTypeHandler"/>
</typeHandlers>
使用上面的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(
MyBatis 3 - User Guide
17
Class type,
List<Class> constructorArgTypes,
List<Object> constructorArgs) {
return super.create(type, constructorArgTypes, constructorArgs);
}
public void setProperties(Properties properties) {
super.setProperties(properties);
}
}
// MapperConfig.xml
<objectFactory type="org.mybatis.example.ExampleObjectFactory">
<property name="someProperty" value="100"/>
</objectFactory>
ObjectFactory 接口非常简单，它包含两个create 的方法，一个是默认构造器，还有一个是
含参数的构造器。最后的 setProperties 方法用来配置 ObjectFactory。在初始化您自己的
ObjectFactory 实例之后，定义在 objectFactory 元素主体中的属性会以参数的形式传递给
setProperties 方法。
Plugins 元素
MyBatis 允许您在映射语句执行的某些点拦截方法调用。默认情况下，MyBatis 允许插件
（plug-ins）拦截下面的方法：
•
Executor
(update, query, flushStatements, commit, rollback, getTransaction, close,
isClosed)
•
ParameterHandler
(getParameterObject, setParameters)
•
ResultSetHandler
(handleResultSets, handleOutputParameters)
•
StatementHandler
(prepare, parameterize, batch, update, query)
通过寻找完整的方法特征能够发现这些类方法的细节，以及在每个 MyBatis 发布版本中的源
代码中找到。假如您要做的不仅仅是监视方法的调用情况，您就应该清楚您将重写的方法的行为
动作。如果您试图修改或者重写给定的方法，您很可能会改变 MyBatis 的核心行为。这些都是比
较底层的类和方法，所以要小心使用插件。
// ExamplePlugin.java
@Intercepts({@Signature(
type= Executor.class,
method = "update",
MyBatis 3 - User Guide
18
args = {MappedStatement.class,Object.class})})
public class ExamplePlugin implements Interceptor {
public Object intercept(Invocation invocation) throws Throwable {
return invocation.proceed();
}
public Object plugin(Object target) {
return Plugin.wrap(target, this);
}
public void setProperties(Properties properties) {
}
}
// MapperConfig.xml
<plugins>
<plugin interceptor="org.mybatis.example.ExamplePlugin">
<property name="someProperty" value="100"/>
</plugin>
</plugins>
上面定义的插件将会拦截所有对 Executor 实例 update 方法的调用。Executor 实例是一个负
责底层映射语句执行的内部对象。
重写配置类（Configuration Class）
除了能用插件方式修改MyBatis 的核心行为，您也可以完全重写配置类（Configuration
Class）。简单地扩展它和重写内部的任何方法，然后作为参数传递给
sqlSessionFactoryBuilder.build(myConfig)方法。再次提醒，这可能对MyBatis 行为产生严重
影响，因此要小心。
Environments 元素
MyBatis 能够配置多套运行环境，这有助于将您的SQL 映射到多个数据库上。例如，在您的
开发、测试、生产环境中，您可能有不同的配置。或者您可能有多个共享同一 schema 的生产用数
据库，或者您想将相同的 SQL 映射应用到两个数据库等等许多用例。
但是请记住：虽然您可以配置多个运行环境，但是每个SqlSessionFactory 实例只能选择一
个运行环境。
因此，如果您想连接两个数据库，就需要创建两个 SqlSessionFactory 实例，一个数据库对
应一个SqlSessionFactory 实例。如果是三个数据库，那就创建三个实例，如此类推。这真的非
常容易记住：
� 每个数据库对应一个SqlSessionFactory 实例。
要指定哪个运行环境被创建，只需要简单地将运行环境作为可选参数传递给
SqlSessionFactoryBuilder，下面是两个接受运行环境的方法：
MyBatis 3 - User Guide
19
SqlSessionFactory
factory = sqlSessionFactoryBuilder.build(reader,
environment);
SqlSessionFactory
factory = sqlSessionFactoryBuilder.build(reader,
environment,properties);
如果环境参数被忽略，那默认的环境配置将被加载，如下面：
SqlSessionFactory
factory = sqlSessionFactoryBuilder.build(reader);
SqlSessionFactory
factory =
sqlSessionFactoryBuilder.build(reader,properties);
environments 元素定义了运行环境是怎么配置的：
<environments default="development">
<environment id="development">
<transactionManager type="JDBC">
<property name="..." value="..."/>
</transactionManager>
<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>
注意这里关键的部分：
•
默认的运行环境 ID，引用一个已经定义好的运行环境 ID（例如：
default=“development”）
•
每个定义的运行环境 ID（例如：id=“development”）
•
事务管理器配置(例如： type=“JDBC”)
•
数据源配置(例如：type=“POOLED”)
默认的环境和环境 ID 是自解（self explanatory）的，只要您喜欢，就可以随意取一个名
字，只要确保默认的运行环境引用一个已定义的运行环境就可以了。
译者注：
<environments default="test">
<environment id="development">
……
</environment>
<environment id="production">
MyBatis 3 - User Guide
20
事务管理器
MyBatis 有两种事务管理类型（即 type=”[JDBC|MANAGED]”）：
•
JDBC – 这个配置直接使用 JDBC 的提交和回滚功能。它依赖于从数据源获得连接来管理
事务的生命周期。
•
MANAGED
– 这个配置基本上什么都不做。它从不提交或者回滚一个连接的事务。而是让
容器（例如：Spring 或者 J2EE 应用服务器）来管理事务的生命周期 。默认情况下，它
会关闭连接，但是一些容器并不会如此，因此，如果您需要通过关闭连接来停止事务，将
属性 closeConnection 设置为false。例如：
<transactionManager type="MANAGED">
<property name="closeConnection" value="false"/>
</transactionManager>
这两个事务管理类型都不需要任何属性。然而它们都是类型别名，换句话说，您可以设置成
指向己实现了 TransactionFactory 接口的完整类名或者别名。
public interface TransactionFactory {
void setProperties(Properties props);
Transaction newTransaction(Connection conn, boolean autoCommit);
}
实例化后，任何在 XML 文件配置的属性都将传递给setProperties()方法。在您的实现中还
需要创建一个非常简单的 Transaction 接口的实现：
public interface Transaction {
Connection getConnection();
void commit() throws SQLException;
void rollback() throws SQLException;
void close() throws SQLException;
}
……
</environment>
<environment id="test">
……
</environment>
</environments>
上面例子中，<environments default="test">配置表明，目前使用的是 test 的运行环境。
当然，您也可以修改为使用 production的运行环境：<environments default="production">。
MyBatis 3 - User Guide
21
通过这两个接口，您能够完全自定义 MyBatis 如何来处理事务。
dataSource 元素
dataSource 元素使用标准的JDBC 数据源接口来配置 JDBC 连接对象源。
� 大部分MyBatis 应用都像上面例子那样配置一个数据源，但这不是必须的。需要认清的
是，只有使用了延迟加载才需要数据源。
MyBatis 内置了三种数据源类型 (如： type=”????”):
UNPOOLED
–
这个类型的数据源实现只是在每次需要的时候简单地打开和关闭连接。虽然有点
慢，但是对于不需要立即响应的简单的应用来说，不失为一种好的选择。不同的数据库在性能方
面也会有所不同，因此对于一些数据库，不使用连接池时，这个配置就是比较理想的。
UNPOOLED 数据源有四个配置属性：
•
driver – 指定JDBC 驱动器。
•
url – 连接数据库实例的 JDBC URL。
•
username –登陆数据库的用户名。
•
password
- 登陆数据库的密码。
•
defaultTransactionIsolationLevel – 指定连接的默认事务隔离级别。
另外，您也可以通过在属性前加前缀“driver”的方式，把属性传递给数据库驱动器，例
如：
•
driver.encoding=UTF8
这将会通过 DriverManager.getConnection(url, driverProperties) 方法，将值是
“UTF8”的属性“encoding”传递给数据库驱动器。
POOLED – 这个数据源的实现缓存了JDBC 连接对象，用于避免每次创建新的数据库连接时都初始
化和进行认证，加快程序响应。并发 WEB 应用通常通过这种做法来获得快速响应。
另外，除了上面(UNPOOLED)的属性外，对 POOLED 数据源，还有很多属性可以设置。
•
poolMaximumActiveConnections – 在任何特定的时间内激活（能够被使用）的连接数
量，默认是 10。
•
poolMaximumIdleConnections –在任何特定的时间内空闲的连接数。
MyBatis 3 - User Guide
22
•
poolMaximumCheckoutTime – 在连接池被强行返回前，一个连接能够“检出”的总时
间。默认是 20000ms（20 秒）。
•
poolTimeToWait – 这是一上比较底层的设置，如果连接占用了很长时间，能够给连接池
一个机会去打印日志，并重新尝试连接。默认是20000ms（20 秒）。
•
poolPingQuery –Ping Query 是发送给数据库的 Ping 信息，测试数据库连接是否良好
和是否准备好了接受请求。默认值是“NO PING QUERY SET”，让大部分数据库都不使用
Ping，返回一个友好的错误信息（译者注：MyBatis 通过向数据执行 SQL 语句来确定与数
据库连接状况）。
•
poolPingEnabled – 这是允许或者禁 ping query 的开关。如果允许，您同时也要用一
条可用的（并且应该是最高效的）SQL 语句来设置poolPingQuery 属性的值。默认是：
false（即禁止）。
•
poolPingConnectionsNotUsedFor – 这个属性配置执行 poolPingQuery 的间隔时间。通
常设置为与数据库连接的超时时间，来避免不必要的 pings 。默认是：0（允许所有连接
随时进行 ping 测试，当然只有poolPingEnabled 设置为true 才会生效）。
JNDI – 这个数据源的配置是为了准备与像 Spring 或应用服务器能够在外部或者内部配置数据
源的容器一起使用，然后在JNDI 上下文中引用它。这个数据源只需配置两个属性：
•
initial_context
– 这个属性被用来从 InitialContext 中查找一个上下文。如：
initialContext.lookup(initial_context)
这个属性是可选的，如果忽略，那么数据源就会直接从InitialContext 中查找。
•
data_source – 这个属性是引用一个能够被找到的数据源实例的上下文路径。它会查找
根据 initial_context 从 initialContext 中搜寻返回的上下文。或者在
initial_context 没有提供的情况下直接在 InitialContext 中进行查找。
译者注：
Context context = (Context) initialContext.lookup(initial_context);//返回
一个上下文
//Context context = (Context)initContext.lookup("java:/comp/env");
DataSource ds = (DataSource) context.lookup(data_source); //返回一个数据源
Connection conn = ds.getConnection();
//DataSource ds = (DataSource)context.lookup("jdbc/myoracle");
MyBatis 3 - User Guide
23
跟数据源的其它属性配置一样，可以通过在属性名前加“env.”的方式直接传递给
InitialContext。例如：
•
env.encoding=UTF8
这将会把属性“encoding”及它的值“UTF8”在 InitialContext 实例化的时候传递给它的构
造器。
Mappers 元素
现在，MyBatis 的行为属性都已经在上面的配置元素中配置好了，接下来开始定义映射SQL
语句。但首先，我们需要告诉 MyBatis 在哪里能够找到我们定义的映射 SQL 语句。在这方面，
JAVA 自动发现没有提供好的方法，因此最好的方法是告诉MyBatis 在哪里能够找到这些映射文
件。您可以使用类资源路径或者URL（包括 file:/// URLs），例如：
// Using classpath relative resources
<mappers>
<mapper resource="org/mybatis/builder/AuthorMapper.xml"/>
<mapper resource="org/mybatis/builder/BlogMapper.xml"/>
<mapper resource="org/mybatis/builder/PostMapper.xml"/>
</mappers>
// Using url fully qualified paths
<mappers>
<mapper url="file:///var/sqlmaps/AuthorMapper.xml"/>
<mapper url="file:///var/sqlmaps/BlogMapper.xml"/>
<mapper url="file:///var/sqlmaps/PostMapper.xml"/>
</mappers>
这些配置告诉 MyBatis 在哪里找到SQL 映射文件。而其它的更详细的信息配置在每一个SQL
映射文件里。这些将在下一章节里讨论