PersistenceException是MyBatis的包装异常，真正原因需通过getCause()查看Caused by行；常见根源为SQL语法错误、BindingException或数据库连接失败，且XML注释必须用而非/ /，namespace与方法名须严格匹配。
PersistenceException 不是具体错误，而是 MyBatis 抛出的“异常包装纸”——它本身不告诉你问题在哪，只说“持久化环节崩了”。真正原因藏在它的 getCause() 里，常见的是 SQLException、IOException 或 BindingException。直接 catch 它却不看 cause，等于蒙眼修车。
查堆栈必须看 Caused by: 那一行
MyBatis 的 PersistenceException 几乎总是包装异常。IDE 控制台或日志里，别只扫第一行，往下翻到第一个 Caused by: ——那才是真凶。
- 如果是
Caused by: java.sql.SQLSyntaxErrorException：SQL 写错了，比如字段名拼错、用了保留字没加反引号 - 如果是
Caused by: org.apache.ibatis.binding.BindingException：Mapper 接口方法和 XML 中的id对不上，或 namespace 写错包路径 - 如果是
Caused by: java.net.ConnectException：数据库连不上，不是 SQL 问题，先别改 Mapper
一个典型日志片段：
org.apache.ibatis.exceptions.PersistenceException: ### Error querying database. Cause: java.sql.SQLSyntaxErrorException: Unknown column 'user_nam' in 'where clause' ### The error may exist in com/example/mapper/UserMapper.xml ### The error may involve com.example.mapper.UserMapper.selectById ### The error occurred while executing a query ### SQL: SELECT * FROM user WHERE user_nam = ? ### Cause: java.sql.SQLSyntaxErrorException: Unknown column 'user_nam' in 'where clause'这里真正要修的是
user_nam → user_name。
XML 映射文件里最隐蔽的坑：注释写法
MyBatis 的 XML 解析器不认 /* ... */，只认标准 XML 注释 <!-- ... -->。用错会导致整个 XML 解析失败，最终抛出 PersistenceException，但堆栈里往往不提“注释”二字。
- ❌ 错误写法：
<!--<select id="list" resultType="User">...</select>-->（这其实是合法的） - ❌ 更危险的写法：
/* <select id="list" ...> */</select>—— 这会让 MyBatis 把整段当纯文本，找不到<select></select>标签 - ✅ 正确写法：一律用
<!-- ... -->，且不要嵌套、不要跨行写在标签中间
namespace 和接口方法名必须严丝合缝
MyBatis 通过 namespace + id 唯一定位 SQL 片段。哪怕差一个字母、多一个空格、大小写不对，都会导致 PersistenceException: Mapped Statements collection does not contain value for ...。
-
namespace必须是接口的**全限定类名**，例如com.example.mapper.OrderMapper，不能漏包、不能写成OrderMapper - XML 中的
<select id="getById"></select>必须和接口中方法名getById()**完全一致**（Java 方法重载不算数，MyBatis 不识别参数差异） - Maven 资源过滤默认不处理
*.xml，如果用了${xxx}占位符又没配resources过滤，XML 会被污染，看似配置对，实则加载的是空文件
别跳过 ErrorContext 提供的现场线索
MyBatis 在抛 PersistenceException 前，会把关键上下文塞进 ErrorContext.instance()，包括：sql、resource（哪个 XML 文件）、object（哪个 Mapper 类）、activity（是查询还是更新）。这些信息就藏在异常的 message 里，不是堆栈，但常被忽略。
- 打印异常时别只用
e.toString()，改用e.getMessage()，能看到类似：### The error may exist in com/example/mapper/UserMapper.xml ### The error may involve com.example.mapper.UserMapper.selectList ### SQL: SELECT * FROM user WHERE id = ? - 如果你用 Logback/Log4j，开启 MyBatis 日志（
logging.level.org.apache.ibatis=DEBUG），它会自动打印绑定的参数值，比猜强十倍
真正卡住的时候，往往不是逻辑多复杂，而是把 Caused by: 当装饰、把 ErrorContext 当废话、把 XML 注释当 Java 注释——修掉这三个，八成的 PersistenceException 就自己消失了。
