1. 项目概述：一个困扰无数开发者的“小”问题
如果你用过MyBatis，尤其是在写DAO层接口方法时，大概率纠结过这个问题：一个方法需要传入多个参数，这个@Param注解，到底什么时候该加，什么时候可以不加？加了吧，感觉代码有点啰嗦；不加吧，运行时又可能直接给你抛个BindingException，告诉你参数找不到。这看似只是一个注解的使用规范问题，但背后牵扯到MyBatis参数绑定的核心机制、接口代理的实现原理，甚至是团队协作的编码习惯。我见过不少项目，因为这个问题没统一，导致同样的查询功能，A同事写的接口能跑，B同事抄过去改个参数名就报错，排查起来费时费力。今天，我们就彻底把这个问题掰开揉碎，不仅告诉你“怎么做”，更要讲清楚“为什么”，让你以后面对多参数传递时，心里有底，手下不慌。
2. 核心机制解析：MyBatis如何“认识”你的参数
要弄明白@Param的用武之地，首先得知道MyBatis在调用你的Mapper接口方法时，它眼里看到的参数到底是什么样的。这涉及到JDK动态代理和参数封装两个关键过程。
2.1 方法参数的“裸奔”与“包装”
当你定义一个Mapper接口方法，例如User selectUser(String name, Integer age);，并通过MyBatis的SqlSession去调用getMapper时，MyBatis会为这个接口生成一个代理对象。这个代理对象的方法调用，最终会被MapperProxy拦截，并将你的方法调用转换成一个MapperMethod的执行。
关键在于，Java在编译后，方法的参数名是会丢失的（除非你使用了-parameters编译参数）。在运行时，MyBatis看到的只是一个Object[]数组，里面按顺序存放着你传入的name和age的值。对于这个数组，MyBatis提供了两套主要的处理策略：
- 默认策略（无
@Param）：MyBatis会尝试用一些默认的逻辑来为这些参数起名字。在旧版本中，它可能使用param1,param2, ... 这样的通用名称；在支持-parameters编译选项且开启的情况下，它也可能尝试获取源码中的参数名。但这种方式不稳定，严重依赖编译环境和配置。 - 显式命名策略（使用
@Param）：你通过@Param("userName")明确告诉MyBatis：“这个参数，在SQL映射里就叫userName”。此时，MyBatis会将这些参数包装成一个ParamMap，这个Map的key就是你指定的注解值，value就是参数值。
所以，@Param的本质是一个命名指令，它解决了Java运行时无法直接获取方法参数名的问题，为SQL映射中的#{xxx}占位符提供了明确的、可靠的查找依据。
2.2 参数绑定的两种场景与底层逻辑
在XML映射文件或注解SQL中，我们通过#{参数名}来引用参数。MyBatis会根据这个“参数名”去它构建的参数上下文里查找。这个查找逻辑，根据你是否使用@Param，决定了它去哪个“仓库”里拿数据。
- 使用
@Param时：参数被放入一个ParamMap。你的SQL引用#{userName}，MyBatis就直接去这个Map里找key为"userName"的value。清晰直接，绝无二义性。 - 不使用
@Param时（多参数）：情况就复杂了。- 首先，MyBatis会尝试把整个参数数组包装成一个
ParamMap，但此时它会尝试用一些规则生成key，例如arg0,arg1,param1,param2。arg0和arg1是JDK8+引入的机制（同样需要-parameters支持），param1和param2是MyBatis自己的保底策略。 - 其次，MyBatis还会将参数数组本身作为一个可访问的对象。在某些版本或配置下，你甚至可以直接用
#{0},#{1}这样的索引来访问（但不推荐，可读性差且易出错）。
- 首先，MyBatis会尝试把整个参数数组包装成一个
这就引出了最常见的错误：你在XML里写了#{name}，但MyBatis在它构建的参数上下文中（可能是param1,arg0这样的key），根本找不到叫"name"的东西，于是抛出org.apache.ibatis.binding.BindingException: Parameter 'name' not found。
注意：这里有一个非常重要的特例。当你的方法只有一个参数时，无论这个参数是基本类型、String，还是复杂的POJO对象，MyBatis的处理都会简单很多。对于非POJO的单个参数，你可以不用
@Param，在SQL中直接用#{任意名字}引用（因为MyBatis知道就只有这一个值，不管叫啥都给它）。但对于POJO对象，通常直接使用其属性名，如#{id}。然而，一旦参数数量大于1，混乱和不确定性就大大增加了，这也是我们讨论的重点。
3. 实战指南：清晰规则与最佳实践
理论讲完，我们来看实战。到底该怎么用？我总结了一个清晰的决定链和一套推荐的最佳实践。
3.1 何时必须加@Param？—— 铁律三条
记住下面这三种情况，@Param是必须的，不加就会出错：
- Mapper接口方法包含多个参数：这是最核心的场景。例如
List<User> selectByCond(String name, Integer status, Date startTime);这三个参数都需要在SQL中使用，你就必须为它们分别添加@Param注解。 - 参数需要在动态SQL（如
<if>）中被引用：即使你的方法只有一个参数，但如果这个参数是一个集合或数组（例如List<Integer> ids），并且你要在<foreach>等标签中使用它，那么也必须添加@Param来指定集合的名称。因为MyBatis对集合类型的单个参数有特殊处理规则，不指定名称会导致引用失败。 - SQL中使用了
${}进行字符串替换（不推荐但存在）：${}是直接拼接字符串，同样需要明确的参数名来定位值。虽然我们强烈建议优先使用#{}来防止SQL注入，但如果你不得不使用${}，参数命名是必须的。
3.2 何时可以不加@Param？—— 安全区
在以下相对安全的情况下，你可以省略@Param：
- 方法只有一个且仅有一个参数，并且这个参数是一个POJO（Java Bean）。此时，在SQL中可以直接使用POJO的属性名。例如，方法
int insertUser(User user);，在XML中可以用#{id},#{name}等。 - 方法只有一个参数，且是Map类型。此时，你可以直接使用Map的key作为参数名。例如，方法
int updateByMap(Map<String, Object> params);，SQL中可以用#{userId},#{userName}（假设Map中有这些key）。 - 你明确使用了
-parameters编译选项，并且团队所有人都清楚这一约定，且项目未来不会改变编译环境。在这种情况下，MyBatis可以获取到实际的参数名。但请注意，这会将项目绑定到特定的构建配置上，降低了可移植性，对于需要多环境构建或对外提供SDK的项目风险较高。
3.3 强烈推荐的最佳实践
基于多年的踩坑经验，我推荐以下实践，这能让代码最清晰、最健壮、最可维护：
规则一：只要方法参数大于等于2个，无脑给每个参数加上@Param注解。
不要纠结，不要尝试去依赖param1或者arg0。显式的命名是最清晰的文档。例如：
User selectUser(@Param("username") String name, @Param("userAge") Integer age, @Param("state") Integer status);在XML中，对应使用#{username},#{userAge},#{state}。参数名和SQL中的占位符名称可以不同，但通过注解建立了明确的映射关系。
规则二：即使单个参数是集合或数组，也加上@Param。
这能彻底避免在动态SQL<foreach>中引用时的歧义。例如：
List<User> selectByIds(@Param("idList") List<Long> ids);在XML中：
<select id="selectByIds" resultType="User"> SELECT * FROM user WHERE id IN <foreach collection="idList" item="id" open="(" separator="," close=")"> #{id} </foreach> </select>这里的collection="idList"就指向了@Param注解指定的名称。
规则三：为@Param起一个有意义的名字。
不要用a,b,c或者param1这样的名字。注解里的名字应该能清晰地表达这个参数的业务含义，例如@Param("startTime")就比@Param("st")好得多。这能极大提升SQL映射文件的可读性。
规则四：团队统一规范。
在项目伊始，就在团队内明确规定@Param的使用规范。是全部强制使用？还是遵循上述的“多参数必加”规则？统一的标准能避免不必要的沟通成本和隐蔽的Bug。
4. 深度避坑与高阶场景剖析
掌握了基本规则，我们来看看一些容易踩坑的细节和高阶用法，这些是很多官方文档不会细说，但在实际开发中经常碰到的问题。
4.1 与#{}和${}的纠葛
#{}与@Param：#{}是预编译占位符，@Param为其提供参数名。这是最安全、最标准的组合。无论参数是什么类型，@Param的名字就是#{}里引用的名字。${}与@Param：如前所述，${}是字符串替换，也需要@Param来定位参数值。但这里有个巨坑：${}替换时，如果参数值是字符串，它会去掉引号直接拼接。这意味着如果你的参数值来自用户输入，且未经过滤，将导致致命的SQL注入漏洞。因此，严禁将用户可控的输入通过${}拼接进SQL。${}仅可用于拼接一些绝对安全的、程序内部控制的元素，如动态表名、排序列名（也需做白名单校验）。
4.2 动态SQL中的参数引用
在<if>,<choose>,<foreach>,<bind>等动态SQL标签中，引用参数的规则与外部一致。
在
<if>的test表达式中：你需要使用_parameter这个特殊的参数来访问整个参数对象。如果使用了@Param，你可以通过@Param指定的名字来访问。例如，对于方法selectByCond(@Param("user") User user, @Param("role") String role)，在<if>中可以这样写：<if test="user.name != null and user.name != ''"> AND username = #{user.name} </if> <if test="role != null"> AND role = #{role} </if>注意，
test表达式里用的是OGNL语法，访问POJO属性直接用点号.。<foreach>的collection属性：这必须指向一个集合或数组对象。如果该集合是某个POJO的属性，则需要用属性名.集合属性的方式；如果该集合本身就是一个通过@Param命名的参数，则直接写注解的名字。这是最容易出错的地方之一。
4.3 与MyBatis-Plus等增强框架的配合
如果你在使用MyBatis-Plus，它的Wrapper查询方式（如QueryWrapper）在一定程度上减少了你手写SQL和参数绑定的需要。但是，当你需要自定义SQL方法，特别是需要传入Wrapper对象和其他参数时，@Param的规则依然适用。
MyBatis-Plus约定，在XML中引用Wrapper参数时，通常使用ew（也可以是ew1,ew2...如果你有多个）。因此，你的接口方法应该这样写：
List<User> selectPageWithCustom(@Param("ew") Wrapper<User> wrapper, @Param("extraStatus") Integer status);在XML中，你可以这样用：
<select id="selectPageWithCustom" resultType="User"> SELECT * FROM user ${ew.customSqlSegment} AND extra_column = #{extraStatus} </select>这里，${ew.customSqlSegment}用于拼接Wrapper生成的WHERE条件（注意是${}，因为Wrapper生成的是SQL片段字符串），而#{extraStatus}则正常引用另一个参数。
4.4 模糊查询与参数处理
一个常见的需求是模糊查询LIKE。很多人会直接在#{}里拼接百分号，如#{'%' + name + '%'}，这是错误的，#{}不支持字符串运算。正确的做法有几种：
- 在Java代码中拼接好：
String searchKey = "%" + keyword + "%";，然后将searchKey作为参数传入。简单直接。 - 在XML中使用
<bind>标签（推荐）：
接口方法：<select id="search" resultType="User"> <bind name="pattern" value="'%' + keyword + '%'"/> SELECT * FROM user WHERE username LIKE #{pattern} </select>List<User> search(@Param("keyword") String keyword);这种方式将拼接逻辑放在了XML里，保持了接口的简洁。 - 使用SQL的
CONCAT函数：LIKE CONCAT('%', #{keyword}, '%')。这种方式依赖于数据库的函数支持，但写法也很清晰。
5. 常见问题排查与调试技巧
即使规则都懂了，实战中还是会遇到各种诡异的问题。这里我记录了几个最常见的报错和排查思路。
5.1 典型错误与解决方案速查表
| 错误信息或现象 | 可能原因 | 解决方案 |
|---|---|---|
BindingException: Parameter ‘xxx’ not found | 1. SQL中引用的参数名xxx，在MyBatis构建的参数上下文中不存在。2. 多参数方法未使用 @Param，却试图用参数名引用。3. 使用了 @Param，但注解里的名字和SQL中引用的名字不一致。 | 1. 检查方法参数个数。>1个则必须为每个参数添加@Param。2. 核对 @Param(“注解名”)与SQL中#{占位名}是否完全一致（区分大小写）。3. 开启MyBatis日志，查看运行时真正的参数映射。 |
集合参数在<foreach>中报错，提示Collection ‘ids‘ not found | 单个集合/数组参数未加@Param，在动态SQL中无法正确识别。 | 为集合参数添加@Param注解，如@Param(“idList”)，并在XML的<foreach collection=”idList”>中使用该名称。 |
参数值为null时，动态SQL<if>判断失效 | 在<if test=”param != null”>中，如果param是基本类型（如int），其值不可能为null，判断会走入错误分支。建议使用包装类型（如Integer）。 | 接口方法中，对于可能为空的参数，一律使用包装类型（Integer,Long,Boolean等），而非基本类型（int,long,boolean）。 |
| 日志中看到传入的参数值正确，但查询结果不对或条件未生效 | 1.#{}和${}误用。2. 参数名与POJO属性名或Map的key名不匹配。 3. 动态SQL的 test表达式写错（例如用了==而不是eq，虽然某些版本支持，但OGNL推荐eq）。 | 1. 确认使用的是#{}。2. 仔细核对参数名，注意大小写。 3. 检查 <if test>表达式，使用OGNL推荐语法，如==比较字符串可能有问题，建议用eq或.equals()。 |
5.2 调试利器：开启MyBatis完整日志
当参数绑定问题让你一头雾水时，最有效的办法是查看MyBatis执行时的真实情况。在application.yml或mybatis-config.xml中配置以下日志级别：
logging: level: org.mybatis: DEBUG # 或者更细粒度地指定你的Mapper接口所在包 com.yourpackage.mapper: DEBUG这样，控制台会打印出详细的SQL执行日志，包括替换前的SQL语句（带?占位符）和替换时传入的每个参数的具体值和类型。通过对比日志中实际绑定的参数名和你XML中写的参数名，可以瞬间定位问题所在。
5.3 关于编译参数-parameters的取舍
从Java 8开始，可以通过在编译时添加-parameters选项来保留方法参数名。对于Maven项目，可以在pom.xml的编译器插件中配置：
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <compilerArgs> <arg>-parameters</arg> </compilerArgs> </configuration> </plugin>开启后，对于单参数方法，理论上可以不用@Param。但我个人仍然不推荐依赖这个特性作为主要开发方式。原因有三：第一，它增加了项目构建配置的复杂性；第二，并非所有IDE和构建工具链都默认支持，可能带来环境不一致问题；第三，也是最关键的，显式的@Param注解本身就是一种代码自文档，任何人看到方法签名，立刻就知道SQL中该用什么名字去引用参数，无需任何额外配置或知识。为了代码的清晰性和可维护性，牺牲一点打字的麻烦是完全值得的。
最后，我的个人体会是，在MyBatis多参数传递这个问题上，采取“多参数必加@Param”这条最简单的规则，能规避掉95%以上的相关Bug。清晰的约定胜过灵活的诡计，尤其是在团队协作中。把这个规则作为团队规范定下来，你会发现DAO层的代码会变得稳定和易于理解很多。
