1 Mapper XML

• select
• insert, update and delete
• sql
• Parameters
• Result Maps
• Auto-mapping
• cache

2 cache

MyBatis includes a powerful transactional query caching feature which is very configurable and customizable. A lot of changes have been made in the MyBatis 3 cache implementation to make it both more powerful and far easier to configure.
MyBatis 包含一个强大的事务性查询缓存特性，它是可配置和可自定义的。MyBatis 3 中的缓存实现有了很多改进以使它更强大的同时也更加易于配置。

2.1 默认的 Cache

By default, just local session caching is enabled that is used solely to cache data for the duration of a session.
默认情况下，只有本地会话缓存是开启的，它仅仅被用来为一个会话期间的数据进行缓存。

2.1.1 开启二级缓存

To enable a global second level of caching you simply need to add one line to your SQL Mapping file:
想要开启全局二级缓存你只需要简单地在你的 SQL 映射文件中添加一行：

<cache/>

这条简单语句的效果如下：

• All results from select statements in the mapped statement file will be cached.
  所有在这个映射文件中的 select 语句执行的结果都将被缓存。

• All insert, update and delete statements in the mapped statement file will flush the cache.
  所有在这个映射文件中的insert、update、delete 语句都会被刷新缓存。

• The cache will use a Least Recently Used (LRU) algorithm for eviction.
  缓存将会使用最近最少使用（LRU）算法来收回。

• The cache will not flush on any sort of time based schedule (i.e. no Flush Interval).
  根据时间表，缓存不会以任何时间顺序来刷新（如 no Flush Interval，无刷新间隔）。

• The cache will store 1024 references to lists or objects (whatever the query method returns).
  缓存将会存储 1024 个列表或对象的引用（无论查询语句返回什么）。

• The cache will be treated as a read/write cache, meaning objects retrieved are not shared and can be safely modified by the caller, without interfering with other potential modifications by other callers or threads.
  缓存将被视为 read/write （可读/可写），意味着对象获取不会被共享，可以安全地被调用者修改，而不干扰其他调用者或线程潜在的修改。

NOTE The cache will only apply to statements declared in the mapping file where the cache tag is located. If you are using the Java API in conjunction with the XML mapping files, then statements declared in the companion interface will not be cached by default. You will need to refer to the cache region using the @CacheNamespaceRef annotation.
注意：缓存将只作用于在使用 cache 标签声明它的映射文件中的语句。如果你一起使用 Java API 和 XML 映射文件，声明在对应接口中的语句默认将不会被缓存。你将需要使用 @CacheNamespaceRef 注解来引用缓存域。

2.1.2 cache 的属性

All of these properties are modifiable through the attributes of the cache element. For example:
所有这些属性都可以通过 cache 元素的属性来修改。

<cache
  eviction="FIFO"
  flushInterval="60000"
  size="512"
  readOnly="true"/>

This more advanced configuration creates a FIFO cache that flushes once every 60 seconds, stores up to 512 references to result objects or lists, and objects returned are considered read-only, thus modifying them could cause conflicts between callers in different threads.
这一更高级的配置创建了一个 FIFO 缓存，它会每隔 60 秒刷新一次，最多存储 512 个结果列表或对象的引用，返回对象是只读的，因此修改它们可能导致不同线程中的调用者之间的冲突。

• eviction（回收策略）

  • LRU – Least Recently Used: Removes objects that haven't been used for the longst period of time.
    LRU（最近最少使用）：移除最长时间不被使用的对象。

  • FIFO – First In First Out: Removes objects in the order that they entered the cache.
    FIFO（先进先出）：按照进入缓存的顺序来移除对象。

  • SOFT – Soft Reference: Removes objects based on the garbage collector state and the rules of Soft References.
    SOFT（软引用）：基于垃圾回收器状态和软引用规则来回收对象。

  • WEAK – Weak Reference: More aggressively removes objects based on the garbage collector state and rules of Weak References.
    WEAK（弱引用）：基于垃圾回收器状态和弱引用规则更加积极地移除对象。

    The default is LRU.
    默认值为 LRU。

• flushInterval（刷新间隔）
  The flushInterval can be set to any positive integer and should represent a reasonable amount of time specified in milliseconds. The default is not set, thus no flush interval is used and the cache is only flushed by calls to statements.
  flushInterval（刷新间隔）可以设置为任意的正整数，而且应该设置一个合理的毫秒数。默认是未设置的，即无刷新间隔，缓存只有在调用语句的时候才会被刷新。

• size（引用数目）
  The size can be set to any positive integer, keep in mind the size of the objects your caching and the available memory resources of your environment. The default is 1024.
  size（引用数目）可以设置为任意的正整数，要记住缓存对象的数目和运行环境的可用内存资源。默认值是 1024。

• readOnly（是否只读）
  The readOnly attribute can be set to true or false. A read-only cache will return the same instance of the cached object to all callers. Thus such objects should not be modified. This offers a significant performance advantage though. A read-write cache will return a copy (via serialization) of the cached object. This is slower, but safer, and thus the default is false.
  readOnly 属性可以被设置为 true 或 false。一个只读的缓存将会给所有的调用者返回缓存对象的相同实例。因此这些对象不能被修改，这提供了一个很重要的性能优势。一个可读写缓存将会返回缓存对象的一个副本（通过序列化）。这会慢一些，但是更加安全，因此 readOnly 的默认值为 false。

NOTE Second level cache is transactional. That means that it is updated when a SqlSession finishes with commit or when it finishes with rollback but no inserts/deletes/updates with flushCache=true where executed.
注意：二级缓存是事务性的。这意味着当一个 SqlSession 提交完成时，或者回滚完成且没有执行设置了 flushCache=true 的 insert/delete/update 语句时，它才会被修改。

2.2 自定义 Cache

In addition to customizing the cache in these ways, you can also completely override the cache behavior by implementing your own cache, or creating an adapter to other 3rd party caching solutions.
除了用这些方式定制缓存外，你也可以通过实现你自己的缓存，或为其他第三方缓存解决方案创建一个适配器来完全覆盖缓存的行为。

<cache type="com.domain.something.MyCustomCache"/>

This example demonstrates how to use a custom cache implementation. The class specified in the type attribute must implement the org.apache.ibatis.cache.Cache interface and provide a constructor that gets an String id as an argument. This interface is one of the more complex in the MyBatis framework, but simple given what it does.
这个例子展示了如何使用一个自定义的缓存实现。在 type 属性中指定的类必须实现 org.apache.ibatis.cache.Cache 接口并提供一个带 String 参数的构造方法。这个接口是 MyBatis 框架中复杂的接口之一，但它的作用是简单的。

public interface Cache {
  String getId();
  int getSize();
  void putObject(Object key, Object value);
  Object getObject(Object key);
  boolean hasKey(Object key);
  Object removeObject(Object key);
  void clear();
}

To configure your cache, simply add public JavaBeans properties to your Cache implementation, and pass properties via the cache Element, for example, the following would call a method called setCacheFile(String file) on your Cache implementation:
要想配置你的缓存，只需要简单地添加公有的 JavaBean 属性到你的 Cache 实现中，并且通过 cache 元素传递属性即可，例如，下面这个例子会在你的缓存实现中调用一个 setCacheFile(String file) 方法。

<cache type="com.domain.something.MyCustomCache">
  <property name="cacheFile" value="/tmp/my-custom-cache.tmp"/>
</cache>

You can use JavaBeans properties of all simple types, MyBatis will do the conversion. And you can specify a placeholder(e.g. &{cache.file}) to replace value defined at configuration properties.
你可以使用任何简单类型的 JavaBean 的属性，MyBatis 将进行转换。你可以指定一个占位符（如 ${cache.file}）来替代 configuration 中的 properties 配置（参见 Mybatis Doc 2.1：Configuration 之 Properties）。

Since 3.4.2, the MyBatis has been supported to call an initialization method after it's set all properties. If you want to use this feature, please implements the org.apache.ibatis.builder.InitializingObject interface on your custom cache class.
从 3.4.2 开始，MyBatis已经能够支持在所有属性设置后调用一个初始化方法。如果你想使用这个特性，请在你自定义的 cache 类中实现 org.apache.ibatis.builder.InitializingObject 接口。

public interface InitializingObject {
  void initialize() throws Exception;
}

NOTE Settings of cache (like eviction strategy, read write..etc.) in section above are not applied when using Custom Cache.
注意：缓存的设置（像回收策略，可读可写等）在使用自定义缓存时是不可用的。

It's important to remember that a cache configuration and the cache instance are bound to the namespace of the SQL Map file. Thus, all statements in the same namespace as the cache are bound by it. Statements can modify how they interact with the cache, or exclude themselves completely by using two simple attributes on a statement-by-statement basis. By default, statements are configured like this:
一定要记住的是，一个缓存配置和缓存实例是绑定到 SQL 映射文件的命名空间的。因此，同一命名空间的语句和缓存通过命名空间绑定在一起。语句可以修改与缓存交互的方式，或者在语句的语句基础上通过使用两个简单的属性来完全排除它们。默认情况下，语句像这样被配置：

<select ... flushCache="false" useCache="true"/>
<insert ... flushCache="true"/>
<update ... flushCache="true"/>
<delete ... flushCache="true"/>

Since that's the default, you obviously should never explicitly configure a statement that way. Instead, only set the flushCache and useCache attributes if you want to change the default behavior.
因为这是默认的，你就不用再像这样显式地配置一条语句。相反地，如果你想要改变默认的行为，只能设置 flushCache 和 useCache 属性。

For example, in some cases you may want to exclude the results of a particular select statement from the cache, or you might want a select statement to flush the cache. Similarly, you may have some update statements that don't need to flush the cache upon execution.
例如，在某些情况下，你可能会想要从缓存中排除特定的查询语句的结果，或者你可能想要某个 select 语句来刷新缓存。同样地，你可能执行一些不需要刷新缓存的 update 语句。

2.3 cache-ref

Recall from the previous section that only the cache for this particular namespace will be used or flushed for statements within the same namespace.
回忆前面我们所讲的，只有这个特定命名空间的缓存会被在同一个命名空间的语句使用或者刷新。

There may come a time when you want to share the same cache configuration and instance between namespaces. In such cases you can reference another cache by using the cache-ref element.
也许在将来的某个时候你会想要在命名空间之间共享相同的缓存配置和缓存实例。在这些情况下，你可以通过使用 cache-ref 元素来引用另一个缓存。

<cache-ref namespace="com.someone.application.data.SomeMapper"/>

最后

说明：MyBatis 官网提供了简体中文的翻译，但个人觉得较为生硬，甚至有些地方逻辑不通，于是自己一个个重新敲着翻译的（都不知道哪里来的自信...），有些地方同官网翻译有出入，有些倔强地保留了自己的，有的实在别扭则保留了官网的，这些都会在实践中一一更正。鉴于个人英文能力有限，文章中保留了官方文档原英文介绍（个别地方加以调整修剪），希望有缘看到这里的朋友们能够有自己的理解，不会被我可能错误或不合理的翻译带跑偏(〃'▽'〃)，欢迎指正！

当前版本：mybatis-3.5.0
官网文档：MyBatis
官网翻译：MyBatis 简体中文
项目实践：MyBatis Learn