Java案例如何编写SQL映射文件（MyBatis实战指南）
目录导读
-
什么是SQL映射文件？它的核心作用是什么？
-
Java案例前的准备：环境搭建与基础配置
-
从零开始：一个完整的用户查询案例
-
映射文件中的核心标签详解（select、insert、update、delete）
-
参数传递与结果映射的常见陷阱
-
动态SQL：让映射文件“活”起来
-
最佳实践与性能优化建议
-
常见问题问答（Q&A）
什么是SQL映射文件？它的核心作用是什么？
在Java企业级开发中,MyBatis作为半自动ORM框架，其核心魅力就在于SQL映射文件，它就像是一座桥梁——将Java对象与数据库表之间的操作映射成XML配置文件，你不需要写冗长的JDBC代码，只需在映射文件中定义SQL语句及其参数、结果集的对应关系，MyBatis便会自动执行并返回Java对象。
核心作用：隔离SQL与业务逻辑，提升开发效率；支持动态SQL，灵活应对复杂查询；通过缓存机制优化数据库访问性能。
Java案例前的准备：环境搭建与基础配置
1 项目依赖（Maven示例）
<dependency>
<groupId>org.mybatis</groupId>
<artifactId>mybatis</artifactId>
<version>3.5.13</version>
</dependency>
2 核心配置文件（mybatis-config.xml）
<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/test"/>
<property name="username" value="root"/>
<property name="password" value="password"/>
</dataSource>
</environment>
</environments>
<mappers>
<mapper resource="com/example/mapper/UserMapper.xml"/>
</mappers>
</configuration>
注意：实际生产环境中，数据库连接信息应通过外部配置文件管理，避免硬编码。
从零开始：一个完整的用户查询案例
假设我们有一个用户表（user），包含字段：id、name、email、create_time，现在需要实现根据ID查询用户的功能。
1 创建Java实体类
public class User {
private Long id;
private String name;
private String email;
private Date createTime;
// getter/setter 省略
}
2 编写SQL映射文件（UserMapper.xml）
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
"https://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.mapper.UserMapper">
<!-- 定义结果映射，解决字段名与属性名不一致的问题 -->
<resultMap id="userResultMap" type="com.example.entity.User">
<id property="id" column="id"/>
<result property="name" column="name"/>
<result property="email" column="email"/>
<result property="createTime" column="create_time"/>
</resultMap>
<!-- 根据ID查询用户 -->
<select id="selectById" resultMap="userResultMap" parameterType="java.lang.Long">
SELECT id, name, email, create_time
FROM user
WHERE id = #{id}
</select>
</mapper>
3 对应Mapper接口
public interface UserMapper {
User selectById(Long id);
}
执行流程：当你调用userMapper.selectById(1L)时，MyBatis会自动读取映射文件中的SQL，用#{id}替换实际参数，执行查询并将结果集封装为User对象。
映射文件中的核心标签详解
| 用途 | 关键属性 | |
|---|---|---|
<select> |
查询操作 | id、resultMap/resultType、parameterType |
<insert> |
插入操作 | id、parameterType、useGeneratedKeys、keyProperty |
<update> |
更新操作 | id、parameterType |
<delete> |
删除操作 | id、parameterType |
1 插入案例（返回自增主键）
<insert id="insertUser" parameterType="com.example.entity.User" useGeneratedKeys="true" keyProperty="id">
INSERT INTO user (name, email, create_time)
VALUES (#{name}, #{email}, #{createTime})
</insert>
注意：
useGeneratedKeys="true"配合keyProperty可以自动将数据库自增ID赋值回Java对象的id字段。
2 批量插入（性能优化关键）
<insert id="batchInsert" parameterType="list">
INSERT INTO user (name, email, create_time)
VALUES
<foreach collection="list" item="user" separator=",">
(#{user.name}, #{user.email}, #{user.createTime})
</foreach>
</insert>
参数传递与结果映射的常见陷阱
1 参数类型混淆
错误示例：接口方法参数为Map<String, Object>，但映射文件中使用#{name}直接取值，而Map中实际key是userName，导致值为null。
正确做法：保持参数名与#{xxx}中的名称一致，或者使用@Param注解明确命名：
User selectByNameAndEmail(@Param("name") String name, @Param("email") String email);
<select ...> WHERE name = #{name} AND email = #{email}</select>
2 结果映射不完整导致NPE
当数据库字段为null时，如果实体类属性为基本类型（如int age），MyBatis会抛出异常，建议实体类属性统一使用包装类型（如Integer）或设置默认值。
动态SQL：让映射文件“活”起来
动态SQL是MyBatis最强大的特性之一,它让你在XML中像写Java代码一样进行逻辑判断。
1 使用<if>实现条件查询
<select id="searchUsers" resultMap="userResultMap">
SELECT * FROM user
<where>
<if test="name != null and name != ''">
AND name LIKE CONCAT('%', #{name}, '%')
</if>
<if test="email != null">
AND email = #{email}
</if>
</where>
</select>
<where>标签会自动处理多余的AND/OR前缀，避免SQL语法错误。
2 使用<choose>实现多分支
<select id="findByCondition" ...>
SELECT * FROM user
<where>
<choose>
<when test="searchType == 'name'">
AND name = #{keyword}
</when>
<when test="searchType == 'email'">
AND email = #{keyword}
</when>
<otherwise>
AND 1=1
</otherwise>
</choose>
</where>
</select>
最佳实践与性能优化建议
- *避免`select `**：明确指定字段名，既可提升性能，也能防止字段顺序变化导致问题。
- 合理使用缓存：开启二级缓存需谨慎，只对更新频率低、查询频繁的数据使用。
- 大结果集分页：使用数据库物理分页（如LIMIT）而不是内存分页，避免OOM。
- 复用resultMap：多个查询可共用同一个resultMap，减少冗余配置。
- 参数类型明确：定义清晰的
parameterType，推荐使用实体类或Map<String, Object>。 - SQL注入防护：始终使用而不是拼接用户输入，仅用于表名、列名等动态场景。
常见问题问答（Q&A）
Q1：映射文件中resultType和resultMap有什么区别？
A：resultType适合字段名与属性名完全一致的情况（如resultType="com.example.entity.User"），当存在差异或需要复杂的映射关系时，必须使用resultMap。
Q2：如何解决映射文件中的SQL注入问题？
A：一律使用传递参数，它会自动生成预编译语句，只有少数动态表名/列名场景才用，且必须确保输入来源可控（如枚举值、配置文件）。
Q3：一个映射文件可以定义多个<select>标签吗？
A：可以，每个<select>必须有唯一id，全局唯一要求是该id与对应的Mapper接口方法名一致（namespace+id唯一）。
Q4：MyBatis映射文件支持XML转义吗？
A：需要，如果SQL中包含<、>、&等特殊字符，需用<![CDATA[ ... ]]>包裹，
<select ...>
<![CDATA[ SELECT * FROM user WHERE age > 18 AND age < 60 ]]>
</select>
通过以上案例解析,你应该已经掌握了如何从零编写一个健壮的SQL映射文件，关键在于：明确映射关系、善用动态SQL、注意参数传递细节，在实际项目中，建议结合MyBatis Generator等代码生成工具，快速生成基础映射文件，然后再手动优化复杂查询，这样既能保证效率，又能保持代码的可维护性。
延伸思考：如果你正在使用Spring Boot，还可以结合MapperScan注解和@Mapper接口，实现零XML配置的纯注解开发，但对于复杂场景，XML映射文件的可维护性依然远高于注解。
