如何用ibatis连接MySQL数据库，为什么必须上传驱动？

想让iBatis顺利连上MySQL，第一步就是把MySQL数据库连接驱动（mysql-connector-java的jar包）准确无误地放进项目的lib目录并配置好classpath路径，这看似简单的一步，却是绝大多数连接报错故障的源头。

我见过太多开发者在iBatis配置文件里折腾半天，最后发现根本问题就是驱动jar包没上传到位或者版本不匹配，今天我就把这条路上的坑全给你指出来，从驱动下载、上传路径到配置验证，一步不落，顺便把你关心的<iBatis连接MySQL数据库时驱动版本要对应哪个Mysql版本、MySQL数据库连接驱动怎么上传才能被识别这些高频疑问一并解开。

加载中

下载MySQL的JDBC驱动

潘1212

2.2万1531

原视频地址

驱动Jar包选择：不同MySQL版本适配有讲究

很多新手习惯随便下载一个最新版驱动包就完事，这种做法在iBatis这种老牌持久层框架上特别容易踩雷，MySQL驱动版本和数据库服务端版本存在兼容关系，虽然高版本驱动能连低版本数据库,但反过来低版本驱动连高版本数据库就会抛异常。

版本匹配的基本原则

• 连接MySQL 5.x系列，驱动选5.1.x版本比较稳妥。
• 连接MySQL 8.0及以上，驱动必须使用8.0.x版本,因为认证插件和连接协议都变了。
• 驱动jar包的命名规则，5.1.x的是mysql-connector-java-5.1.49.jar，8.0.x的是mysql-connector-java-8.0.33.jar，中间有version数字段，下载时别删掉版本号,很多配置路径写死了文件名。

下载渠道和校验

去MySQL官网的Connector/J下载页面，或者通过Maven中央仓库获取jar包，下载后随手校验一下文件大小和哈希值，防止下载损坏的包，从Maven中央仓库拉取时，直接在pom.xml里写依赖声明也可以，但传统iBatis项目更喜欢手动放置jar包,便于团队统一管理版本。

MySQL数据库连接驱动怎么上传：三种落地路径详解

驱动jar包拿到手后，上传到哪个目录决定了能不能被iBatis运行时加载到，三个常用位置，优先级别不同,效果也不同。

放进项目WEB-INF/lib目录（最传统）

对于war包部署的传统Java Web项目，把jar包复制到webapp/WEB-INF/lib/下面，Servlet容器启动时会自动加载这些库，操作路径就是打开项目目录，找到webapp或者src/main/webapp下的WEB-INF文件夹,把jar包拖进lib子目录。

这个方式的优势在于容器级管理，不用额外配置classpath,容器启动就知道去哪加载。

将jar包路径写入classpath环境变量（适用于独立应用）

如果你的iBatis是运行在独立Java应用里（不是Web项目），那就要手动把jar包路径配置到classpath里,在启动脚本中追加：

java -classpath .;mysql-connector-java-8.0.33.jar com.example.MainClass

或者在IDE的Run Configuration中，把jar包添加进项目的Libraries列表里，这一步骤里最容易出错的地方，就是classpath里路径分隔符，Windows用分号,Linux和Mac用冒号。

构建工具统一管理（Maven项目常用）

项目使用Maven的，在pom.xml中加入：

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

Maven会自动下载依赖并打包到最终的可运行jar中，但iBatis的SqlMapConfig.xml里配置驱动类时，依然要确保运行时能加载到驱动类，路径写全,不能只写版本号。

配置驱动连接：从SqlMapConfig到properties一一对应

jar包上传完毕，接下来就是在iBatis的配置文件里写对连接参数，这里面最容易混的就是驱动类的名字和URL格式,不同驱动版本写法略有差异。

驱动类全名别写错

连接MySQL时，<property name="driver" value="com.mysql.jdbc.Driver"/>是老写法，只适用于5.x驱动。

MySQL 8.x驱动里，驱动类改名为com.mysql.cj.jdbc.Driver，如果还在用老名字,会提示找不到驱动类或者直接抛ClassNotFoundException。

URL连接串的细微差别

x版本的URL可以写成jdbc:mysql://localhost:3306/databaseName，8.x版本推荐加上时区参数，否则可能报错提示Server returns invalid timezone：

jdbc:mysql://localhost:3306/databaseName?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai

这里的&在XML配置文件中要写成&，否则XML解析直接报错，这是iBatis连接MySQL数据库超时排查时最容易被忽视的一个细节，配置文件解析都过不去,连接自然建立不起来。

用户名密码的读取方式

更多时候，数据库连接参数独立放在jdbc.properties文件里，通过iBatis的<properties resource="jdbc.properties"/>标签引入，这样环境切换时只需要改配置文件，不需要动主配置文件,运维部署也能少踩坑。

线上排查实录：连接失败和驱动加载异常怎么办

List item布局

当项目启动后报错Cause: java.lang.ClassNotFoundException: com.mysql.jdbc.Driver,说明jar包根本没被加载到运行时环境。

按这个顺序检查：

1. jar包是否真实存在于WEB-INF/lib目录,检查文件大小是否为零字节。
2. 项目有没有clean之后再redeploy,Tomcat的临时缓存可能导致旧依赖没清理干净。
3. 多个版本的驱动包是否同时存在于classpath内,版本冲突会引发奇怪的调用异常。

MySQL 8.x认证插件不兼容

MySQL 8.0默认使用caching_sha2_password认证插件，老驱动5.1.x完全不认识这种认证方式，会报Unable to load authentication plugin 'caching_sha2_password'

。

处理方法有两个，要么升驱动版本到8.x,要么在MySQL层把用户的认证插件改回mysql_native_password：

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'yourpassword';

iBatis连接MySQL数据库常见报错还有Communications link failure，这个多数情况下是网络不通或者服务端防火墙拦截了3306端口，在服务器上执行telnet 目标IP 3306就能验证端口是否可达。

SQL执行超时的定位思路

连接能建但SQL跑不动超时，方向就不一样了，先看MySQL的wait_timeout和interactive_timeout，再检查iBatis里connectionTimeout的配置是否设置得太短，业内专家指出，大多数超时问题并非数据库性能本身,而是连接池和数据库空闲连接的回收策略不匹配导致的。

这里给出一组常见配置参考表格：

代码里没有设置这些连接池参数的，iBatis内部默认值非常保守,多线程并发时很容易出现获取连接超时的情况。

老项目迁移升级iBatis的驱动版本要注意什么

问这些我该从哪说起呢？很多时候一个数据库从MySQL 5.7升到8.0，iBatis项目本身不动，只要换最新驱动就能跑通，但实际上总会有各种意外，升级驱动版本前,有几件事必须确认。

驱动包和项目JDK版本的兼容性

MySQL 8.x的驱动要求JDK 8及以上，如果你的老项目还在用JDK 6或7，只能用5.1.x系列的老驱动，而这老驱动又连不了MySQL 8，这种情况下升级数据库前，先升级项目JDK版本,没有其他捷径。

字符集参数必须显式声明

老项目从MySQL 5.6往上升级时，数据库默认字符集可能从utf8换成了utf8mb4，连接串里的characterEncoding=utf8可能不够用，推荐显式写characterEncoding=utf8mb4,并确保数据库表字段的collation也支持表情符号之类的扩展字符。

驱动jar包和新数据库不匹配的典型症状

急诊最常见的报错是Unsupported major.minor version 52.0，意思就是驱动字节码要求的JDK版本高于当前JRE，这种报错一出现，先对比JRE版本和驱动要求的JDK，再决定升级哪头,别盲目改代码。

数据库授权和驱动连接的配合

连接驱动搭好之后，MySQL服务端还得允许这个客户端访问，不然连接一样失败,检查授权情况：

SELECT user, host FROM mysql.user;

如果root用户的host是localhost，本地网络内的其他机器用root连接就会被拒绝,常规做法是创建单独账号给应用使用，

CREATE USER 'app_user'@'%' IDENTIFIED BY 'StrongPassword123';
GRANT SELECT, INSERT, UPDATE, DELETE ON app_db. TO 'app_user'@'%';
FLUSH PRIVILEGES;

连接MySQL数据库的驱动上传问题解决后，这些安全方面的配置直接影响运行稳定性，行业共识认为,连接信息泄露和弱口令配置是数据库安全问题里最高发的两个漏洞来源。

常见问题解答

Q1：iBatis连接MySQL数据库时，驱动类到底写哪个，经常写错会怎样？

写com.mysql.jdbc.Driver还是com.mysql.cj.jdbc.Driver，取决于你加载的驱动jar包版本，5.x版本驱动只认前者，8.x版本驱动两者都认但推荐后者，如果你用了8.x驱动却写旧类名，8.x驱动里提供了一个兼容别名，通常也能启动，但不保证后续没有警告信息，驱动类名写错，启动就报ClassNotFoundException,根本走不到建立网络连接那一步。

Q2：上传MySQL数据库连接驱动时，把jar包放在Tomcat的lib目录可以吗？

可以，但不推荐，放在Tomcat的全局lib目录里，所有部署在同一个Tomcat下的项目都会共享这个驱动类，项目之间会产生隐式依赖，影响可移植性，更推荐放在每个项目自己的WEB-INF/lib下，Tomcat的类加载机制是WebApp优先，这样项目隔离性更好，切换驱动版本时也不会影响别的应用，要注意的是，如果你确实放到了Tomcat的lib下，项目里lib目录再放一份相同驱动，可能引起ClassCastException,因为两个类由不同的类加载器加载。

Q3：iBatis连接MySQL数据库超时可能什么原因？

连接池配置不合理占大头，比如poolMaximumActiveConnections设置太保守，业务高峰期拿不到连接，表面看起来就是超时，数据库端wait_timeout设置太短，空闲连接被服务端断开，连接池又不知道，下一次请求直接使用失效连接也会报超时，防火墙的TCP连接空闲超时也是高发因素，云环境默认安全组策略常常在几分钟内掐断空闲TCP连接，这几个方向逐一排查配置项,大多数超时问题都会浮出水面。

驱动上传、版本匹配、连接配置、权限管理，这四个环节走通，iBatis和MySQL的组合就能稳定运行下去了，搞定连接问题只是开始,后续的SQL映射和事务管理才有发挥空间。