Java搭建MyBatis环境教程详解

本文深入解析了使用Java搭建MyBatis持久层环境时最常见、最易踩坑的四大核心问题：JDK 11+与MyBatis 3.4+的兼容性陷阱（尤其是JAXB移除导致的NoClassDefFoundError）、SqlSessionFactory构建失败的根源（classpath路径误用与XML加载方式错误）、MySQL 8驱动因缺失serverTimezone引发的静默连接失败，以及Mapper接口与XML绑定失效的隐蔽原因（namespace不匹配、注册路径错误、id大小写敏感等）。每一步都直击新手调试时“报错信息不明确、定位耗时长、网上方案治标不治本”的痛点，并给出经验证的现代解决方案和关键验证手段，助你避开90%的配置雷区，快速打通MyBatis开发第一关。

MyBatis 3.4+ 和 JDK 8+ 的版本兼容问题

MyBatis 3.4 开始不再支持 JDK 7，如果你用的是 JDK 11 或 JDK 17，别直接抄老教程里的 mybatis-3.2.8.jar——它会在启动时抛 java.lang.NoClassDefFoundError: javax/xml/bind/annotation/XmlRootElement。这不是你配置错了，是 JAXB 被 JDK 11 移除了。

解决方法很简单：用 MyBatis 官方推荐的现代组合。

• 选 mybatis-3.5.13（或更高） + mybatis-spring-2.0.7（对应 Spring 5.3+）
• 如果项目用 Maven，mybatis 本身不依赖 JAXB，但你的 spring-jdbc 或数据库驱动可能间接需要；JDK 11+ 下需显式加 jakarta.xml.bind:jakarta.xml.bind-api
• 验证是否生效：启动后看日志里有没有 Creating a new SqlSessionFactory，而不是卡在类加载异常

SqlSessionFactoryBuilder.build() 报空指针的常见原因

新手最常卡在这一步：调 new SqlSessionFactoryBuilder().build(inputStream) 直接抛 NullPointerException，但 inputStream 明明没打印 null——其实是资源路径没对上。

MyBatis 默认只从 classpath 根目录找 mybatis-config.xml，不会自动扫描 src/main/resources 下的子文件夹。

• 确保配置文件放在 src/main/resources/mybatis-config.xml，不是 src/main/resources/config/mybatis-config.xml
• 用 Resources.getResourceAsStream("mybatis-config.xml") 加载，别用 new FileInputStream(...) —— 后者走的是文件系统路径，打包成 jar 后必然失败
• 检查 XML 是否有语法错误：比如 标签没闭合，或 缺了 default 属性，这时 build() 会静默失败再抛 NPE

MySQL 驱动 8.x 连接 URL 不写时区会连不上

用 mysql-connector-java:8.0.33 时，如果 jdbcUrl 还沿用老写法 jdbc:mysql://localhost:3306/test，启动会卡住几秒后报 Could not create connection to database server，根本看不到 SQL 执行。

这是 MySQL 8 强制要求服务端与客户端时区一致导致的，默认尝试读系统时区失败就放弃连接。

• 必须加上 serverTimezone=UTC 或 serverTimezone=Asia/Shanghai，完整写法：jdbc:mysql://localhost:3306/test?serverTimezone=UTC&useUnicode=true&characterEncoding=UTF-8
• & 是 HTML 实体，在 XML 配置里要写成 &，否则解析失败
• 别信某些博客说“加 useSSL=false 就行”——那是掩盖问题，真正根源是时区

Mapper 接口找不到对应的 XML 文件

写了 UserMapper.java，也写了 UserMapper.xml，但执行 session.selectList("selectUsers") 报 org.apache.ibatis.binding.BindingException: Invalid bound statement (not found)。

根本原因不是文件名没对上，而是 MyBatis 没把 XML 注册进 Configuration。

• mybatis-config.xml 里必须有 ，路径是 classpath 相对路径，不是包名
• XML 文件里的 namespace 必须和 Mapper 接口全限定名完全一致，比如 namespace="com.example.mapper.UserMapper"，少个 .mapper 都不行
• 接口方法名要和 XML 中 <select id="selectUsers"> 的 id 严格匹配，大小写敏感，不能靠 IDE 自动生成糊弄过去

这些地方任意一个出错，MyBatis 都不会报“找不到 XML”，而是等你真调方法时才甩出那个让人摸不着头脑的绑定异常。

终于介绍完啦！小伙伴们，这篇关于《Java搭建MyBatis环境教程详解》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！