简介这是一份面向Java开发者的Spring Boot使用JDBC连接MySQL数据库的完整解决方案覆盖从环境准备、驱动配置、连接参数设置到数据访问与项目运行的全过程适合正在学习Spring Boot数据持久化、或需要在业务项目中快速整合数据库的初中级开发者。资源共136个文件以Java源码、class字节码、SQL脚本、XML配置为核心同时附带dll、exe、msi等依赖库和安装组件整体大小约637MB可支撑从开发调试到部署上线的完整链路。包内JdbcController、User等类配合SQL脚本与配置文件可直接对照理解JDBC连接池初始化、CRUD操作封装以及异常处理等关键环节。已有598人学习下载说明这套方案在同类场景中具有参考价值可直接应用于实际项目也能帮助读者避开常见配置坑降低Spring Boot连接MySQL的入门门槛。1. 先说结论SpringBoot用JDBC连MySQL为什么绕不开花三分钟用 SpringBoot 自带的 JDBC Starter 直连 MySQL你能把整个数据链路从头到尾握在手里SQL 是自己写的、连接是自己开的、事务是自己控的。相比 JPA 的隐式查询和 MyBatis 的 XML 映射JDBC 这种方式没有任何黑匣子出问题一行一行日志就能定位。这篇方案适合正在做轻量级后台、内部工具、学习框架底层或者被 ORM 生成的 SQL 坑过的开发者也适合想从零搭一个可维护数据访问层的团队。它不是要替代 MyBatis 或 JPA而是把最可靠的兜底方案讲透从装 MySQL 到写好 DAO 再到避开高频坑照着做就能跑。2. 先把运行环境装明白MySQL安装包、JDK版本与SpringBoot工程骨架在写任何一行 Java 代码之前先把三样东西坐实MySQL 服务能连、JDK 版本和 SpringBoot 版本匹配、驱动包能加载。这里最容易翻车的不是代码而是环境。装 MySQL 时安装包选哪个、初始化时密码怎么定、JDK 是 8 还是 17这三个问题不先定下来后面所有连接代码都会在同一个地方报错。2.1 安装并验证 MySQL 服务解压版与图形安装包的差异MySQL 安装包常见两种形态图形化安装程序和免安装解压版。图形化安装程序会把服务注册成 Windows 服务或 systemd 服务适合不熟悉 MySQL 内部结构的开发者解压版需要手动初始化数据目录并启动 mysqld好处是整目录可移植、能被项目源码库一起管理。这套方案里我建议用解压版因为“整套解决方案带安装包”的落地场景通常是离线环境或内网部署解压版不依赖在线安装器目录一拷就能用。# 解压版 MySQL 初始化并启动Linux/macOS 通用思路 mysqld --initialize-insecure --datadir/data/mysql-data mysqld --datadir/data/mysql-data --port3306 --socket/tmp/mysql.sock mysql -uroot -h127.0.0.1 -P3306 -p第一行--initialize-insecure会生成一个无密码的 root 账号适合本地第一条连接验证第二行启动服务时指定端口和 socket第三行用客户端验证服务是否真的能接受 TCP 连接。注意--initialize-insecure只适合开发环境生产环境一定要用--initialize并设置强密码。注意--initialize-insecure生成的空密码 root 账号只用于本地首次验证对外暴露前必须设置强密码并限制 root 的远程登录。2.2 创建 SpringBoot 工程选对 starter 与 JDK 版本工程创建用最常见的 Spring Initializr 方式或 IDE 内置向导关键在选择JDK 8 配 SpringBoot 2.xJDK 17 配 SpringBoot 3.x这两个组合是生态里验证最充分的。JDBC 相关的依赖只需要两个spring-boot-starter-jdbc和 MySQL 驱动。前者提供JdbcTemplate、DataSource自动配置和事务管理器后者是 Java 与 MySQL 协议之间的翻译层。!-- pom.xml 中与 JDBC 直连 MySQL 相关的核心依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependencymysql-connector-j是当前 MySQL 官方驱动的坐标SpringBoot 2.7 及以上版本推荐使用这个坐标更早的写法mysql:mysql-connector-java已不建议新工程使用。较新版本的 SpringBoot 会自动管理驱动版本所以这里不写version。runtime作用域表示编译期不需要直接引用驱动类只在运行期加载这样代码里不会硬编码驱动类名便于后续切换连接池实现。spring-boot-starter-jdbc这个依赖并不只是引入几个 jar它把所有与数据库连接相关的自动配置都带进来了。也就是说当你在配置文件里提供了 datasource 信息Spring 会自动创建DataSource、JdbcTemplate、PlatformTransactionManager这三个核心对象。你不需要写任何Bean方法这种现象在团队协作里尤其重要新成员只要遵循同样配置约定就不会出现每个人一套连接写法的局面。2.3 写一份能跑通的最小配置先直连再谈封装配置文件的写法决定了你能少踩多少坑。别急着上连接池、别急着配多数据源先确保一个最简单连接能跑通再逐步加东西。spring: datasource: url: jdbc:mysql://127.0.0.1:3306/demo_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalse username: root password: root123 driver-class-name: com.mysql.cj.jdbc.Driverurl里的四个参数直接对应四个高频报错serverTimezone解决时区异常characterEncodingutf8解决中文乱码useSSLfalse避免本地连接时的 SSL 握手告警useUnicodetrue是历史兼容写法。driver-class-name在 SpringBoot 2.x 中写com.mysql.cj.jdbc.Driver老驱动com.mysql.jdbc.Driver已经不建议使用。配置写好后可以用一个最简单的CommandLineRunner验证连接是否真的可用也可以在工程里写一个健康检查接口。但注意验证连接和验证查询不一样前者只证明 TCP 和认证通过后者才能证明驱动、编码、SQL 语法整体没有问题。所以我在跑通环境时习惯先执行一条SELECT 1再查询真实表。3. JDBC 连接的核心写法从 DriverManager 到 DataSource 的演进环境就绪后真正的连接代码从一行DriverManager.getConnection()开始。这个 API 是 JDBC 最原始的入口也是理解后面一切封装的基础。很多线上问题比如连接数被打满、每次请求都卡在获取连接上根源就是没理解这一步发生了什么。3.1 DriverManager 直连能跑但撑不住并发// 最原始的 JDBC 直连写法仅用于理解连接生命周期 public Connection getConnection() throws SQLException { String url jdbc:mysql://127.0.0.1:3306/demo_db ?serverTimezoneAsia/ShanghaiuseSSLfalse; return DriverManager.getConnection(url, root, root123); }每次调用这个方法都会新建一条 TCP 连接到 MySQL执行完 SQL 后这条连接要由调用方手动close()。问题在于连接的建立要经历 TCP 握手、MySQL 认证、权限校验平均耗时在几十毫秒到几百毫秒之间高并发下这个开销会被无限放大。所以直连写法只适合学习、写测试脚本或一次性数据迁移不适合放进 Web 服务的请求链路里。3.2 用 DataSource 接管连接让连接变成可复用的资源SpringBoot 的spring-boot-starter-jdbc自动配置了一个DataSource只要你在配置里写了spring.datasourceSpring 容器里就会有一个可注入的数据源对象。这个数据源默认是 HikariCP 连接池实现它做的事情是提前建立一批连接放在池子里每次请求从池中借用用完归还而不是关闭。// 注入 Spring 托管的 DataSource获取连接并归还连接 Service public class UserDao { private final DataSource dataSource; public UserDao(DataSource dataSource) { this.dataSource dataSource; } public String queryUserName(Long id) throws SQLException { String sql SELECT name FROM user_info WHERE id ?; try (Connection conn dataSource.getConnection(); PreparedStatement ps conn.prepareStatement(sql)) { ps.setLong(1, id); try (ResultSet rs ps.executeQuery()) { return rs.next() ? rs.getString(name) : null; } } } }代码里的 try-with-resources 是关键Connection、PreparedStatement、ResultSet都会在 try 块结束时自动关闭。Connection.close()在连接池场景下不是真的断开 TCP而是把连接归还到池中所以这里即使调用 close 也不会产生重复建连的开销。手动管理连接的代码如果漏了 finally 里的 close连接池会被慢慢耗尽这是排查连接数满问题时最先怀疑的点。3.3 连接 URL 的四个关键参数时区、编码、SSL 与超时JDBC URL 是整套方案里最容易被复制粘贴出错的部分。常见做法是把它当作一个配置项来管理而不是散落在代码里。四个参数按优先级排序。参数作用不设的后果serverTimezone指定 MySQL 会话时区驱动报 The server time zone value 异常characterEncoding指定客户端编码中文写入后读出乱码useSSL是否启用 SSL 加密本地开发时握手慢且有告警日志connectTimeout建立 TCP 连接的超时时间数据库宕机时请求线程长时间挂起connectTimeout和socketTimeout经常被忽略。默认情况下 Java 驱动可能长时间等待网络响应导致接口假死。建议至少设置connectTimeout3000socketTimeout60000让连接失败快速暴露而不是让调用方无限等待。4. 写一个完整的增删改查链路从请求参数到 SQL 参数的流转连接层解决之后真正进入日常工作的是业务代码。一个查询请求从 Controller 进去经过 Service最后到 DAO 执行 SQL任何一个环节类型转换不对、占位符不匹配、事务边界放错位置都会表现为线上数据不对或接口报错。这一章把这套链路完整过一遍。4.1 DAO 层用 PreparedStatement防注入也从源头规避类型转换// DAO 层插入一条用户记录并返回自增主键 public Long insertUser(String name, Integer age) throws SQLException { String sql INSERT INTO user_info (name, age) VALUES (?, ?); try (Connection conn dataSource.getConnection(); PreparedStatement ps conn.prepareStatement(sql, Statement.RETURN_GENERATED_KEYS)) { ps.setString(1, name); ps.setInt(2, age); ps.executeUpdate(); try (ResultSet keys ps.getGeneratedKeys()) { return keys.next() ? keys.getLong(1) : null; } } }?占位符由驱动负责转义杜绝了字符串拼接带来的注入风险。setString、setInt这类方法还会在驱动层做类型校验Java 的Integer不会因为 SQL 拼接而变成意外的字符串。RETURN_GENERATED_KEYS用来拿自增主键注意必须放在prepareStatement的第二个参数里放在executeUpdate之后拿不到。4.2 Service 层的事务边界多表操作必须放在同一个事务里JDBC 默认每条 SQL 自动提交两条 SQL 之间如果第二条失败第一条已经落库。业务上常见的方案是在 Service 层开启编程式事务把一条业务逻辑里的多条 SQL 包在同一个事务里任何一步失败就整体回滚。// Service 层用编程式事务管理多条 SQL 的原子性 Service public class UserService { private final UserDao userDao; private final PlatformTransactionManager txManager; public void createUserWithOrder(String name, Integer age, String orderNo) { TransactionDefinition def new DefaultTransactionDefinition(); TransactionStatus status txManager.getTransaction(def); try { userDao.insertUser(name, age); userDao.insertOrder(orderNo); txManager.commit(status); } catch (Exception e) { txManager.rollback(status); throw new RuntimeException(创建用户及订单失败事务已回滚, e); } } }PlatformTransactionManager是 Spring 提供的统一事务抽象接口默认实现会基于DataSource拿到同一个数据库连接并且在事务期间让该连接上的自动提交变为 false。事务的边界是getTransaction到commit或rollback之间两条 insert 共用这一条连接所以它们要么都成功要么都失败。4.3 Controller 层到 Service 层的参数转换别让请求体直接进 SQL// Controller 层只做参数接收与简单校验 RestController RequestMapping(/users) public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService userService; } PostMapping public Long createUser(RequestBody UserCreateRequest request) { return userService.createUser(request.getName(), request.getAge()); } }Controller 里不写任何 SQL 相关代码请求体先转成业务参数再向下传递。好处是后续接口入参变化时只需要改 Controller 的 DTODAO 和 Service 不受影响。另一个容易被忽略的细节是不要把前端传入的排序字段或列名直接拼进 SQL排序、分页、过滤这些操作的白名单要在 Service 层做否则等于把 SQL 注入的入口送给了调用方。关于参数传递我的建议是 Service 层接收基本类型或一个轻量 DTO而不是让 DAO 直接依赖 Controller 的请求体对象。这样 DAO 的复用性最高调用方可以是 Controller也可以是定时任务、消息消费者。如果你发现某个 DAO 方法有五个以上参数优先把参数封装成一个查询条件对象而不是继续加参数列表。5. JDBC 连 MySQL 的 5 个高频踩坑与排查路径JDBC 连接 MySQL 的报错信息往往很直接但报错之前那些“看起来连上了、数据却不对”的问题才是真正耗时的。这里整理五个高频问题按现象、原因、解决三个步骤来梳理遇到类似情况可以直接对照处理。5.1 时区报错The server time zone value Öйú±ê׼ʱ¼ä现象应用启动或第一次执行 SQL 时抛出The server time zone value Öйú±ê׼ʱ¼ä is unrecognized or represents more than one time zone。原因MySQL 服务端的时区设置与 JDBC 驱动不一致驱动无法解析服务端返回的时区标识。解决在 JDBC URL 中显式追加serverTimezoneAsia/Shanghai。如果不想改 URL也可以改 MySQL 全局时区配置但改 URL 更直观、不影响其他客户端。5.2 驱动类找不到ClassNotFoundException 与版本错位现象启动时出现java.lang.ClassNotFoundException: com.mysql.jdbc.Driver。原因绝大部分情况是依赖坐标不对或者驱动版本与 MySQL 服务端版本差距过大。解决把驱动坐标换成mysql-connector-j确认 SpringBoot 的依赖管理已经引入驱动版本一般无需手动指定如果指定了优先选择 8.0.x 系列它能同时兼容 MySQL 5.7 和 8.x 服务端。5.3 中文乱码写入正常、查询变问号现象客户端查到的是???但用 MySQL 客户端工具直接查数据库显示正常。原因JDBC URL 缺少characterEncodingutf8驱动使用默认字符集与数据库交互。解决在 URL 中加入characterEncodingutf8并确认数据库表本身字符集是utf8mb4而不是latin1。改完 URL 后重启应用即可生效不需要改表数据。5.4 连接拒绝Communications link failure 与 Access denied现象连接时报Communications link failure或Access denied for user。原因前者通常是网络不通、MySQL 未启动、bind-address限制了来源 IP后者是用户名密码或权限问题。解决先用命令行客户端在应用所在机器执行同样的连接命令确认网络和服务层面是否可达再看 MySQL 用户表里的 host是否限制了只允许本机连接。应用配置里127.0.0.1与localhost的区别也要注意前者走 TCP后者可能走 socket 文件。5.5 连接泄漏连接池耗尽导致接口全部超时现象应用运行一段时间后所有查询接口开始排队超时重启后恢复过段时间又复发。原因代码里获取了Connection但异常路径没有关闭连接池里可用连接被慢慢耗尽。解决统一改成 try-with-resources把Connection、Statement、ResultSet的获取放在 try 的括号里。如果历史代码多推荐加一个连接池监控实时查看活跃连接数一旦持续增长就定位到具体 DAO 方法。五条里最容易反复出现的是最后一条因为它的报错滞后于问题发生。连接池监控里活跃连接数从个位数慢慢涨到上限这个过程通常跨越几个小时甚至几天等到接口超时再查代码往往已经很难定位是哪一次请求漏关了连接。所以我的习惯是在写 DAO 的第一天就统一用 try-with-resources不留手写 close 的空间。6. 把直连方案升级成可交付的工程连接池参数、事务注解与源码组织到这里基础链路已经能跑了但离“整套解决方案”还差两步一是把连接管理交给专业的连接池并设置好参数二是把事务从手写代码换成注解让业务代码更干净。6.1 调整 HikariCP 核心参数让连接池适配你的并发量SpringBoot 默认的 HikariCP 参数偏保守。常见的做法是在application.yml里追加连接池配置而不是直接改代码。spring: datasource: hikari: maximum-pool-size: 10 minimum-idle: 5 connection-timeout: 30000 idle-timeout: 600000 max-lifetime: 1800000maximum-pool-size不是越大越好MySQL 默认最大连接数一般是 151应用实例数量乘以连接池上限后要留出余量否则其他管理工具连不进去。connection-timeout是等待获取连接的超时时间max-lifetime要小于 MySQL 的wait_timeout避免服务端把连接回收后客户端还在用。线上调参建议从 10 开始观察活跃连接数曲线后再逐步调整。6.2 用 Transactional 替换手写事务一个注解管的边界编程式事务适合事务逻辑频繁变化的场景但更多情况下Transactional更省事。把注解加在 Service 方法上Spring 会在方法执行前开启事务、正常返回时提交、抛异常时回滚。要注意方法的访问权限必须是 public并且注解生效是通过代理实现的同类内部调用不会触发事务。这个细节排查起来很隐蔽如果发现事务没生效先确认是不是同一个类里 this 调用。6.3 源码组织与交付把安装包说明、SQL 脚本和代码分层放在一起一套能交付的解决方案在代码之外要配套三类文件环境说明、初始化 SQL、启动步骤。环境说明里写明 JDK 版本、MySQL 版本、连接驱动版本初始化 SQL 里建库建表并插入基础数据启动步骤覆盖“安装 MySQL→导入 SQL→修改配置→启动应用→验证接口”五步。源码部分建议按controller、service、dao、config四层包结构组织config里只放数据源和事务相关配置。我的习惯是每次交付前在干净的机器上按文档从头执行一遍装 MySQL、导 SQL、改配置、起应用哪一步出了文档里没覆盖的问题就当场把文档补上。这个操作看起来很基础但它能筛掉相当一部分“在我机器上能跑”的隐患。希望帮到你。本文还有配套的精品资源点击获取