MyBatis 不写 @Param 也能成功？一招教你验证 Maven 参数名保留机制

问题提出

在使用 MyBatis 时，发现 Mapper 接口的方法参数未添加 @Param 注解，但代码仍能正常运行。例如：

@Select("SELECT e.*, d.name AS deptName FROM emp e LEFT JOIN dept d ON e.dept_id = d.id LIMIT #{start}, #{pageSize}")
public List<Emp> list(Integer start, Integer pageSize); // 未使用 @Param

疑问：

1. 为什么省略 @Param 后参数仍能正确绑定？
2. 如何验证编译时是否启用了参数名保留机制（-parameters）？

解决步骤

1. 检查 Maven 编译配置

MyBatis 依赖方法参数名绑定 SQL 占位符（如 #{start}），而参数名保留需通过 -parameters 编译参数实现。以下是验证方法：

1. 生成有效 POM 文件
   在项目根目录执行以下命令，输出完整生效的 POM 配置：

   mvn help:effective-pom > effective-pom.xml

   生成 effective-pom.xml

2. 搜索 -parameters 配置
   打开生成的 effective-pom.xml，查找 maven-compiler-plugin 配置：

   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-compiler-plugin</artifactId>
     <version>3.13.0</version>
     <configuration>
       <parameters>true</parameters> <!-- 关键配置 -->
     </configuration>
   </plugin>

   • 若存在 <parameters>true</parameters>，表示已启用参数名保留。

2. 验证结果

通过上述步骤确认配置后，无需其他复杂检查（如反射或反编译）。

• 成功现象：MyBatis 能直接通过参数名（如 start, pageSize）绑定 SQL 占位符。
• 失败现象：未启用时，MyBatis 需依赖 @Param 或默认参数名（arg0, arg1）。

失败时-解决方法

1. 显式启用 -parameters

在 pom.xml 中配置 maven-compiler-plugin：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.13.0</version>
    <configuration>
        <parameters>true</parameters> <!-- 保留参数名 -->
    </configuration>
</plugin>

重新编译项目后，MyBatis 即可通过参数名自动绑定。

2. 代码适配规则

• 可省略 @Param 的场景：

  1. 方法参数名与 SQL 占位符名称完全一致。
  2. 确认 -parameters 已启用。

• 建议保留 @Param 的场景：

  1. 参数数量较多（如超过 3 个）。
  2. 参数类型为集合（如 List、Map）。
  3. 需要自定义参数名（如 @Param("offset") 对应 #{offset}）。

结论

1. 根本原因：

   • 项目通过 maven-compiler-plugin 的 <parameters>true</parameters> 启用了参数名保留机制，编译时会将方法参数名（如 start, pageSize）写入字节码，MyBatis 可直接读取。

2. 验证方式：

   • 仅需通过 mvn help:effective-pom 检查编译配置，无需其他复杂工具。

3. 最佳实践：

   • 简单场景：参数名清晰且与 SQL 一致时，可省略 @Param。
   • 复杂场景：显式使用 @Param 提高可读性。
   • 配置保障：始终显式启用 -parameters，避免依赖隐式行为。