configuration 元素结构

configuration 是 MyBatis 核心配置文件的根元素，其子元素有严格的顺序要求。理解这个结构是编写正确配置文件的提。

子元素顺序规则

MyBatis 使用 DTD 约束定义了子元素的顺序，必须严格按照以下顺序排列：

XML

properties → settings → typeAliases → typeHandlers → 
objectFactory → plugins → environment → mappers

如果顺序错误，启动时会报类似如下异常：

XML

The content of element type "configuration" must match
"(properties?,settings?,typeAliases?,typeHandlers?,objectFactory?,
objectWrapperFactory?,reflectorFactory?,plugins?,environments?,
databaseIdProvider?,typeHandlers?,mappers?)".

各元素说明

元素	出现次数	说明
properties	0-1	引入外部属性文件
settings	0-1	全局运行时设置
typeAliases	0-1	类型别名
typeHandlers	0-1	类型处理器
objectFactory	0-1	对象工厂
plugins	0-1	插件配置
environments	0-1	数据源配置
databaseIdProvider	0-1	数据库厂商标识
mappers	0-1	映射文件注册

注意：所有子元素都是可选的（0-1 次），但如果存在就必须按照上述顺序排列。

完整的配置文件示例

下面是一个包含所有常用元素的完整配置：

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>

    <!-- 1. 引入外部属性文件 -->
    <properties resource="db.properties"/>

    <!-- 2. 全局设置 -->
    <settings>
        <setting name="cacheEnabled" value="true"/>
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <setting name="logImpl" value="SLF4J"/>
        <setting name="defaultStatementTimeout" value="30"/>
        <setting name="useGeneratedKeys" value="true"/>
    </settings>

    <!-- 3. 类型别名 -->
    <typeAliases>
        <package name="com.example.entity"/>
    </typeAliases>

    <!-- 4. 数据源配置 -->
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="${db.driver}"/>
                <property name="url" value="${db.url}"/>
                <property name="username" value="${db.username}"/>
                <property name="password" value="${db.password}"/>
            </dataSource>
        </environment>
    </environments>

    <!-- 5. 注册 Mapper -->
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
        <mapper resource="mapper/OrderMapper.xml"/>
    </mappers>

</configuration>

最小配置文件

实际项目中，不需要配置所有元素。一个最小可用配置只需包含数据源和 Mapper 注册：

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="com.mysql.cj.jdbc.Driver"/>
                <property name="url" value="jdbc:mysql://localhost:3306/mydb"/>
                <property name="username" value="root"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>

    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>

</configuration>

常见配置场景

场景一：使用注解 + 接口扫描

XML

<configuration>
    <properties resource="db.properties"/>

    <settings>
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <setting name="logImpl" value="SLF4J"/>
    </settings>

    <typeAliases>
        <package name="com.example.entity"/>
    </typeAliases>

    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="${db.driver}"/>
                <property name="url" value="${db.url}"/>
                <property name="username" value="${db.username}"/>
                <property name="password" value="${db.password}"/>
            </dataSource>
        </environment>
    </environments>

    <!-- 扫描 Mapper 接口包，替代 XML 映射文件 -->
    <mappers>
        <package name="com.example.mapper"/>
    </mappers>
</configuration>

场景二：XML + 接口混合使用

XML

<mappers>
    <!-- XML 映射文件 -->
    <mapper resource="mapper/UserMapper.xml"/>
    <mapper url="file:///var/mappers/OrderMapper.xml"/>

    <!-- 接口扫描 -->
    <package name="com.example.mapper"/>
</mappers>

注册方式	说明	适用场景
resource	classpath 下的 XML 文件	最常用的方式
url	本地文件路径或网络地址	配置文件在固定路径
class	直接注册 Mapper 接口类	配合注解使用
package	扫描包下所有 Mapper	项目中大量 Mapper 时使用

场景三：多数据库厂商标识

XML

<configuration>
    <properties resource="db.properties"/>

    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="${db.driver}"/>
                <property name="url" value="${db.url}"/>
                <property name="username" value="${db.username}"/>
                <property name="password" value="${db.password}"/>
            </dataSource>
        </environment>
    </environments>

    <!-- 数据库厂商标识 -->
    <databaseIdProvider type="DB_VENDOR">
        <property name="MySQL" value="mysql"/>
        <property name="Oracle" value="oracle"/>
        <property name="PostgreSQL" value="postgresql"/>
    </databaseIdProvider>

    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

配置后，Mapper XML 中可以使用 databaseId 区分不同数据库的 SQL：

XML

<select id="selectUsers" resultType="user">
    <if test="_databaseId == 'mysql'">
        SELECT * FROM user LIMIT #{limit}
    </if>
    <if test="_databaseId == 'oracle'">
        SELECT * FROM user WHERE ROWNUM &lt;= #{limit}
    </if>
</select>

顺序错误常见排查

错误示例：settings 在 properties 之前

XML

<!-- 错误！settings 必须在 properties 之后 -->
<configuration>
    <settings>
        <setting name="cacheEnabled" value="true"/>
    </settings>

    <properties resource="db.properties"/>
</configuration>

正确写法

text

<configuration>
    <!-- 1. properties 在前 -->
    <properties resource="db.properties"/>

    <!-- 2. settings 在后 -->
    <settings>
        <setting name="cacheEnabled" value="true"/>
    </settings>
</configuration>

记忆技巧：配置加载顺序与元素顺序一致 —— 先加载属性文件，再应用全局设置，然后注册类型，最后配置数据源和 Mapper。

DTD 约束说明

配置文件头部的 DOCTYPE 声明定义了 DTD 约束：

text

<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-config.dtd">

PUBLIC 表示使用公共标识符
-//mybatis.org//DTD Config 3.0//EN 是 DTD 的公共标识符
http://mybatis.org/dtd/mybatis-3-config.dtd 是 DTD 的 URL 地址

IDE（如 IntelliJ IDEA）会自动下载并缓存 DTD 文件，提供 XML 自动补全和校验功能。如果无法联网，可以手动下载 DTD 文件到本地。

要点总结

configuration 是根元素，所有配置都在其内部
子元素有严格顺序：properties → settings → typeAliases → typeHandlers → objectFactory → plugins → environment → mappers
所有子元素都是可选的，最小配置只需 environments + mappers
mappers 支持 resource、url、class、package 四种注册方式
databaseIdProvider 用于多数据库兼容的 SQL 编写
配置文件头部 DOCTYPE 声明提供 IDE 自动补全和校验支持

📝 发现内容有误？点击此处直接编辑