MyBatis Parameter ‘list‘ not found. Available parameters are [cars, param1] 错误详解

MyBatisParameter ‘list‘ not found. Available parameters are [cars, param1]错误详解一、错误现象运行测试时抛出异常org.apache.ibatis.binding.BindingException: Parameter list not found. Available parameters are [cars, param1]错误位置在com.xie.mapper.CarMapper.insertMore方法。二、错误含义这个错误表明MyBatis 在解析 XML 中的foreach标签时试图从参数中获取名为list的值但实际传入的参数中只有cars和param1两个可用参数不存在list这个名称。错误信息中的Available parameters are [cars, param1]明确告诉你当前方法可用的参数名是cars和param1但你用了list。三、根本原因分析3.1 代码示例错误情况你的 Mapper 接口中可能定义了这样的方法publicinterfaceCarMapper{// ❌ 错误使用了 Param(cars)但 XML 中用了 collectionlistintinsertMore(Param(cars)ListCarcarList);}对应的 XML 映射中使用了foreach标签insertidinsertMoreINSERT INTO t_car (car_num, brand, guide_price, produce_time, car_type) VALUESforeachcollectionlistitemcarseparator,(#{car.carNum}, #{car.brand}, #{car.guidePrice}, #{car.produceTime}, #{car.carType})/foreach/insert测试代码Testpublicvoidtest6(){ListCarcarListArrays.asList(newCar(京A11111,宝马,30.0,2024-01-01,燃油车),newCar(京A22222,奔驰,45.0,2024-01-02,燃油车));// ❌ 调用时传入的是 carListcarMapper.insertMore(carList);}3.2 执行流程方法参数上有Param(cars)MyBatis 将参数放入 Map 时Key 为cars同时也会用param1作为备用 Key。XML 中collectionlistMyBatis 去 Map 中查找 Key 为list的值找不到。抛出Parameter list not found异常并提示可用参数为[cars, param1]。四、解决方案方案一修改 XML 中的collection属性推荐将collection改为Param注解的值insertidinsertMoreINSERT INTO t_car (car_num, brand, guide_price, produce_time, car_type) VALUES!-- ✅ 将 list 改为 cars与 Param(cars) 一致 --foreachcollectioncarsitemcarseparator,(#{car.carNum}, #{car.brand}, #{car.guidePrice}, #{car.produceTime}, #{car.carType})/foreach/insert方案二去掉Param注解使用默认名称// 去掉 Param 注解intinsertMore(ListCarcarList);此时 MyBatis 会使用list作为默认 KeyXML 中可以继续使用collectionlist。foreachcollectionlistitemcarseparator,方案三使用param1作为 collection!-- 不推荐可读性差 --foreachcollectionparam1itemcarseparator,五、参数命名规则速查表场景方法签名XML 中可用的collection值有Param(xxx)int insert(Param(cars) ListCar list);cars推荐无ParamListint insert(ListCar list);list无ParamArrayint insert(Long[] ids);array无ParamSetint insert(SetLong ids);collection使用Param 默认int insert(Param(cars) ListCar list);param1不推荐六、常见易错点总结1. ❌Param注解名与collection不一致Param(cars)ListCarcarListforeachcollectionlist!-- 错误应该用 cars --2. ❌ 误用默认名称Param(cars)ListCarcarListforeachcollectioncars!-- 正确 --3. ❌ 无Param时用了自定义名称ListCarinsertBatch(ListCarcarList);// 无 ParamforeachcollectioncarList!-- 错误应该用 list --4. ✅ 推荐做法intinsertMore(Param(cars)ListCarcarList);foreachcollectioncarsitemcarseparator,七、修正后的完整代码7.1 Mapper 接口publicinterfaceCarMapper{/** * 批量插入车辆 * param carList 车辆列表 * return 插入条数 */intinsertMore(Param(cars)ListCarcarList);}7.2 XML 映射insertidinsertMoreINSERT INTO t_car (car_num, brand, guide_price, produce_time, car_type) VALUESforeachcollectioncarsitemcarseparator,(#{car.carNum}, #{car.brand}, #{car.guidePrice}, #{car.produceTime}, #{car.carType})/foreach/insert7.3 测试代码Testpublicvoidtest6(){ListCarcarListArrays.asList(newCar(京A11111,宝马,30.0,2024-01-01,燃油车),newCar(京A22222,奔驰,45.0,2024-01-02,燃油车),newCar(京A33333,奥迪,35.0,2024-01-03,燃油车));introwscarMapper.insertMore(carList);System.out.println(插入条数rows);sqlSession.commit();}八、错误排查流程图┌─────────────────────────────────────────────────────────────────┐ │ BindingException: Parameter xxx not found │ │ Available parameters are [a, b, param1, ...] │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Step 1: 查看 XML 中 foreach 的 collection 属性值 │ │ 当前值list │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Step 2: 查看 Mapper 接口方法的 Param 注解 │ │ 当前Param(cars) │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Step 3: 对比 collection 值与 Param 值 │ │ list ≠ cars → 不一致 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 解决方案统一 collection 与 Param 名称 │ │ 方案Acollectioncars推荐 │ │ 方案B去掉 Param使用 list │ └─────────────────────────────────────────────────────────────────┘九、总结速查表错误信息根本原因解决方案Parameter list not found. Available parameters are [cars, param1]XML 中collectionlist但方法参数使用了Param(cars)将collection改为carsParameter xxx not found. Available parameters are [list, param1]使用了自定义名称但方法无Param用list或加ParamReturn value (3) was not iterable传入单个值但 XML 用了foreach改用或传入集合结语Parameter xxx not found错误是 MyBatis 中参数绑定最常见的问题之一。核心原则是XML 中collection属性的值必须与方法参数或Param注解的名称保持一致。记住两条黄金法则如果方法参数有Param(xxx)XML 中用collectionxxx。如果方法参数没有Param对于List使用list对于Array使用array。养成使用Param注解并保持命名一致的习惯可以避免 90% 以上的参数绑定问题。