MyBatis 配置文件详解

发表于 分类于
适合对象：已经知道 MyBatis 的基本运行流程，想看懂 mybatis-config.xml 中常见配置项的同学。 官方参考： MyBatis XML 配置 MyBatis 入门 1. 配置文件负责什么？ mybatis-config.xml 是 MyBatis 的全局配置文件。它负责告诉 My

适合对象：已经知道 MyBatis 的基本运行流程，想看懂 mybatis-config.xml 中常见配置项的同学。

官方参考：

1. 配置文件负责什么？

mybatis-config.xml 是 MyBatis 的全局配置文件。它负责告诉 MyBatis：

  • 数据库连接信息从哪里来
  • 运行时行为怎么设置
  • Java 类型有没有别名
  • 使用哪个数据库环境
  • Mapper XML 映射文件在哪里

常见结构如下：

1
2
3
4
5
6
7
8
9
flowchart TD
    A["configuration"] --> B["properties<br/>外部属性"]
    A --> C["settings<br/>运行时设置"]
    A --> D["typeAliases<br/>类型别名"]
    A --> E["environments<br/>环境配置"]
    E --> F["environment"]
    F --> G["transactionManager<br/>事务管理器"]
    F --> H["dataSource<br/>数据源"]
    A --> I["mappers<br/>映射文件注册"]

下面只讲这些入门阶段最常见、并且示例代码中已经用到的配置项。

2. XML 头部和 configuration 根标签

配置文件通常这样开头：

1
2
3
4
5
6
7
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
        PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
        "https://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    ...
</configuration>

这段内容说明：

内容 含义
<?xml version="1.0" encoding="UTF-8" ?> 声明这是 XML 文件，并使用 UTF-8
DOCTYPE configuration 使用 MyBatis 配置文件的 DTD 规则
<configuration> MyBatis 全局配置的根标签

新手可以先把这部分当作固定格式，重点关注 <configuration> 里面写了什么。

3. properties：加载外部属性

数据库连接信息通常不直接写死在配置文件里，而是放到单独的属性文件中：

1
<properties resource="config.properties"/>

属性文件可以这样写：

1
2
3
4
driver=com.mysql.cj.jdbc.Driver
url=jdbc:mysql://localhost:3306/mybatis
username=root
password=<your-password>

然后在配置文件中使用 ${属性名} 引用：

1
2
3
4
<property name="driver" value="${driver}"/>
<property name="url" value="${url}"/>
<property name="username" value="${username}"/>
<property name="password" value="${password}"/>

这样做有两个好处：

  • 数据库连接信息集中管理，修改方便。
  • 配置文件结构更清楚，不会被连接细节打散。

属性加载顺序可以这样理解：

1
2
3
4
flowchart TD
    A["properties 标签内部 property"] --> B["resource 或 url 指向的属性文件"]
    B --> C["SqlSessionFactoryBuilder.build(...) 传入的属性"]
    C --> D["最终用于替换 ${driver}、${url} 等占位符"]

如果多个地方出现同名属性，后读取的值会覆盖先读取的值。入门阶段最常见的写法就是 resource="config.properties"。

4. settings：开启下划线转驼峰

settings 用来改变 MyBatis 的运行行为。一个很常见的设置是：

1
2
3
<settings>
    <setting name="mapUnderscoreToCamelCase" value="true"/>
</settings>

它表示开启“下划线命名转驼峰命名”。例如：

数据库列名 Java 属性名
id id
name name
gender gender
age age
home_address homeAddress

Java 类里可以这样写：

1
private String homeAddress;

SQL 中仍然使用数据库字段名：

1
home_address

开启 mapUnderscoreToCamelCase 后，查询结果里的 home_address 可以自动映射到 Java 对象的 homeAddress。

如果没有这个设置，home_address 和 homeAddress 这种命名风格不同的字段，就需要手动处理映射关系。

5. typeAliases：给 Java 类型起短名字

Mapper XML 中经常要写 Java 类型。如果每次都写全类名，会比较长：

1
com.bytepro.entity.Employee

可以通过 typeAliases 给类型起别名：

1
2
3
4
<typeAliases>
    <typeAlias type="com.bytepro.entity.Employee" alias="employee"/>
    <package name="com.bytepro.entity"/>
</typeAliases>

还可以在类上使用 @Alias：

1
2
3
4
5
6
7
8
@Alias("emp")
public class Employee {
    private Integer id;
    private String name;
    private Character gender;
    private Integer age;
    private String homeAddress;
}

这样在 XML 中就可以写：

1
2
3
<select id="selectEmployee" resultType="emp">
    select * from employee where id = #{id}
</select>

这里的 resultType="emp" 表示：查询结果要封装成 Employee 对象。

常见写法对比如下：

写法 示例 说明
全类名 com.bytepro.entity.Employee 最直接，但比较长
手动别名 employee 来自 <typeAlias alias="employee"/>
注解别名 emp 来自 @Alias("emp")

入门时只要记住：别名只是 Java 类型的短名字，不会改变类本身。

6. environments：配置数据库环境

environments 用来配置数据库连接环境。示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<environments default="product">
    <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>

    <environment id="product">
        <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>

这里配置了两个环境：

环境 id 含义
development 开发环境
product 生产环境示例

默认使用哪个环境，由 default 决定：

1
<environments default="product">

也就是说，如果不额外指定环境，MyBatis 会使用 id="product" 的那套配置。

transactionManager：事务管理器

示例配置：

1
<transactionManager type="JDBC"/>

JDBC 表示使用 JDBC 自带的提交和回滚机制。执行增删改之后常见写法是：

1
session.commit();

如果整合 Spring，事务通常会交给 Spring 管理；但在纯 MyBatis 入门示例中，使用 JDBC 事务管理器很常见。

dataSource：数据源

示例配置：

1
2
3
4
5
6
<dataSource type="POOLED">
    <property name="driver" value="${driver}"/>
    <property name="url" value="${url}"/>
    <property name="username" value="${username}"/>
    <property name="password" value="${password}"/>
</dataSource>

POOLED 表示使用 MyBatis 内置连接池。连接池可以简单理解为：

提前管理一批数据库连接，需要时拿一个，用完再还回去，减少频繁创建连接的成本。

四个基础属性分别是：

属性 作用
driver JDBC 驱动类
url 数据库连接地址
username 数据库用户名
password 数据库密码

这些值通常通过 ${driver}、${url}、${username}、${password} 从外部属性文件读取。

7. mappers：注册 SQL 映射文件

Mapper XML 是真正写 SQL 的地方。MyBatis 需要通过 mappers 知道这些 XML 在哪里：

1
2
3
4
<mappers>
    <mapper resource="mapper/EmployeeMapper.xml"/>
    <mapper resource="mapper/EmployeeMapperInterface.xml"/>
</mappers>

常见注册方式有两类：

写法 示例 说明
resource <mapper resource="mapper/EmployeeMapper.xml"/> 按 classpath 资源路径注册 XML
class <mapper class="com.bytepro.mapper.EmployeeMapper"/> 按 Mapper 接口注册

入门时最容易理解的是 resource：写清楚 XML 映射文件的位置，MyBatis 就能加载里面的 SQL。

8. 配置文件整体运行图

把上面内容串起来，可以得到这样一张图：

1
2
3
4
5
6
7
8
9
10
flowchart TD
    A["mybatis-config.xml"] --> B["properties<br/>加载 config.properties"]
    B --> C["dataSource<br/>替换 ${driver}/${url}/${username}/${password}"]
    A --> D["settings<br/>开启下划线转驼峰"]
    A --> E["typeAliases<br/>Employee 可写成 employee 或 emp"]
    A --> F["environments<br/>选择默认环境"]
    F --> G["transactionManager=JDBC"]
    F --> H["dataSource=POOLED"]
    A --> I["mappers<br/>注册 Mapper XML"]
    I --> J["XML 中的 SQL"]

9. 这一篇先记住什么？

  • properties 用来加载外部属性文件，配合 ${} 使用。
  • settings 会影响 MyBatis 的运行行为，常见设置是下划线转驼峰。
  • typeAliases 让 XML 里的 Java 类型名更短。
  • environments 配置数据库环境，default 决定默认使用哪一个。
  • transactionManager type="JDBC" 表示使用 JDBC 事务。
  • dataSource type="POOLED" 表示使用 MyBatis 内置连接池。
  • mappers 负责注册真正写 SQL 的 XML 映射文件。