我們已經(jīng)討論過如何配置 MyBatis 和創(chuàng)建映射文件了坛善。MyBatis 的 Java API 就是你收獲你所做的努力的地方天梧。正如你即將看到的，和 JDBC 相比冰蘑，MyBatis 很大程度簡化了你的代碼并保持代碼簡潔目锭，容易理解并維護(hù)评汰。MyBatis 3 已經(jīng)引入了很多重要的改進(jìn)來使得 SQL 映射更加優(yōu)秀。

SqlSessions

使用 MyBatis 的主要 Java 接口就是 SqlSession痢虹。你可以通過這個接口來執(zhí)行命令被去，獲取映射器和管理事務(wù)。我們會概括討論一下 SqlSession 本身奖唯，但是首先我們還是要了解如何獲取一個 SqlSession 實(shí)例惨缆。SqlSessions 是由 SqlSessionFactory 實(shí)例創(chuàng)建的。SqlSessionFactory 對象包含創(chuàng)建 SqlSession 實(shí)例的所有方法。而 SqlSessionFactory 本身是由 SqlSessionFactoryBuilder 創(chuàng)建的踪央，它可以從 XML臀玄、注解或手動配置 Java 代碼來創(chuàng)建 SqlSessionFactory。

注意?當(dāng) Mybatis 與一些依賴注入框架（如 Spring 或者 Guice）同時使用時畅蹂，SqlSessions 將被依賴注入框架所創(chuàng)建健无，所以你不需要使用 SqlSessionFactoryBuilder 或者 SqlSessionFactory，可以直接看 下面的SqlSession 這部分液斜。

SqlSessionFactoryBuilder

SqlSessionFactoryBuilder 有五個 build() 方法累贤，每一種都允許你從不同的資源中創(chuàng)建一個 SqlSession 實(shí)例。

第一種方法是最常用的少漆，它使用了一個參照了 XML 文檔或上面討論過的更特定的 mybatis-config.xml 文件的 Reader 實(shí)例臼膏。可選的參數(shù)是 environment 和 properties示损。environment 決定加載哪種環(huán)境渗磅，包括數(shù)據(jù)源和事務(wù)管理器。比如：

如果你調(diào)用了參數(shù)有 environment 的 build 方法检访，那么 MyBatis 將會使用 configuration 對象來配置這個 environment始鱼。當(dāng)然，如果你指定了一個不合法的 environment脆贵，你就會得到錯誤提示医清。如果你調(diào)用了不帶 environment 參數(shù)的 build 方法，那么就使用默認(rèn)的 environment（在上面的示例中指定為 default="development" 的代碼）卖氨。

如果你調(diào)用了參數(shù)有 properties 實(shí)例的方法会烙，那么 MyBatis 就會加載那些 properties（屬性配置文件），并在配置中可用筒捺。那些屬性可以用${propName} 語法形式多次用在配置文件中柏腻。

回想一下，屬性可以從 mybatis-config.xml 中被引用系吭，或者直接指定它葫盼。因此理解優(yōu)先級是很重要的。我們在文檔前面已經(jīng)提及它了村斟，但是這里要再次重申贫导，如果一個屬性存在于這些位置，那么 MyBatis 將會按照下面的順序來加載它們：

首先讀取在 properties 元素體中指定的屬性蟆盹；

其次孩灯，讀取從 properties 元素的類路徑 resource 或 url 指定的屬性，且會覆蓋已經(jīng)指定了的重復(fù)屬性逾滥；

最后峰档，讀取作為方法參數(shù)傳遞的屬性败匹，且會覆蓋已經(jīng)從 properties 元素體和 resource 或 url 屬性中加載了的重復(fù)屬性。

因此讥巡，通過方法參數(shù)傳遞的屬性的優(yōu)先級最高掀亩，resource 或 url 指定的屬性優(yōu)先級中等，在 properties 元素體中指定的屬性優(yōu)先級最低欢顷。

總結(jié)一下槽棍，前四個方法很大程度上是相同的，但是由于覆蓋機(jī)制抬驴，便允許你可選地指定 environment 和/或 properties炼七。以下給出一個從 mybatis-config.xml 文件創(chuàng)建 SqlSessionFactory 的示例：

注意到這里我們使用了 Resources 工具類，這個類在 org.apache.ibatis.io 包中布持。Resources 類正如其名豌拙，會幫助你從類路徑下、文件系統(tǒng)或一個 web URL 中加載資源文件题暖“锤担看一下這個類的源代碼或者通過你的 IDE 來查看，就會看到一整套相當(dāng)實(shí)用的方法胧卤。這里給出一個簡表：

最后一個 build 方法的參數(shù)為 Configuration 實(shí)例唯绍。configuration 類包含你可能需要了解 SqlSessionFactory 實(shí)例的所有內(nèi)容。Configuration 類對于配置的自查很有用灌侣，它包含查找和操作 SQL 映射（當(dāng)應(yīng)用接收請求時便不推薦使用）。作為一個 Java API 的 configuration 類具有所有配置的開關(guān)裂问，這些你已經(jīng)了解了侧啼。這里有一個簡單的示例，教你如何手動配置 configuration 實(shí)例堪簿，然后將它傳遞給 build() 方法來創(chuàng)建 SqlSessionFactory痊乾。

通過上面的方法你就獲得一個可以用來創(chuàng)建 SqlSession 實(shí)例的 SqlSessionFactory 了！

SqlSessionFactory

SqlSessionFactory 有六個方法創(chuàng)建 SqlSession 實(shí)例椭更。通常來說哪审，當(dāng)你選擇這些方法時你需要考慮以下幾點(diǎn)：

事務(wù)處理：我需要在 session 使用事務(wù)或者使用自動提交功能（auto-commit）嗎？（通常意味著很多數(shù)據(jù)庫和/或 JDBC 驅(qū)動沒有事務(wù)）

連接：我需要依賴 MyBatis 獲得來自數(shù)據(jù)源的配置嗎虑瀑？還是使用自己提供的配置湿滓？

執(zhí)行語句：我需要 MyBatis 復(fù)用預(yù)處理語句和/或批量更新語句（包括插入和刪除）嗎？

基于以上需求舌狗，有下列已重載的多個 openSession() 方法供使用叽奥。

默認(rèn)的 openSession()方法沒有參數(shù)，它會創(chuàng)建有如下特性的 SqlSession：

會開啟一個事務(wù)（也就是不自動提交）痛侍。

將從由當(dāng)前環(huán)境配置的 DataSource 實(shí)例中獲取 Connection 對象朝氓。

事務(wù)隔離級別將會使用驅(qū)動或數(shù)據(jù)源的默認(rèn)設(shè)置。

預(yù)處理語句不會被復(fù)用，也不會批量處理更新赵哲。

這些方法大都是可讀性強(qiáng)的待德。向?autoCommit?可選參數(shù)傳遞?true?值即可開啟自動提交功能。若要使用自己的?Connection?實(shí)例枫夺，傳遞一個?Connection?實(shí)例給?connection?參數(shù)即可将宪。注意并未覆寫同時設(shè)置?Connection?和?autoCommit?兩者的方法，因?yàn)?MyBatis 會使用正在使用中的筷屡、設(shè)置了 Connection 的環(huán)境涧偷。MyBatis 為事務(wù)隔離級別調(diào)用使用了一個 Java 枚舉包裝器，稱為?TransactionIsolationLevel毙死，若不使用它燎潮，將使用 JDBC 所支持五個隔離級（NONE、READ_UNCOMMITTED扼倘、READ_COMMITTED确封、REPEATABLE_READ?和?SERIALIZABLE），并按它們預(yù)期的方式來工作再菊。

還有一個可能對你來說是新見到的參數(shù)爪喘，就是?ExecutorType。這個枚舉類型定義了三個值:

ExecutorType.SIMPLE：這個執(zhí)行器類型不做特殊的事情纠拔。它為每個語句的執(zhí)行創(chuàng)建一個新的預(yù)處理語句秉剑。

ExecutorType.REUSE：這個執(zhí)行器類型會復(fù)用預(yù)處理語句。

ExecutorType.BATCH：這個執(zhí)行器會批量執(zhí)行所有更新語句稠诲，如果 SELECT 在它們中間執(zhí)行侦鹏，必要時請把它們區(qū)分開來以保證行為的易讀性。

注意?在 SqlSessionFactory 中還有一個方法我們沒有提及臀叙，就是 getConfiguration()略水。這 個方法會返回一個 Configuration 實(shí)例，在運(yùn)行時你可以使用它來自檢 MyBatis 的配置劝萤。

注意?如果你使用的是 MyBatis 之前的版本渊涝，你要重新調(diào)用 openSession，因?yàn)榕f版本的 session床嫌、事務(wù)和批量操作是分離開來的跨释。如果使用的是新版本，那么就不必這么做了厌处，因?yàn)樗鼈儸F(xiàn)在都包含在 session 的作用域內(nèi)了煤傍。你不必再單獨(dú)處理事務(wù)或批量操作就能得到想要的全部效果。

SqlSession

正如上面所提到的嘱蛋，SqlSession 實(shí)例在 MyBatis 中是非常強(qiáng)大的一個類蚯姆。在這里你會看到所有執(zhí)行語句五续、提交或回滾事務(wù)和獲取映射器實(shí)例的方法。在 SqlSession 類中有超過 20 個方法龄恋，所以將它們組合成易于理解的分組疙驾。這些方法被用來執(zhí)行定義在 SQL 映射的 XML 文件中的 SELECT、INSERT郭毕、UPDATE 和 DELETE 語句它碎。它們都會自行解釋，每一句都使用語句的 ID 屬性和參數(shù)對象显押，參數(shù)可以是原生類型（自動裝箱或包裝類）扳肛、JavaBean、POJO 或 Map乘碑。

selectOne 和 selectList 的不同僅僅是 selectOne 必須返回一個對象或 null 值挖息。如果返回值多于一個，那么就會拋出異常兽肤。如果你不知道返回對象的數(shù)量套腹，請使用 selectList。如果需要查看返回對象是否存在资铡，可行的方案是返回一個值即可（0 或 1）电禀。selectMap 稍微特殊一點(diǎn)，因?yàn)樗鼤⒎祷氐膶ο蟮钠渲幸粋€屬性作為 key 值笤休，將對象作為 value 值尖飞，從而將多結(jié)果集轉(zhuǎn)為 Map 類型值。因?yàn)椴⒉皇撬姓Z句都需要參數(shù)店雅，所以這些方法都重載成不需要參數(shù)的形式政基。

insert、update和delete方法返回的值就是受語句影響的行數(shù)底洗。

光標(biāo)提供與列表相同的結(jié)果腋么，但它使用迭代器延遲獲取數(shù)據(jù)咕娄。

最后亥揖，還有 select 方法的三個高級版本，它們允許你限制返回行數(shù)的范圍圣勒，或者提供自定義結(jié)果控制邏輯费变，這通常在數(shù)據(jù)集合龐大的情形下使用。

RowBounds 參數(shù)會告訴 MyBatis 略過指定數(shù)量的記錄圣贸，還有限制返回結(jié)果的數(shù)量挚歧。RowBounds 類有一個構(gòu)造方法來接收 offset 和 limit，另外吁峻，它們是不可二次賦值的滑负。

所以在這方面在张，不同的驅(qū)動能夠取得不同級別的高效率。為了取得最佳的表現(xiàn)矮慕，請使用結(jié)果集的 SCROLL_SENSITIVE 或 SCROLL_INSENSITIVE 的類型(換句話說：不用 FORWARD_ONLY)帮匾。

ResultHandler 參數(shù)允許你按你喜歡的方式處理每一行。你可以將它添加到 List 中痴鳄、創(chuàng)建 Map 和 Set瘟斜，或者丟棄每個返回值都可以，它取代了僅保留執(zhí)行語句過后的總結(jié)果列表的死板結(jié)果痪寻。你可以使用 ResultHandler 做很多事螺句，并且這是 MyBatis 自身內(nèi)部會使用的方法，以創(chuàng)建結(jié)果集列表橡类。從3.4.6開始蛇尚，傳遞給可調(diào)用語句的resultHandler將用于存儲過程的每個refcursor輸出參數(shù)（如果有）。它的接口很簡單猫态。

ResultContext 參數(shù)允許你訪問結(jié)果對象本身佣蓉、被創(chuàng)建的對象數(shù)目、以及返回值為 Boolean 的 stop 方法亲雪，你可以使用此 stop 方法來停止 MyBatis 加載更多的結(jié)果勇凭。使用 ResultHandler 的時候需要注意以下兩種限制：

從被 ResultHandler 調(diào)用的方法返回的數(shù)據(jù)不會被緩存。

當(dāng)使用結(jié)果映射集（resultMap）時义辕，MyBatis 大多數(shù)情況下需要數(shù)行結(jié)果來構(gòu)造外鍵對象虾标。如果你正在使用 ResultHandler，你可以給出外鍵（association）或者集合（collection）尚未賦值的對象灌砖。

有一個方法可以刷新（執(zhí)行）存儲在 JDBC 驅(qū)動類中的批量更新語句璧函。當(dāng)你將?ExecutorType.BATCH?作為?ExecutorType?使用時可以采用此方法。

List<BatchResult> flushStatements()

控制事務(wù)作用域有四個方法基显。當(dāng)然蘸吓，如果你已經(jīng)設(shè)置了自動提交或你正在使用外部事務(wù)管理器，這就沒有任何效果了撩幽。然而库继，如果你正在使用 JDBC 事務(wù)管理器，由Connection 實(shí)例來控制窜醉，那么這四個方法就會派上用場：

默認(rèn)情況下 MyBatis 不會自動提交事務(wù)宪萄，除非它偵測到有插入、更新或刪除操作改變了數(shù)據(jù)庫榨惰。如果你已經(jīng)做出了一些改變而沒有使用這些方法拜英，那么你可以傳遞 true 值到 commit 和 rollback 方法來保證事務(wù)被正常處理（注意，在自動提交模式或者使用了外部事務(wù)管理器的情況下設(shè)置 force 值對 session 無效）琅催。很多時候你不用調(diào)用 rollback()居凶，因?yàn)?MyBatis 會在你沒有調(diào)用 commit 時替你完成回滾操作虫给。然而，如果你需要在支持多提交和回滾的 session 中獲得更多細(xì)粒度控制侠碧，你可以使用回滾操作來達(dá)到目的狰右。

注意?MyBatis-Spring 和 MyBatis-Guice 提供了聲明事務(wù)處理，所以如果你在使用 Mybatis 的同時使用了Spring 或者 Guice舆床，那么請參考它們的手冊以獲取更多的內(nèi)容棋蚌。

本地緩存

Mybatis 使用到了兩種緩存：本地緩存（local cache）和二級緩存（second level cache）。

每當(dāng)一個新 session 被創(chuàng)建挨队，MyBatis 就會創(chuàng)建一個與之相關(guān)聯(lián)的本地緩存谷暮。任何在 session 執(zhí)行過的查詢語句本身都會被保存在本地緩存中，那么盛垦，相同的查詢語句和相同的參數(shù)所產(chǎn)生的更改就不會二度影響數(shù)據(jù)庫了湿弦。本地緩存會被增刪改、提交事務(wù)腾夯、關(guān)閉事務(wù)以及關(guān)閉 session 所清空颊埃。

默認(rèn)情況下，本地緩存數(shù)據(jù)可在整個 session 的周期內(nèi)使用蝶俱，這一緩存需要被用來解決循環(huán)引用錯誤和加快重復(fù)嵌套查詢的速度班利，所以它可以不被禁用掉，但是你可以設(shè)置 localCacheScope=STATEMENT 表示緩存僅在語句執(zhí)行時有效榨呆。

注意罗标，如果 localCacheScope 被設(shè)置為 SESSION，那么 MyBatis 所返回的引用將傳遞給保存在本地緩存里的相同對象积蜻。對返回的對象（例如 list）做出任何更新將會影響本地緩存的內(nèi)容闯割，進(jìn)而影響存活在 session 生命周期中的緩存所返回的值。因此竿拆，不要對 MyBatis 所返回的對象作出更改宙拉，以防后患。

你可以隨時調(diào)用以下方法來清空本地緩存：

使用完確保 SqlSession 被關(guān)閉

必須保證的最重要的事情是你要關(guān)閉所打開的任何 session丙笋。保證做到這點(diǎn)的最佳方式是下面的寫法:

注意?就像 SqlSessionFactory谢澈，你可以通過調(diào)用當(dāng)前使用中的 SqlSession 的 getConfiguration 方法來獲得 Configuration 實(shí)例：

也可以獲取映射器實(shí)例：

上述的各個 insert、update不见、delete 和 select 方法都很強(qiáng)大澳化，但也有些繁瑣崔步，可能會產(chǎn)生類型安全問題并且對于你的 IDE 和單元測試也沒有實(shí)質(zhì)性的幫助稳吮。在上面的入門章節(jié)中我們已經(jīng)看到了一個使用映射器的示例。

因此井濒，一個更通用的方式來執(zhí)行映射語句是使用映射器類灶似。一個映射器類就是一個僅需聲明與 SqlSession 方法相匹配的方法的接口類列林。下面的示例展示了一些方法簽名以及它們是如何映射到 SqlSession 上的。

總之酪惭，每個映射器方法簽名應(yīng)該匹配相關(guān)聯(lián)的 SqlSession 方法希痴，而字符串參數(shù) ID 無需匹配。相反春感，方法名必須匹配映射語句的 ID砌创。

此外，返回類型必須匹配期望的結(jié)果類型鲫懒，單返回值時為所指定類的值嫩实，多返回值時為數(shù)組或集合。所有常用的類型都是支持的窥岩，包括：原生類 型甲献、Map、POJO 和 JavaBean颂翼。

注意?映射器接口不需要去實(shí)現(xiàn)任何接口或繼承自任何類晃洒。只要方法可以被唯一標(biāo)識對應(yīng)的映射語句就可以了。映射器接口可以繼承自其他接口朦乏。當(dāng)使用 XML 來構(gòu)建映射器接口時要保證語句被包含在合適的命名空間中球及。而且，唯一的限制就是你不能在兩個繼承關(guān)系的接口中擁有相同的方法簽名（潛在的危險(xiǎn)做法不可壬胝睢）桶略。

你可以傳遞多個參數(shù)給一個映射器方法。如果你這樣做了诲宇，默認(rèn)情況下它們將會以 "param" 字符串緊跟著它們在參數(shù)列表中的位置來命名际歼，比如：#{param1}、#{param2}等姑蓝。如果你想改變參數(shù)的名稱（只在多參數(shù)情況下）鹅心，那么你可以在參數(shù)上使用 @Param("paramName") 注解。

你也可以給方法傳遞一個 RowBounds 實(shí)例來限制查詢結(jié)果纺荧。

映射器注解

因?yàn)樽畛踉O(shè)計(jì)時旭愧，MyBatis 是一個 XML 驅(qū)動的框架。配置信息是基于 XML 的宙暇，而且映射語句也是定義在 XML 中的输枯。而到了 MyBatis 3，就有新選擇了占贫。MyBatis 3 構(gòu)建在全面且強(qiáng)大的基于 Java 語言的配置 API 之上桃熄。這個配置 API 是基于 XML 的 MyBatis 配置的基礎(chǔ)，也是新的基于注解配置的基礎(chǔ)型奥。注解提供了一種簡單的方式來實(shí)現(xiàn)簡單映射語句瞳收，而不會引入大量的開銷碉京。

注意?不幸的是，Java 注解的的表達(dá)力和靈活性十分有限螟深。盡管很多時間都花在調(diào)查谐宙、設(shè)計(jì)和試驗(yàn)上，最強(qiáng)大的 MyBatis 映射并不能用注解來構(gòu)建——并不是在開玩笑界弧，的確是這樣凡蜻。比方說，C#屬性就沒有這些限制垢箕，因此 MyBatis.NET 將會比 XML 有更豐富的選擇咽瓷。也就是說，基于 Java 注解的配置離不開它的特性舰讹。

注解如下表所示：

這個例子展示了如何使用 @SelectKey 注解來在插入前讀取數(shù)據(jù)庫序列的值：

這個例子展示了如何使用 @SelectKey 注解來在插入后讀取數(shù)據(jù)庫識別列的值：

這個例子展示了如何使用?@Flush?注解去調(diào)用?SqlSession#flushStatements()：

這些例子展示了如何通過指定 @Result 的 id 屬性來命名結(jié)果集：

這個例子展示了單一參數(shù)使用 @SqlProvider 注解：

這個例子展示了多參數(shù)使用 @SqlProvider 注解：

此示例顯示providerMethodResolver的默認(rèn)實(shí)現(xiàn)的用法（自mybatis 3.5.1或更高版本以后可用）：