Spring Boot 项目里连 MySQL,这事看起来简单,但我在群里看到太多人卡在起跑线上:依赖加了、配置写了,一启动就报错,或者好不容易起来了,查询接口又给你来一个 404,再不就是分页查不出来。究其原因,大多是三件套之间的版本匹配和配置细节没对上。
所以我就想用一篇文章,把"Spring Boot + MyBatis-Plus 连接 MySQL"这条链路从头到尾捋一遍。不绕弯子,直接给你能跑通的方案,顺带把为什么这么配、背后是什么原理讲清楚。无论你是刚入门想搭第一个项目,还是工作中需要快速初始化一个带数据库的服务,这篇文章都能让你少踩几个坑。
1. 整体方案与选型思路
1.1 为什么是这三件套
先说结论:这个组合几乎就是当前 Java 后端业务系统开发最主流的起步配置,没有之一。
Spring Boot 负责把整个应用的骨架搭起来,它最大的价值是自动装配。你只需要在 pom 里声明依赖,框架会自动帮你把数据源、事务管理器、Web 容器这些基础设施初始化好,省掉了大量 XML 配置。Spring 官方也一直在往"约定优于配置"的方向走,所以用它做底座,团队协作时心智负担最小。
MyBatis-Plus 是在 MyBatis 之上做增强的持久层框架。它保留了 MyBatis 的灵活 SQL 能力,同时内置了通用 Mapper、通用 Service、分页插件这些高频能力。实际开发中你不需要手写 INSERT、UPDATE、SELECT BY ID 这类基础 SQL,框架会根据实体类自动生成。这一点对快速开发来说太关键了——你想想,一个模块几十张表,每张表都手写一遍增删改查,那是在浪费生命。
MySQL 这个就不用多说了,开源免费、生态成熟、资料多,中小规模项目的首选关系型数据库。虽然现在各种分布式数据库层出不穷,但 MySQL 作为业务主库的地位依然稳固,几乎所有人学习后端的第一站都是它。
1.2 技术选型背后的考量
如果只追求"能跑",方案不止这一个,Spring Data JPA 和原生 MyBatis 也都是选项。我这里强调一下为什么 MyBatis-Plus 在实战中更讨喜。
Spring Data JPA 的抽象层级高,简单 CRUD 确实香,但一旦业务查询复杂起来,你要不就得写 @Query 注解里那串 JPQL,要不就得忍受嵌套接口继承带来的调试痛苦。尤其国内很多团队的 SQL 功底比 Java 功底扎实,让他们用 Hibernate 那种自动生成 SQL 的思路工作,反而觉得不顺手。
而原生 MyBatis 又太"裸"了——每张表都要手写 Mapper 接口、Mapper XML、实体类,一个简单的列表接口零件一堆。MyBatis-Plus 刚好卡在中间:它把你的常规操作接管了,99% 的基础接口一行代码都不用写;那 1% 的复杂查询,你依然可以用 @Select 注解或 XML 手写 SQL。这是非常务实的设计哲学。
而且 MyBatis-Plus 的代码生成器也很成熟,可以从数据库表结构直接反推出实体类、Mapper、Service、Controller 全套代码。这意味着你在新项目里定好表结构之后,代码骨架几分钟就能拉出来。
1.3 这套方案适用的场景
选型还要看场景,不是所有项目都适合。
如果你的团队熟悉 SQL,追求快速交付业务功能,尤其是传统的信息管理系统、后台管理系统、中小型互联网应用,这个组合是最稳的。MyBatis-Plus 提供的分页、条件构造器、逻辑删除、乐观锁插件,几乎覆盖了 CRUD 系统的所有常规需求。
反过来,如果你的项目是纯 RESTful API 且查询逻辑极其复杂(比如报表聚合、多维度分析),或者需要大量走 Hibernate 的一级二级缓存特性,那可能要重新评估。另外,如果团队明确需要数据库无关性(比如同套代码支持多个数据库切换),基于 JPA 的方言抽象会更省心。不过绝大多数项目部署时数据库就定死了一个,所以这个问题不常见。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与版本匹配
2.1 JDK、Maven、MySQL 的安装检查
连接数据库之前,先确认本机环境是齐的。这三个工具缺一个,后面跑源码都是白搭。
JDK 建议直接用 8 或 11。Spring Boot 2.x 系列在 JDK 8 上最稳,Spring Boot 3.x 强制要求 JDK 17。如果你刚起步,我建议用 Spring Boot 2.7.x + JDK 8 的组合,网上资料最多,踩坑时一搜一大把。安装 JDK 后记得在命令行敲 java -version 验证一下,Path 环境变量没配好的话,IDE 里能跑但命令行跑不了,后面部署时会很痛苦。
Maven 的安装相对简单,下载二进制压缩包解压后配置 MAVEN_HOME 和 PATH 就行。需要注意的是,Maven 默认中央仓库在国外,首次下载依赖会很慢。建议在 settings.xml 里配置阿里云镜像,这个不是可选项,是省时间利器。配置方式很简单,在 <mirrors> 标签里加一段:
xml复制<mirror>
<id>aliyunmaven</id>
<mirrorOf>central</mirrorOf>
<name>阿里云公共仓库</name>
<url>https://maven.aliyun.com/repository/public</url>
</mirror>
MySQL 的安装分两种情况。一种是本地直接装,Windows 用户去官网下载 MySQL Installer,选择 Server 组件安装即可,安装过程中会让你设置 root 密码,自己记好。另一种是直接用 Docker 拉镜像,我喜欢这种方式,因为干净、可重复、删了重来不心疼。命令行跑一下:
bash复制docker run -d \
--name mysql8 \
-p 3306:3306 \
-e MYSQL_ROOT_PASSWORD=root123 \
-e MYSQL_DATABASE=testdb \
mysql:8.0
这样 MySQL 8.0 就在本机 3306 端口起来了,还顺手建了一个 testdb 数据库。注意 -p 3306:3306 是端口映射,容器内 MySQL 默认 3306,映射到宿主机 3306,这样 Spring Boot 在宿主机上连接时就用 localhost:3306。
2.2 版本对应关系与兼容性
这里一定要强调,Spring Boot 和 MySQL 驱动、MyBatis-Plus 的版本是有联动关系的。我整理了一张常用版本匹配表,照着选基本不会出问题:
| Spring Boot | JDK 版本 | MyBatis-Plus | MySQL 驱动 | 说明 |
|---|---|---|---|---|
| 2.3.x | 8 | 3.4.x | mysql-connector-java 8.0.x | 老项目常见 |
| 2.5.x | 8/11 | 3.5.x | 8.0.x | 稳定组合,推荐新手 |
| 2.7.x | 8/11 | 3.5.3+ | 8.0.33 | 组合最稳,资料最全 |
| 3.0.x | 17+ | 3.5.4+ | com.mysql:mysql-connector-j 8.0.33 | 注意 javax 改 jakarta |
| 3.1.x | 17+ | 3.5.5+ | com.mysql:mysql-connector-j | 最新生态 |
一个常见的坑是:MySQL 8.x 版本下,驱动类名要用 com.mysql.cj.jdbc.Driver,而 MySQL 5.x 用的是 com.mysql.jdbc.Driver。如果你复制了老项目的配置,怎么启动都报 ClassNotFoundException,大概率就是驱动类名不对。另一个坑是 Spring Boot 3.x 之后,驱动坐标从 mysql:mysql-connector-java 改成了 com.mysql:mysql-connector-j,依赖名称也变了。
2.3 准备数据库和用户
MySQL 装好之后,不要直接用 root 账号去连业务数据库,这是我从生产环境学到的教训。开发环境虽然随意,但统一规范能避免不少权限问题。我们先建一个专用用户,并赋予它某个库的所有权限:
sql复制CREATE DATABASE IF NOT EXISTS `demo` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'demo_user'@'%' IDENTIFIED BY 'demo_pass';
GRANT ALL PRIVILEGES ON `demo`.*
