不知道你有没有遇到过这种情况升级 MySQL 驱动版本时去 Maven 仓库搜了一下发现常用的com.mysql:mysql-connector-java坐标下面最新版本还停留在 8.0.33接着又冒出来一个com.mysql:mysql-connector-j版本反而更新、下载量也上来了。我当时第一次看到这个新坐标第一反应是“哪个第三方蹭名发布了一个山寨驱动”随手点开仓库详情才发现这就是 MySQL 官方自己放的包。其实这不只是改名还牵扯到依赖治理、安全扫描、传递依赖冲突等一系列工程问题。很多人项目里改到一半就踩坑要么版本解析失败要么被安全扫描卡住要么因为两个坐标混用导致出现两份驱动类。这篇就把mysql-connector-java和mysql-connector-j的来龙去脉、具体差异、迁移步骤和常见坑完整理一遍适合所有正在用 MySQL JDBC 驱动、或者在维护老项目的 Java 开发直接参考。1. 两个坐标的关系这根本不是“另一个驱动”而是官方改名1.1 从 artifactId 命名差异看本质先说结论mysql-connector-java和mysql-connector-j是指同一个 MySQL 官方 JDBC 驱动MySQL Connector/J只是 Maven 坐标里的artifactId变了。我最早接触这个驱动时pom 里一直是这样写的dependency groupIdcom.mysql/groupId artifactIdmysql-connector-java/artifactId version8.0.28/version /dependency这个坐标用了很多年Spring Boot 的老版本也一直帮你默认管理这个依赖。但到了 2022 年MySQL 官方在发布 Connector/J 8.0.31 版本时悄悄把 artifactId 换成了mysql-connector-jgroupId 还是com.mysql没有变化。也就是说新坐标长这样dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.0.31/version /dependency你能从这个项目的命名里看出一点意图官方更希望 artifact 名能和软件本身的名字“Connector/J”保持一致而不是强调 “java” 后缀。毕竟 artifact 名里带 “java” 很容易让人混淆比如有同事刚接触项目时总会问“mysql-connector-java 是 MySQL 的 Java 客户端吗那它和表结构工具是不是一回事”改名之后“mysql-connector-j” 更像一个明确的组件代号指向性更强。1.2 包结构和驱动类名没有变迁移成本比想象中低很多团队一听到“换坐标”就觉得要改一堆代码实际上不用。这个驱动改名前后JAR 包内部的 Java 包结构完全没变驱动类还是com.mysql.cj.jdbc.Driver连接 URL 也依然是以jdbc:mysql://开头。也就是说你只需要把 Maven或 Gradle里的依赖坐标和版本调整一下代码里基本不用动。Class.forName(com.mysql.jdbc.Driver)这种老写法在 8.x 驱动里已经不再推荐正常情况下使用数据源配置的地方也不用改因为 Spring Boot、MyBatis、HikariCP 这些框架都是按配置项去加载驱动类而驱动类路径根本没有变。给一个直观对照表对比项mysql-connector-javamysql-connector-jgroupIdcom.mysqlcom.mysqlartifactIdmysql-connector-javamysql-connector-j驱动类名com.mysql.cj.jdbc.Drivercom.mysql.cj.jdbc.DriverJDBC URL 前缀jdbc:mysql://jdbc:mysql://项目名MySQL Connector/JMySQL Connector/J最先出现的版本很老5.x 时代就有8.0.312022 年 10 月左右Maven Central 最新可用版本8.0.338.0.33 / 8.1.0 / 8.2.0 / 8.3.0 / 9.x持续更新中从表格就能看出两者本质上就是同一个东西在不同阶段的“马甲名”。1.3 为什么容易误认为两个独立驱动因为 MySQL 还有一个叫mysql-connector-java的 GPL 协议发行包在一些 Linux 发行版、老教程和书籍里经常出现而 Maven Central 上又确实存在这两个 artifactId很多不熟悉背景的人就会认为这是“老驱动”和“新驱动”两个项目。再加上这两个坐标在 8.0.31 到 8.0.33 这段时间是同时在发布版本的同一个版本号在两个坐标下都能拉到就越发容易让人困惑。这里也提醒一句如果你在 GitHub 或 Gitee 上搜到一些老项目它们的 pom 里可能还写着mysql-connector-java不要急着全局替换要先看它用的版本号。如果版本号小于 8.0.31说明项目是从旧时代一路升上来的替换时要配合版本升级如果版本号已经大于等于 8.0.31那换成新坐标也不迟。2. 官方为什么改名供应链安全、命名统一与版本管理2.1 老坐标安全性问题多官方想重新开始从安全角度讲com.mysql:mysql-connector-java这个坐标在 2022 年前后问题不断。MySQL Connector/J 历史上披露过多个可以导致远程代码执行或敏感信息泄露的漏洞比如 8.0.27 之前版本里那些允许攻击者通过反序列化或特定连接参数触发危险的漏洞。很多安全扫描工具会直接盯着这个 artifact只要项目引用了某个低于修复版本的旧坐标扫描结果立刻就亮红灯。另外一个更现实的原因是Maven Central 上出现过针对mysql-connector-java的恶意仿冒包事件某些仿冒坐标甚至携带恶意代码。Oracle 官方后来主动切换 artifactId也有相当一部分考虑是希望新项目能够直接使用受官方分支维护的新坐标从源头上规避对旧坐标的各种供应链风险。我自己见过团队把mysql-connector-java从 8.0.18 升级到 8.0.28安全扫描仍然提示“此依赖存在已知漏洞建议升级到官方修复版本”后来一查发现 8.0.28 并不在官方推荐清单前列。这种情况虽然不是非得换坐标才能解决但借着升级版本的机会一并改成新坐标确实减少了后续很多解释成本。2.2 从 8.0.31 开始官方把两个坐标同时发布了一段时间一个容易被忽略的细节是com.mysql:mysql-connector-j并不是一夜之间取代老坐标的。在 8.0.31、8.0.32、8.0.33 这几个版本中两个坐标都能在 Maven Central 上找到官方是并行发布状态。这个并行期对老项目来说很友好你可以在同一个版本号下先做坐标切换不改变任何行为和性能。理论上讲从mysql-connector-java:8.0.33切到mysql-connector-j:8.0.33连驱动 jar 的文件内容都几乎一致只是坐标名字不同。但是到了 8.1.0 及之后旧坐标就再也没有新版本了。这也意味着如果继续使用旧坐标并想升级到 9.x就必须迁移到新坐标。2.3 不同驱动产品线的命名历史让情况更复杂还有一层背景让不少人困惑MySQL 官方在不同历史阶段发布过多个 Java 连接器相关的组件。比如非常古老的org.gjt.mm.mysql.Driver驱动以及后来被 MySQL Connector/J 取代的com.mysql.jdbc.Driver等。在 Maven 仓库里相关的 artifactId 也换过好几次。加上 MySQL Connector/J 要同时支持 JDBC 4.2 规范、XA 事务、多种认证插件这些能力都塞在同一个 JAR 里导致大家对这个驱动“到底该叫什么”一直都没什么统一认知。官方最终用mysql-connector-j把命名收敛成一个干净的名字配合模块化设计这也是从“能用”走向“好维护”的一步。3. 如何正确切换Maven、Gradle、Spring Boot 的实际操作3.1 Maven 项目迁移方法如果你正在维护一个 Maven 项目迁移步骤其实就三步改坐标、换版本、清理旧依赖。以升级到 8.0.33 为例修改前后的依赖长这样。改之前dependency groupIdcom.mysql/groupId artifactIdmysql-connector-java/artifactId version8.0.28/version /dependency改之后dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.0.33/version /dependency如果项目里用了dependencyManagement统一管理版本那就在父 pom 的dependencyManagement部分同步修改。我强烈建议在迁移时顺手去 Maven Central 看一眼当前最新稳定版本号不要随便填一个 8.0.3x 就完事。因为 8.0.x 是长期支持的旧版本线官方还推出了 8.1.0、8.2.0、8.3.0、9.x 等较新版本线要根据你的 JDK 版本和应用场景选择。如果你是 JDK 8 的存量项目选择 8.0.33 完全合理如果是新项目且 JDK 17可以考虑新版本线但要注意新版本线只维护到对应最新版本后续发布频率和兼容性策略不太一样。3.2 Gradle 项目迁移方法Gradle 项目同样很简单。改之前implementation com.mysql:mysql-connector-java:8.0.28改之后implementation com.mysql:mysql-connector-j:8.0.33如果你用的是 Gradle 的 version catalog也就是libs.versions.toml只需要修改依赖坐标字符串不需要改动使用处的调用代码。3.3 Spring Boot 项目里要注意版本管理覆盖Spring Boot 的项目有个特殊点Spring Boot 的 dependency management 里已经内置了数据库驱动的版本管理。不同 Spring Boot 版本管理的是哪个数据库驱动坐标呢这里要注意Spring Boot 2.7.x 及更早版本默认管理的是com.mysql:mysql-connector-java这个老坐标Spring Boot 3.0 及之后版本则切换成了com.mysql:mysql-connector-j并同时提升了最低要求的驱动版本。这意味着如果你把 Spring Boot 从 2.x 升到 3.xpom 里即使你自己不写版本号驱动也会从老坐标自动切到新坐标。很多人在升级 Spring Boot 后出现驱动相关异常以为是框架兼容问题其实是因为底层坐标变了、自己代码或配置里还在引用旧的东西。在实际项目里我通常建议在 Spring Boot 项目里显式声明这个依赖并且不要完全依赖 Spring Boot 的默认版本原因有两个Spring Boot 的默认版本管理通常会滞后于官方最新版部分安全问题需要自己升级到更新版本才能消除。显式声明版本后全项目统一不会因为子模块的传递依赖不同而出现驱动版本漂移。举一个我正在用的配置示例dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.0.33/version /dependency这段放在dependencies里且不写scope默认就是compile够用。3.4 记住这些配置不需要改不管坐标怎么变下面这些都不需要动spring.datasource.driver-class-namecom.mysql.cj.jdbc.Driver spring.datasource.urljdbc:mysql://localhost:3306/test?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai如果项目里还是老式的Class.forName(com.mysql.jdbc.Driver);并且代码用的是 MySQL Connector/J 8.x那这个类其实已经被移除了。8.x 驱动只保留com.mysql.cj.jdbc.Driver。这种情况不是坐标切换导致的而是从 5.x 升级到 8.x 时的历史遗留问题。4. 版本怎么选别只看坐标还要看 JDK 和 MySQL 版本4.1 一个版本对照参考既然两个坐标本质是同一驱动的新旧命名那实际选择时大家真正关心的是选哪个版本。有一个大致的版本线可以参考。驱动版本对应坐标最低 JDK适用场景8.0.13 ~ 8.0.30mysql-connector-javaJava 8老项目升级、历史依赖8.0.31 ~ 8.0.33mysql-connector-java 或 mysql-connector-jJava 8官方并行发布期推荐切新坐标8.1.0 / 8.2.0 / 8.3.0mysql-connector-jJava 8新特性验证适合 JDK 8 项目9.xmysql-connector-jJDK 8 或更高具体以官方为准较新版本线建议评估后使用这里需要说明驱动版本和 MySQL 服务器版本并不是强绑定的。MySQL Connector/J 8.x 可以连接 MySQL 5.7、8.0可以连接腾讯云数据库 MySQL、阿里云 RDS MySQL也能通过 MariaDB 的兼容模式连接部分场景下的 MariaDB。不过如果 MySQL 服务器版本过低某些新特性用不了如果服务器版本过高、驱动太老也可能出现握手失败或者认证插件不兼容的问题。4.2 不要盲目追求最新版本我在生产环境里吃过一次亏某次顺手把驱动升到了当时最新的 8.1.0结果第二天就碰到一个连接池场景下的偶发超时问题。当然这个问题不一定是驱动锅可能是参数配置不匹配但这也验证了一个原则生产环境的驱动版本应该选择已经有足够社区反馈、有稳定口碑的版本而不是最新发布的那一个。对于大多数项目我建议的默认选择是8.0.33。它处于 8.0 长期分支的后期修复版本兼容性经过了大量项目验证而且本质上和之前的 8.0.3x 一脉相承升级风险很小。如果你想用较新的版本线建议先在测试环境跑一段时间重点观察连接池、SSL、时区处理、批量插入等常见场景。4.3 Java 模块系统JPMS对驱动的影响还有一个容易忽略的点从 MySQL Connector/J 8.0.31 开始JAR 包内添加了module-info.class也就是说驱动开始支持 Java 模块系统。这个变化也解释了为什么官方愿意顺势调整 Maven 坐标——让模块名和 artifact 名更一致避免出现“包名叫 java.sql”但坐标却叫mysql-connector-java的错位感。如果你的项目使用了 JPMSmodule-info.java做了模块化拆分引入新坐标后模块名通常是com.mysql.cj你在module-info.java里需要声明requires com.mysql.cj;这个在切换坐标前就需要注意。如果你只改 Maven 坐标但没处理模块声明编译时会遇到模块找不到的问题。5. 实操中常见的报错、坑与排查记录5.1 热搜第一的那个报错Cannot resolve com.mysql:mysql-connector-j:release很多人把坐标改完后写版本号时直接写了release就像这样dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId versionrelease/version /dependency结果 IDEA 报错Cannot resolve com.mysql:mysql-connector-j:release。这个问题的根源不是你用了新坐标而是 Maven 仓库里根本不叫 “release” 的版本号。Maven 里确实有一个“release”的概念它指的是仓库中maven-metadata.xml里标记的最新发布版本但这不是你随手写在 pom 里的合法版本字符串。你也不能像 Gradle 一样写implementation com.mysql:mysql-connector-j:让 Maven 自动拉最新版Maven 在version标签里写release、latest、LATEST都属于不规范做法尤其生产项目绝对不能用。正确做法是写一个明确的版本号dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.0.33/version /dependency5.2 依赖冲突两个坐标同时存在导致加载了两个版本的驱动最容易出问题的场景是多模块项目。比如父模块用老坐标子模块用新坐标最终打包时两个 artifact 都被打入 classpath里面出现了两份com.mysql.cj.jdbc.Driver类。这种情况在本地开发时未必立刻报错因为 JVM 加载类是有顺序的先加载到哪份就用哪份。但到了某些容器环境、或者类加载顺序变化时就可能出现java.lang.NoSuchMethodError java.lang.LinkageError排查方法很简单在项目根目录执行mvn dependency:tree -Dincludescom.mysql看输出里是否同时包含这两个 artifact。如果存在你需要在引用老坐标的地方排除掉dependency groupIdorg.example/groupId artifactIdsome-lib/artifactId version1.0/version exclusions exclusion groupIdcom.mysql/groupId artifactIdmysql-connector-java/artifactId /exclusion /exclusions /dependency5.3 安全扫描拦截老坐标即使版本新也会被列为风险项我之前在一个客户项目里遇到的问题很典型他们刚把驱动从 5.1.49 升级到 8.0.30安全扫描依然失败。扫描报告显示的是com.mysql:mysql-connector-java:8.0.30存在 CVE 风险。我当时建议直接把坐标切到com.mysql:mysql-connector-j:8.0.33扫描立刻通过。为什么会这样因为安全漏洞数据库对 artifact 的记录是按坐标标识来的很多扫描器给mysql-connector-java这个老 artifact 打了非常宽泛的风险标记。而新坐标mysql-connector-j是一个全新的 artifact ID受到的历史漏洞标记少很多或者说主要追踪的是新版本有没有新漏洞。这样一来同样功能的驱动换新坐标在合规上干净得多。当然这不是让你利用坐标来“躲避”扫描。真正底层的驱动版本是否安全还是要以官方安全公告为准。只是在目前的工具生态里新坐标确实能少很多误报和警报。5.4 升级后连接失败时区、SSL、认证插件问题会集中暴露有些老项目长期不升级驱动一旦从 5.x 升到 8.x再切到新坐标可能出现连接失败。常见报错包括java.sql.SQLException: The server time zone value Öйú±ê׼ʱ¼ä is unrecognized...或java.sql.SQLException: Access denied for user root... using password: YES第一个是时区问题。8.x 驱动默认要求serverTimezone参数你可以连接 URL 里加jdbc:mysql://localhost:3306/test?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai第二个通常是认证插件问题。如果 MySQL 服务器是 8.0 及以上默认认证插件是caching_sha2_password而旧驱动不支持这个认证方式。解决方法是把驱动版本升到 8.x你换到新坐标后自然就解决了或者在服务器端创建一个使用mysql_native_password插件的用户。5.5 数据库连接池和 ORM 框架兼容性在 Spring Boot 3.x 项目里MyBatis 或 JPA 与 MySQL 新驱动配合一般没有问题。但在一些较老的 ORM 框架或连接池版本里可能存在对驱动类名硬编码的情况。比如有个老项目代码里自己写了一个工具类每次创建连接时通过DriverManager.getConnection获取并且Class.forName(com.mysql.jdbc.Driver)。这种代码在新驱动 8.x 下一定会报ClassNotFoundException因为 8.x 里这个类已经删了需要在代码里改成Class.forName(com.mysql.cj.jdbc.Driver);如果项目用的是 Druid 连接池注意 Druid 版本不要太老。老版本 Druid 在连接 MySQL 8.x 时可能出现fail fast异常或者初始化失败。推荐 Druid 1.2.x 以上版本。5.6 pom 文件里版本被父依赖覆盖还有一种隐蔽情况你自己的 pom 里明明写的是新坐标mysql-connector-j:8.0.33最终打包出来的还是老坐标 8.0.30。这通常是因为某个公共父 pom 或 BOMBill of Materials里用dependencyManagement重新指定了版本和坐标。检查办法mvn help:effective-pom然后搜一下mysql-connector能看到有效 pom 里最终生效的依赖列表。如果发现被覆盖就在你自己的 pom 里显式声明坐标并放到依赖列表的前面或者修改父 pom 的依赖管理。6. 最佳实践我现在的依赖配置和代码习惯经过多次踩坑后我现在在项目里的数据库依赖配置基本固定下来了。如果你也想一步到位可以参考下面的方式。第一明确选择新坐标并在所有模块统一使用一个版本变量。示例properties mysql.connector.version8.0.33/mysql.connector.version /properties dependencyManagement dependencies dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version${mysql.connector.version}/version /dependency /dependencies /dependencyManagement这样后续升级只需要改一个属性。第二连接 URL 里的参数要写全。我常用的模板jdbc:mysql://127.0.0.1:3306/dbName?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue其中allowPublicKeyRetrievaltrue在某些环境特别是第一次建立连接时使用 caching_sha2_password 认证是必须的否则可能出现Public Key Retrieval is not allowed第三如果项目里同时有老代码在使用 JDBC 直连统一收口到一个ConnectionFactory不要在 50 个地方散落Class.forName。这样以后迁移任何依赖都方便。最后持续关注 MySQL 官方发布的 Connector/J 更新公告。每当有安全修复版本出来先在自己的分支上升级跑一遍测试再把改动合入主干。数据库驱动这类基础依赖最忌讳“长期不升、一升跳好几个大版本”最好是跟着小版本节奏持续更新。7. 从 Maven Central 拉不到包时还有哪些排查思路有时候不是坐标写错而是镜像仓库同步滞后或者私有仓库没有对应版本。国内开发环境比较常见的现象是Maven Central 上已经有新版本但本机配置的阿里云镜像同步延迟拉取时总是 404。这时候可以先在命令行强制解析一下看具体报错mvn dependency:get -Dartifactcom.mysql:mysql-connector-j:8.0.33如果这一步失败再去检查 Maven 的settings.xml看mirror是不是把central指向了一个更新不及时的私服地址。我见过很多项目把 Nexus 私服地址写死结果私服上一直缓存着旧版本新的 artifact 永远不会出现。解决方法是去私服管理后台手动执行元数据刷新或代理仓库同步。如果你是用 IDEA 开发修改 pom 后左上角出现红色波浪线但同时命令行构建能成功那就是 IDEA 的 Maven 索引缓存问题。执行一次Reload All Maven Projects或者删掉本地仓库里com/mysql目录下的残留.lastUpdated文件再重新拉取都能解决。8. 我与这个坐标变更打过交道的几点体会从mysql-connector-java切到mysql-connector-j表面上看只是改一个 artifactId但它背后牵涉到依赖管理、安全合规、版本升级、团队协作等多个环节。我个人在实际操作中的体会是这类基础组件的变更最值得花时间的地方不是“改一行配置”而是评估现有项目里的传递依赖、安全扫描规则和代码里是否有历史遗留写法。如果你今天正好因为这个标题搜到了这里那我的建议非常直接新项目一定用com.mysql:mysql-connector-j老项目在下次升级驱动时一起切过去不要在 pom 里长期混用两个坐标。改完后把代码里所有显式加载驱动类的地方全部检查一遍再跑一遍基于真实数据库的集成测试基本就不会有什么问题了。
