4.6 文件 Mapper

文件 Mapper 不是独立于 Mapper API 的另一套 DAO 形态。它通常和 Mapper 接口配合使用，把接口方法背后的 SQL 从注解迁移到 XML 文件中。

适合场景

• SQL 较长，不适合放在 Java 注解中。
• 动态 SQL 片段多，需要集中维护。
• 希望 SQL 和 Java 代码分离，便于 review 或交给数据库相关角色维护。
• 需要复用 SQL 片段、配置 resultMap、配置 XML 形式的对象映射。

不适合场景

• SQL 很短，直接用方法注解更直观。
• 只是常规单表 CRUD，优先使用 Mapper API（BaseMapper）。
• 希望完全通过链式 API 生成 SQL，优先使用 构造器 API。

最小示例

Mapper 接口

@RefMapper("/mapper/userMapper.xml")
public interface UserMapper {
    List<User> listUsers(@Param("status") String status, @Param("name") String name);
}

规则写法（推荐）

规则写法让 SQL 保持接近原生 SQL，动态条件直接内嵌在语句中。简单查询和常见条件拼接优先使用这种方式。

userMapper.xml

<mapper namespace="com.example.UserMapper">
    <select id="listUsers" resultType="com.example.User">
        select * from users
            @{and, status = :status}
            @{and, name like concat(:name, '%')}
    </select>
</mapper>

XML 标签写法

XML 标签写法适合迁移已有 MyBatis 风格 SQL，或团队已经习惯通过标签表达动态逻辑的场景。

userMapper.xml

<mapper namespace="com.example.UserMapper">
    <select id="listUsers" resultType="com.example.User">
        select * from users
        <where>
            <if test="status != null">
                and status = #{status}
            </if>
            <if test="name != null">
                and name like concat(#{name}, '%')
            </if>
        </where>
    </select>
</mapper>

已有 DataSource

DataSource dataSource = ...;

Configuration config = new Configuration();
Session session = config.newSession(dataSource);
UserMapper mapper = session.createMapper(UserMapper.class);

List<User> users = mapper.listUsers("ACTIVE", "A");

已有 Connection

Connection conn = ...;

Configuration config = new Configuration();
Session session = config.newSession(conn);
UserMapper mapper = session.createMapper(UserMapper.class);

List<User> users = mapper.listUsers("ACTIVE", "A");

动态 SQL 选择

Mapper 文件中有两类动态 SQL 能力：

方式	说明	入口
规则系统	@{and}、@{in}、@{set} 等，写法更轻量。	SQL 规则
XML 标签	<if>、<choose>、<foreach> 等，兼容 MyBatis 风格。	动态 SQL 标签

深入阅读

• Mapper 文件：XML 文件结构、标签和映射能力。
• SQL 标签：select、insert、update、execute 等标签。
• 调用文件 Mapper：通过 Mapper/BaseMapper 调用 XML statement。