MyBatis-Plus 分页查询@Param 注解

前言

在 SpringBoot + MyBatis-Plus 的后端开发中，分页查询是最常用的功能之一。很多新手在编写 Mapper 接口时，都会遇到和你一样的困惑：

Page<PaymentOrderVO> selectRevenuePaymentOrderPage(
    Page<PaymentOrderVO> page,
    @Param("query") PaymentOrderPageQueryDTO query
);

• 这个方法到底是1 个参数还是 2 个参数？
• 为什么query必须加@Param，page却不用加？
• 不写@Param到底行不行？

---

MyBatis 核心规则：多参数必须加 @Param

1. 基础规则

• 单参数 ：可以不加@Param
• 多参数（2 个及以上） ：业务参数必须加@Param("别名")

2. 为什么必须加？

MyBatis 底层无法直接识别参数名，多参数时会自动把参数重命名为：

arg0、arg1、param1、param2

如果不加@Param("query")，你的 XML 文件就无法识别query这个名称：

<!-- 不加@Param，这里会报错，MyBatis不认识query -->
WHERE status = #{query.status}

加了@Param("query")，相当于给参数起别名，XML 就能正常取值。

---

特殊疑问：Page 参数为什么不用加 @Param？

这是 MyBatis-Plus 的专属特性，也是最容易疑惑的点！

参数	身份	处理方	是否需要在 XML 手写	是否需要 @Param
Page<T> page	MP内置分页对象	MyBatis-Plus 自动处理	❌ 不需要	❌ 不需要
QueryDTO query	自定义业务查询对象	开发者手动在 XML 使用	✅ 必须写	✅ 必须加

直白解释

1. Page是 MyBatis-Plus 的亲儿子 ，框架会自动识别它，自动拼接LIMIT分页 SQL，你完全不需要在 XML 里调用page的属性；
2. 既然 XML 里用不到它，就没必要给它起别名，自然不用加@Param；
3. 强行给page加@Param也不会报错，但完全多余。

---

实战验证：加与不加的区别

1. 正确写法

// 分页参数：MP自动处理，不加@Param
// 查询参数：XML要用，必须加@Param
Page<PaymentOrderVO> selectRevenuePaymentOrderPage(
    Page<PaymentOrderVO> page,
    @Param("query") PaymentOrderPageQueryDTO query
);

WHERE create_time BETWEEN #{query.beginTime} AND #{query.endTime}

2. 错误写法（报错）

// 多参数不加@Param，XML无法识别query
Page<PaymentOrderVO> selectRevenuePaymentOrderPage(
    Page<PaymentOrderVO> page,
    PaymentOrderPageQueryDTO query
);

报错原因：MyBatis 不认识query别名。

总结

1. MyBatis 多参数场景 ：自定义业务参数必须加@Param；
2. MyBatis-Plus 的Page分页参数 ：框架自动处理，永远不用加@Param；