MyBatis3 用户指南中文版（一）

转自：http://lihui.luo.blog.163.com/blog/static/18969062010721432238/ 

 本文是《MyBatis3 用户指南》中文版，为学习与研究从《MyBatis-3-User-Guide》翻译而来，仅供读者参考，最权威的应以官方文档为准。如果发现翻译有错误，请留言指正，或者发邮件到。谢谢。

    本文翻译的内容没有版权，可任意使用，但希望使用者能注明出处。

    本翻译文档PDF版本可从百度文库里下载：

    MyBatis3 用户指南--MyBatis-3-User-Guide-zh_CN  

    http://wenku.baidu.com/view/c02aab40be1e650e52ea992c.html

 

 

 

 

 

MyBatis 3

 

中文用户指南

 Version 1.0

 

 

 

 罗利辉 译

 2010.08.01

 

 

 

 

关于从本文档复制代码的警告

其实，这不是一个什么法律警告，这仅仅是一个提示。现代文字处理器做了出色的工作，以非常优美的方式使文本具有可读性和具有良好格式化。然而，有时看起来是一个您完全想要的代码示例，也往往完全毁于插入了特殊字符。 “引号”和连字符就是一个很好的例子，在文档中看到引号和连字符，拷贝到IDE或编辑器中却不能很好工作，至少不是您期望的方式。

因此，阅读这份文档指南并享受它，希望它有助于您。当您拷贝的代码来自本文档代码示例时，最好找出附带下载的例子（包括单元测试等），或是网站或邮件列表的例子。

 

如何更好地使用本文档…

如果您发现这个文档存在任何不足，或者缺少了对某个特性的描述，最好的方式是先学习它，然后自己写一份文档。

我们接受公众撰写的文档，并通过下列网址上传：

http://opensource.atlassian.com/confluence/oss/display/IBATIS/Contribute+Documentation

如果您的文档写的很棒，人们将会喜欢您并阅读您的文档！

 

 

 

 

 

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配置，在这里我们先展示一个简单的例子：

<?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配置文件的头部，会使用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的类加载（原文：in this case, BlogMapper.xml would be loaded based on the classpath and name of 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的调用。

<?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" parameterType="int" resultType="Blog"> 

    select * from Blog where id = #{id} 

  </select> 

</mapper>

         

     这个简单的例子看起来有不少的开销，但它确实非常地轻巧，只要您喜欢，您可以在一个映射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。这样做会被视为“没品味”（bad smell）。所是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();

}