问题分析​

遇到 org.mybatis.spring.MyBatisSystemException 嵌套 org.apache.ibatis.exceptions.PersistenceException 异常，通常表示 MyBatis 在执行 SQL 过程中遇到了不可预期的错误。以下是可能的原因及解决方案：

---

​1. SQL 语法或参数错误​

​表现​

• 异常信息中包含 Bad SQL grammar 或 Parameter index out of range。
• 日志中打印的 SQL 语句有明显语法错误（如缺少逗号、表名/列名拼写错误）。

​解决方案​

1. ​检查 SQL 语句​：

   • 在数据库客户端（如 MySQL Workbench）中直接运行 MyBatis 生成的 SQL，验证语法正确性。
   • 动态 SQL（如 <if>、<foreach>）需检查条件分支是否覆盖所有场景。

   <!-- 示例：检查动态SQL条件 -->
   <select id="selectUsers" resultType="User">
       SELECT * FROM user
       <where>
           <if test="name != null">
               AND name = #{name}
           </if>
       </where>
   </select>

2. ​参数绑定​：

   • 确认 Mapper 接口方法参数与 XML 中的 #{param} 名称一致。
   • 使用 @Param 注解明确参数名：

     List<User> selectUsers(@Param("userName") String name);

---

​2. 结果集映射错误​

​表现​

• 异常信息中包含 ResultMap 或 Unknown column in result set。
• 返回的数据库字段与 Java 实体类属性不匹配。

​解决方案​

1. ​**检查 resultMap 或 resultType**​：

   • 确保 resultMap 中定义的列名与数据库查询结果一致。
   • 使用 as 别名解决列名与属性名不一致问题：

     <select id="selectUser" resultType="User">
         SELECT user_name AS userName, age FROM user
     </select>

2. ​开启驼峰命名映射​：

   • 在 application.properties 中配置：

     mybatis.configuration.map-underscore-to-camel-case=true

---

​3. 数据库连接或事务问题​

​表现​

• 异常信息中包含 Connection is closed 或 Timeout。
• 事务未提交或回滚导致资源锁定。

​解决方案​

1. ​检查数据库连接配置​：

   • 确认 application.properties 中的数据库 URL、用户名、密码正确：

     spring.datasource.url=jdbc:mysql://localhost:3306/mydb?useSSL=false
     spring.datasource.username=root
     spring.datasource.password=123456

2. ​验证连接池配置​：

   • 调整连接池参数（如 HikariCP）：

     spring.datasource.hikari.maximum-pool-size=10
     spring.datasource.hikari.connection-timeout=30000

3. ​检查事务管理​：

   • 在需要事务的方法上添加 @Transactional：

     @Transactional
     public void updateUser(User user) {
         userMapper.update(user);
     }

---

​4. MyBatis 配置错误​

​表现​

• 异常信息中包含 Invalid bound statement (not found)。
• Mapper XML 文件未被扫描或加载。

​解决方案​

1. ​确认 Mapper 扫描路径​：

   • 在启动类或配置类中添加 @MapperScan：

     @SpringBootApplication
     @MapperScan("com.example.mapper")
     public class App { ... }

2. ​检查 XML 文件位置​：

   • 确保 application.properties 中指定了 XML 文件路径：

     mybatis.mapper-locations=classpath:mapper/*.xml

---

​5. 依赖冲突​

​表现​

• 异常信息中包含 ClassNotFoundException 或 NoSuchMethodError。
• 项目依赖中存在多个 MyBatis 或数据库驱动版本。

​解决方案​

1. ​统一依赖版本​：

   • 在 pom.xml 中排除冲突依赖：

     <dependency>
         <groupId>com.example</groupId>
         <artifactId>some-module</artifactId>
         <exclusions>
             <exclusion>
                 <groupId>org.mybatis</groupId>
                 <artifactId>mybatis</artifactId>
             </exclusion>
         </exclusions>
     </dependency>

2. ​检查依赖树​：

   • 使用 Maven 命令分析依赖：

     mvn dependency:tree

---

​6. 日志调试​

​启用 MyBatis 详细日志​

1. 在 application.properties 中开启调试日志：

   logging.level.com.example.mapper=DEBUG

2. 观察控制台输出的完整 SQL 及参数，定位具体错误位置。

---

​示例：排查流程​

1. ​查看完整异常堆栈​：

   Caused by: org.apache.ibatis.exceptions.PersistenceException: 
   ### Error querying database. Cause: java.sql.SQLSyntaxErrorException: Unknown column 'user_name' in 'field list'

   • ​结论​：数据库表中无 user_name 列，需修改 SQL 或表结构。

2. ​检查实体类与表结构​：

   public class User {
       private String userName; // 对应数据库列名应为 user_name 或 userName
   }

---

​总结​

通过以下步骤定位并解决问题：

1. ​阅读异常堆栈​：关注 Caused by 后的根本原因。
2. ​检查 SQL 和映射​：确保 SQL 语法、参数绑定、结果集映射正确。
3. ​验证配置​：数据库连接、事务、Mapper 扫描路径。
4. ​依赖管理​：排除版本冲突。
5. ​日志分析​：通过详细日志追踪执行过程。