JDBC 这个东西很多 Java 开发天天在用但真要自己从零写一遍“Java 连 MySQL 并完成增删改查”不少人反而会卡在几个很基础的环节上。驱动版本不一致、时区报错、连接池参数不会填、PreparedStatement 和 Statement 搞混这些坑我早年都踩过。这篇文章我会从一条完整的链路讲起怎么选驱动、怎么写连接代码、怎么处理事务和批量操作、怎么配置连接池最后再把常见的报错和排查思路整理成一张速查表。目标是让你看完能直接照着写并且理解每一步为什么要这么干。这篇内容适合谁刚学完 Java 语法、想在项目里接数据库的同学或者工作中主要用框架比如 Spring Boot JPA但对底层 JDBC 交互逻辑不太清楚的开发者。如果你属于后者这篇文章尤其有用因为框架只是把底层的 Connection、Statement、ResultSet 封装了一旦出现诡异报错最终还是得回到 JDBC 原理上来排查。1. 连接 MySQL 的整体思路与技术选型1.1 连接背后的核心链路Java 连接任何关系型数据库走的核心链路都是一样的应用代码通过 JDBC API 发起请求驱动把请求翻译成数据库能理解的协议数据库返回结果后驱动再把结果翻译回 Java 对象。打个比方JDBC 就像电源插座的标准驱动就是各种转换插头MySQL 驱动负责把 Java 的“电流”转换成 MySQL 能接收的“电流”。这条链路上有几个关键角色JDBC API是 Java 标准库的一部分java.sql包定义了一组接口比如Connection、Statement、ResultSet、PreparedStatement。JDBC Driver真正的实现者。MySQL 官方提供了mysql-connector-j以前叫mysql-connector-java它实现了 JDBC 接口底层用 socket 和 MySQL 服务端通信。数据库 URL一个格式固定的字符串告诉驱动“你要连哪台机器上的哪个数据库实例”。连接池解决“频繁创建数据库连接开销大”的问题HikariCP、Druid 都是干这个的。很多人一开始直接学框架反而跳过了这条链路。结果就是Spring Boot 里配置一个spring.datasource.url就能连上数据库但一旦换环境、改端口、调参数就不知道怎么排查。1.2 为什么直接用 JDBC 而不是上手就谈框架我见过不少新手有这种疑问现在写 Java 都是 Spring Boot MyBatis谁还手写 JDBC我的观点是框架解决的是效率问题JDBC 解决的是理解问题。你只有亲自写过一遍Class.forName虽然现在可以省略、DriverManager.getConnection、preparedStatement.executeQuery()、resultSet.next()才能理解 MyBatis 的Mapper接口背后发生了什么才能理解“数据库连接一定要释放”这句话为什么是铁律。而且手写 JDBC 在一些轻量级工具类里仍然有不可替代的价值。比如你写一个小的数据迁移脚本、一个定时任务需要快速从数据库拉数据没必要为了这点功能引入一整套 ORM 框架。所以这篇文章的代码示例也会刻意不用框架就用纯 JDBC把底子打牢。1.3 版本匹配那些容易踩的坑版本问题是我最想先说的因为这是新手最容易踩的第一个坑报错信息还不直观。MySQL 服务器版本和驱动版本需要匹配。如果你用的是 MySQL 5.7那驱动用 5.x 或 8.x 都行如果你用的是 MySQL 8.x那驱动强烈建议用 8.x因为 MySQL 8 默认的认证插件是caching_sha2_password老驱动5.1.x 及更早根本不支持这个插件连上去直接报Authentication plugin caching_sha2_password cannot be loaded。驱动坐标也变了。老项目里你可能看到的是dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version5.1.49/version /dependency新版本8.0.31 之后官方把 artifactId 改成了mysql-connector-jdependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.3.0/version /dependency别小看这个改名Maven 中央仓库里老的坐标虽然还能下但已经不再更新用新坐标才是长期方案。另外一个容易被忽略的点是 URL 参数。MySQL 8 的驱动类名从com.mysql.jdbc.Driver变成了com.mysql.cj.jdbc.DriverURL 也必须处理时区jdbc:mysql://localhost:3306/test?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf8很多报错The server time zone value Öйú±ê׼ʱ¼ä is unrecognized就是时区参数没配导致的。2. 环境准备与依赖配置2.1 JDK、MySQL 与驱动的版本搭配软件版本搭配没有唯一标准答案但有个稳妥组合可以照抄组件推荐版本说明JDK8 / 11 / 178 仍然兼容性最好17 是长期支持版MySQL Server5.7 / 8.0生产环境建议 8.0Connector/J8.0.x / 8.3.x对应新 artifactIdJDK 版本不会太挑剔真正有兼容性门槛的是驱动和数据库。有些老项目还在用 JDK 7那你只能选驱动 5.1.x。JDK 8 及以上就可以无脑上 8.x 驱动了。2.2 Maven 依赖引入的正确写法用 Maven 管理依赖推荐直接写新坐标。如果你已经在用 Spring Boot 2.7spring-boot-starter-jdbc里自带的驱动版本管理会帮你覆盖版本号不写version也可以。但如果你没有用 Spring Boot只是单独的普通 Java 工程那必须显式声明版本。完整依赖长这样dependencies !-- MySQL 驱动 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.3.0/version /dependency !-- 推荐再带上日志排查的时候能看到 SQL 执行信息 -- dependency groupIdorg.slf4j/groupId artifactIdslf4j-simple/artifactId version2.0.13/version /dependency /dependencies2.3 没有 Maven 的老项目怎么办我接手过一些老项目不用 Maven 也不用 Gradle就是普通 Eclipse Java 工程依赖全靠手动往 classpath 里塞 jar 包。这种情况下注意一点驱动 jar 包必须放在 WEB-INF/lib 下如果是 Web 项目或者直接加进 classpath并且发布的时候确认 jar 包真的打进去了。之前在某个老系统上遇到过“本地能连数据库部署到服务器就连不上”的诡异问题排查到最后发现是构建工具没有把驱动 jar 包打进去classpath 里根本没有驱动类。这种问题不会给你清晰的报错提示只会报ClassNotFoundException但从日志上不容易看出是打包问题。3. 基础交互JDBC 五步法与关键细节3.1 加载驱动与建立连接早期写法里第一行一定是Class.forName(com.mysql.cj.jdbc.Driver);JDBC 4.0 之后SPI 机制会自动加载驱动这行代码其实可以省略。但我个人的建议是在框架外写代码时保留这一行不要赌环境。用了Class.forName可以让驱动注册过程显式化一旦驱动包缺失报错能更早暴露。接下来是建立连接String url jdbc:mysql://localhost:3306/test?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf8; String username root; String password 123456; try (Connection conn DriverManager.getConnection(url, username, password)) { System.out.println(连接成功数据库产品信息 conn.getMetaData().getDatabaseProductName()); }这段代码有几个值得展开的地方。getConnection的底层逻辑是DriverManager遍历所有注册过的驱动逐个尝试用你的 URL 去连接哪个驱动能解析这个 URL 就用哪个。如果 URL 写错了比如端口不对会报Communications link failure这个错我后面会详细说。URL 里的参数每个都有讲究useSSLfalseMySQL 8 默认是 true但本地开发环境一般没有配置 SSL 证书true 反而会报 SSL 警告甚至连接失败。生产环境如果要加密传输单独配置证书链。serverTimezoneAsia/Shanghai解决时区问题。characterEncodingutf8避免中文乱码。注意 MySQL 里utf8不是真正的全量 UTF-8utf8mb4才是。所以强烈建议数据库建表用utf8mb4连接参数可以写characterEncodingutf8驱动会做映射也可以用最新的参数名connectionCollationutf8mb4_unicode_ci。还要注意一点MySQL 8.x 默认认证插件是caching_sha2_password如果驱动版本支持连接没问题但当你看到Public Key Retrieval is not allowed这个报错时需要给 URL 加上allowPublicKeyRetrievaltrue这个参数的含义是允许客户端向服务端请求公钥用于 RSA 加密传输密码。生产环境谨慎开启本地开发直接打开省事。3.2 Statement 执行 SQL 与 ResultSet 遍历连接建立后执行 SQL 需要三个步骤创建 Statement、执行、处理结果。try (Connection conn DriverManager.getConnection(url, username, password); Statement stmt conn.createStatement(); ResultSet rs stmt.executeQuery(SELECT id, name, age FROM user)) { while (rs.next()) { int id rs.getInt(id); String name rs.getString(name); int age rs.getInt(age); System.out.println(id id , name name , age age); } }这里最容易忽略的是ResultSet的行指针机制。刚查询完指针指向第一行之前的区域必须调用rs.next()把指针往下移动一行移动到有数据的位置时返回true移动到末尾返回false。这个机制也是很多从别的语言转过来的开发者容易不习惯的地方。getXxx方法有按列名取和按列索引取两种方式。按列索引取下标从 1 开始不是 0这一点和数组不同。如果列名写错运行时不会马上报错只有取数据的时候报Column xxx not found排查起来要仔细看 SQL 里的别名和列名。3.3 增删改查的完整实现增删改查四类操作只有查询用executeQuery其他都用executeUpdate。这里直接给一个完整的工具类雏形覆盖五个基础方法public class UserDao { private static final String URL jdbc:mysql://localhost:3306/test?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf8allowPublicKeyRetrievaltrue; private static final String USERNAME root; private static final String PASSWORD 123456; public ListUser findAll() { String sql SELECT id, name, age FROM user; ListUser list new ArrayList(); try (Connection conn DriverManager.getConnection(URL, USERNAME, PASSWORD); Statement stmt conn.createStatement(); ResultSet rs stmt.executeQuery(sql)) { while (rs.next()) { User user new User(rs.getInt(id), rs.getString(name), rs.getInt(age)); list.add(user); } } catch (SQLException e) { e.printStackTrace(); } return list; } public int insert(User user) { String sql INSERT INTO user (name, age) VALUES ( user.getName() , user.getAge() ); try (Connection conn DriverManager.getConnection(URL, USERNAME, PASSWORD); Statement stmt conn.createStatement()) { return stmt.executeUpdate(sql); } catch (SQLException e) { e.printStackTrace(); } return 0; } }注意这个 insert 方法演示用没问题真实项目绝对不能这样写。字符串拼接 SQL 会引发两个严重问题一是 SQL 注入二是在值里遇到单引号时直接语法错误。下一节我会重点讲怎么用PreparedStatement解决。3.4 资源释放的正确姿势资源释放是 JDBC 学习里最重要的一条军规Connection、Statement、ResultSet 全部都要关闭顺序是逆序关闭——先关 ResultSet再关 Statement最后关 Connection。为什么要逆序从资源依赖关系上理解Connection 是底层物理连接Statement 依赖 Connection 创建ResultSet 又依赖 Statement。释放的时候如果先关 Connection底层连接已经断了依赖它的 Statement 和 ResultSet 可能就没办法正常释放内部资源。现代 Java 提供了try-with-resources语法极大简化了这个过程。只要类实现了AutoCloseable接口try块结束时 JVM 会按照创建顺序的逆序自动关闭所有资源。所以上面的代码里我全部用了try (...)。但不是所有资源都能写进 try 的括号里。比如你从连接池里拿的Connection关闭它其实意味着“归还给连接池”而不是真正物理断开这个语义上的差异用try-with-resources也能正确处理因为连接池的close()方法内部就是归还逻辑。注意finally块里手动关闭资源的老写法仍然大量存在于生产代码中但新代码请一律用try-with-resources。它不仅能避免遗漏关闭还能让异常处理更干净。4. SQL 注入与 PreparedStatement 实战4.1 SQL 注入是怎么发生的假设你的登录查询是String sql SELECT * FROM user WHERE name name AND password password ;如果用户在输入框里输入admin --注意后面有个空格拼接出来的 SQL 就变成了SELECT * FROM user WHERE name admin -- AND password --在 MySQL 里是注释符后面的条件全被注释掉了。只要你输入一个存在的用户名不需要密码就能绕过认证。更严重的还能拼出; DROP TABLE user;--这种破坏性语句。这是 Web 安全领域最经典的攻击方式之一至今依然存在。别看是老技术我见过的新项目里依然有这种拼接写法。4.2 PreparedStatement 防注入的原理PreparedStatement解决注入的思路是SQL 骨架先编译数据后填充。String sql SELECT * FROM user WHERE name ? AND password ?; try (Connection conn DriverManager.getConnection(URL, USERNAME, PASSWORD); PreparedStatement ps conn.prepareStatement(sql)) { ps.setString(1, name); ps.setString(2, password); try (ResultSet rs ps.executeQuery()) { while (rs.next()) { // 处理结果 } } }?是占位符setString方法填进去的内容会被驱动转义成一个合法的字符串字面量单引号、反斜杠都会被正确处理。用户输入变成“数据”而不是“SQL 片段”从根上断了注入的路。这里有几个细节容易出问题占位符序号从 1 开始不是 0。setString并不是唯一选择传入日期要用setDate传入整数用setInt类型不匹配时数据库会报错方便提前暴露问题。同一个PreparedStatement可以重复执行先setObject(1, a)执行一次再setObject(1, b)执行一次SQL 骨架不变效率比反复拼接 SQL 高。4.3 预编译在性能上的收益预编译另一个好处是性能。数据库接到 SQL 之后要先解析、优化、编译生成执行计划。对于使用?占位符的 SQL只要骨架一样MySQL 会缓存执行计划后续只需要把参数填进去执行即可。举个例子循环插入一万条数据for (User user : userList) { String sql INSERT INTO user (name, age) VALUES ( user.getName() , user.getAge() ); stmt.executeUpdate(sql); }执行这条 SQL 一万次数据库编译了一万次。而用PreparedStatementString sql INSERT INTO user (name, age) VALUES (?, ?); try (Connection conn DriverManager.getConnection(URL, USERNAME, PASSWORD); PreparedStatement ps conn.prepareStatement(sql)) { for (User user : userList) { ps.setString(1, user.getName()); ps.setInt(2, user.getAge()); ps.addBatch(); if (userList.indexOf(user) % 500 0) { ps.executeBatch(); } } ps.executeBatch(); }SQL 只编译一次配合addBatch/executeBatch做批量提交性能提升非常明显。我实测过万条数据逐条 insert 大约需要十几秒用批量提交压缩到一两秒以内。5. 事务控制与批量操作5.1 手动提交事务的完整流程JDBC 默认的提交模式是自动提交也就是每条 SQL 执行完就立刻 commit。但在真实业务里比如转账、下单扣库存必须保证“多条 SQL 同时成功或同时失败”。核心步骤就三步关闭自动提交、执行多条 SQL、提交或回滚。try (Connection conn DriverManager.getConnection(URL, USERNAME, PASSWORD)) { // 关键关闭自动提交 conn.setAutoCommit(false); try (PreparedStatement ps conn.prepareStatement(UPDATE account SET balance balance - 100 WHERE id ?)) { ps.setInt(1, 1); ps.executeUpdate(); try (PreparedStatement ps2 conn.prepareStatement(UPDATE account SET balance balance 100 WHERE id ?)) { ps2.setInt(1, 2); ps2.executeUpdate(); } } conn.commit(); } catch (SQLException e) { // 一旦出错回滚 conn.rollback(); e.printStackTrace(); }注意回滚的写法。很多人会把rollback放在catch块里这没错但有一个细节如果数据库连接本身因为网络异常断开执行rollback可能又抛出一个新的 SQLException。更稳妥的做法是 catch 里先判断连接是否还有效catch (SQLException e) { if (conn ! null) { try { conn.rollback(); } catch (SQLException ex) { ex.addSuppressed(e); ex.printStackTrace(); } } }另外一个高频错误是如果在事务里执行了 DDL比如CREATE TABLEMySQL 会隐式提交导致事务边界失效。这一点极其坑人排查事务不生效的问题时先看看事务里有没有混入 DDL 语句。5.2 批量写入的十万行实践批量写入在实际工作中非常有价值。你帮业务方导数据十万条记录如果一条条 insert可能要几分钟用批量写入十几秒就能跑完。批量写入的底层逻辑是先把多条 SQL 攒在客户端内存里攒到一定量后一次性发给数据库执行减少网络往返。这个“一定量”很关键不是越多越好。每个数据库驱动都有自己的参数限制MySQL 驱动默认有rewriteBatchedStatements参数如果不开它批量写实际退化成逐条执行。所以要开连接参数jdbc:mysql://localhost:3306/test?rewriteBatchedStatementstrue代码写法String sql INSERT INTO user (name, age) VALUES (?, ?); try (Connection conn DriverManager.getConnection(URL, USERNAME, PASSWORD); PreparedStatement ps conn.prepareStatement(sql)) { conn.setAutoCommit(false); int batchSize 500; for (int i 0; i 100000; i) { ps.setString(1, user_ i); ps.setInt(2, i % 100); ps.addBatch(); if (i % batchSize batchSize - 1) { ps.executeBatch(); conn.commit(); } } ps.executeBatch(); conn.commit(); }批量大小我一般设 300 到 1000经验值。设太小频繁执行批量操作收益打折设太大内存占用和驱动内部缓冲可能出问题。如果你要导大量数据建议先小样本测试找到当前表结构下的最优批量大小。经验批量插入最怕主键冲突和唯一索引。批量执行报错时日志不会明确告诉你哪条数据出了问题定位难度大。导入前先清洗一遍数据确保没有重复记录再执行批量。6. 连接池选型与配置6.1 为什么不用 DriverManager 裸连DriverManager.getConnection每次调用都会创建一个物理连接数据库端需要完成 TCP 握手、认证、分配线程等操作这个开销相当可观。在一个日活几万人的系统里每个请求都裸连数据库数据库很快就会被拖垮。连接池的思路是预先创建一批物理连接放在池子里谁用谁取用完归还不够就新增空闲太多就回收。市面上主流的连接池有连接池特点适用场景HikariCPSpring Boot 默认性能极高代码精简绝大多数新项目Druid阿里开源监控能力强内置 SQL 防火墙需要监控和权限控制的中大型系统DBCP老牌连接池老项目维护、简单场景C3P0时代久远不推荐新项目使用遗留系统我的建议是新项目直接 HikariCP一个常用功能一个没有短板性能还最强。需要监控大屏和 SQL 审计再看 Druid。6.2 HikariCP 配置实战引入依赖dependency groupIdcom.zaxxer/groupId artifactIdHikariCP/artifactId version5.1.0/version /dependency注意HikariCP 5.x 要求 JDK 11如果还在用 JDK 8用 4.0.3 版本。基本配置HikariConfig config new HikariConfig(); config.setJdbcUrl(URL); config.setUsername(root); config.setPassword(123456); config.setDriverClassName(com.mysql.cj.jdbc.Driver); config.setMaximumPoolSize(20); config.setMinimumIdle(5); config.setConnectionTimeout(30000); config.setIdleTimeout(600000); config.setMaxLifetime(1800000); config.setPoolName(myAppPool); HikariDataSource dataSource new HikariDataSource(config);使用的时候很简单try (Connection conn dataSource.getConnection()) { try (PreparedStatement ps conn.prepareStatement(SELECT 1)) { try (ResultSet rs ps.executeQuery()) { rs.next(); System.out.println(rs.getInt(1)); } } }拿到的 Connection 用法和直接用DriverManager拿到的完全一样只是close()的语义从“关闭物理连接”变成了“归还连接池”。6.3 连接池参数怎么调连接池参数没有万能模板要根据系统的并发量、SQL 平均执行时间、数据库规格来调整。几个关键参数maximumPoolSize最大连接数。很多人一上来就设 200数据库 CPU 都打满了还加连接反而互相抢资源。经验公式大概是((核心线程数 * 2) 有效磁盘数)HikariCP 官方文档推荐的计算方式是connections ((core_count * 2) effective_spindle_count)。8 核机器例如就是 16~20。并发再高也建议先压测不要盲目调大。minimumIdle池中最小空闲连接数一般和 maximumPoolSize 设成一样避免频繁创建和销毁连接。connectionTimeout等待连接的最大毫秒数超过就抛异常。一般 3 秒到 10 秒。maxLifetime连接池中连接的最长存活时间要小于数据库端wait_timeout不然连接会被数据库端空闲断开池子里拿到坏连接。idleTimeout连接空闲多久后从池中移除要小于 maxLifetime。踩过最典型的坑是数据库端wait_timeout默认 8 小时而连接池里连接的 maxLifetime 设置成了 13 小时半夜没流量MySQL 把连接断开第二天早上来流量应用从池子里拿到已经被断开的死连接报Communications link failure。解决方式就是让连接池的连接生命週期低于数据库端的超时时间并且加上连接有效性校验。7. 常见问题与排查技巧7.1 经典报错速查表整理一份速查表按报错信息准确度排序方便遇到问题快速定位报错信息常见原因解决思路ClassNotFoundException: com.mysql.cj.jdbc.Driver驱动 jar 包没引入或没打进去检查 Maven 依赖、检查打包产物Communications link failure网络不通、端口错、MySQL 没启动、连接被数据库断开用 telnet 测端口确认 MySQL 状态Access denied for user rootlocalhost账号密码错误或主机白名单限制核对账号密码确认 MySQL 的 host 授权Unknown database test数据库不存在先建库或者改 URL 里的库名Server time zone value ... is unrecognizedURL 缺少时区参数加上serverTimezoneAsia/ShanghaiPublic Key Retrieval is not allowedMySQL 8 认证插件问题URL 缺参数加上allowPublicKeyRetrievaltrueThe driver has not received any packets from the server网络问题或服务器端防火墙拦连接用 MySQL 客户端先本机测试再检查防火墙Cant connect to MySQL server on localhost (10061)MySQL 服务未启动或端口未监听启动服务检查端口监听状态7.2 排查思路与方法排查数据库连接问题我有几个固定套路成本低见效快先telnet测端口通不通telnet localhost 3306端口不通不用看代码先看数据库服务状态和防火墙。端口通了再用命令行客户端试试mysql -uroot -p -h localhost -P 3306这个命令能成功说明账号、网络、权限都没问题问题大概率在 JDBC 驱动的 URL 参数或驱动版本上。也验证过 MySQL 8 下跑了 5.x 驱动导致的认证失败用这个套路能快速定位。还有一个容易被忽略的历史项目里存在多个版本驱动 jar 包。比如容器里既有mysql-connector-java-5.1.x.jar又有mysql-connector-java-8.0.x.jarDriverManager是按类加载顺序来的可能同一个 Java 进程里某些区域用老驱动某些区域用新驱动报错非常隐蔽。检查一遍 lib 目录把旧驱动清理干净。7.3 性能调优的实操体会最后说点性能优化的实操体会。连接池配好、PreparedStatement 用上、批量写入开了之后数据库性能还有几个提升空间SQL 执行计划分析对慢 SQL 用EXPLAIN查看执行计划关注type和rows列。全表扫描的typeALL要重点优化考虑加索引。字段类型匹配Java 端setString传的值如果和数据库字段类型不匹配MySQL 会发生隐式类型转换导致索引失效。比如数据库字段是intJava 端传1两个都没错但执行计划就走偏了。连接参数rewriteBatchedStatementstrue必须开这是批量写入提速的关键。useServerPrepStmtstruecachePrepStmtstrue也能提升 PreparedStatement 的预编译缓存效果。我个人在实际操作中还有一个习惯每个查询都先问自己“这条 SQL 会扫描多少行”。不会扫描超过一万行的查询不需要什么花哨优化会扫描上百万行的查询连接池配得再好也救不了你。先优化 SQL再考虑连接层面的调优顺序不能反。数据库连接这块踩坑是正常的。版本、时区、连接池参数、事务边界每一项单独看都不难但叠在一起就容易让人焦头烂额。遇到问题别急着翻框架源码回到 JDBC 这条最基础的链路上从 URL 到 Driver 到 Connection 一层层排查多半能定位。最后再分享一个小技巧写测试类的时候先写一个SELECT 1的验证代码确认“最小链路”通了再往上叠业务逻辑能帮你把问题的范围缩小一大半。