MyBatis 对单个简单类型参数的默认处理详解

在 MyBatis 的 Mapper 接口中，当方法只有一个参数，并且该参数是简单类型 （如 String、Integer、Long、Date 等）时，MyBatis 的处理机制与 POJO 或 Map 有显著不同。

理解这一点，可以帮你避免在 XML 中因参数名写错而导致的 Parameter 'xxx' not found 等异常，也能让你写出更简洁的代码。

下面我将从核心规则、底层原理、#{} 与 ${} 的差异 以及最佳实践四个方面详细拆解。

一、核心规则：参数名称"形同虚设"

规则：当方法只有一个简单类型参数时，#{} 中的名称可以是任意字符串（如 #{id}、#{value}、#{abc}），MyBatis 不会校验名称是否与方法参数名一致，而是直接将传入的参数值传递给 SQL 占位符。

1.1 代码示例

Mapper 接口：

java 复制代码

public interface UserMapper {
    // 方法只有一个参数，且为 String 类型
    User selectByUsername(String username);
}

XML 映射（无论写成哪种都能正常运行）：

xml 复制代码

<!-- 写法 1：名称与参数名一致（推荐） -->
<select id="selectByUsername" resultType="User">
    SELECT * FROM user WHERE username = #{username}
</select>

<!-- 写法 2：名称任意（也能运行） -->
<select id="selectByUsername" resultType="User">
    SELECT * FROM user WHERE username = #{abc}
</select>

<!-- 写法 3：即使写成 value 或任何单词 -->
<select id="selectByUsername" resultType="User">
    SELECT * FROM user WHERE username = #{xyz123}
</select>

以上三种写法均可以正常运行 ，传入的 username 值都会正确替换 ? 占位符。

1.2 为什么会这样？

因为 MyBatis 在处理单个简单类型参数且未使用 @Param 注解时，会忽略 #{} 中的名字 。它只关心参数的数量 和参数的位置 。它知道只有一个参数，只要遇到 #{}，就把这个唯一的参数值放在那里。

二、底层原理：为什么不报错？

MyBatis 的参数解析由 ParamNameResolver 类负责。处理流程如下：

检查是否有 @Param 注解 ：
- 如果参数上有 @Param("username")，则必须以该注解的值为 Key（即必须写 #{username}），否则报错。
如果没有任何 @Param 注解 ：
- MyBatis 判断参数数量。
- 如果参数数量为 1 ：将该参数放入 Map 时，既会使用索引键（arg0 / param1），也会存储这个值。当解析 #{} 时，MyBatis 发现 Map 中没有对应的 Key，但发现参数数量只有 1 个，因此直接取唯一的参数值进行替换。这就是名称可以随便写的底层原因。
- 如果参数数量大于 1 （且没有 @Param）：MyBatis 只能用 arg0、arg1 或 param1、param2 作为 Key。此时如果你写 #{username}，在 Map 中找不到 username 这个 Key，就会抛出 Parameter 'username' not found 异常。

三、必须注意的陷阱：`${}` 与单个简单类型参数

虽然 #{} 允许随便写名字，但 ${} 在默认情况下（没有 @Param）却不行！

3.1 `${}` 的默认隐式命名

当使用 ${} 且没有 @Param 时，MyBatis 不会自动忽略名称，它必须找到 Map 中确切的 Key。默认情况下，唯一的 Key 是 value （或 _parameter）。

示例：

xml 复制代码

<!-- 错误写法：会报错 Parameter 'tableName' not found -->
<select id="getTableData" resultType="User">
    SELECT * FROM ${tableName}
</select>

正确写法（必须写 value 或 _parameter）：

xml 复制代码

<select id="getTableData" resultType="User">
    SELECT * FROM ${value}
</select>

3.2 如何让 `${}` 也能自定义名字？

解决方法 ：使用 @Param 注解。

java 复制代码

public interface UserMapper {
    // 加上 @Param 注解
    User getTableData(@Param("tableName") String tableName);
}

此时 XML 中就可以写 FROM ${tableName} 了。

四、对比总结：`#{}` vs `${}`

场景	`#{}`（预编译占位符）	`${}`（字符串替换）
无 `@Param` 单参数	名称可任意（如 `#{abc}`）	只能用 `value` （如 `${value}`）
有 `@Param` 单参数	必须用 `@Param` 指定的名称	必须用 `@Param` 指定的名称
是否防 SQL 注入	✅ 安全	❌ 不安全
适用场景	传参值（WHERE、INSERT 值）	表名、列名、ORDER BY 字段

五、实战建议与最佳实践

强烈推荐给单参数加上 @Param 注解 虽然不加也能运行，但加上 @Param 后：
- 可以在 #{} 和 ${} 中统一使用自定义名称，无需记 value 这种特殊规则。
- 增强可读性，方便后续维护（即使未来参数增加，也不易出错）。
- 避免因为 #{} 名称写错而导致的潜在混淆。
java 复制代码
```
User selectByUsername(@Param("username") String username);
```
无论是 #{} 还是 ${}，尽量保持名称与参数名一致 即使 MyBatis 允许随便写，但为了代码的可维护性和团队协作的规范性，建议统一使用有意义的名称（如 #{username}）。
如果确定是单参数且永远不扩展，可以省略 @Param 但前提是绝对不要使用 ${} ，只使用 #{}，且代码极其简单，不担心未来维护成本。

六、总结

情况	写法是否合法	推荐做法
单参数 + `@Param`	`#{name}`（必须匹配注解值）	✅ 推荐
单参数 + 无 `@Param` + `#{}`	`#{任意名称}`（均可）	⚠️ 可用，但可读性差
单参数 + 无 `@Param` + `${}`	只能用 `${value}`	❌ 极易踩坑，不推荐

一句话总结 ：为了避免记忆负担和潜在 bug，无论参数多少、类型如何，建议在所有 Mapper 接口方法的参数上都加上 @Param 注解。这是 MyBatis 开发中最重要的最佳实践之一。

MyBatis 对单个简单类型参数的默认处理详解