Mybatis專題一：配置文件 · JavaCook

> 文檔出自：[https://mybatis.org/mybatis-3/zh/configuration.html](https://mybatis.org/mybatis-3/zh/configuration.html) ## Mybatis專題一：配置文件 [TOC] ### XML讀取配置文件XMLConfigBuilder類 ~~~ // org.apache.ibatis.builder.xml.XMLConfigBuilder.java private void parseConfiguration(XNode root) { try { this.propertiesElement(root.evalNode("properties")); Properties settings = this.settingsAsProperties(root.evalNode("settings")); this.loadCustomVfs(settings); this.typeAliasesElement(root.evalNode("typeAliases")); this.pluginElement(root.evalNode("plugins")); this.objectFactoryElement(root.evalNode("objectFactory")); this.objectWrapperFactoryElement(root.evalNode("objectWrapperFactory")); this.reflectorFactoryElement(root.evalNode("reflectorFactory")); this.settingsElement(settings); this.environmentsElement(root.evalNode("environments")); this.databaseIdProviderElement(root.evalNode("databaseIdProvider")); this.typeHandlerElement(root.evalNode("typeHandlers")); this.mapperElement(root.evalNode("mappers")); } catch (Exception var3) { throw new BuilderException("Error parsing SQL Mapper Configuration. Cause: " + var3, var3); } } ~~~ ### 屬性（properties）這些屬性可以在外部進行配置，并可以進行動態替換。你既可以在典型的 Java 屬性文件中配置這些屬性，也可以在 properties 元素的子元素中設置。例如： ~~~ <properties resource="org/mybatis/example/config.properties"> <property name="username" value="dev_user"/> <property name="password" value="F2Fa3!33TYyg"/> </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 = new SqlSessionFactoryBuilder().build(reader, props); // ... 或者 ... SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, environment, props); ~~~ 如果一個屬性在不只一個地方進行了配置，那么，MyBatis 將按照下面的順序來加載： * 首先讀取在 properties 元素體內指定的屬性。 * 然后根據 properties 元素中的 resource 屬性讀取類路徑下屬性文件，或根據 url 屬性指定的路徑讀取屬性文件，并覆蓋之前讀取過的同名屬性。 * 最后讀取作為方法參數傳遞的屬性，并覆蓋之前讀取過的同名屬性。因此，通過方法參數傳遞的屬性具有最高優先級，resource/url 屬性中指定的配置文件次之，最低優先級的則是 properties 元素中指定的屬性。從 MyBatis 3.4.2 開始，你可以為占位符指定一個默認值。例如： ~~~ <dataSource type="POOLED">  <property name="username" value="${username:ut_user}"/>  </dataSource> ~~~ 這個特性默認是關閉的。要啟用這個特性，需要添加一個特定的屬性來開啟這個特性。例如： ~~~ <properties resource="org/mybatis/example/config.properties">  <property name="org.apache.ibatis.parsing.PropertyParser.enable-default-value" value="true"/>  </properties> ~~~ 如果你在屬性名中使用了":"字符（如：db:username），或者在 SQL 映射中使用了 OGNL 表達式的三元運算符（如：${tableName != null ? tableName : 'global\_constants'}），就需要設置特定的屬性來修改分隔屬性名和默認值的字符。例如： ~~~ <properties resource="org/mybatis/example/config.properties">  <property name="org.apache.ibatis.parsing.PropertyParser.default-value-separator" value="?:"/>  </properties> ~~~ ~~~ <dataSource type="POOLED">  <property name="username" value="${db:username?:ut_user}"/> </dataSource> ~~~ ### 設置（settings）這是 MyBatis 中極為重要的調整設置，它們會改變 MyBatis 的運行時行為。下表描述了設置中各項設置的含義、默認值等。 | 設置名 | 描述 | 有效值 | 默認值 | | --- | --- | --- | --- | | cacheEnabled | 全局性地開啟或關閉所有映射器配置文件中已配置的任何緩存。 | true | false | true | | lazyLoadingEnabled | 延遲加載的全局開關。當開啟時，所有關聯對象都會延遲加載。特定關聯關系中可通過設置fetchType屬性來覆蓋該項的開關狀態。 | true | false | false | | aggressiveLazyLoading | 開啟時，任一方法的調用都會加載該對象的所有延遲加載屬性。否則，每個延遲加載屬性會按需加載（參考lazyLoadTriggerMethods)。 | true | false | false （在 3.4.1 及之前的版本中默認為 true） | | multipleResultSetsEnabled | 是否允許單個語句返回多結果集（需要數據庫驅動支持）。 | true | false | true | | useColumnLabel | 使用列標簽代替列名。實際表現依賴于數據庫驅動，具體可參考數據庫驅動的相關文檔，或通過對比測試來觀察。 | true | false | true | | useGeneratedKeys | 允許 JDBC 支持自動生成主鍵，需要數據庫驅動支持。如果設置為 true，將強制使用自動生成主鍵。盡管一些數據庫驅動不支持此特性，但仍可正常工作（如 Derby）。 | true | false | False | | autoMappingBehavior | 指定 MyBatis 應如何自動映射列到字段或屬性。 NONE 表示關閉自動映射；PARTIAL 只會自動映射沒有定義嵌套結果映射的字段。 FULL 會自動映射任何復雜的結果集（無論是否嵌套）。 | NONE, PARTIAL, FULL | PARTIAL | | autoMappingUnknownColumnBehavior | 指定發現自動映射目標未知列（或未知屬性類型）的行為。 | NONE, WARNING, FAILING | NONE | | defaultExecutorType | 配置默認的執行器。SIMPLE 就是普通的執行器；REUSE 執行器會重用預處理語句（PreparedStatement）； BATCH 執行器不僅重用語句還會執行批量更新。 | SIMPLE REUSE BATCH | SIMPLE | | defaultStatementTimeout | 設置超時時間，它決定數據庫驅動等待數據庫響應的秒數。 | 任意正整數 | 未設置 (null) | | defaultFetchSize | 為驅動的結果集獲取數量（fetchSize）設置一個建議值。此參數只可以在查詢設置中被覆蓋。 | 任意正整數 | 未設置 (null) | | defaultResultSetType | 指定語句默認的滾動策略。（新增于 3.5.2） | FORWARD\_ONLY | SCROLL\_SENSITIVE | SCROLL\_INSENSITIVE | DEFAULT（等同于未設置） | 未設置 (null) | | safeRowBoundsEnabled | 是否允許在嵌套語句中使用分頁（RowBounds）。如果允許使用則設置為 false。 | true | false | False | | safeResultHandlerEnabled | 是否允許在嵌套語句中使用結果處理器（ResultHandler）。如果允許使用則設置為 false。 | true | false | True | | mapUnderscoreToCamelCase | 是否開啟駝峰命名自動映射，即從經典數據庫列名 A\_COLUMN 映射到經典 Java 屬性名 aColumn。 | true | false | False | | localCacheScope | MyBatis 利用本地緩存機制（Local Cache）防止循環引用和加速重復的嵌套查詢。默認值為 SESSION，會緩存一個會話中執行的所有查詢。若設置值為 STATEMENT，本地緩存將僅用于執行語句，對相同 SqlSession 的不同查詢將不會進行緩存。 | SESSION | STATEMENT | SESSION | | jdbcTypeForNull | 當沒有為參數指定特定的 JDBC 類型時，空值的默認 JDBC 類型。某些數據庫驅動需要指定列的 JDBC 類型，多數情況直接用一般類型即可，比如 NULL、VARCHAR 或 OTHER。 | JdbcType 常量，常用值：NULL、VARCHAR 或 OTHER。 | OTHER | | lazyLoadTriggerMethods | 指定對象的哪些方法觸發一次延遲加載。 | 用逗號分隔的方法列表。 | equals,clone,hashCode,toString | | defaultScriptingLanguage | 指定動態 SQL 生成使用的默認腳本語言。 | 一個類型別名或全限定類名。 | org.apache.ibatis.scripting.xmltags.XMLLanguageDriver | | defaultEnumTypeHandler | 指定 Enum 使用的默認TypeHandler。（新增于 3.4.5） | 一個類型別名或全限定類名。 | org.apache.ibatis.type.EnumTypeHandler | | callSettersOnNulls | 指定當結果集中值為 null 的時候是否調用映射對象的 setter（map 對象時為 put）方法，這在依賴于 Map.keySet() 或 null 值進行初始化時比較有用。注意基本類型（int、boolean 等）是不能設置成 null 的。 | true | false | false | | returnInstanceForEmptyRow | 當返回行的所有列都是空時，MyBatis默認返回null。當開啟這個設置時，MyBatis會返回一個空實例。請注意，它也適用于嵌套的結果集（如集合或關聯）。（新增于 3.4.2） | true | false | false | | logPrefix | 指定 MyBatis 增加到日志名稱的前綴。 | 任何字符串 | 未設置 | | logImpl | 指定 MyBatis 所用日志的具體實現，未指定時將自動查找。 | SLF4J | LOG4J | LOG4J2 | JDK\_LOGGING | COMMONS\_LOGGING | STDOUT\_LOGGING | NO\_LOGGING | 未設置 | | proxyFactory | 指定 Mybatis 創建可延遲加載對象所用到的代理工具。 | CGLIB | JAVASSIST | JAVASSIST （MyBatis 3.3 以上） | | vfsImpl | 指定 VFS 的實現 | 自定義 VFS 的實現的類全限定名，以逗號分隔。 | 未設置 | | useActualParamName | 允許使用方法簽名中的名稱作為語句參數名稱。為了使用該特性，你的項目必須采用 Java 8 編譯，并且加上\-parameters選項。（新增于 3.4.1） | true | false | true | | configurationFactory | 指定一個提供Configuration實例的類。這個被返回的 Configuration 實例用來加載被反序列化對象的延遲加載屬性值。這個類必須包含一個簽名為static Configuration getConfiguration()的方法。（新增于 3.2.3） | 一個類型別名或完全限定類名。 | 未設置 | 一個配置完整的 settings 元素的示例如下： ~~~ <settings> <setting name="cacheEnabled" value="true"/> <setting name="lazyLoadingEnabled" value="true"/> <setting name="multipleResultSetsEnabled" value="true"/> <setting name="useColumnLabel" value="true"/> <setting name="useGeneratedKeys" value="false"/> <setting name="autoMappingBehavior" value="PARTIAL"/> <setting name="autoMappingUnknownColumnBehavior" value="WARNING"/> <setting name="defaultExecutorType" value="SIMPLE"/> <setting name="defaultStatementTimeout" value="25"/> <setting name="defaultFetchSize" value="100"/> <setting name="safeRowBoundsEnabled" value="false"/> <setting name="mapUnderscoreToCamelCase" value="false"/> <setting name="localCacheScope" value="SESSION"/> <setting name="jdbcTypeForNull" value="OTHER"/> <setting name="lazyLoadTriggerMethods" value="equals,clone,hashCode,toString"/> </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> ~~~ 當這樣配置時，Blog可以用在任何使用domain.blog.Blog的地方。也可以指定一個包名，MyBatis 會在包名下面搜索需要的 Java Bean，比如： ~~~ <typeAliases> <package name="domain.blog"/> </typeAliases> ~~~ 每一個在包domain.blog中的 Java Bean，在沒有注解的情況下，會使用 Bean 的首字母小寫的非限定類名來作為它的別名。比如domain.blog.Author的別名為author；若有注解，則別名為其注解值。見下面的例子： ~~~ @Alias("author") public class Author { ... } ~~~ 下面是一些為常見的 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）中的參數或從結果集中取出一個值時，都會用類型處理器將獲取到的值以合適的方式轉換成 Java 類型。下表描述了一些默認的類型處理器。提示從 3.4.5 開始，MyBatis 默認支持 JSR-310（日期和時間 API）。 | 類型處理器 | Java 類型 | JDBC 類型 | | --- | --- | --- | | BooleanTypeHandler | java.lang.Boolean,boolean | 數據庫兼容的BOOLEAN | | ByteTypeHandler | java.lang.Byte,byte | 數據庫兼容的NUMERIC或BYTE | | ShortTypeHandler | java.lang.Short,short | 數據庫兼容的NUMERIC或SMALLINT | | IntegerTypeHandler | java.lang.Integer,int | 數據庫兼容的NUMERIC或INTEGER | | LongTypeHandler | java.lang.Long,long | 數據庫兼容的NUMERIC或BIGINT | | FloatTypeHandler | java.lang.Float,float | 數據庫兼容的NUMERIC或FLOAT | | DoubleTypeHandler | java.lang.Double,double | 數據庫兼容的NUMERIC或DOUBLE | | BigDecimalTypeHandler | java.math.BigDecimal | 數據庫兼容的NUMERIC或DECIMAL | | StringTypeHandler | java.lang.String | CHAR,VARCHAR | | ClobReaderTypeHandler | java.io.Reader | \- | | ClobTypeHandler | java.lang.String | CLOB,LONGVARCHAR | | NStringTypeHandler | java.lang.String | NVARCHAR,NCHAR | | NClobTypeHandler | java.lang.String | NCLOB | | BlobInputStreamTypeHandler | java.io.InputStream | \- | | ByteArrayTypeHandler | byte\[\] | 數據庫兼容的字節流類型 | | BlobTypeHandler | byte\[\] | BLOB,LONGVARBINARY | | DateTypeHandler | java.util.Date | TIMESTAMP | | DateOnlyTypeHandler | java.util.Date | DATE | | TimeOnlyTypeHandler | java.util.Date | TIME | | SqlTimestampTypeHandler | java.sql.Timestamp | TIMESTAMP | | SqlDateTypeHandler | java.sql.Date | DATE | | SqlTimeTypeHandler | java.sql.Time | TIME | | ObjectTypeHandler | Any | OTHER或未指定類型 | | EnumTypeHandler | Enumeration Type | VARCHAR 或任何兼容的字符串類型，用來存儲枚舉的名稱（而不是索引序數值） | | EnumOrdinalTypeHandler | Enumeration Type | 任何兼容的NUMERIC或DOUBLE類型，用來存儲枚舉的序數值（而不是名稱）。 | | SqlxmlTypeHandler | java.lang.String | SQLXML | | InstantTypeHandler | java.time.Instant | TIMESTAMP | | LocalDateTimeTypeHandler | java.time.LocalDateTime | TIMESTAMP | | LocalDateTypeHandler | java.time.LocalDate | DATE | | LocalTimeTypeHandler | java.time.LocalTime | TIME | | OffsetDateTimeTypeHandler | java.time.OffsetDateTime | TIMESTAMP | | OffsetTimeTypeHandler | java.time.OffsetTime | TIME | | ZonedDateTimeTypeHandler | java.time.ZonedDateTime | TIMESTAMP | | YearTypeHandler | java.time.Year | INTEGER | | MonthTypeHandler | java.time.Month | INTEGER | | YearMonthTypeHandler | java.time.YearMonth | VARCHAR或LONGVARCHAR | | JapaneseDateTypeHandler | java.time.chrono.JapaneseDate | DATE | 你可以重寫已有的類型處理器或創建你自己的類型處理器來處理不支持的或非標準的類型。具體做法為：實現org.apache.ibatis.type.TypeHandler接口，或繼承一個很便利的類org.apache.ibatis.type.BaseTypeHandler，并且可以（可選地）將它映射到一個 JDBC 類型。比如： ~~~ // ExampleTypeHandler.java @MappedJdbcTypes(JdbcType.VARCHAR) public class ExampleTypeHandler extends BaseTypeHandler<String> { @Override public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException { ps.setString(i, parameter); } @Override public String getNullableResult(ResultSet rs, String columnName) throws SQLException { return rs.getString(columnName); } @Override public String getNullableResult(ResultSet rs, int columnIndex) throws SQLException { return rs.getString(columnIndex); } @Override public String getNullableResult(CallableStatement cs, int columnIndex) throws SQLException { return cs.getString(columnIndex); } } ~~~ ~~~  <typeHandlers> <typeHandler handler="org.mybatis.example.ExampleTypeHandler"/> </typeHandlers> ~~~ 使用上述的類型處理器將會覆蓋已有的處理 Java String 類型的屬性以及 VARCHAR 類型的參數和結果的類型處理器。要注意 MyBatis 不會通過檢測數據庫元信息來決定使用哪種類型，所以你必須在參數和結果映射中指明字段是 VARCHAR 類型，以使其能夠綁定到正確的類型處理器上。這是因為 MyBatis 直到語句被執行時才清楚數據類型。通過類型處理器的泛型，MyBatis 可以得知該類型處理器處理的 Java 類型，不過這種行為可以通過兩種方法改變： * 在類型處理器的配置元素（typeHandler 元素）上增加一個javaType屬性（比如：javaType="String"）； * 在類型處理器的類上增加一個@MappedTypes注解指定與其關聯的 Java 類型列表。如果在javaType屬性中也同時指定，則注解上的配置將被忽略。可以通過兩種方式來指定關聯的 JDBC 類型： * 在類型處理器的配置元素上增加一個jdbcType屬性（比如：jdbcType="VARCHAR"）； * 在類型處理器的類上增加一個@MappedJdbcTypes注解指定與其關聯的 JDBC 類型列表。如果在jdbcType屬性中也同時指定，則注解上的配置將被忽略。當在ResultMap中決定使用哪種類型處理器時，此時 Java 類型是已知的（從結果類型中獲得），但是 JDBC 類型是未知的。因此 Mybatis 使用javaType=\[Java 類型\], jdbcType=null的組合來選擇一個類型處理器。這意味著使用@MappedJdbcTypes注解可以*限制*類型處理器的作用范圍，并且可以確保，除非顯式地設置，否則類型處理器在ResultMap中將不會生效。如果希望能在ResultMap中隱式地使用類型處理器，那么設置@MappedJdbcTypes注解的includeNullJdbcType=true即可。然而從 Mybatis 3.4.0 開始，如果某個 Java 類型**只有一個**注冊的類型處理器，即使沒有設置includeNullJdbcType=true，那么這個類型處理器也會是ResultMap使用 Java 類型時的默認處理器。最后，可以讓 MyBatis 幫你查找類型處理器： ~~~  <typeHandlers> <package name="org.mybatis.example"/> </typeHandlers> ~~~ 注意在使用自動發現功能的時候，只能通過注解方式來指定 JDBC 的類型。你可以創建能夠處理多個類的泛型類型處理器。為了使用泛型類型處理器，需要增加一個接受該類的 class 作為參數的構造器，這樣 MyBatis 會在構造一個類型處理器實例的時候傳入一個具體的類。 ~~~ //GenericTypeHandler.java public class GenericTypeHandler<E extends MyObject> extends BaseTypeHandler<E> { private Class<E> type; public GenericTypeHandler(Class<E> type) { if (type == null) throw new IllegalArgumentException("Type argument cannot be null"); this.type = type; } ... ~~~ EnumTypeHandler和EnumOrdinalTypeHandler都是泛型類型處理器，我們將會在接下來的部分詳細探討。 ### 處理枚舉類型若想映射枚舉類型Enum，則需要從EnumTypeHandler或者EnumOrdinalTypeHandler中選擇一個來使用。比如說我們想存儲取近似值時用到的舍入模式。默認情況下，MyBatis 會利用EnumTypeHandler來把Enum值轉換成對應的名字。 **注意EnumTypeHandler在某種意義上來說是比較特別的，其它的處理器只針對某個特定的類，而它不同，它會處理任意繼承了Enum的類。** 不過，我們可能不想存儲名字，相反我們的 DBA 會堅持使用整形值代碼。那也一樣簡單：在配置文件中把EnumOrdinalTypeHandler加到typeHandlers中即可，這樣每個RoundingMode將通過他們的序數值來映射成對應的整形數值。 ~~~  <typeHandlers> <typeHandler handler="org.apache.ibatis.type.EnumOrdinalTypeHandler" javaType="java.math.RoundingMode"/> </typeHandlers> ~~~ 但要是你想在一個地方將Enum映射成字符串，在另外一個地方映射成整形值呢？自動映射器（auto-mapper）會自動地選用EnumOrdinalTypeHandler來處理枚舉類型，所以如果我們想用普通的EnumTypeHandler，就必須要顯式地為那些 SQL 語句設置要使用的類型處理器。（下一節才開始介紹映射器文件，如果你是首次閱讀該文檔，你可能需要先跳過這里，過會再來看。） ~~~ <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <mapper namespace="org.apache.ibatis.submitted.rounding.Mapper"> <resultMap type="org.apache.ibatis.submitted.rounding.User" id="usermap"> <id column="id" property="id"/> <result column="name" property="name"/> <result column="funkyNumber" property="funkyNumber"/> <result column="roundingMode" property="roundingMode"/> </resultMap> <select id="getUser" resultMap="usermap"> select * from users </select> <insert id="insert"> insert into users (id, name, funkyNumber, roundingMode) values ( #{id}, #{name}, #{funkyNumber}, #{roundingMode} ) </insert> <resultMap type="org.apache.ibatis.submitted.rounding.User" id="usermap2"> <id column="id" property="id"/> <result column="name" property="name"/> <result column="funkyNumber" property="funkyNumber"/> <result column="roundingMode" property="roundingMode" typeHandler="org.apache.ibatis.type.EnumTypeHandler"/> </resultMap> <select id="getUser2" resultMap="usermap2"> select * from users2 </select> <insert id="insert2"> insert into users2 (id, name, funkyNumber, roundingMode) values ( #{id}, #{name}, #{funkyNumber}, #{roundingMode, typeHandler=org.apache.ibatis.type.EnumTypeHandler} ) </insert> </mapper> ~~~ 注意，這里的 select 語句必須指定resultMap而不是resultType。 ### 對象工廠（objectFactory）每次 MyBatis 創建結果對象的新實例時，它都會使用一個對象工廠（ObjectFactory）實例來完成實例化工作。默認的對象工廠需要做的僅僅是實例化目標類，要么通過默認無參構造方法，要么通過存在的參數映射來調用帶有參數的構造方法。如果想覆蓋對象工廠的默認行為，可以通過創建自己的對象工廠來實現。比如： ~~~ // ExampleObjectFactory.java public class ExampleObjectFactory extends DefaultObjectFactory { public Object create(Class type) { return super.create(type); } public Object create(Class type, List<Class> constructorArgTypes, List<Object> constructorArgs) { return super.create(type, constructorArgTypes, constructorArgs); } public void setProperties(Properties properties) { super.setProperties(properties); } public <T> boolean isCollection(Class<T> type) { return Collection.class.isAssignableFrom(type); }} ~~~ ~~~  <objectFactory type="org.mybatis.example.ExampleObjectFactory"> <property name="someProperty" value="100"/> </objectFactory> ~~~ ObjectFactory 接口很簡單，它包含兩個創建實例用的方法，一個是處理默認無參構造方法的，另外一個是處理帶參數的構造方法的。另外，setProperties 方法可以被用來配置 ObjectFactory，在初始化你的 ObjectFactory 實例后， objectFactory 元素體中定義的屬性會被傳遞給 setProperties 方法。 ### 插件（plugins） MyBatis 允許你在映射語句執行過程中的某一點進行攔截調用。默認情況下，MyBatis 允許使用插件來攔截的方法調用包括： * Executor (update, query, flushStatements, commit, rollback, getTransaction, close, isClosed) * ParameterHandler (getParameterObject, setParameters) * ResultSetHandler (handleResultSets, handleOutputParameters) * StatementHandler (prepare, parameterize, batch, update, query) 這些類中方法的細節可以通過查看每個方法的簽名來發現，或者直接查看 MyBatis 發行包中的源代碼。如果你想做的不僅僅是監控方法的調用，那么你最好相當了解要重寫的方法的行為。因為在試圖修改或重寫已有方法的行為時，很可能會破壞 MyBatis 的核心模塊。這些都是更底層的類和方法，所以使用插件的時候要特別當心。通過 MyBatis 提供的強大機制，使用插件是非常簡單的，只需實現 Interceptor 接口，并指定想要攔截的方法簽名即可。 ~~~ // ExamplePlugin.java @Intercepts({@Signature( type= Executor.class, method = "update", args = {MappedStatement.class,Object.class})}) public class ExamplePlugin implements Interceptor { private Properties properties = new Properties(); public Object intercept(Invocation invocation) throws Throwable { // implement pre processing if need Object returnObject = invocation.proceed(); // implement post processing if need return returnObject; } public void setProperties(Properties properties) { this.properties = properties; } } ~~~ ~~~  <plugins> <plugin interceptor="org.mybatis.example.ExamplePlugin"> <property name="someProperty" value="100"/> </plugin> </plugins> ~~~ 上面的插件將會攔截在 Executor 實例中所有的 “update” 方法調用，這里的 Executor 是負責執行底層映射語句的內部對象。提示**覆蓋配置類** 除了用插件來修改 MyBatis 核心行為以外，還可以通過完全覆蓋配置類來達到目的。只需繼承配置類后覆蓋其中的某個方法，再把它傳遞到 SqlSessionFactoryBuilder.build(myConfig) 方法即可。再次重申，這可能會極大影響 MyBatis 的行為，務請慎之又慎。 ### 環境配置（environments） MyBatis 可以配置成適應多種環境，這種機制有助于將 SQL 映射應用于多種數據庫之中，現實情況下有多種理由需要這么做。例如，開發、測試和生產環境需要有不同的配置；或者想在具有相同 Schema 的多個生產數據庫中使用相同的 SQL 映射。還有許多類似的使用場景。 **不過要記住：盡管可以配置多個環境，但每個 SqlSessionFactory 實例只能選擇一種環境。** 所以，如果你想連接兩個數據庫，就需要創建兩個 SqlSessionFactory 實例，每個數據庫對應一個。而如果是三個數據庫，就需要三個實例，依此類推，記起來很簡單： * **每個數據庫對應一個 SqlSessionFactory 實例** 為了指定創建哪種環境，只要將它作為可選的參數傳遞給 SqlSessionFactoryBuilder 即可。可以接受環境配置的兩個方法簽名是： ~~~ SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, environment); SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, environment, properties); ~~~ 如果忽略了環境參數，那么將會加載默認環境，如下所示： ~~~ SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader); SqlSessionFactory factory = new 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（比如：default="development"）。 * 每個 environment 元素定義的環境 ID（比如：id="development"）。 * 事務管理器的配置（比如：type="JDBC"）。 * 數據源的配置（比如：type="POOLED"）。默認環境和環境 ID 顧名思義。環境可以隨意命名，但務必保證默認的環境 ID 要匹配其中一個環境 ID。 **事務管理器（transactionManager）** 在 MyBatis 中有兩種類型的事務管理器（也就是 type="\[JDBC|MANAGED\]"）： * JDBC – 這個配置直接使用了 JDBC 的提交和回滾設施，它依賴從數據源獲得的連接來管理事務作用域。 * MANAGED – 這個配置幾乎沒做什么。它從不提交或回滾一個連接，而是讓容器來管理事務的整個生命周期（比如 JEE 應用服務器的上下文）。默認情況下它會關閉連接。然而一些容器并不希望連接被關閉，因此需要將 closeConnection 屬性設置為 false 來阻止默認的關閉行為。例如: ~~~ <transactionManager type="MANAGED"> <property name="closeConnection" value="false"/> </transactionManager> ~~~ 提示如果你正在使用 Spring + MyBatis，則沒有必要配置事務管理器，因為 Spring 模塊會使用自帶的管理器來覆蓋前面的配置。這兩種事務管理器類型都不需要設置任何屬性。它們其實是類型別名，換句話說，你可以用 TransactionFactory 接口實現類的全限定名或類型別名代替它們。 ~~~ public interface TransactionFactory { default void setProperties(Properties props) { // 從 3.5.2 開始，該方法為默認方法 // 空實現 } Transaction newTransaction(Connection conn); Transaction newTransaction(DataSource dataSource, TransactionIsolationLevel level, boolean autoCommit); } ~~~ 在事務管理器實例化后，所有在 XML 中配置的屬性將會被傳遞給 setProperties() 方法。你的實現還需要創建一個 Transaction 接口的實現類，這個接口也很簡單： ~~~ public interface Transaction { Connection getConnection() throws SQLException; void commit() throws SQLException; void rollback() throws SQLException; void close() throws SQLException; Integer getTimeout() throws SQLException; } ~~~ 使用這兩個接口，你可以完全自定義 MyBatis 對事務的處理。 **數據源（dataSource）** dataSource 元素使用標準的 JDBC 數據源接口來配置 JDBC 連接對象的資源。 * 大多數 MyBatis 應用程序會按示例中的例子來配置數據源。雖然數據源配置是可選的，但如果要啟用延遲加載特性，就必須配置數據源。有三種內建的數據源類型（也就是 type="\[UNPOOLED|POOLED|JNDI\]"）： **UNPOOLED**– 這個數據源的實現會每次請求時打開和關閉連接。雖然有點慢，但對那些數據庫連接可用性要求不高的簡單應用程序來說，是一個很好的選擇。性能表現則依賴于使用的數據庫，對某些數據庫來說，使用連接池并不重要，這個配置就很適合這種情形。UNPOOLED 類型的數據源僅僅需要配置以下 5 種屬性： * driver– 這是 JDBC 驅動的 Java 類全限定名（并不是 JDBC 驅動中可能包含的數據源類）。 * url– 這是數據庫的 JDBC URL 地址。 * username– 登錄數據庫的用戶名。 * password– 登錄數據庫的密碼。 * defaultTransactionIsolationLevel– 默認的連接事務隔離級別。 * defaultNetworkTimeout– 等待數據庫操作完成的默認網絡超時時間（單位：毫秒）。查看java.sql.Connection#setNetworkTimeout()的 API 文檔以獲取更多信息。作為可選項，你也可以傳遞屬性給數據庫驅動。只需在屬性名加上“driver.”前綴即可，例如： * driver.encoding=UTF8 這將通過 DriverManager.getConnection(url, driverProperties) 方法傳遞值為UTF8的encoding屬性給數據庫驅動。 **POOLED**– 這種數據源的實現利用“池”的概念將 JDBC 連接對象組織起來，避免了創建新的連接實例時所必需的初始化和認證時間。這種處理方式很流行，能使并發 Web 應用快速響應請求。除了上述提到 UNPOOLED 下的屬性外，還有更多屬性用來配置 POOLED 的數據源： * poolMaximumActiveConnections– 在任意時間可存在的活動（正在使用）連接數量，默認值：10 * poolMaximumIdleConnections– 任意時間可能存在的空閑連接數。 * poolMaximumCheckoutTime– 在被強制返回之前，池中連接被檢出（checked out）時間，默認值：20000 毫秒（即 20 秒） * poolTimeToWait– 這是一個底層設置，如果獲取連接花費了相當長的時間，連接池會打印狀態日志并重新嘗試獲取一個連接（避免在誤配置的情況下一直失敗且不打印日志），默認值：20000 毫秒（即 20 秒）。 * poolMaximumLocalBadConnectionTolerance– 這是一個關于壞連接容忍度的底層設置，作用于每一個嘗試從緩存池獲取連接的線程。如果這個線程獲取到的是一個壞的連接，那么這個數據源允許這個線程嘗試重新獲取一個新的連接，但是這個重新嘗試的次數不應該超過poolMaximumIdleConnections與poolMaximumLocalBadConnectionTolerance之和。默認值：3（新增于 3.4.5） * poolPingQuery– 發送到數據庫的偵測查詢，用來檢驗連接是否正常工作并準備接受請求。默認是“NO PING QUERY SET”，這會導致多數數據庫驅動出錯時返回恰當的錯誤消息。 * poolPingEnabled– 是否啟用偵測查詢。若開啟，需要設置poolPingQuery屬性為一個可執行的 SQL 語句（最好是一個速度非常快的 SQL 語句），默認值：false。 * poolPingConnectionsNotUsedFor– 配置 poolPingQuery 的頻率。可以被設置為和數據庫連接超時時間一樣，來避免不必要的偵測，默認值：0（即所有連接每一時刻都被偵測 — 當然僅當 poolPingEnabled 為 true 時適用）。 **JNDI**– 這個數據源實現是為了能在如 EJB 或應用服務器這類容器中使用，容器可以集中或在外部配置數據源，然后放置一個 JNDI 上下文的數據源引用。這種數據源配置只需要兩個屬性： * initial\_context– 這個屬性用來在 InitialContext 中尋找上下文（即，initialContext.lookup(initial\_context)）。這是個可選屬性，如果忽略，那么將會直接從 InitialContext 中尋找 data\_source 屬性。 * data\_source– 這是引用數據源實例位置的上下文路徑。提供了 initial\_context 配置時會在其返回的上下文中進行查找，沒有提供時則直接在 InitialContext 中查找。和其他數據源配置類似，可以通過添加前綴“env.”直接把屬性傳遞給 InitialContext。比如： * env.encoding=UTF8 這就會在 InitialContext 實例化時往它的構造方法傳遞值為UTF8的encoding屬性。你可以通過實現接口org.apache.ibatis.datasource.DataSourceFactory來使用第三方數據源實現： ~~~ public interface DataSourceFactory { void setProperties(Properties props); DataSource getDataSource(); } ~~~ org.apache.ibatis.datasource.unpooled.UnpooledDataSourceFactory可被用作父類來構建新的數據源適配器，比如下面這段插入 C3P0 數據源所必需的代碼： ~~~ import org.apache.ibatis.datasource.unpooled.UnpooledDataSourceFactory; import com.mchange.v2.c3p0.ComboPooledDataSource; public class C3P0DataSourceFactory extends UnpooledDataSourceFactory { public C3P0DataSourceFactory() { this.dataSource = new ComboPooledDataSource(); } } ~~~ 為了令其工作，記得在配置文件中為每個希望 MyBatis 調用的 setter 方法增加對應的屬性。下面是一個可以連接至 PostgreSQL 數據庫的例子： ~~~ <dataSource type="org.myproject.C3P0DataSourceFactory"> <property name="driver" value="org.postgresql.Driver"/> <property name="url" value="jdbc:postgresql:mydb"/> <property name="username" value="postgres"/> <property name="password" value="root"/> </dataSource> ~~~ ### 數據庫廠商標識（databaseIdProvider） MyBatis 可以根據不同的數據庫廠商執行不同的語句，這種多廠商的支持是基于映射語句中的databaseId屬性。 MyBatis 會加載帶有匹配當前數據庫databaseId屬性和所有不帶databaseId屬性的語句。如果同時找到帶有databaseId和不帶databaseId的相同語句，則后者會被舍棄。為支持多廠商特性，只要像下面這樣在 mybatis-config.xml 文件中加入databaseIdProvider即可： ~~~ <databaseIdProvider type="DB_VENDOR" /> ~~~ databaseIdProvider 對應的 DB\_VENDOR 實現會將 databaseId 設置為DatabaseMetaData#getDatabaseProductName()返回的字符串。由于通常情況下這些字符串都非常長，而且相同產品的不同版本會返回不同的值，你可能想通過設置屬性別名來使其變短： ~~~ <databaseIdProvider type="DB_VENDOR"> <property name="SQL Server" value="sqlserver"/> <property name="DB2" value="db2"/> <property name="Oracle" value="oracle" /> </databaseIdProvider> ~~~ 在提供了屬性別名時，databaseIdProvider 的 DB\_VENDOR 實現會將 databaseId 設置為數據庫產品名與屬性中的名稱第一個相匹配的值，如果沒有匹配的屬性，將會設置為 “null”。在這個例子中，如果getDatabaseProductName()返回“Oracle (DataDirect)”，databaseId 將被設置為“oracle”。你可以通過實現接口org.apache.ibatis.mapping.DatabaseIdProvider并在 mybatis-config.xml 中注冊來構建自己的 DatabaseIdProvider： ~~~ public interface DatabaseIdProvider { default void setProperties(Properties p) { // 從 3.5.2 開始，該方法為默認方法 // 空實現 } String getDatabaseId(DataSource dataSource) throws SQLException; } ~~~ ### 映射器（mappers）既然 MyBatis 的行為已經由上述元素配置完了，我們現在就要來定義 SQL 映射語句了。但首先，我們需要告訴 MyBatis 到哪里去找到這些語句。在自動查找資源方面，Java 并沒有提供一個很好的解決方案，所以最好的辦法是直接告訴 MyBatis 到哪里去找映射文件。你可以使用相對于類路徑的資源引用，或完全限定資源定位符（包括file:///形式的 URL），或類名和包名等。例如： ~~~  <mappers> <mapper resource="org/mybatis/builder/AuthorMapper.xml"/> <mapper resource="org/mybatis/builder/BlogMapper.xml"/> <mapper resource="org/mybatis/builder/PostMapper.xml"/> </mappers> ~~~ ~~~  <mappers> <mapper url="file:///var/mappers/AuthorMapper.xml"/> <mapper url="file:///var/mappers/BlogMapper.xml"/> <mapper url="file:///var/mappers/PostMapper.xml"/> </mappers> ~~~ ~~~  <mappers> <mapper class="org.mybatis.builder.AuthorMapper"/> <mapper class="org.mybatis.builder.BlogMapper"/> <mapper class="org.mybatis.builder.PostMapper"/> </mappers> ~~~ ~~~  <mappers> <package name="org.mybatis.builder"/> </mappers> ~~~