MyBatis 核心配置文件 SqlMapConfig.xml 全解析

SqlMapConfig.xml是 MyBatis 的全局配置文件，相当于框架的 "总开关"，定义了数据库连接、事务管理、类型别名、映射器加载等核心参数。本文结合实战场景，拆解核心标签用法、避坑指南和性能优化技巧，帮你快速掌握配置文件的精髓。

一、核心概述

SqlMapConfig.xml是 MyBatis 的全局配置入口，所有影响框架运行的核心参数都在这里定义。它的核心作用是：

• 管理数据库连接（多环境适配）；
• 简化类名书写（类型别名）；
• 加载 SQL 映射文件（Mapper.xml）；
• 控制全局行为（日志、缓存、驼峰映射等）。

关键规则：配置标签必须按官方指定顺序书写（否则启动报错），顺序如下：properties → settings → typeAliases → typeHandlers → objectFactory → plugins → environments → mappers

二、核心标签详解

1. properties 标签：数据库配置解耦

核心作用

统一管理数据库连接参数（driver、url、username、password），实现 "配置与代码分离"，便于开发 / 测试 / 生产环境切换。

两种配置方式

方式 1：内部硬编码（仅测试用，不推荐）

<configuration>
    <properties>
        <property name="jdbc.driver" value="com.mysql.cj.jdbc.Driver"/>
        <property name="jdbc.url" value="jdbc:mysql:///mybatis_db?useUnicode=true&amp;characterEncoding=utf8&amp;useSSL=false&amp;serverTimezone=Asia/Shanghai"/>
        <property name="jdbc.username" value="root"/>
        <property name="jdbc.password" value="root"/>
    </properties>

    <!-- 环境配置引用内部属性 -->
    <environments default="mysql">
        <environment id="mysql">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="${jdbc.driver}"/>
                <property name="url" value="${jdbc.url}"/>
                <property name="username" value="${jdbc.username}"/>
                <property name="password" value="${jdbc.password}"/>
            </dataSource>
        </environment>
    </environments>
</configuration>

方式 2：加载外部 properties 文件（推荐，解耦）

① 新建jdbc.properties（resources 目录下）：

# jdbc.properties
jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/mybatis_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
jdbc.username=root
jdbc.password=root
# 测试环境配置
jdbc.test.url=jdbc:mysql://test-server:3306/mybatis_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai

② SqlMapConfig.xml 加载外部文件：

<configuration>
    <!-- 加载外部属性文件，可定义默认值（外部文件无该属性时生效） -->
    <properties resource="jdbc.properties">
        <property name="jdbc.username" value="default_root"/>
    </properties>

    <environments default="mysql">
        <!-- 开发环境 -->
        <environment id="mysql">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="${jdbc.driver}"/>
                <property name="url" value="${jdbc.url}"/>
                <property name="username" value="${jdbc.username}"/>
                <property name="password" value="${jdbc.password}"/>
            </dataSource>
        </environment>
        <!-- 测试环境 -->
        <environment id="test">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="${jdbc.driver}"/>
                <property name="url" value="${jdbc.test.url}"/>
                <property name="username" value="${jdbc.username}"/>
                <property name="password" value="${jdbc.password}"/>
            </dataSource>
        </environment>
    </environments>
</configuration>

扩展技巧：多环境动态切换

结合 Maven Profiles 实现环境一键切换（开发 / 测试 / 生产）：① pom.xml 配置 Profiles：

<profiles>
    <profile>
        <id>dev</id>
        <properties>
            <env>dev</env>
        </properties>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
    </profile>
    <profile>
        <id>test</id>
        <properties>
            <env>test</env>
        </properties>
    </profile>
</profiles>

② 新建jdbc-dev.properties和jdbc-test.properties，Maven 打包时自动加载对应环境配置。

避坑点

• MySQL8.0 + 驱动类是com.mysql.cj.jdbc.Driver，必须指定时区（serverTimezone=Asia/Shanghai）；
• XML 中&需转义为&（如&useSSL=false → &useSSL=false）；
• resource指向类路径（resources 目录），url指向绝对路径（如file:///D:/jdbc.properties）。

2. typeAliases 标签：简化类名书写

核心作用

为 Java 类定义 "简写别名"，替代冗长的全类名（如mybatis.domain.User → user），减少 Mapper.xml 冗余代码。

三种配置方式

方式 1：单个类精准配置

<configuration>
    <typeAliases>
        <!-- type=全类名，alias=自定义别名（大小写不敏感） -->
        <typeAlias type="mybatis.domain.User" alias="user"/>
        <typeAlias type="mybatis.vo.QueryVo" alias="queryVo"/>
    </typeAliases>
</configuration>

使用示例：

<!-- Mapper.xml直接用别名 -->
<select id="findAll" resultType="user">
    select * from user
</select>
<select id="findByVo" parameterType="queryVo" resultType="user">
    select * from user where username = #{user.username}
</select>

方式 2：包扫描批量配置（推荐）

<configuration>
    <typeAliases>
        <!-- 扫描包下所有类，别名=类名首字母小写（User→user，QueryVo→queryVo） -->
        <package name="mybatis.domain"/>
        <package name="mybatis.vo"/>
    </typeAliases>
</configuration>

优势：新增类无需修改配置，自动生成别名，适配快速开发。

方式 3：注解自定义别名（进阶）

在实体类上用@Alias覆盖默认别名：

package mybatis.domain;
import org.apache.ibatis.type.Alias;

// 自定义别名，优先级高于包扫描默认规则
@Alias("myUser")
public class User {
    // 字段+getter/setter
}

使用示例：

<select id="findAll" resultType="myUser">
    select * from user
</select>

MyBatis 内置别名（无需配置，直接用）

全类名	内置别名	说明
java.lang.Integer	int	大小写均可（int/Integer）
java.lang.String	string
java.util.Date	date
java.util.List	list
java.util.Map	map

实用技巧

• 别名优先级：@Alias注解 > 单个类配置 > 包扫描默认别名 > 内置别名；
• 不同包下同名类（如mybatis.domain.User和mybatis.test.User），需用@Alias避免冲突；
• 推荐统一使用小写别名，规范开发。

3. environments 标签：数据库环境配置

核心作用

配置数据库连接环境（支持多环境：开发 / 测试 / 生产），指定默认环境。

核心子标签说明

标签	作用
environments	根标签，default 属性指定默认环境 ID（如 default="mysql"）
environment	单个环境配置，id 属性唯一标识（如 id="mysql"、id="test"）
transactionManager	事务管理器：JDBC（手动控制事务，推荐）MANAGED（交给容器管理，如 Spring）
dataSource	数据源：POOLED（连接池，推荐）UNPOOLED（无连接池）JNDI（容器数据源）

实战配置（生产级）

<environments default="mysql">
    <!-- 开发环境 -->
    <environment id="mysql">
        <transactionManager type="JDBC">
            <!-- 事务超时时间（可选） -->
            <property name="timeout" value="30"/>
        </transactionManager>
        <dataSource type="POOLED">
            <property name="driver" value="${jdbc.driver}"/>
            <property name="url" value="${jdbc.url}"/>
            <property name="username" value="${jdbc.username}"/>
            <property name="password" value="${jdbc.password}"/>
            <!-- 连接池优化 -->
            <property name="poolMaximumActiveConnections" value="20"/> <!-- 最大活跃连接 -->
            <property name="poolMaximumIdleConnections" value="5"/>   <!-- 最大空闲连接 -->
            <property name="poolMaximumCheckoutTime" value="20000"/>  <!-- 连接最大占用时间（毫秒） -->
        </dataSource>
    </environment>
    <!-- 测试环境 -->
    <environment id="test">
        <transactionManager type="JDBC"/>
        <dataSource type="POOLED">
            <property name="driver" value="${jdbc.driver}"/>
            <property name="url" value="${jdbc.test.url}"/>
            <property name="username" value="${jdbc.username}"/>
            <property name="password" value="${jdbc.password}"/>
        </dataSource>
    </environment>
</environments>

避坑点

• default属性必须匹配某个environment的 id，否则启动报错；
• 连接池最大活跃连接数不宜过大（建议 10-50），避免数据库连接耗尽；
• 整合 Spring 后，事务和数据源由 Spring 管理，此处可简化配置。

4. mappers 标签：加载 SQL 映射文件

核心作用

加载 Mapper.xml（或 Mapper 接口），让 MyBatis 识别 SQL 映射配置。

四种加载方式

方式	语法示例	适用场景
resource 加载	<mapper resource="mappers/UserMapper.xml"/>	主流方式，加载类路径 xml
url 加载	<mapper url="file:///D:/mappers/UserMapper.xml"/>	加载绝对路径 xml
class 加载	<mapper class="mybatis.mapper.UserMapper"/>	注解式 Mapper（无 xml）
package 扫描加载	<package name="mybatis.mapper"/>	批量加载（推荐）

推荐配置（批量加载）

<mappers>
    <!-- 扫描mapper包下所有接口和xml（要求：接口名=xml文件名，同目录） -->
    <package name="mybatis.mapper"/>
</mappers>

避坑点

• resource 路径用/分隔（如mappers/UserMapper.xml），不要用.；
• package 扫描时，Mapper 接口和 Mapper.xml 必须：① 同包名 ② 同名（如 UserMapper.java 和 UserMapper.xml）；
• 注解式 Mapper（如@Select("select * from user")）无需 xml，直接用 class/package 加载。

5. settings 标签：全局行为控制（进阶）

settings 是 MyBatis 的 "全局开关"，控制日志、缓存、懒加载等核心行为，以下是高频配置：

<settings>
    <!-- 控制台输出SQL日志（调试专用） -->
    <setting name="logImpl" value="STDOUT_LOGGING"/>
    <!-- 开启二级缓存 -->
    <setting name="cacheEnabled" value="true"/>
    <!-- 开启懒加载（关联查询） -->
    <setting name="lazyLoadingEnabled" value="true"/>
    <!-- 下划线字段自动转驼峰（如user_name→userName） -->
    <setting name="mapUnderscoreToCamelCase" value="true"/>
</settings>

核心实用配置：

• mapUnderscoreToCamelCase=true：无需手动配置 resultMap，自动映射下划线字段到驼峰属性；
• logImpl=STDOUT_LOGGING：快速开启 SQL 日志，无需配置 log4j，测试必备。

三、生产级配置模板

<?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="jdbc.properties">
        <property name="jdbc.username" value="root"/>
    </properties>

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

    <!-- 3. 类型别名 -->
    <typeAliases>
        <package name="mybatis.domain"/>
        <package name="mybatis.vo"/>
    </typeAliases>

    <!-- 4. 数据库环境 -->
    <environments default="mysql">
        <environment id="mysql">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="${jdbc.driver}"/>
                <property name="url" value="${jdbc.url}"/>
                <property name="username" value="${jdbc.username}"/>
                <property name="password" value="${jdbc.password}"/>
                <property name="poolMaximumActiveConnections" value="20"/>
            </dataSource>
        </environment>
    </environments>

    <!-- 5. 加载映射器 -->
    <mappers>
        <package name="mybatis.mapper"/>
    </mappers>
</configuration>

四、避坑与优化指南

1. 常见错误

• 标签顺序错误：严格按官方顺序（properties→settings→typeAliases→...→mappers）；
• 路径错误：resource 是类路径，避免绝对路径硬编码；
• 数据库参数错误：MySQL8.0 + 驱动 / 时区配置、密码错误等。

2. 性能优化

• 数据源：使用 POOLED 连接池，合理配置最大活跃连接数（10-50）；
• 别名：包扫描批量配置，减少维护成本；
• 日志：开发环境开启，生产环境关闭（或降级）；
• 驼峰映射：开启mapUnderscoreToCamelCase，减少 resultMap 配置。

3. 多环境与安全

• 多环境分离：通过 Maven Profiles + 多份 properties 文件实现，避免修改核心配置；
• 敏感信息：生产环境加密数据库密码（如 MyBatis 加密插件、Nacos 配置中心），避免明文存储。

五、总结

SqlMapConfig.xml的核心是 "简化配置、解耦环境、提升效率"，日常开发重点掌握：

1. properties：外部化管理数据库配置，适配多环境；
2. typeAliases：批量配置别名，减少冗余代码；
3. environments：配置数据库连接和事务，优化连接池；
4. mappers：批量加载映射器，规范文件结构；
5. settings：全局优化（驼峰映射、日志、缓存）。

整合 Spring 后，数据源、事务等配置可迁移到 Spring 配置文件，进一步简化 MyBatis 配置，但核心思想和标签用法完全通用。