MyBatis框架实战：从基础配置到高级映射技巧

1. MyBatis框架概述与核心价值

MyBatis作为Java生态中持久层框架的经典选择，已经服务了无数企业级应用。我在实际项目中使用MyBatis已有七年时间，从最初的XML配置到现在的注解混合开发模式，见证了它的演进历程。与Hibernate等全自动ORM框架不同，MyBatis巧妙地平衡了自动化与灵活性，让开发者既能享受对象关系映射的便利，又能精细控制SQL语句。

重要提示：MyBatis 3.5+版本对动态SQL进行了重大优化，建议新项目直接采用3.5.6以上版本

框架的核心优势体现在三个方面：首先是通过XML或注解将Java方法与SQL语句解耦，使SQL维护变得清晰；其次是强大的动态SQL功能，可以摆脱传统JDBC中大量拼接字符串的困扰；最后是灵活的映射机制，能处理各种复杂的数据库表关系。我在电商系统开发中就曾用MyBatis的<collection>标签完美映射了商品与SKU的一对多关系。

2. 开发环境搭建与基础配置

2.1 项目初始化与依赖管理

使用Maven构建项目时，核心依赖只需包含mybatis和对应JDBC驱动。以下是pom.xml的典型配置：

xml复制<dependencies>
    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis</artifactId>
        <version>3.5.9</version>
    </dependency>
    <!-- MySQL驱动示例 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.28</version>
    </dependency>
</dependencies>

实际项目中我推荐添加PageHelper分页插件和MyBatis-Plus增强工具，它们能显著提升开发效率。特别是在处理复杂分页查询时，PageHelper可以自动改写count查询，避免手动编写重复SQL。

2.2 核心配置文件详解

mybatis-config.xml是框架的主配置文件，有几个关键配置项需要特别注意：

xml复制<configuration>
    <settings>
        <!-- 开启驼峰命名自动映射 -->
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <!-- 查询时打印SQL语句 -->
        <setting name="logImpl" value="STDOUT_LOGGING"/>
    </settings>
    <typeAliases>
        <package name="com.example.model"/>
    </typeAliases>
    <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/test"/>
                <property name="username" value="root"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>
    <mappers>
        <mapper resource="mapper/UserMapper.xml"/>
    </mappers>
</configuration>

在微服务架构下，我通常会将数据源配置抽离到Spring Cloud Config，而MyBatis配置只保留映射相关部分。特别注意mapUnderscoreToCamelCase这个设置，它能自动将数据库的user_name字段映射到Java的userName属性，省去大量重复映射配置。

3. SQL映射文件深度解析

3.1 基础CRUD操作实现

Mapper XML文件是MyBatis的核心工作单元。以用户管理为例，一个完整的UserMapper.xml应包含以下基本元素：

xml复制<mapper namespace="com.example.mapper.UserMapper">
    <resultMap id="BaseResultMap" type="User">
        <id column="id" property="id" jdbcType="BIGINT"/>
        <result column="username" property="username" jdbcType="VARCHAR"/>
        <result column="create_time" property="createTime" jdbcType="TIMESTAMP"/>
    </resultMap>

    <select id="selectById" resultMap="BaseResultMap">
        SELECT * FROM user WHERE id = #{id}
    </select>

    <insert id="insert" useGeneratedKeys="true" keyProperty="id">
        INSERT INTO user(username) VALUES(#{username})
    </insert>

    <update id="updateById">
        UPDATE user SET username=#{username} WHERE id=#{id}
    </update>

    <delete id="deleteById">
        DELETE FROM user WHERE id=#{id}
    </delete>
</mapper>

经验之谈：insert操作务必设置useGeneratedKeys和keyProperty，这样插入后能自动回填主键到实体对象

我在金融项目中就曾因为漏配这两个属性，导致后续业务逻辑无法获取自增ID，引发了一系列问题。另一个容易忽略的是jdbcType指定，虽然MyBatis能自动推断类型，但在Nullable字段上显式声明能避免潜在的类型转换异常。

3.2 动态SQL实战技巧

MyBatis的动态SQL是其最强大的特性之一。以下是几种典型场景的实现：

条件查询：

xml复制<select id="selectByCondition" resultMap="BaseResultMap">
    SELECT * FROM user
    <where>
        <if test="username != null and username != ''">
            AND username LIKE CONCAT('%',#{username},'%')
        </if>
        <if test="status != null">
            AND status = #{status}
        </if>
    </where>
    ORDER BY create_time DESC
</select>

批量插入：

xml复制<insert id="batchInsert">
    INSERT INTO user(username) VALUES
    <foreach collection="list" item="item" separator=",">
        (#{item.username})
    </foreach>
</insert>

选择更新：

xml复制<update id="updateSelective">
    UPDATE user
    <set>
        <if test="username != null">username=#{username},</if>
        <if test="status != null">status=#{status},</if>
    </set>
    WHERE id=#{id}
</update>

在物流系统中，我们曾用<foreach>标签处理过上万条运单的批量插入，性能比单条插入提升近百倍。但要注意：MySQL的批量插入语句长度有限制（默认4M），超长时需要分批次处理。

4. 高级映射与关联查询

4.1 复杂结果集映射

处理一对多关系时，<collection>标签非常实用。以博客系统为例：

xml复制<resultMap id="BlogWithPostsMap" type="Blog">
    <id property="id" column="blog_id"/>
    <result property="title" column="blog_title"/>
    <collection property="posts" ofType="Post">
        <id property="id" column="post_id"/>
        <result property="title" column="post_title"/>
    </collection>
</resultMap>

<select id="selectBlogWithPosts" resultMap="BlogWithPostsMap">
    SELECT 
        b.id as blog_id, b.title as blog_title,
        p.id as post_id, p.title as post_title
    FROM blog b
    LEFT JOIN post p ON p.blog_id = b.id
    WHERE b.id = #{id}
</select>

4.2 嵌套查询与延迟加载

对于更复杂的场景，可以使用嵌套查询：

xml复制<resultMap id="BlogWithPostsNestedMap" type="Blog">
    <id property="id" column="id"/>
    <collection 
        property="posts" 
        select="selectPostsByBlogId" 
        column="id"
        fetchType="lazy"/>
</resultMap>

<select id="selectBlog" resultMap="BlogWithPostsNestedMap">
    SELECT * FROM blog WHERE id = #{id}
</select>

<select id="selectPostsByBlogId" resultType="Post">
    SELECT * FROM post WHERE blog_id = #{blogId}
</select>

在配置文件中需要开启延迟加载：

xml复制<settings>
    <setting name="lazyLoadingEnabled" value="true"/>
    <setting name="aggressiveLazyLoading" value="false"/>
</settings>

性能提示：N+1查询问题在大型系统中需要特别注意，合理使用join查询和嵌套查询

我在内容管理系统优化中就遇到过典型的N+1问题：当查询100篇文章时，由于每篇文章又查询其标签，最终产生了101次数据库访问。解决方案是在列表查询时使用join一次性获取所有数据，或者使用MyBatis的批量加载功能。

5. 注解开发与XML混合模式

5.1 常用注解速查

MyBatis提供了丰富的注解支持：

java复制public interface UserMapper {
    @Select("SELECT * FROM user WHERE id = #{id}")
    User selectById(Long id);

    @Insert("INSERT INTO user(username) VALUES(#{username})")
    @Options(useGeneratedKeys = true, keyProperty = "id")
    int insert(User user);

    @Update("UPDATE user SET username=#{username} WHERE id=#{id}")
    int updateById(User user);

    @Delete("DELETE FROM user WHERE id=#{id}")
    int deleteById(Long id);
}

5.2 动态SQL注解方案

使用@SelectProvider实现动态SQL：

java复制public class UserSqlProvider {
    public String selectByCondition(Map<String, Object> params) {
        return new SQL() {{
            SELECT("*");
            FROM("user");
            if (params.get("username") != null) {
                WHERE("username LIKE CONCAT('%',#{username},'%')");
            }
            if (params.get("status") != null) {
                WHERE("status = #{status}");
            }
            ORDER_BY("create_time DESC");
        }}.toString();
    }
}

// 在Mapper接口中使用
@SelectProvider(type = UserSqlProvider.class, method = "selectByCondition")
List<User> selectByCondition(Map<String, Object> params);

在实际项目中，我通常采用混合模式：简单CRUD用注解，复杂查询和动态SQL用XML。这样既保持了接口的简洁性，又能发挥XML的强大功能。特别是在团队协作时，XML文件更易于版本控制和多人协同编辑。

6. 性能优化与最佳实践

6.1 缓存机制剖析

MyBatis提供两级缓存：

• 一级缓存：SqlSession级别，默认开启
• 二级缓存：Mapper级别，需要手动配置

启用二级缓存步骤：

1. 全局配置开启缓存：

xml复制<settings>
    <setting name="cacheEnabled" value="true"/>
</settings>

2. 在Mapper XML中添加：

xml复制<cache eviction="LRU" flushInterval="60000" size="512" readOnly="true"/>

3. 实体类实现Serializable接口

缓存陷阱：更新操作会清空缓存，高并发写入场景慎用二级缓存

6.2 批量操作优化

使用SqlSession的批量执行器：

java复制try(SqlSession session = sqlSessionFactory.openSession(ExecutorType.BATCH)) {
    UserMapper mapper = session.getMapper(UserMapper.class);
    for (int i = 0; i < 1000; i++) {
        mapper.insert(new User("user"+i));
        if(i % 200 == 0) {
            session.flushStatements(); // 分段提交
        }
    }
    session.commit();
}

在数据迁移项目中，这种批量处理方式比单条提交快10倍以上。但要注意：批量操作的事务要么全部成功，要么全部失败，需要合理设置批处理大小。

6.3 类型处理器高级用法

自定义类型处理器处理枚举：

java复制@MappedTypes(UserStatus.class)
@MappedJdbcTypes(JdbcType.INTEGER)
public class UserStatusHandler extends BaseTypeHandler<UserStatus> {
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, 
            UserStatus parameter, JdbcType jdbcType) {
        ps.setInt(i, parameter.getCode());
    }
    // 其他方法实现...
}

在配置文件中注册：

xml复制<typeHandlers>
    <typeHandler handler="com.example.handler.UserStatusHandler"/>
</typeHandlers>

这样就能自动将数据库中的1/0转换为UserStatus.ACTIVE/INACTIVE枚举值。我在权限系统中就用这种方式优雅地处理了各种状态枚举。

7. 常见问题排查指南

7.1 典型异常处理

7.2 SQL注入防范

虽然MyBatis使用预编译语句能防止大部分SQL注入，但以下情况仍需注意：

1. 模糊查询避免直接拼接：

java复制// 错误做法
@Select("SELECT * FROM user WHERE username LIKE '%${name}%'")

// 正确做法
@Select("SELECT * FROM user WHERE username LIKE CONCAT('%',#{name},'%')")

2. 动态表名/列名必须使用${}时，务必进行白名单校验：

java复制public String queryByField(@Param("field") String field) {
    if(!Arrays.asList("username","email").contains(field)) {
        throw new IllegalArgumentException("Invalid field name");
    }
    return "SELECT * FROM user ORDER BY " + field;
}

在安全审计中，我曾发现过因滥用${}导致的潜在注入漏洞。建议团队制定严格的SQL编写规范，必要时使用MyBatis的SQL注入检测插件。