文件 Mapper

当 SQL 逻辑复杂或篇幅较长时，编程式 API、声明式 API 或 构造器 API 都会导致代码可读性下降。 此时将 SQL 放置于独立的 Mapper XML 文件 中是最佳选择。

特点

• SQL 与代码分离：通过 Mapper XML 文件集中管理 SQL，代码中只需调用接口方法。
• 支持 两种动态 SQL 方式：规则方式（推荐，语法更简洁）和 XML 标签方式（兼容 MyBatis 风格）。
• 支持 SQL 片段复用 <sql> + <include> ，避免重复 SQL。
• 支持 多种结果映射：resultType（Bean、Map、int、string 等）和 resultMap（自定义列到属性的映射）。
• Mapper 文件是 声明式 API 的扩展，可混合使用注解方法和 XML 方法。
• 通过 session.executeStatement / session.queryStatement / session.pageStatement 执行。

定义 Mapper 文件

classpath:/mapper/userMapper.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//dbvisitor.net//DTD Mapper 1.0//EN"
        "https://www.dbvisitor.net/schema/dbvisitor-mapper.dtd">
<mapper namespace="com.example.UserMapper">
    <insert id="insertUser">
        insert into users (id, name, age) values (#{id}, #{name}, #{age})
    </insert>

    <select id="selectById" resultType="com.example.User">
        select * from users where id = #{id}
    </select>

    <select id="selectAll" resultType="com.example.User">
        select * from users order by id
    </select>

    <update id="updateEmail">
        update users set email = #{email} where id = #{id}
    </update>

    <delete id="deleteById">
        delete from users where id = #{id}
    </delete>
</mapper>

动态 SQL

Mapper 文件中可以使用动态 SQL 实现条件查询、动态更新等逻辑。dbVisitor 提供了 两种方式：

条件查询

使用规则（推荐）

使用 @{and} 规则，参数为空时自动跳过该条件，无需手动处理 WHERE 和 AND 连接符。

<select id="search" resultType="com.example.User">
    select * from users
        @{and, name = :name}
        @{and, age = :age}
        @{and, email = :email}
</select>

XML 标签

使用 <where> + <if> 标签，<where> 会自动去除首个多余的 AND/OR。

<select id="search" resultType="com.example.User">
    select * from users
    <where>
        <if test="name != null">AND name = #{name}</if>
        <if test="age != null">AND age = #{age}</if>
        <if test="email != null">AND email = #{email}</if>
    </where>
</select>

集合 IN 查询

使用规则（推荐）

使用 @{in} 规则，自动将集合参数展平为 IN (?, ?, ...)。

<select id="selectByIds" resultType="com.example.User">
    select * from users
    where id in @{in, :ids}
</select>

XML 标签

使用 <foreach> 标签遍历集合生成 IN 子句。

<select id="selectByIds" resultType="com.example.User">
    select * from users where id in
    <foreach collection="ids" item="id" open="(" separator="," close=")">
        #{id}
    </foreach>
</select>

动态更新

使用规则（推荐）

使用 @{set} 规则，参数为空时自动跳过，自动管理逗号分隔符。

<update id="updateUser">
    update users
    set update_time = now()
        @{set, name = :name}
        @{set, email = :email}
    where id = :id
</update>

XML 标签

使用 <set> + <if> 标签，<set> 会自动去除末尾多余的逗号。

<update id="updateUser">
    update users
    <set>
        update_time = now(),
        <if test="name != null">name = #{name},</if>
        <if test="email != null">email = #{email},</if>
    </set>
    where id = #{id}
</update>

了解更多动态 SQL

• 语句生成规则 — 完整的规则清单，包括 @{and}、@{or}、@{in}、@{set}、@{case}、@{macro} 等。
• 动态 SQL 标签 — XML 标签详细用法（<if>、<choose>、<where>、<set>、<foreach> 等）。

关联接口

通过 @RefMapper 将接口方法映射到 XML 中的语句

@RefMapper("/mapper/userMapper.xml")
public interface UserMapper {
    int insertUser(User user);
    User selectById(@Param("id") int id);
    List<User> selectAll();
    int updateEmail(@Param("id") int id, @Param("email") String email);
    int deleteById(@Param("id") int id);
}

创建和使用

加载 Mapper 并通过接口或 Session 调用

Configuration config = new Configuration();
Session session = config.newSession(dataSource);

// 方式一：通过接口调用（推荐）
UserMapper mapper = session.createMapper(UserMapper.class);
User user = mapper.selectById(1);

// 方式二：通过 Session 直接调用（使用 namespace.id）
List<User> list = session.queryStatement("com.example.UserMapper.selectAll", null);

有关 文件 Mapper 的详细信息，请参阅：

• Mapper 文件