Mapper 接口定义

Mapper 接口是 MyBatis 的核心组件，定义了数据库操作的抽象方法。正确定义接口方法是保证接口绑定的前提。

接口基本结构

package com.example.mapper;

import com.example.entity.User;
import java.util.List;
import org.apache.ibatis.annotations.Param;

public interface UserMapper {

    // 查询操作
    User selectById(Long id);
    List<User> selectAll();
    List<User> selectByStatus(Integer status);

    // 插入操作
    int insert(User user);
    int batchInsert(List<User> users);

    // 更新操作
    int updateById(User user);

    // 删除操作
    int deleteById(Long id);
}

接口方法定义需遵循三个对齐原则：方法名对齐、返回类型对齐、参数对齐。

方法名与 XML statement id 匹配

接口方法名必须与 XML 中对应 SQL 语句的 id 属性完全一致：

// 接口定义
public interface UserMapper {
    User selectById(Long id);
}

<!-- XML 映射 -->
<mapper namespace="com.example.mapper.UserMapper">
    <!-- id 必须与方法名一致 -->
    <select id="selectById" resultType="com.example.entity.User">
        SELECT * FROM user WHERE id = #{id}
    </select>
</mapper>

返回类型匹配

返回类型决定了 MyBatis 如何将结果集映射为 Java 对象：

单个对象

User selectById(Long id);

对应 XML 使用 resultType 或 resultMap：

<select id="selectById" resultType="com.example.entity.User">
    SELECT * FROM user WHERE id = #{id}
</select>

列表结果

List<User> selectAll();

<select id="selectAll" resultType="com.example.entity.User">
    SELECT * FROM user
</select>

注意：XML 中仍然写 resultType 而非 resultType="List"，MyBatis 会根据接口返回类型自动判断。

影响行数

int insert(User user);
int updateById(User user);
int deleteById(Long id);

<insert id="insert" parameterType="com.example.entity.User">
    INSERT INTO user (username, email) VALUES (#{username}, #{email})
</insert>

void 返回

void updateStatus(@Param("id") Long id, @Param("status") Integer status);

<update id="updateStatus">
    UPDATE user SET status = #{status} WHERE id = #{id}
</update>

常见返回类型对照表

参数匹配

单参数

User selectById(Long id);

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

单参数时，XML 中 #{} 内的名称可任意写，推荐使用参数语义化名称。

多参数

// 方式一：使用 @Param 注解（推荐）
List<User> selectByCondition(@Param("status") Integer status,
                              @Param("keyword") String keyword);

<select id="selectByCondition" resultType="User">
    SELECT * FROM user
    <where>
        <if test="status != null">
            AND status = #{status}
        </if>
        <if test="keyword != null and keyword != ''">
            AND username LIKE CONCAT('%', #{keyword}, '%')
        </if>
    </where>
</select>

// 方式二：使用 Map 参数
List<User> selectByMap(Map<String, Object> params);

<select id="selectByMap" resultType="User">
    SELECT * FROM user
    <where>
        <if test="status != null">AND status = #{status}</if>
        <if test="keyword != null">AND username LIKE #{keyword}</if>
    </where>
</select>

// 方式三：使用对象参数
List<User> selectByUser(User query);

<select id="selectByUser" resultType="User">
    SELECT * FROM user
    <where>
        <if test="status != null">AND status = #{status}</if>
        <if test="username != null">AND username LIKE #{username}</if>
    </where>
</select>

参数错误示例

// 错误：多参数未使用 @Param，XML 中无法正确引用
List<User> selectByCondition(Integer status, String keyword);

<!-- XML 中 status 和 keyword 无法区分，MyBatis 会使用 arg0, arg1 或 param1, param2 -->
<select id="selectByCondition" resultType="User">
    SELECT * FROM user WHERE status = #{status}  <!-- 找不到 status 参数 -->
</select>
<!-- 抛出：BindingException 或 PropertyNotFoundException -->

解决：多参数必须使用 @Param 注解标注。

正确与错误定义对比

正确定义

public interface UserMapper {
    User selectById(Long id);                         // 方法名匹配，返回类型正确
    List<User> selectByStatus(@Param("status") Integer s); // 多参数使用 @Param
    int insert(User user);                            // 影响行数用 int
}

<mapper namespace="com.example.mapper.UserMapper">
    <select id="selectById" resultType="User">SELECT * FROM user WHERE id = #{id}</select>
    <select id="selectByStatus" resultType="User">SELECT * FROM user WHERE status = #{status}</select>
    <insert id="insert" parameterType="User">INSERT INTO user (username) VALUES (#{username})</insert>
</mapper>

错误定义

public interface UserMapper {
    // 错误1：方法名与 XML id 不一致
    User findById(Long id);

    // 错误2：返回类型与 SQL 不匹配（SELECT 多条却返回单个对象）
    User selectAll();

    // 错误3：多参数未使用 @Param
    List<User> selectByNameAndStatus(String name, Integer status);
}

要点总结

• 接口方法名必须与 XML 中 statement id 完全一致
• 返回类型需与 SQL 结果匹配：单对象、List、int、void 等
• 多条记录查询 XML 仍写 resultType，MyBatis 自动识别 List
• 多参数必须使用 @Param 注解，否则 XML 中无法正确引用
• 单参数时 XML 中 #{ } 名称可任意写，建议语义化
• 接口需通过 @Mapper 或 @MapperScan 注册到 MyBatis 容器