Spring Boot 可以说是目前做个人项目、课程设计和中小型业务系统时最常用的 Java 框架，而 MySQL 又几乎成了本地开发的默认数据库。两件事单拎出来都不难，但放到一起，版本、驱动、连接池、字符集、SSL 认证这些环节就像接力赛一样一环扣一环，稍不留神就会出现“本地连不上数据库”这种让人抓狂的局面。
这篇内容我基于前后端分离开发时的真实踩坑经历，把 Spring Boot 项目本地连接并操作 MySQL 数据库的完整链路重新捋了一遍，从版本选择、MySQL 安装、数据源配置，到实体映射、增删改查接口实现，再到最后的异常排查，全部按操作顺序展开。不管你是刚学 Java Web、正在做毕设，还是准备面试时想补一下 Spring Boot 与 MySQL 的细节，都可以照着这份步骤走。
1. 先想清楚：Spring Boot 连 MySQL 的链路到底是怎么走的
1.1 一次完整请求从 Controller 到表的调用顺序
很多人写 Spring Boot 项目时会有一种错觉：只要在配置文件里填上数据库地址和密码，代码里就能自动拿到数据。其实背后有个标准的调用链，只是框架帮我们藏住了细节。
当你向本地服务发起一个请求，比如GET /students，请求先打到 Controller 层，Controller 再调用 Service，Service 调用 Repository 或者 Mapper 接口。这里有一个很关键的概念：Spring Boot 的自动装配机制会在项目启动时读取spring.datasource.*配置，帮你创建数据源和连接池。连接池里维护的是一批到 MySQL 的物理连接，你的增删改查操作并不是每次新建连接，而是从池子里借一个连接，执行完再还回去。
真正执行 SQL 的是 JDBC Driver，也就是我们常说的mysql-connector-j驱动。驱动负责把数据库 URL、用户名、密码转成 MySQL 服务端能理解的握手协议，再通过 TCP 3306 端口把 SQL 命令发过去，MySQL 执行完再把结果集返回给驱动。Spring Boot 里的 JPA 或 MyBatis 只是在驱动上层再做一次对象关系映射，把结果集变成 Java 对象而已。
搞清楚这条链路有什么用？最大的作用就是定位问题。如果报错出现在 URL 解析，那是配置问题；如果报错是驱动加载失败，那是依赖问题；如果报错卡在 SSL 握手，那是服务端认证方式问题。很多新手看到一大段异常就直接搜“Spring Boot 连不上 MySQL”，但真正有效的处理方式是先判断异常发生在链路中的哪一段。
1.2 本地开发环境与生产环境差在哪里
本地开发环境通常比较随意，MySQL 和 Spring Boot 都在同一台电脑上，网络没有隔离，账号权限也放得很宽。而生产环境往往是独立数据库服务器，有独立的账号、端口、SSL 要求，甚至还会通过安全组限制访问来源。
这种差异会直接影响配置写法。本地图省事，通常用 root 账号或者一个拥有全库权限的账号，useSSL=false也问题不大。但生产环境如果照搬本地配置，轻则连不上，重则带来安全隐患。我在本地开发时，习惯单独创建一个业务数据库，再单独创建一个只能在本机访问的账号，这样产生的配置在迁移到生产时，只需要换主机地址、密码和 SSL 参数，代码逻辑不用动。这一步听起来没有必要，但等你项目变大、团队里多几个人一起开发时，就知道独立账号、独立库有多重要了。
2. 环境准备：JDK、MySQL 8、可视化客户端怎么搭最省事
2.1 版本选型：JDK、Spring Boot、MySQL 三者怎么搭配
我经常看到有人拿着很新的 Spring Boot 3 项目，却还在用 JDK 8 编译，结果一堆报错。这里先明确一个硬性标准：Spring Boot 3.x 强制要求 JDK 17 以上，而且包名从javax换成了jakarta。如果电脑上只有 JDK 8，就别硬上 Spring Boot 3，老老实实用 Spring Boot 2.7.18。
版本搭配建议参考下面这张表：
| 使用场景 | JDK | Spring Boot | MySQL | 说明 |
|---|---|---|---|---|
| 维护老项目 | JDK 8 | 2.7.18 | 5.7 / 8.0 | 兼容性好，资料多，适合低版本环境 |
| 新项目首选 | JDK 17 | 3.2.x | 8.0 | 长期维护，安全更新及时 |
| 本地快速验证 | JDK 17 | 3.2.x | 8.0 | 配合 MySQL 8 官方驱动即可 |
MySQL 5.7 和 8.0 的默认认证插件不一样，5.7 是mysql_native_password，8.0 是caching_sha2_password。如果你用旧驱动连 MySQL 8，会出现认证插件不兼容的报错。解决方法是换新的com.mysql.cj.jdbc.Driver，不要只看教程把老写法抄下来。
2.2 MySQL 8 本地安装与初始化要点
官方下载安装包这个环节本身不难，难的是安装之后要记得做两件小事：设置字符集和记录初始化密码。
以 Windows 解压版为例，下载mysql-8.0.x-winx64.zip后，解压到比如 C 盘某个目录。建议在根目录下创建my.ini，至少把字符集和端口固定下来：
[mysqld] basedir=C:/mysql-8.0.36-winx64 datadir=C:/mysql-8.0.36-winx64/data port=3306 character-set-server=utf8mb4 collation-server=utf8mb4_unicode_ci default_authentication_plugin=mysql_native_password [mysql] default-character-set=utf8mb4然后以管理员身份打开命令行，执行初始化命令：
mysqld --initialize --console这一步会在控制台打印一个临时 root 密码，一定要复制保存下来，后面登录时要用。接着执行：
mysqld --install net start mysql服务启动成功后，用临时密码登录：
mysql -uroot -p首次登录后尽快改掉 root 密码，我建议直接创建一个专用开发账号，而不是拿 root 到处用。macOS 用户用 Homebrew 安装更省事，Linux 用户用 apt 或 dnf 也可以，但无论哪种方式，初始化之后的第一件事都是确认端口、字符集、认证方式这三点。
2.3 创建测试数据库与专用账号
登录 MySQL 后，先把默认字符集固化到库级别，这样即使代码里漏配字符集参数，中文也不会变成乱码：
CREATE DATABASE demo_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'demo_user'@'localhost' IDENTIFIED BY 'Demo123456'; GRANT ALL PRIVILEGES ON demo_db.* TO 'demo_user'@'localhost'; FLUSH PRIVILEGES;需要说明的是，权限精确到demo_db而不是*.，是刻意为之。后面如果不想让别人看到其他库，这个权限模型就能直接复用，不用再改结构。搞定之后，使用 Navicat、MySQL Workbench 或命令行随便哪个客户端，用demo_user去连demo_db，能连上就说明数据库侧环境已经就绪。
3. 项目创建与配置：一份能直接跑的 application.yml 是怎么来的
3.1 用 IDEA 从 Spring Initializr 建项目
本地项目不用搞太复杂的构建方式，直接用 IDEA 新建 Spring Boot 项目就行。在 Spring Initializr 界面里，Java 版本选 17，然后勾选这三个依赖：
- Spring Web：提供 REST 接口能力
- Spring Data JPA：负责对象关系映射和仓库接口
- MySQL Driver：负责和 MySQL 服务通信
用这种方式创建出来的项目，自带一个可启动的主类。之后只要把配置写对，就能跑通连接。如果你更习惯用 MyBatis，可以把 Spring Data JPA 换成 MyBatis 相关依赖，后面我会专门说一下差异。
创建一个/tmp/mysql表用于演示，不过现在先不急着建，等代码写完再一起看效果。项目创建好后，pom.xml里的依赖片段大概是这样的：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency>Spring Boot 3 里，官方把驱动坐标改成了com.mysql:mysql-connector-j，不少老教程里写的mysql:mysql-connector-java已经不推荐了。如果你发现自己项目里驱动加载不到，先看一下是不是用了旧坐标。
3.2 application.yml 配置里的每一项都有用
Spring Boot 的配置文件既可以用application.properties，也可以用application.yml。我个人更推荐 yml，因为层次关系清楚，数据库这种多级配置不会写成一长串。下面是一份实测能跑的完整配置：
server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/demo_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true username: demo_user password: Demo123456 driver-class-name: com.mysql.cj.jdbc.Driver hikari: minimum-idle: 2 maximum-pool-size: 10 connection-timeout: 30000 max-lifetime: 1200000 jpa: hibernate: ddl-auto: update show-sql: true properties: hibernate: format_sql: true先解释url这一段。jdbc:mysql://localhost:3306/demo_db说明数据库在本地 3306 端口，库名是demo_db。后面的参数里：
useUnicode=true&characterEncoding=utf8：请求使用 UTF-8 编码，配合数据库的utf8mb4，中文才稳。useSSL=false：本地开发时禁用 SSL，减少握手阶段的报错。serverTimezone=Asia/Shanghai：统一时区，避免 MySQL 驱动和本地系统时区不一致。allowPublicKeyRetrieval=true：连接 MySQL 8 时允许获取公钥，解决认证插件验证问题。
driver-class-name推荐写com.mysql.cj.jdbc.Driver。老的com.mysql.jdbc.Driver在 MySQL 8 中虽然兼容，但会有过时警告，直接写新的更干净。
3.3 连接池、自动装配和 Driver 的那点关系
Spring Boot 项目默认带 HikariCP 连接池。它的工作原理是启动时预创建一批空闲连接，请求来了直接复用，避免每次操作数据库都经历建连、认证、释放的过程。自动装配由DataSourceAutoConfiguration完成，它会读取spring.datasource.*配置，然后创建HikariDataSource实例。
连接池参数不是越大越好。本地开发机器和单库场景下，maximum-pool-size设在 10 左右足够，minimum-idle可以保持 2。max-lifetime指的是连接最大存活时间，建议小于 MySQL 的wait_timeout，不让数据库端把空闲连接断开后客户端还在傻等。这段配置虽然不直接产出业务功能，却决定了高并发下的连接等待体验。
4. 把 MySQL 真正操作起来：用 JPA 实现一套增删改查
4.1 建表、实体类映射
先给数据库准备一张学生表，用于演示本地数据读写：
USE demo_db; CREATE TABLE student ( id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(50) NOT NULL, age INT NOT NULL, major VARCHAR(100) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;然后创建实体类。Spring Boot 3 + JPA 里，实体注解用的是jakarta.persistence包：
package com.example.demo.entity; import jakarta.persistence.Entity; import jakarta.persistence.GeneratedValue; import jakarta.persistence.GenerationType; import jakarta.persistence.Id; import jakarta.persistence.Table; @Entity @Table(name = "student") public class Student { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; private String name; private Integer age; private String major; public Student() { } public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public Integer getAge() { return age; } public void setAge(Integer age) { this.age = age; } public String getMajor() { return major; } public void setMajor(String major) { this.major = major; } }这里有个细节：Java 实体里的字段命名用驼峰，数据库列用下划线，JPA 的命名策略会默认把createTime映射为create_time。如果你自己写@Column(name = "create_time")，那就以注解为准，不发生自动转换。
4.2 Repository 与 Controller：少写很多样板代码
Spring Data JPA 的核心价值在于，你只要定义一个继承JpaRepository的接口，不用写实现类，框架就会自动实现基本增删改查方法。查询方法也可以根据方法名自动生成 SQL，比如findByAgeBetween会自动翻译成WHERE age BETWEEN ? AND ?：
package com.example.demo.repository; import com.example.demo.entity.Student; import org.springframework.data.jpa.repository.JpaRepository; import java.util.List; public interface StudentRepository extends JpaRepository<Student, Long> { List<Student> findByAgeBetween(Integer min, Integer max); }接着写一个 Controller，用来提供 REST 接口，验证本地数据库读写：
package com.example.demo.controller; import com.example.demo.entity.Student; import com.example.demo.repository.StudentRepository; import org.springframework.web.bind.annotation.*; import java.util.List; @RestController @RequestMapping("/students") public class StudentController { private final StudentRepository studentRepository; public StudentController(StudentRepository studentRepository) { this.studentRepository = studentRepository; } @GetMapping public List<Student> list() { return studentRepository.findAll(); } @GetMapping("/{id}") public Student one(@PathVariable Long id) { return studentRepository.findById(id).orElseThrow(); } @PostMapping public Student create(@RequestBody Student student) { return studentRepository.save(student); } @PutMapping("/{id}") public Student update(@PathVariable Long id, @RequestBody Student student) { return studentRepository.findById(id) .map(existing -> { existing.setName(student.getName()); existing.setAge(student.getAge()); existing.setMajor(student.getMajor()); return studentRepository.save(existing); }) .orElseThrow(); } @DeleteMapping("/{id}") public void delete(@PathVariable Long id) { studentRepository.deleteById(id); } }控制器代码写得很薄，业务直接落在 Repository 上，本地演示足够。实际项目到了后期，我会把“取数据、做校验、改状态、落库”这些逻辑抽到 Service 层，Controller 里保持温和。
4.3 用 curl 走一遍请求并回头查库
项目启动之后，控制台出现 Tomcat started 的日志，说明 Spring Boot 已经起来。此时用 curl 模拟客户端请求，顺序验证增删改查。
新增一条数据：
curl -X POST http://localhost:8080/students \ -H "Content-Type: application/json" \ -d '{"name":"张三","age":21,"major":"软件工程"}'查询全部：
curl http://localhost:8080/students不出意外，返回的 JSON 里会出现刚才新增的记录，而且数据库里student表也多了对应的一行。这就是本地连接成功最直观的证据。接下来再验证更新和删除：
curl -X PUT http://localhost:8080/students/1 \ -H "Content-Type: application/json" \ -d '{"name":"李四","age":22,"major":"大数据"}' curl -X DELETE http://localhost:8080/students/1演示完后，可以回数据库执行SELECT * FROM student;，看看数据是否真的发生变化。这一步看起来像是在绕路，但实际操作中有很多人接口返回成功，数据库却是空的，原因往往是用了别的库或者测试数据写进了内存数据库。回到原库去查，才能确定操作的就是我们希望的库表。
4.4 换用 MyBatis、MyBatis-Plus 或 JdbcTemplate 时要注意什么
JPA 不是本地连接 MySQL 的唯一途径。下面这张表是不同方案在本地开发中的实际表现：
| 方案 | 优点 | 适合场景 |
|---|---|---|
| Spring Data JPA | 单表 CRUD 代码量少，自动装配方便 | 快速原型、简单的管理后台 |
| MyBatis | SQL 全自动，复杂查询可读性好 | 擅长报表、统计类查询 |
| MyBatis-Plus | 继承基础 CRUD，条件构造器好用 | 业务系统、单表操作占比高 |
| JdbcTemplate | 轻量，无 ORM 概念 | 追求极致控制、连接池复用 |
不管用哪种组合，数据源配置部分完全一样。区别只是在依赖和 Mapper 注解上，spring.datasource.url、username、password不会被影响。这正是 Spring Boot 设计的巧妙之处：数据库连接是一层独立能力，业务选型无论 JPA 还是 MyBatis，都可以共用同一份数据源配置。
5. 本地连接 MySQL 最常见的 5 类问题
5.1 SSL 错误与认证插件不兼容
现象一：启动项目时报SSL connection error，或Unable to load authentication plugin 'caching_sha2_password'。
本质是 MySQL 8 默认用的认证插件和驱动侧的 SSL 策略不一致。本地开发时，最简单的处理是在 URL 后追加两个参数：
useSSL=false&allowPublicKeyRetrieval=true这能解决本地约八成的连接失败。需要明确，useSSL=false只适用于本地开发，生产环境如果数据库支持 SSL，应该反过来开启 SSL 并配置证书，而不是图省事继续关闭。
有一种更绕的坑：项目里引了mysql-connector-java5.x 老版本驱动，这版不支持 MySQL 8 的认证方式。改成 Spring Boot 3 默认管理的com.mysql:mysql-connector-j后，问题会直接消失。
5.2 “Public Key Retrieval is not allowed” 是怎么回事
这个报错几乎只在 MySQL 8 上出现，非常典型。原因是caching_sha2_password算法在内网连接时，需要向服务器请求公钥来加密密码。如果allowPublicKeyRetrieval没开，驱动就不允许获取公钥，连接自然失败。
解决方案有两个。一是加上allowPublicKeyRetrieval=true，本地用最简单。二是把用户的认证插件改回mysql_native_password：
ALTER USER 'demo_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'Demo123456'; FLUSH PRIVILEGES;从实用角度讲，我会优先选第一种，因为改认证插件属于数据库层面的全局动作，可能会影响其他客户端，没有必要为一个连接去改服务端默认行为。
5.3 时区、字符集和乱码
报错最常见的这种：
The server time zone value '...' is unrecognized or represents more than one time zone.原因很简单：MySQL 服务器时区和运行 Spring Boot 的 JVM 时区不一致。追加serverTimezone=Asia/Shanghai即可。想彻底点，也可以在 MySQL 端执行SET global time_zone = '+8:00';，双管齐下。
乱码问题则通常是字符集不一致。常见情况是数据库默认latin1，而实体类往里面写中文，结果落到库里全变成问号。最佳实践是数据库、表、连接 URL 三处都用utf8mb4。utf8mb4比utf8多支持四字节字符，未来遇到 emoji 也不会出岔子。
5.4 驱动、URL 与 Access denied
这类问题通常直接体现在异常前几行，容易定位：
| 异常关键字 | 原因 | 解决方法 |
|---|---|---|
ClassNotFoundException | 缺少驱动依赖或坐标写错 | 换成com.mysql:mysql-connector-j |
Unknown database | URL 里的库名不存在 | 在 MySQL 里创建同名数据库 |
Access denied for user | 用户名密码错误或权限不足 | 检查密码、账号是否只授权了指定库 |
Communications link failure | 服务没启动或端口不可达 | `netstat -ano |
这里特别提醒一句：Access denied 不一定是密码错。我遇到过两次，都是因为账号权限只授权了其他人的库，业务库里根本没权限。所以排查时先执行SHOW GRANTS FOR 'demo_user'@'localhost';，看看账号到底能碰哪些库。
5.5 MySQL 服务没起来，或者端口被占用
如果项目启动时直接报Connection refused，先把 MySQL 服务状态确认一遍。Windows 上可以用net start MySQL或任务管理器查看服务，macOS 和 Linux 用service mysql status或systemctl status mysql。
端口占用也是本地开发常见的坑。360 或某些全家桶软件喜欢占用 3306，或者你自己开了多个 MySQL 实例导致端口冲突。执行下面这条命令，能立刻看到是谁占用了 3306：
netstat -ano | findstr 3306如果发现占用进程不是 mysqld，要么停掉该进程，要么把 MySQL 端口改成 3307，同时把 URL 里的端口也同步改掉。端口这东西只要两处一致，就不存在“对不上”的问题。
6. 连接成功后的几个本地开发好习惯
6.1 全链路字符集对齐：数据库、连接、实体一处不漏
中文乱码的根源十有八九是字符集不一致。数据库是utf8mb4，连接 URL 也要带上useUnicode=true&characterEncoding=utf8，而 Maven 项目里的源码文件编码，最好在pom.xml里设置成 UTF-8：
<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties>这套链路看着繁琐，但能让你在本地开发时彻底告别“页面全是问号”的情况。相比之下，任何一环缺失，都可能让人花半小时去排查一个根本不复杂的编码问题。
6.2 连接池生命周期要与 MySQL 超时匹配
MySQL 服务端默认wait_timeout一般是 8 小时，也就是说连接空闲超过这个阈值会被服务端主动断开。如果连接池里的连接存活时间超过 8 小时，某次请求就会拿到失效连接，出现“用着用着突然报连接关闭”的情况。
本地开发和生产环境都要遵守一个规则：连接池的max-lifetime比 MySQL 的wait_timeout小一点。比如 MySQL 的wait_timeout是 28800 秒，HikariCP 的max-lifetime可以配成 1200000 毫秒，也就是 20 分钟，这比 8 小时小得多，完全能避免拿到已断开的连接。
想确认 MySQL 端真实超时时间，执行：
SHOW VARIABLES LIKE 'wait_timeout';这个命令在生产排查时同样适用，属于数据库优化里很基础但必须了解的点。
6.3 用日志和客户端观察 SQL 执行
show-sql: true能帮你在控制台看到 JPA 自动生成的 SQL。注意，show-sql因为使用stdout输出，启动时可能打印 SQL，但也容易刷屏。实际项目我更推荐用logging.level.org.hibernate.SQL=debug，这样 SQL 可以统一进日志文件，不污染控制台。
本地调试时，我会同时开着 Navicat 或 MySQL Workbench 的会话监控。这样当 Controller 收到请求后，数据库客户端能立刻看到哪条表被加了锁、哪个连接被占住。有一次我发现接口慢到十几秒，排查后不是 SQL 慢，而是锁等待时间过长，这种情况只靠业务代码看很难定位，数据库端会话列表一打开就一目了然。
再补充一个成本很低但很实用的习惯：每次本地调试完数据，不要手动在客户端里乱改表，尽量通过接口或明确的 SQL 脚本来操作。这样项目在换人接手时，只需要跑一遍初始化脚本就能复现全流程，不必靠人工记忆“当初往库里塞了哪些测试数据”。这个习惯对长期维护的帮助，比想象中的大得多。
