一、引言

在 Java 后端开发中，MyBatis 作为半自动化的 ORM 框架，几乎是主流项目的标配 —— 而 Mapper 接口作为 Java 代码与 SQL 语句之间的 “桥梁”，参数传递则是这层桥梁中最容易出问题的环节。相信很多开发者都有过这样的经历：写好 Mapper 接口和 XML 中的 SQL，运行时却抛出 Parameter 'userId' not found 异常；单参数传参时一切正常，多参数传参就报错；甚至明明参数名一致，却依然无法映射……

这些问题的核心，几乎都指向 MyBatis 中一个看似简单却至关重要的注解 ——@Param。作为 Mapper 接口参数传递的 “核心开关”，@Param 注解的作用远不止 “给参数起个名字” 这么简单：它决定了 MyBatis 如何将接口方法的参数绑定到 SQL 中的占位符，也影响着参数传递的灵活性和代码的可读性。

但实际开发中，很多开发者对 @Param 的理解停留在 “多参数就加” 的浅层认知：要么不管场景一律加 @Param 导致代码冗余，要么该加不加引发参数映射异常，甚至对 “为什么单参数不需要加、多参数必须加”“实体类传参要不要加” 等问题一知半解。

今天这篇文章，我们就从 @Param 注解的核心原理出发，结合实际开发中的各种场景（单参数、多参数、实体类参数、集合参数等），详细拆解它的使用规则、底层实现逻辑，以及企业开发中的最佳实践，帮你彻底搞懂 Mapper 接口中 @Param 注解的所有细节，从此告别参数传递的各种坑。

二、不加@Param

@Param 不是 “万能必加项”，不加的后果完全取决于参数数量、参数类型、MyBatis 版本，核心是 “参数名能否被 MyBatis 正确识别并映射到 SQL”：

2.1 单参数（非集合 / 数组）

单参数（非集合 / 数组）→ 不加也正常

// Mapper 接口
User selectById(Long id);

// XML SQL
SELECT * FROM user WHERE id = #{id}

✅ 结果：正常运行💡

原因：MyBatis 对单个普通参数（基本类型 / 包装类 / 字符串 / 实体类），会忽略参数名，直接把参数值绑定到 SQL 中的占位符（哪怕写 #{xxx} 也能匹配，只是规范上要写参数名）。

2.2 多参数

多参数 → 不加必报错

// Mapper 接口（不加@Param）
User selectByUsernameAndPwd(String username, String password);

// XML SQL
SELECT * FROM user WHERE username = #{username} AND pwd = #{password}

❌ 结果：抛出 Parameter 'username' not found 异常💡

原因：MyBatis 对多参数会把参数封装成 Map，默认 key 是 param1、param2...（或 arg0、arg1...），而非你定义的 username/password，此时 SQL 中写 #{username} 必然找不到。

✅ 临时补救（不推荐）：SQL 中写 #{param1} #{param2} 也能运行，但可读性极差。

2.3 集合 / 数组参数 

集合 / 数组参数 → 不加可能报错

// Mapper 接口（不加@Param）
List<User> selectByIds(List<Long> ids);

// XML SQL（使用foreach）
SELECT * FROM user WHERE id IN 
<foreach collection="ids" item="id" open="(" close=")" separator=",">
    #{id}
</foreach>

❌ 结果：抛出 Parameter 'ids' not found 异常

💡 原因：MyBatis 对集合 / 数组有默认别名（List→list、数组→array），只有 SQL 中写 collection="list" 才会正常；若你写 collection="ids"，必须加 @Param("ids") 显式指定名称。

三、加@Param

Java 编译时默认会丢失方法参数名（比如编译后参数名变成 arg0、arg1），@Param 可以强制指定参数名，保证 SQL 能正确绑定到参数。

• 多参数传递：接口方法有 2 个及以上参数（无论类型），必须加 @Param 命名，比如 @Param("username") String username；
• 集合 / 数组参数自定义名称：若 SQL 中想自定义集合名称（如不用默认的 list/array），必须加 @Param("ids") List<Long> ids；
• 参数名与 SQL 占位符名不一致：比如接口参数名是 uid，但 SQL 中想写 #{userId}，需加 @Param("userId") Long uid；
• 动态 SQL 依赖参数名：比如 <if test="status != null"> 中的 status，若参数未加 @Param，MyBatis 无法识别这个名称，会报错。

注意：

如果传入的参数是一个实体类，不加@Param可以直接#{字段名}，如果加了@Param，需要#{实体类.字段名}

四、底层原理

@Param 的核心作用是给参数 “命名”，让 MyBatis 能通过名称找到对应的参数值，底层分 3 步：

4.1 参数封装（MyBatis 的 ParamNameResolver 类）

当调用 Mapper 方法时，MyBatis 会通过 ParamNameResolver 解析参数：

• 若参数加了 @Param("xxx")：将参数封装到 Map 中，key = xxx，value = 参数值；
• 若没加 @Param：
  • 单参数：直接把参数值存入 Map，key = 参数名（JDK8+ 可通过参数名反射获取）或 param1；
  • 多参数：key = param1、param2...（或 arg0、arg1...），value = 对应参数值。

4.2 SQL 参数绑定

MyBatis 解析 XML / 注解 SQL 中的 #{xxx} 时，会从上述 Map 中根据 xxx 查找值：

• 加了 @Param：能精准匹配 Map 中的 key，找到对应值；
• 没加 @Param（多参数）：Map 中无 xxx 这个 key，直接抛出 “参数未找到” 异常。

4.3 底层注解本质

@Param 是 MyBatis 自定义的注解（全类名：org.apache.ibatis.annotations.Param），仅包含一个 value() 方法，用于指定参数名称：

public @interface Param {
    String value(); // 唯一属性，指定参数名
}

它不属于 JDK 注解，仅在 MyBatis 解析 Mapper 接口时生效，运行时不会影响 JVM 执行逻辑。

五、IDEA

• JDK 8 及以上支持 “参数名反射”：编译时会把参数名（如 username）保留在字节码中，MyBatis 可通过反射获取参数名，无需 @Param 也能识别；
• IDEA 默认开启了 -parameters 编译参数：在 File → Settings → Build → Compiler → Java Compiler 中，IDEA 会自动添加 -parameters 选项，确保编译后的字节码保留参数名。

但这种方式不推荐（依赖编译配置，换环境可能失效），所以为了规范，所有的参数最好都加上@Param