JDBC-SQL执行
[TOC]
概述
JDBC(Java Database Connectivity,Java 数据库连接) 是 Java SE 核心类库中定义的一套用于执行 SQL 语句的标准 Java API,主要由 java.sql 和 javax.sql 两个包中的接口与类组成。
在没有统一规范之前,不同关系型数据库(如 MySQL、Oracle、PostgreSQL、SQL Server)各自拥有私有的网络通信协议与底层 C/C++ 客户端库。如果 Java 程序员直接调用各数据库厂商的私有 API,一旦项目更换底层数据库,所有数据访问层代码都必须重写。JDBC 通过引入“面向接口编程”的设计思想,由官方制定统一的标准接口,由各数据库厂商提供遵循该标准的底层实现类(即数据库驱动 Jar 包),从而实现 Java 应用程序与具体数据库的解耦。
架构设计
JDBC 采用桥接模式(Bridge Pattern)与服务提供者框架(SPI),将整体架构划分为面向应用开发者的标准接口层(JDBC API) 与面向数据库厂商的驱动实现层(JDBC Driver API)。
JDBC API
JDBC API 位于 java.sql(核心基础接口)与 javax.sql(数据源、连接池与分布式事务扩展接口)包中,供 Java 应用程序直接调用。应用代码在编译期和运行期只需依赖这套标准接口即可完成连接获取、SQL 发送、结果集解析和事务控制,无需关心底层连接的是哪一种数据库。
JDBC Driver API
JDBC Driver API 是各数据库厂商根据自身私有通信协议对 java.sql 标准接口做出的具体实现(如 MySQL 提供的 mysql-connector-j、Oracle 提供的 ojdbc)。驱动内部负责将标准 JDBC 方法调用转换为特定数据库的二进制网络报文(如 MySQL Protocol),并将数据库服务端返回的字节流解析封装为标准结果集对象。

示例: 模拟 JDBC
为了直观理解 JDBC 的解耦思想,可以通过 myjdbc 的四段核心代码模拟“Java 官方标准接口”、“数据库厂商驱动实现”与“Java 应用程序调用”三方之间的协作关系。
1. JdbcInterface
模拟 Java 官方制定的 JDBC 标准接口,仅声明获取连接、执行增删改查和关闭连接的统一方法签名,不包含任何特定数据库的底层实现:
package myjdbc;
// 1. 模拟 Java 官方规定的 JDBC 规范接口
public interface JdbcInterface {
// 2. 定义获取数据库连接的统一标准方法
public Object getConnection();
// 3. 定义执行增删改查操作的统一标准方法
public void crud();
// 4. 定义关闭数据库连接的统一标准方法
public void close();
}2. MysqlJdbcImpl
模拟 MySQL 数据库厂商提供的驱动实现类,实现官方 JdbcInterface 接口,在方法体内编写针对 MySQL 底层协议的具体连接与操作逻辑:
package myjdbc;
// 1. 模拟 MySQL 厂商实现官方 JdbcInterface 规范接口
public class MysqlJdbcImpl implements JdbcInterface {
@Override
public Object getConnection() {
System.out.println("得到 mysql 的连接");
return null;
}
@Override
public void crud() {
System.out.println("完成 mysql 增删改查");
}
@Override
public void close() {
System.out.println("关闭 mysql 的连接");
}
}3. OracleJdbcImpl
模拟 Oracle 数据库厂商提供的驱动实现类,同样实现 JdbcInterface 接口,使不同厂商的驱动在调用层面保持完全一致的形态:
package myjdbc;
// 1. 模拟 Oracle 厂商实现官方 JdbcInterface 规范接口
public class OracleJdbcImpl implements JdbcInterface {
@Override
public Object getConnection() {
System.out.println("得到 oracle 的连接");
return null;
}
@Override
public void crud() {
System.out.println("完成 oracle 增删改查");
}
@Override
public void close() {
System.out.println("关闭 oracle 的连接");
}
}4. TestJDBC
模拟 Java 应用程序调用层。开发者通过父接口 JdbcInterface 引用指向具体的驱动实现类(多态机制),面向接口完成数据操作;当底层数据库从 MySQL 切换为 Oracle 时,只需替换实例化的驱动对象,后续所有的业务调用代码均无需改动:
package myjdbc;
public class TestJDBC {
public static void main(String[] args) {
// 1. 通过接口引用指向 MySQL 驱动实现类,面向接口调用标准方法
JdbcInterface jdbcInterface = new MysqlJdbcImpl();
jdbcInterface.getConnection();
jdbcInterface.crud();
jdbcInterface.close();
// 2. 切换为 Oracle 驱动实现类,后续调用逻辑完全保持不变
jdbcInterface = new OracleJdbcImpl();
jdbcInterface.getConnection();
jdbcInterface.crud();
jdbcInterface.close();
}
}驱动分类
根据驱动底层实现方式与通信链路的演进历史,JDBC 驱动共分为四种类型:
1. JDBC-ODBC 桥驱动(已移除)
一类驱动(Type 1) 将 JDBC 调用转换为微软的 ODBC(开放式数据库连接)调用,再由操作系统本地的 ODBC 驱动调用数据库客户端库。由于强依赖操作系统的本地 C 语言二进制库,跨平台能力差且存在性能损耗,已在 JDK 8 中被正式移除。
2. 本地 API 驱动
二类驱动(Type 2) 使用 Java 编写上层接口,底层通过 JNI(Java 本地接口)直接调用数据库厂商提供的本地 C/C++ 客户端动态链接库(如 Oracle OCI 驱动)。虽然省去了 ODBC 转发环节,但依然需要在运行机器上安装特定平台的数据库客户端软件,可移植性受限。
3. 网络协议驱动
三类驱动(Type 3) 采用纯 Java 编写,将 JDBC 调用转换为与数据库无关的中间件网络协议并发送给独立的中间件服务器,再由中间件服务器翻译为目标数据库协议。通常用于跨网段网关代理或异构数据源聚合场景。
4. 纯 Java 本地协议驱动
四类驱动(Type 4,又称瘦驱动 Thin Driver) 完全使用纯 Java 代码编写,直接实现目标数据库的私有网络通信协议,通过 Socket 与数据库服务端直接建立 TCP 连接通信。它无需在客户端安装任何非 Java 依赖,兼具跨平台特性与高性能,是目前生产环境中 MySQL、PostgreSQL、Oracle 等主流数据库统一采用的标准驱动形态。
核心组件
在一次标准的 JDBC 数据库交互过程中,主要依赖四个核心接口或类的协同配合:
1. DriverManager
驱动管理类,负责加载并管理当前 JVM 中注册的所有 Driver 驱动实现类。当应用程序传入数据库 URL 发起连接请求时,DriverManager 会遍历已注册的驱动列表,匹配出能够识别该 URL 协议头的驱动并创建对应的数据库连接。
2. Connection
数据库连接接口,代表 Java 应用程序与数据库服务端之间建立的一条物理通信会话(通常对应底层一条 TCP Socket 连接)。所有的 SQL 语句执行对象都必须通过 Connection 创建,同时它还承担着事务开启、提交(commit)与回滚(rollback)的控制职责。
3. Statement
SQL 语句执行接口(含预编译子接口 PreparedStatement 与存储过程子接口 CallableStatement),负责通过已建立的 Connection 通道向数据库服务端发送 SQL 指令,并接收数据库返回的受影响行数或查询结果集。
4. ResultSet
结果集接口,用于封装执行 SELECT 查询语句后数据库返回的表格数据。ResultSet 内部维护了一个指向当前数据行的游标(Cursor) ,默认位于第一行数据之前,开发者通过向下移动游标逐行读取列数据。
环境搭建
在使用 JDBC 编写数据访问代码前,需要先在数据库中准备测试表,并在 Java 项目中引入对应数据库厂商的驱动依赖。
准备数据库表
在 MySQL 数据库 test_db 中创建测试表 t_user 并插入初始数据:
-- 1. 创建测试表 t_user
CREATE TABLE t_user (
id INT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(50) NOT NULL,
balance DECIMAL(10, 2) NOT NULL
);
-- 2. 插入初始测试数据
INSERT INTO t_user (username, balance)
VALUES ('Alice', 1000.00),
('Bob', 500.00);
-- 3. 查询余额大于 200 的用户记录
SELECT id, username, balance
FROM t_user
WHERE balance > 200.00
ORDER BY id ASC;引入驱动依赖
根据项目的构建方式,可以通过手动导入 Jar 包或使用构建工具将 MySQL 驱动引入类路径(Classpath)中。
手动导入驱动包
在未使用构建工具的普通 Java 项目中,需手动下载并挂载驱动 Jar 包:
拷贝驱动包:在项目根目录下新建
lib(或libs)目录,将下载的驱动文件(如mysql-connector-j-8.3.0.jar)复制到该目录下。添加至类路径:在 IDE(如 IntelliJ IDEA)中右键点击该
lib目录或驱动 Jar 包,选择Add as Library...将其加入到当前模块的编译与运行类路径中。
Maven 坐标引入
若使用 Maven 构建项目,只需在 pom.xml 中添加 mysql-connector-j 坐标依赖,由 Maven 自动下载并管理类路径:
<!-- 引入 MySQL 8.x JDBC 驱动依赖 -->
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<version>8.3.0</version>
</dependency>标准执行流程
使用 JDBC 操作关系型数据库遵循固定的五步标准流程:
注册并加载驱动:将数据库厂商的
Driver实现类加载到内存中,向DriverManager完成注册(自 JDBC 4.0 起支持通过 SPI 自动加载,无需手动编写Class.forName)。获取数据库连接:调用
DriverManager.getConnection方法,传入数据库新连接地址(URL)、用户名与密码,获取Connection连接实例。创建 SQL 语句执行对象:调用
Connection对象的createStatement或prepareStatement方法,获取用于发送 SQL 的执行对象。执行 SQL 并处理结果:调用
executeUpdate执行增删改(DML)或建表(DDL)语句并获取受影响行数;或调用executeQuery执行查询(DQL)语句,通过ResultSet游标遍历提取字段值。释放数据库资源:数据库底层连接、游标与语句缓冲区均属于昂贵的外部系统资源,使用完毕后必须按“先开后关”的逆序(
ResultSet→Statement→Connection)显式关闭。

手动释放资源
在传统的异常处理结构中,为了确保发生 SQLException 时底层连接依然能够被正常回收,必须在 finally 代码块中逐一判空并关闭资源:
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class JdbcClassicDemo {
public static void main(String[] args) {
Connection conn = null;
Statement stmt = null;
ResultSet rs = null;
try {
// 1. 通过 DriverManager 获取数据库连接
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
conn = DriverManager.getConnection(url, "root", "123456");
// 2. 创建 Statement 语句执行对象
stmt = conn.createStatement();
// 3. 发送 SQL 查询语句并获取 ResultSet 结果集
String sql = "SELECT id, username, balance FROM t_user";
rs = stmt.executeQuery(sql);
// 4. 移动游标遍历结果集并按列名提取字段值
while (rs.next()) {
int id = rs.getInt("id");
String username = rs.getString("username");
double balance = rs.getDouble("balance");
System.out.println(id + " - " + username + " - " + balance);
}
} catch (SQLException e) {
e.printStackTrace();
} finally {
// 5. 按先开后关的逆序释放数据库资源
if (rs != null) {
try {
rs.close();
} catch (SQLException e) {
e.printStackTrace();
}
}
if (stmt != null) {
try {
stmt.close();
} catch (SQLException e) {
e.printStackTrace();
}
}
if (conn != null) {
try {
conn.close();
} catch (SQLException e) {
e.printStackTrace();
}
}
}
}
}自动释放资源
自 JDK 7 引入 try-with-resources 语法后,Connection、Statement 和 ResultSet 均继承了 AutoCloseable 接口。将资源声明在 try (...) 括号内部,当代码块执行完毕或抛出异常时,JVM 会自动按照声明的逆序调用它们的 close 方法,大幅简化资源释放模板代码:
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;
public class JdbcAutoCloseDemo {
public static void main(String[] args) {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String sql = "UPDATE t_user SET balance = 1200.00 WHERE username = 'Alice'";
// 1. 在 try 括号内声明实现 AutoCloseable 的资源,代码块结束时自动逆序关闭
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement()) {
// 2. 执行 DML 更新语句并返回受影响的行数
int rows = stmt.executeUpdate(sql);
System.out.println("受影响行数: " + rows);
} catch (SQLException e) {
e.printStackTrace();
}
}
}DriverManager
是 JDBC 规范提供的驱动管理核心类,充当管理所有数据库驱动(java.sql.DriverManagerjava.sql.Driver)并创建数据库连接(java.sql.Connection)的工厂组件。
在内部实现中,DriverManager 维护了一个线程安全的 CopyOnWriteArrayList<DriverInfo> 静态集合(registeredDrivers),用于存储当前 JVM 中已注册的所有驱动实例。当应用程序请求建立连接时,DriverManager 会遍历该集合,寻找能够识别目标数据库 URL 的驱动并委托其创建底层物理连接。
Driver.connect
在不借助 DriverManager 管理器的情况下,最底层的方式是直接实例化数据库厂商提供的 Driver 实现类(或通过反射 Class.forName 动态创建实例),将数据库账号与密码封装在 Properties 集合中,直接调用 方法获取连接:driver.connect(url, info)
import com.mysql.cj.jdbc.Driver;
import java.sql.Connection;
import java.sql.SQLException;
import java.util.Properties;
public class DirectDriverConnectDemo {
public static void main(String[] args) throws SQLException {
// 1. 直接实例化 MySQL 驱动类对象(也可通过反射动态实例化以降低耦合)
Driver driver = new Driver();
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
// 2. 将数据库用户名与密码封装到 Properties 属性集中
Properties info = new Properties();
info.setProperty("user", "root");
info.setProperty("password", "123456");
// 3. 绕过 DriverManager,直接调用 Driver 的 connect 方法获取底层连接
try (Connection conn = driver.connect(url, info)) {
System.out.println("直接通过 Driver 获取连接: " + conn);
}
}
}这种方式需要开发者在代码中手动创建并维护具体的 Driver 实例与 Properties 对象;而引入 DriverManager 的目的正是为了统一托管多个驱动实例,并对外提供更简捷的连接获取入口。
驱动注册
在调用 DriverManager 获取连接之前,必须先将数据库厂商提供的 java.sql.Driver 实现类(如 MySQL 8.x 的 com.mysql.cj.jdbc.Driver)注册到 registeredDrivers 集合中。根据演进历史与解耦程度,共有三种驱动注册方式。
registerDriver
最原始的注册方式是直接实例化数据库厂商的 Driver 类,并显式调用静态方法 DriverManager.registerDriver 完成注册:
import com.mysql.cj.jdbc.Driver;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
public class RegisterDriverDemo {
// 1. 显式创建特定数据库厂商的 Driver 实例并完成注册
public static void main(String[] args) throws SQLException {
DriverManager.registerDriver(new Driver());
// 2. 从 DriverManager 获取数据库连接
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
System.out.println("连接对象: " + conn);
}
}
}在实际开发中不推荐使用显式调用 registerDriver 的方式,原因有二:
编译期硬编码耦合:代码中直接
import了com.mysql.cj.jdbc.Driver,导致业务代码在编译期强依赖特定数据库驱动包;若切换数据库,必须修改 Java 源码并重新编译。重复注册两次驱动:查看
com.mysql.cj.jdbc.Driver的源码可以发现,其类内部的static静态代码块已经调用了一次DriverManager.registerDriver。当外部执行new Driver()时,类加载初始化会先触发一次静态代码块注册,随后外部方法调用又会注册第二个Driver实例:javapackage com.mysql.cj.jdbc; import java.sql.DriverManager; import java.sql.SQLException; // 1. MySQL 驱动实现类继承自 NonRegisteringDriver 并实现 java.sql.Driver public class Driver extends NonRegisteringDriver implements java.sql.Driver { // 2. 类加载初始化阶段自动执行静态代码块,向 DriverManager 注册自身实例 static { try { DriverManager.registerDriver(new Driver()); } catch (SQLException E) { throw new RuntimeException("Can't register driver!"); } } // 3. 供反射或外部实例化调用的无参构造器 public Driver() throws SQLException { } }
Class.forName@
为了消除编译期对具体驱动类的硬编码依赖,经典做法是通过反射调用 加载驱动类的全限定名。Class.forNameClass.forName 默认会将目标类加载到内存并执行类初始化(即触发 com.mysql.cj.jdbc.Driver 中的 static 静态代码块),从而仅完成一次驱动注册,且类名字符串可以抽取到外部配置文件中读取:
import java.sql.Connection;
import java.sql.DriverManager;
public class ClassForNameDemo {
public static void main(String[] args) throws Exception {
// 1. 通过反射加载驱动类,触发其 static 静态代码块完成注册
Class.forName("com.mysql.cj.jdbc.Driver");
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
// 2. 获取并使用数据库连接
try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
System.out.println("连接成功: " + conn);
}
}
}ServiceLoader
自 JDBC 4.0(JDK 6)起,JDBC 引入了 Java SPI(Service Provider Interface)服务发现机制。符合 JDBC 4.0 规范的驱动 Jar 包会在 META-INF/services/ 目录下内置一个名为 java.sql.Driver 的文本文件,文件内容即为具体的驱动实现类全限定名(如 com.mysql.cj.jdbc.Driver)。
当应用程序首次调用 DriverManager 的静态方法时,DriverManager 内部会执行 ensureDriversInitialized 方法,通过 ServiceLoader.load(Driver.class) 自动扫描类路径下所有驱动 Jar 包中的 META-INF/services/java.sql.Driver 文件并完成类加载与注册。因此在现代 JDK 环境中,无需手动编写 Class.forName 即可直接获取连接:

import java.sql.Driver;
import java.sql.DriverManager;
import java.util.Enumeration;
public class SpiDriverDemo {
public static void main(String[] args) {
// 1. 无需调用 Class.forName,直接获取 DriverManager 已自动注册的所有驱动
Enumeration<Driver> drivers = DriverManager.getDrivers();
// 2. 遍历并打印通过 SPI 机制自动加载的驱动实现类名称
while (drivers.hasMoreElements()) {
Driver driver = drivers.nextElement();
System.out.println("已注册驱动: " + driver.getClass().getName());
}
}
}JDBC URL
JDBC URL 是用于标识目标数据库协议类型、网络地址、端口、实例名称以及连接属性的标准统一资源定位符,DriverManager 依靠它来路由匹配的驱动。
语法结构
标准的 JDBC URL 由冒号分隔的三个核心部分及可选查询参数组成,格式为 jdbc:<子协议>:<子名称>?<参数名=参数值>&...:
- 主协议:固定为
jdbc,表示当前采用 JDBC 通信规范。 - 子协议:标识具体的数据库厂商或驱动类型,如 MySQL 为
mysql、Oracle 为oracle:thin、PostgreSQL 为postgresql。Driver实现类正是通过校验子协议前缀来判断自身是否能够处理该连接请求。 - 子名称:包含数据库服务端的 IP 地址(或域名)、监听端口以及目标数据库名,例如
//localhost:3306/test_db。
本机简写
在连接本地 MySQL 数据库(即主机地址为 localhost 或 127.0.0.1,且端口为默认的 3306)时,子名称中的主机名与端口号可以省略,直接本机简写为三斜杠形式:
- 完整写法:
jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC - 简写形式:
jdbc:mysql:///test_db?serverTimezone=UTC
常用参数
在数据库名称后可通过 ? 追加连接配置参数,多个参数之间使用 & 连接(在 XML 配置文件中需转义为 &):
- serverTimezone:指定 JVM 与 MySQL 服务端交互使用的时区(如
UTC或Asia/Shanghai),MySQL 8.x 驱动在服务端时区无法映射时必须显式指定。 - characterEncoding:指定客户端与服务端通信的字符集编码(如
utf8或UTF-8),MySQL 8.x 默认已采用utf8mb4。 - useSSL:是否启用 SSL 加密连接(取值为
true或false),本地开发环境通常设为false以避免证书校验警告。 - allowPublicKeyRetrieval:当 MySQL 8.x 采用
caching_sha2_password认证插件且未开启 SSL 时,需设为true允许客户端从服务端获取公钥以完成密码加密握手。 - rewriteBatchedStatements:是否开启批处理 SQL 重写优化(取值为
true或false),设为true时驱动会将多条INSERT语句合并重写为单条多值INSERT INTO ... VALUES (...), (...)语句,大幅提升批处理吞吐量。
getConnection
DriverManager 提供了多个重载的静态 getConnection 方法,用于向数据库服务端发起认证并返回 Connection 连接实例。
驱动匹配机制
所有 getConnection 重载方法最终都会汇聚到私有核心方法 getConnection(String url, Properties info, Class<?> caller)。其底层驱动匹配与连接创建逻辑如下:
private static Connection getConnection(String url, java.util.Properties info, Class<?> caller) throws SQLException {
// 1. 校验数据库 URL 是否为空,为空则直接抛出 SQLException
if (url == null) {
throw new SQLException("The url cannot be null", "08001");
}
// 2. 确保 SPI 驱动初始化已完成
ensureDriversInitialized();
// 3. 遍历 CopyOnWriteArrayList 容器中已注册的所有 DriverInfo
SQLException reason = null;
for (DriverInfo aDriver : registeredDrivers) {
if (isDriverAllowed(aDriver.driver, callerCL)) {
try {
// 4. 调用具体驱动的 connect 方法,若 URL 协议匹配则返回非空 Connection
Connection con = aDriver.driver.connect(url, info);
if (con != null) {
return con;
}
} catch (SQLException ex) {
if (reason == null) {
reason = ex;
}
}
}
}
throw new SQLException("No suitable driver found for " + url, "08001");
}当 被调用时,驱动首先会调用自身的 aDriver.driver.connect(url, info)acceptsURL(url) 方法检查 URL 子协议是否匹配:
协议不匹配:若当前遍历到的是 PostgreSQL 驱动,而传入的是
jdbc:mysql:...,则connect方法不会抛出异常,而是直接返回null,DriverManager继续遍历下一个驱动。协议匹配:若当前驱动能够识别该 URL,则向目标数据库发起 TCP 握手与身份认证,认证成功后返回创建的
Connection对象并终止循环。全部不匹配:若遍历完
registeredDrivers中所有驱动均返回null,则最终抛出SQLException: No suitable driver found for ...(常见于未引入驱动 Jar 包或 JDBC URL 协议头拼写错误)。

Properties
调用 getConnection(String url, Properties info) 时,开发者可以将数据库用户名(固定键名 user)、密码(固定键名 password)以及其他驱动级连接属性统一封装在 java.util.Properties 对象中传入,适合从外部 配置文件直接加载连接信息的场景:.properties
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Properties;
public class PropertiesConnDemo {
public static void main(String[] args) throws SQLException {
// 1. 创建 Properties 属性集并存入 user、password 及连接参数
Properties info = new Properties();
info.setProperty("user", "root");
info.setProperty("password", "123456");
info.setProperty("connectTimeout", "3000");
// 2. 传入数据库 URL 与 Properties 对象获取连接
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, info)) {
System.out.println("通过 Properties 获取连接成功: " + conn);
}
}
}在实际开发中,通常将连接地址与认证参数抽取到外部 .properties 配置文件(如 src/jdbc.properties)中,通过 Properties.load 动态读取以消除硬编码:
# src/jdbc.properties
url=jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC
user=root
password=123456
connectTimeout=3000import java.io.FileInputStream;
import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;
public class PropertiesFileConnDemo {
public static void main(String[] args) throws Exception {
// 1. 从外部 .properties 配置文件加载数据库连接属性
Properties info = new Properties();
try (FileInputStream fis = new FileInputStream("src/jdbc.properties")) {
info.load(fis);
}
// 2. 提取 URL 并直接将加载后的 Properties 对象传入 getConnection
String url = info.getProperty("url");
try (Connection conn = DriverManager.getConnection(url, info)) {
System.out.println("从配置文件获取连接成功: " + conn);
}
}
}账号密码参数
日常开发中最常使用的是三参数重载 getConnection(String url, String user, String password)。查看其 JDK 源码实现可以看到,该方法本质上是一个便捷包装方法,内部会自动实例化 Properties 对象并将非空的 user 和 password 放入其中,最后委托给核心 getConnection 方法执行:
public static Connection getConnection(String url, String user, String password) throws SQLException {
// 1. 内部自动创建 Properties 实例封装账号与密码
java.util.Properties info = new java.util.Properties();
if (user != null) {
info.put("user", user);
}
if (password != null) {
info.put("password", password);
}
// 2. 委托给核心重载方法完成驱动匹配与连接创建
return getConnection(url, info, Reflection.getCallerClass());
}API: Driver
构造方法
DriverDriver():(),驱动实例构造。创建数据库驱动实现类实例,用于直接发起底层数据库连接或向DriverManager注册驱动。
注意事项:
java.sql.Driver本身为标准接口,实际代码中调用的new Driver()属于各数据库厂商提供的具体驱动实现类(如 MySQL 的com.mysql.cj.jdbc.Driver)。com.mysql.cj.jdbc.Driver的无参构造方法声明抛出了SQLException,且在其类加载阶段会通过static静态代码块自动调用DriverManager.registerDriver(new Driver())完成注册。
import com.mysql.cj.jdbc.Driver;
import java.sql.SQLException;
public class DriverConstructorDemo {
public static void main(String[] args) throws SQLException {
// 1. 调用驱动实现类的无参构造方法创建 Driver 实例
Driver driver = new Driver();
// 2. 输出已创建的驱动实例信息
System.out.println("成功创建驱动实例: " + driver);
}
}连接建立
booleanacceptsURL():(String url),URL 协议校验。判断当前数据库驱动是否能够识别并打开指定格式的 JDBC URL;若协议头匹配则返回true,否则返回false。Connectionconnect():(String url, Properties info),物理连接创建。使用给定的 JDBC URL 和包含认证及配置参数的Properties集合尝试建立数据库连接;若当前驱动不支持该 URL 协议,则直接返回null而非抛出异常。DriverPropertyInfo[]getPropertyInfo():(String url, Properties info),连接属性探测。解析给定的 URL 与初始属性集合,返回连接目标数据库可配置的完整属性元数据数组,供可视化数据库客户端工具动态生成连接配置表单。
注意事项:
- 当传入的
url不属于当前驱动支持的协议时,connect()按规范必须返回null而不是抛出SQLException;只有当驱动识别了该 URL 但因网络故障或凭证错误导致建连失败时,才会抛出SQLException。- 实际业务开发中通常通过
DriverManager.getConnection()间接调用驱动,但直接实例化特定厂商的Driver实现类并调用connect()也是完全合法的底层连接获取方式。
import com.mysql.cj.jdbc.Driver;
import java.sql.Connection;
import java.sql.DriverPropertyInfo;
import java.sql.SQLException;
import java.util.Properties;
public class DriverConnectDemo {
public static void main(String[] args) throws SQLException {
// 1. 实例化 MySQL 驱动实现类
Driver driver = new Driver();
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
// 2. 判断当前驱动是否支持目标 JDBC URL
boolean accepted = driver.acceptsURL(url);
System.out.println("是否支持该 URL: " + accepted);
// 3. 封装连接属性并探测驱动支持的配置项元数据
Properties props = new Properties();
props.setProperty("user", "root");
props.setProperty("password", "123456");
DriverPropertyInfo[] propInfos = driver.getPropertyInfo(url, props);
System.out.println("探测到的驱动配置项数量: " + propInfos.length);
// 4. 直接调用 Driver.connect 建立底层物理数据库连接
try (Connection conn = driver.connect(url, props)) {
System.out.println("直接建立连接成功: " + conn);
}
}
}驱动元数据
intgetMajorVersion():(),主版本号获取。返回当前数据库驱动的主版本号(例如 MySQL Connector/J 8.3.0 返回8)。intgetMinorVersion():(),次版本号获取。返回当前数据库驱动的次版本号(例如 MySQL Connector/J 8.3.0 返回3)。booleanjdbcCompliant():(),规范兼容性检测。标识当前驱动是否完全通过了官方 JDBC 兼容性测试并完整支持 SQL-92 Entry Level 标准;仅当完全达标时返回true。LoggergetParentLogger():(),根日志器获取。返回当前驱动所使用的所有 JUL(java.util.logging.Logger)日志记录器的父级根日志器;若驱动未使用 JUL 日志体系,则抛出SQLFeatureNotSupportedException。
注意事项:
- 主流数据库驱动(如 MySQL 的
com.mysql.cj.jdbc.Driver)因底层 SQL 方言差异且未默认绑定java.util.logging日志体系,调用jdbcCompliant()会固定返回false,调用getParentLogger()会抛出SQLFeatureNotSupportedException。
import com.mysql.cj.jdbc.Driver;
import java.sql.SQLException;
import java.sql.SQLFeatureNotSupportedException;
import java.util.logging.Logger;
public class DriverMetaDemo {
public static void main(String[] args) throws SQLException {
// 1. 实例化数据库驱动对象
Driver driver = new Driver();
// 2. 获取驱动的主版本号与次版本号
int major = driver.getMajorVersion();
int minor = driver.getMinorVersion();
System.out.println("驱动版本: " + major + "." + minor);
// 3. 检测驱动是否完全符合官方 JDBC 规范要求
boolean compliant = driver.jdbcCompliant();
System.out.println("是否通过完整 JDBC 兼容性认证: " + compliant);
// 4. 尝试获取驱动的 JUL 父级根日志器
try {
Logger parentLogger = driver.getParentLogger();
System.out.println("父级日志器: " + parentLogger.getName());
} catch (SQLFeatureNotSupportedException e) {
System.out.println("当前驱动未启用 JUL 日志体系: " + e.getMessage());
}
}
}API: DriverManager
驱动管理
DriverManager.registerDriver():数据库驱动注册。将给定的
Driver实现类实例注册到DriverManager内部的线程安全驱动列表registeredDrivers中。void:(Driver driver),标准驱动注册。向DriverManager注册给定的驱动实例;若该驱动已注册则不会重复添加。void:(Driver driver, DriverAction da),带回调驱动注册。注册给定驱动的同时绑定一个DriverAction监听器,当驱动后续被调用deregisterDriver注销时将触发其deregister()回调方法。
voidDriverManager.deregisterDriver():(Driver driver),数据库驱动注销。从DriverManager的已注册驱动列表中移除指定的驱动实例;出于类加载器隔离安全考虑,仅允许注销由当前调用方类加载器所加载的驱动。DriverDriverManager.getDriver():(String url),协议匹配驱动获取。遍历当前已注册的驱动列表,查找并返回第一个调用acceptsURL(url)返回true的Driver实例;若无任何驱动匹配则抛出SQLException。Enumeration<Driver>DriverManager.getDrivers():(),已注册驱动枚举。返回当前调用方类加载器有权限访问的所有已注册 JDBC 驱动的Enumeration枚举器。Stream<Driver>DriverManager.drivers():(),已注册驱动流获取。返回当前调用方类加载器可访问的所有已注册 JDBC 驱动的顺序流(Stream),自 JDK 9 引入以替代传统的Enumeration遍历。
注意事项:
DriverManager的构造方法被private修饰,无法通过new DriverManager()实例化,所有功能均通过静态方法对外提供。- 在 Web 容器(如 Tomcat)中,若应用
WEB-INF/lib下引入了数据库驱动,应在应用停止(ServletContextListener.contextDestroyed)时主动调用DriverManager.deregisterDriver()注销驱动,否则系统类加载器中的DriverManager强引用应用类加载器创建的Driver,会导致 Web 应用卸载时发生ClassLoader内存泄漏。
import com.mysql.cj.jdbc.Driver;
import java.sql.DriverManager;
import java.sql.SQLException;
public class DriverManageDemo {
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
// 1. 显式创建并注册一个数据库驱动实例
Driver customDriver = new Driver();
DriverManager.registerDriver(customDriver);
// 2. 根据 JDBC URL 匹配能够处理该协议的驱动对象
java.sql.Driver matched = DriverManager.getDriver(url);
System.out.println("匹配到的驱动: " + matched.getClass().getName());
// 3. 获取当前已注册的所有驱动流并遍历打印
DriverManager.drivers().forEach(
d -> System.out.println("已注册驱动: " + d)
);
// 4. 从 DriverManager 中注销指定的驱动实例
DriverManager.deregisterDriver(customDriver);
}
}连接获取
- DriverManager.getConnection():物理数据库连接创建。遍历
registeredDrivers列表,依次委托各驱动的connect(url, info)方法尝试建立连接,返回第一个成功建立的Connection实例。Connection:(String url, String user, String password),账密参数建连。将传入的user和password封装进内部Properties对象后,向匹配url的驱动发起连接请求。Connection:(String url, Properties info),属性集合建连。使用包含user、password及其他驱动自定义连接参数(如超时时间、字符集等)的Properties集合建立数据库连接。Connection:(String url),单 URL 字符串建连。仅传入 JDBC URL 建立连接,适用于无需认证的内存数据库,或已将账号密码直接拼接在 URL 查询参数中的场景。
注意事项:
- 三个重载方法在底层最终都会汇总调用私有方法
getConnection(String url, Properties info, Class<?> caller)。- 当遍历完所有已注册驱动后,
connect()均返回null(即没有任何驱动能够识别该 URL 协议头),getConnection()会抛出异常信息为No suitable driver found for ...的SQLException。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Properties;
public class DriverConnectionDemo {
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
// 1. 传入 URL、用户名与密码直接获取数据库连接
try (Connection connByUser = DriverManager.getConnection(url, "root", "123456")) {
System.out.println("方式一获取连接成功: " + connByUser);
}
// 2. 通过 Properties 集合封装认证与附加连接参数获取连接
Properties info = new Properties();
info.setProperty("user", "root");
info.setProperty("password", "123456");
info.setProperty("connectTimeout", "3000");
try (Connection connByProps = DriverManager.getConnection(url, info)) {
System.out.println("方式二获取连接成功: " + connByProps);
}
// 3. 将账号密码拼接在 URL 查询参数中,使用单参数重载获取连接
String fullUrl = url + "&user=root&password=123456";
try (Connection connByUrl = DriverManager.getConnection(fullUrl)) {
System.out.println("方式三获取连接成功: " + connByUrl);
}
}
}全局配置
voidDriverManager.setLoginTimeout():(int seconds),连接超时设置。设置驱动尝试连接数据库服务器时允许等待的最大秒数;设为0表示无超时限制。intDriverManager.getLoginTimeout():(),连接超时获取。获取当前驱动建立数据库连接所允许的最大等待秒数。voidDriverManager.setLogWriter():(PrintWriter out),日志字符流设置。设置DriverManager和所有驱动共用的全局日志追踪字符输出流;传入null将禁用全局 JDBC 日志记录。PrintWriterDriverManager.getLogWriter():(),日志字符流获取。返回当前全局配置的 JDBC 日志追踪字符输出流PrintWriter。voidDriverManager.println():(String message),日志消息打印。若当前已通过setLogWriter配置了全局日志流,则向该流中输出一行指定的追踪消息并自动刷新缓冲区。
注意事项:
- 早期基于字节流的
setLogStream(PrintStream)与getLogStream()方法已标记为@Deprecated废弃,应当统一使用字符流版本的setLogWriter()与getLogWriter()。
import java.io.PrintWriter;
import java.sql.DriverManager;
public class DriverConfigDemo {
public static void main(String[] args) {
// 1. 配置并读取全局数据库连接的最大超时时间(单位:秒)
DriverManager.setLoginTimeout(10);
int timeout = DriverManager.getLoginTimeout();
System.out.println("当前连接超时秒数: " + timeout);
// 2. 将全局 JDBC 诊断日志输出流绑定到标准控制台输出
PrintWriter writer = new PrintWriter(System.out, true);
DriverManager.setLogWriter(writer);
// 3. 验证日志流并向全局 JDBC 日志中写入追踪消息
if (DriverManager.getLogWriter() != null) {
DriverManager.println("JDBC 全局诊断日志已启用");
}
}
}API: Connection
语句创建
createStatement():静态语句对象创建。创建用于向数据库发送静态 SQL 语句的
Statement对象,支持指定结果集的滚动类型、并发修改模式与事务提交后的游标保持策略。Statement:(),默认语句对象创建。创建一个默认配置(仅向前滚动TYPE_FORWARD_ONLY、只读并发CONCUR_READ_ONLY)的Statement实例。Statement:(int resultSetType, int resultSetConcurrency),指定类型与并发度创建。创建生成指定滚动类型(如双向滚动)和并发模式(如可更新结果集)的Statement实例。Statement:(int resultSetType, int resultSetConcurrency, int resultSetHoldability),指定完整结果集属性创建。在指定结果集类型与并发模式的基础上,显式指定事务提交后结果集游标是否保持打开(Holdability)。
prepareStatement():预编译语句对象创建。创建带
?占位符的预编译 SQL 语句对象PreparedStatement,支持主键自动回填以及自定义结果集属性。PreparedStatement:(String sql),标准预编译创建。使用包含参数占位符的 SQL 语句创建默认结果集属性的PreparedStatement实例。PreparedStatement:(String sql, int autoGeneratedKeys),自增主键回填创建。创建预编译语句对象,并通过Statement.RETURN_GENERATED_KEYS或NO_GENERATED_KEYS控制是否检索数据库自动生成的主键。PreparedStatement:(String sql, int[] columnIndexes),按列索引回填创建。创建预编译语句对象,指定在执行插入后需要通过getGeneratedKeys()返回的目标自增列索引数组。PreparedStatement:(String sql, String[] columnNames),按列名回填创建。创建预编译语句对象,指定在执行插入后需要通过getGeneratedKeys()返回的目标自增列名称数组。PreparedStatement:(String sql, int resultSetType, int resultSetConcurrency),指定结果集类型与并发创建。创建生成特定滚动类型与并发修改模式的PreparedStatement实例。PreparedStatement:(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability),指定完整结果集属性创建。创建具备指定滚动类型、并发模式及游标保持策略的PreparedStatement实例。
prepareCall():存储过程调用对象创建。创建用于调用数据库存储过程或函数的
CallableStatement对象。CallableStatement:(String sql),默认存储过程调用创建。使用标准 JDBC 存储过程转义语法(如{call proc_name(?, ?)})创建默认配置的CallableStatement实例。CallableStatement:(String sql, int resultSetType, int resultSetConcurrency),指定结果集类型与并发创建。创建返回特定滚动类型与并发模式结果集的CallableStatement实例。CallableStatement:(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability),指定完整结果集属性创建。创建具备指定滚动类型、并发模式及游标保持策略的CallableStatement实例。
StringnativeSQL():(String sql),原生方言语法转换。将包含标准 JDBC 转义语法(如{fn ...}、{d ...})的 SQL 字符串翻译为底层目标数据库的原生 SQL 方言字符串并返回。
注意事项:
- 除非业务明确需要双向滚动或直接通过结果集更新数据,否则应优先使用无参
createStatement()或单参数prepareStatement(String sql),避免因开启高级游标特性带来额外的数据库内存与性能开销。- MySQL 驱动默认在客户端模拟预编译,若需开启真正的数据库服务端预编译,需在 JDBC URL 中显式添加
useServerPrepStmts=true参数。
import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class ConnectionStatementDemo {
// 1. 建立数据库连接并演示各类 SQL 语句执行对象的创建
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
// 2. 将包含 JDBC 转义语法的 SQL 转换为底层数据库原生方言
String nativeSql = conn.nativeSQL("SELECT {fn NOW()}");
System.out.println("转换后的原生 SQL: " + nativeSql);
// 3. 创建支持双向滚动与只读并发模式的静态 Statement 对象
try (Statement stmt = conn.createStatement(
ResultSet.TYPE_SCROLL_INSENSITIVE,
ResultSet.CONCUR_READ_ONLY)) {
System.out.println("创建 Statement 成功: " + stmt);
}
// 4. 创建支持返回自增主键的预编译 PreparedStatement 对象
String insertSql = "INSERT INTO t_user (username, balance) VALUES (?, ?)";
try (PreparedStatement pstmt = conn.prepareStatement(
insertSql, Statement.RETURN_GENERATED_KEYS)) {
System.out.println("创建 PreparedStatement 成功: " + pstmt);
}
// 5. 创建用于调用数据库存储过程的 CallableStatement 对象
try (CallableStatement cstmt = conn.prepareCall("{call sp_query_user(?)}")) {
System.out.println("创建 CallableStatement 成功: " + cstmt);
}
}
}
}事务控制
final intConnection.TRANSACTION_NONE:不支持事务常量。常量值为0,标识当前底层数据源不支持事务机制。final intConnection.TRANSACTION_READ_UNCOMMITTED:读未提交隔离常量。常量值为1,允许读取其他事务尚未提交的脏数据,无法避免脏读、不可重复读与幻读。final intConnection.TRANSACTION_READ_COMMITTED:读已提交隔离常量。常量值为2,仅允许读取其他事务已提交的数据,可避免脏读,但仍可能出现不可重复读与幻读(Oracle、PostgreSQL 默认级别)。final intConnection.TRANSACTION_REPEATABLE_READ:可重复读隔离常量。常量值为4,保证同一事务内多次读取同一行记录的结果一致,可避免脏读与不可重复读(MySQL InnoDB 默认级别)。final intConnection.TRANSACTION_SERIALIZABLE:串行化隔离常量。常量值为8,最高事务隔离级别,强制事务串行执行以彻底规避脏读、不可重复读与幻读,但并发性能最低。voidsetAutoCommit():(boolean autoCommit),自动提交模式设置。开启或关闭当前连接的事务自动提交模式;设为false时将开启手动事务,后续 DML 操作需显式调用commit()才会持久化。booleangetAutoCommit():(),自动提交状态获取。检索当前Connection对象是否处于事务自动提交模式(新创建的连接默认返回true)。voidcommit():(),事务正式提交。使自上次提交或回滚以来在当前事务中执行的所有数据更改永久生效,并释放当前Connection持有的数据库锁。rollback():事务数据回滚。撤销当前事务中的全部更改,或局部回滚至指定的事务保存点(
Savepoint)。void:(),全量事务回滚。撤销当前事务中的所有未提交更改,并释放当前连接持有的所有数据库锁,只能在autoCommit为false时调用。void:(Savepoint savepoint),保存点局部回滚。撤销在设置给定Savepoint保存点之后执行的所有数据更改,保留该保存点之前的事务操作。
voidsetTransactionIsolation():(int level),事务隔离级别设置。将当前连接的事务隔离级别修改为指定的Connection.TRANSACTION_*常量值。intgetTransactionIsolation():(),事务隔离级别获取。获取当前连接会话正在生效的事务隔离级别常量值。setSavepoint():事务保存点创建。在当前手动事务内部设置一个回滚标记点,以便后续通过
rollback(Savepoint)实现细粒度的局部事务回滚。Savepoint:(),匿名保存点创建。在当前事务中创建一个未命名的保存点并返回代表该节点的Savepoint实例。Savepoint:(String name),命名保存点创建。在当前事务中创建一个具有指定名称的保存点并返回对应的Savepoint实例。
voidreleaseSavepoint():(Savepoint savepoint),事务保存点释放。从当前事务中移除指定的Savepoint保存点对象;释放后若再次针对该保存点执行回滚将抛出SQLException。
注意事项:
- 当连接处于自动提交模式(
getAutoCommit() == true)时,直接调用commit()、rollback()或setSavepoint()均会抛出SQLException。- 若在未完成手动事务期间调用
setAutoCommit(true)切换回自动提交模式,JDBC 规范要求底层驱动自动将该连接上挂起的事务立即提交。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;
import java.sql.Savepoint;
public class ConnectionTransactionDemo {
// 1. 演示事务隔离级别配置、保存点回滚与手动提交
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
// 2. 设置事务隔离级别为读已提交并关闭自动提交模式
conn.setTransactionIsolation(Connection.TRANSACTION_READ_COMMITTED);
conn.setAutoCommit(false);
System.out.println("自动提交状态: " + conn.getAutoCommit() + ", 隔离级别: " + conn.getTransactionIsolation());
String sql = "UPDATE t_user SET balance = balance - ? WHERE username = ?";
try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
pstmt.setDouble(1, 100.00);
pstmt.setString(2, "Alice");
pstmt.executeUpdate();
// 3. 在第一阶段更新完成后创建命名事务保存点
Savepoint sp = conn.setSavepoint("STAGE_ONE");
pstmt.setDouble(1, 200.00);
pstmt.setString(2, "Bob");
pstmt.executeUpdate();
// 4. 局部回滚至保存点并释放该保存点资源
conn.rollback(sp);
conn.releaseSavepoint(sp);
// 5. 正式提交保存点之前的事务更改
conn.commit();
} catch (SQLException e) {
// 6. 发生异常时全量回滚当前事务
conn.rollback();
throw e;
}
}
}
}会话配置
DatabaseMetaDatagetMetaData():(),数据库元数据获取。返回封装了底层数据库产品信息、驱动版本、表结构定义及功能支持情况的DatabaseMetaData对象。voidsetReadOnly():(boolean readOnly),只读会话模式设置。将当前连接设置为只读模式,作为驱动与数据库启用只读查询优化或路由至只读从库的提示。booleanisReadOnly():(),只读会话状态查询。判断当前Connection对象是否处于只读模式。voidsetCatalog():(String catalog),数据库目录设置。设置当前连接操作的子数据库(Catalog)名称;在 MySQL 中对应切换具体的 Database。StringgetCatalog():(),数据库目录获取。获取当前连接正在生效的 Catalog 名称。voidsetSchema():(String schema),数据库模式设置。设置当前连接默认访问的命名空间模式(Schema)名称。StringgetSchema():(),数据库模式获取。获取当前连接正在生效的 Schema 名称。voidsetHoldability():(int holdability),游标保持策略设置。修改当前连接创建的ResultSet在调用commit()提交事务后的默认游标保持策略(HOLD_CURSORS_OVER_COMMIT或CLOSE_CURSORS_AT_COMMIT)。intgetHoldability():(),游标保持策略获取。获取当前连接默认的ResultSet游标保持性常量。setClientInfo():客户端元数据写入。向连接会话写入客户端上下文信息(如应用名称、主机名、调用方用户),便于数据库服务端在会话监控视图或审计日志中追踪连接来源。
void:(String name, String value),单属性元数据设置。按指定的属性名与属性值设置单条客户端追踪信息,失败时抛出SQLClientInfoException。void:(Properties properties),集合元数据批量替换。使用给定的Properties集合完整替换当前连接的全部客户端属性,未包含在集合中的已有属性将被清空。
getClientInfo():客户端元数据读取。读取当前连接已配置的客户端追踪属性。
String:(String name),按名称读取客户端属性。返回指定客户端信息属性名称对应的字符串值。Properties:(),读取全部客户端属性。返回包含当前连接所有受支持客户端信息键值对的Properties集合。
voidsetTypeMap():(Map<String, Class<?>> map),自定义类型映射设置。安装自定义 SQL 结构化类型(UDT)名称与 JavaSQLData实现类之间的映射字典表。Map<String, Class<?>>getTypeMap():(),自定义类型映射获取。获取当前连接绑定的 SQL 自定义类型映射表Map。
注意事项:
setReadOnly(boolean)不能在事务执行中途调用,必须在事务开启前切换,否则会抛出SQLException。- 在 MySQL 中,
Catalog等价于数据库名(Database),而getSchema()默认返回null;在 PostgreSQL 或 Oracle 中,则主要通过Schema区分同一实例下的不同逻辑命名空间。
import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
public class ConnectionSessionDemo {
// 1. 演示连接会话上下文配置与数据库元数据读取
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
// 2. 获取底层数据库的全局元数据对象
DatabaseMetaData metaData = conn.getMetaData();
System.out.println("数据库产品名: " + metaData.getDatabaseProductName());
// 3. 查看并配置当前连接会话的 Catalog 与只读模式
conn.setCatalog("test_db");
conn.setReadOnly(true);
System.out.println("当前 Catalog: " + conn.getCatalog() + ", 是否只读: " + conn.isReadOnly());
// 4. 配置结果集可保持性并写入客户端应用追踪信息
conn.setHoldability(ResultSet.CLOSE_CURSORS_AT_COMMIT);
conn.setClientInfo("ApplicationName", "OrderService");
System.out.println("客户端应用标识: " + conn.getClientInfo("ApplicationName"));
}
}
}类型工厂
ClobcreateClob():(),字符大对象创建。创建并返回一个初始为空的Clob(Character Large Object)实例,用于向数据库写入超长文本数据。BlobcreateBlob():(),二进制大对象创建。创建并返回一个初始为空的Blob(Binary Large Object)实例,用于向数据库写入二进制字节数组或流数据。NClobcreateNClob():(),国家字符集大对象创建。创建并返回一个初始为空的NClob实例,用于存储基于国家字符集(如 UTF-16/Unicode)的大文本数据。SQLXMLcreateSQLXML():(),XML 类型对象创建。创建并返回一个初始为空的SQLXML实例,用于读写数据库原生的XML字段类型。ArraycreateArrayOf():(String typeName, Object[] elements),SQL 数组对象创建。将给定的 Java 对象数组封装为对应数据库元素类型名称typeName的java.sql.Array实例。StructcreateStruct():(String typeName, Object[] attributes),SQL 结构体对象创建。使用给定的属性数组创建映射数据库指定自定义复合类型typeName的Struct实例。
注意事项:
- 通过工厂方法创建的
Clob、Blob、NClob与SQLXML对象在内存中持有数据缓冲区,使用完毕后应主动调用其free()方法释放底层资源。- MySQL 数据库原生不支持 SQL 标准数组与複合结构体类型,因此在 MySQL 驱动上调用
createArrayOf()或createStruct()会直接抛出SQLFeatureNotSupportedException。
import java.sql.Blob;
import java.sql.Clob;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.NClob;
import java.sql.SQLException;
import java.sql.SQLXML;
public class ConnectionFactoryDemo {
// 1. 演示使用 Connection 工厂方法创建 LOB 与 XML 类型对象
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
// 2. 创建并填充字符大对象 Clob 与宽字符大对象 NClob
Clob clob = conn.createClob();
clob.setString(1, "长文本内容示例");
NClob nClob = conn.createNClob();
nClob.setString(1, "多语言宽字符内容");
// 3. 创建并填充二进制大对象 Blob 与 SQLXML 实例
Blob blob = conn.createBlob();
blob.setBytes(1, new byte[]{1, 2, 3, 4});
SQLXML sqlxml = conn.createSQLXML();
sqlxml.setString("<config><env>prod</env></config>");
// 4. 使用完毕后主动释放大对象底层内存资源
System.out.println("Clob 长度: " + clob.length() + ", Blob 长度: " + blob.length());
clob.free();
nClob.free();
blob.free();
sqlxml.free();
}
}
}状态管理
voidclose():(),物理连接关闭。立即释放当前Connection对象的数据库会话与底层 JDBC 资源(若是由连接池代理的Connection,则将其归还至连接池中复用)。booleanisClosed():(),连接关闭状态判断。检查当前Connection对象是否已被调用close()关闭;该判断仅检查本地状态标记,不能用于探测网络异常断开。booleanisValid():(int timeout),连接存活探测。向数据库发送轻量级探测包(如 MySQLPING命令)以验证连接是否真实有效;参数timeout指定等待验证响应的最大秒数(0表示不限制)。voidabort():(Executor executor),连接强制终止。使用给定的异步线程池Executor强制终止并销毁出现挂起或死锁的物理连接,即使当前连接正在执行 SQL 操作也会立即标记为关闭。voidsetNetworkTimeout():(Executor executor, int milliseconds),网络读写超时设置。设置当前连接等待数据库网络 I/O 响应的最大毫秒数;超时触发后将由传入的Executor异步关闭该连接。intgetNetworkTimeout():(),网络读写超时获取。返回当前连接配置的底层 Socket 等待响应的最大毫秒数。SQLWarninggetWarnings():(),连接告警链获取。返回当前连接会话上报告的第一个SQLWarning告警对象;后续告警可通过SQLWarning.getNextWarning()链式遍历。voidclearWarnings():(),连接告警清空。清除当前Connection对象上累积的所有SQLWarning告警记录。voidbeginRequest():(),请求边界开启。自 JDK 9 引入的default默认方法,向驱动提示一个独立业务请求工作单元的开始,供连接池或驱动执行会话级初始化与状态绑定。voidendRequest():(),请求边界结束。自 JDK 9 引入的default默认方法,向驱动提示当前业务请求工作单元已结束,便于驱动回收请求级临时资源。setShardingKeyIfValid():分片键有效性校验设置。自 JDK 9 引入的
default默认方法,在给定的超时秒数内验证分片键是否属于当前物理连接所指向的数据分片,验证通过则绑定该分片键并返回true。boolean:(ShardingKey shardingKey, int timeout),单层分片键校验绑定。在timeout秒内验证并绑定主分片键shardingKey。boolean:(ShardingKey shardingKey, ShardingKey superShardingKey, int timeout),双层分片键校验绑定。在timeout秒内同时验证并绑定子分片键shardingKey与超分片键superShardingKey。
setShardingKey():分片键直接设置。自 JDK 9 引入的
default默认方法,将指定的分片键设置为当前连接会话的路由上下文。void:(ShardingKey shardingKey),单层分片键绑定。为当前连接直接设置主分片键shardingKey。void:(ShardingKey shardingKey, ShardingKey superShardingKey),双层分片键绑定。为当前连接同时设置子分片键shardingKey与超分片键superShardingKey。
注意事项:
- 永远不要使用
!conn.isClosed()来校验连接池中的连接是否可用,因为当数据库服务端主动断开空闲连接或网络闪断时,客户端未调用过close(),isClosed()依然返回false;必须调用conn.isValid(timeout)发起实际网络探测。- 在已经关闭的
Connection上重复调用close()方法是幂等安全的(空操作),不会抛出异常。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.SQLWarning;
import java.util.concurrent.Executors;
public class ConnectionLifecycleDemo {
// 1. 演示数据库连接有效性探测、超时控制与告警清理
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
Connection conn = DriverManager.getConnection(url, "root", "123456");
// 2. 设置底层 Socket 网络超时时间并校验连接存活状态
conn.setNetworkTimeout(Executors.newSingleThreadExecutor(), 5000);
boolean valid = conn.isValid(3);
System.out.println("网络超时毫秒数: " + conn.getNetworkTimeout() + ", 连接是否有效: " + valid);
// 3. 检查并清空当前连接会话累积的 SQLWarning 告警链
SQLWarning warning = conn.getWarnings();
if (warning == null) {
conn.clearWarnings();
}
// 4. 显式关闭物理连接并验证关闭状态
conn.close();
System.out.println("连接是否已关闭: " + conn.isClosed());
}
}继承: Wrapper
isWrapperFor, unwrap
Statement
是 JDBC 中用于向数据库发送静态 SQL 语句并获取执行结果的基础接口,由 java.sql.StatementConnection 实例调用 createStatement 方法创建。
在底层通信层面,Statement 对应数据库的纯文本传输协议(如 MySQL 的 COM_QUERY 文本协议包)。它不具备参数占位与预编译能力,所有动态条件都必须在 Java 内存中预先拼接成完整的 SQL 字符串,再一次性发送给数据库服务端解析执行。
静态文本协议执行
当应用程序通过 Statement 发送一条 SQL 字符串时,JDBC 驱动不会对 SQL 的语法结构进行拆解,而是直接将该字符串编码为字节流封装进网络报文,通过 TCP 连接原样发送给数据库服务端。
服务端解析流程
数据库服务端接收到完整的 SQL 文本后,必须依次执行以下四个标准阶段才能完成响应:
词法与语法分析:解析器(Parser) 对传入的 SQL 字符串进行分词,识别出关键字(如
SELECT、WHERE)、表名、列名与字面量参数,校验语法规则并构建抽象语法树(AST)。语义与权限检查:预处理器检查语法树中引用的表和列在数据字典中是否真实存在,并验证当前连接账户是否具备相应的表级或列级操作权限。
生成执行计划:查询优化器(Optimizer) 基于统计信息计算不同索引路径与连接顺序的访问成本(CBO),为当前语法树选出最优的物理执行计划。
引擎调用与结果封装:执行器(Executor) 按照生成的执行计划调用底层存储引擎读写数据。若是增删改(DML)或结构定义(DDL)操作,服务端向驱动返回受影响行数数据包(OK Packet);若是查询(DQL)操作,服务端将匹配的记录行流式返回给驱动,由驱动封装为
ResultSet对象。
静态 SQL 执行示例
对于不含外部动态参数、结构完全固定的 DDL 建表语句或静态数据操作,可直接通过 Statement 发送执行:
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class StatementExecuteDemo {
public static void main(String[] args) {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
// 1. 建立数据库连接并创建静态 Statement 执行通道
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement()) {
// 2. 发送静态 DML 语句,返回受影响的行数
String insertSql = "INSERT INTO t_user (username, balance) VALUES ('Charlie', 800.00)";
int affectedRows = stmt.executeUpdate(insertSql);
System.out.println("新增记录行数: " + affectedRows);
// 3. 发送静态 DQL 查询语句,返回封装结果数据的 ResultSet
String querySql = "SELECT id, username, balance FROM t_user WHERE username = 'Charlie'";
try (ResultSet rs = stmt.executeQuery(querySql)) {
while (rs.next()) {
System.out.println(rs.getInt("id") + " -> " + rs.getDouble("balance"));
}
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}结果集游标独占限制
根据 JDBC 规范约定,同一个 Statement 实例在同一时刻最多只能保持一个处于打开状态的 ResultSet 结果集对象。
ResultSet 的生命周期与创建它的 Statement 强绑定。如果在第一个 ResultSet 尚未遍历完毕时,应用程序复用同一个 Statement 实例再次发送查询或更新语句,JDBC 驱动会隐式调用前一个 ResultSet 的 close 方法将其释放。当外层循环试图继续移动第一个结果集的游标时,就会触发 SQLException: Operation not allowed after ResultSet closed 异常:

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class StatementCursorConflictDemo {
public static void main(String[] args) {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement()) {
// 1. 使用 stmt 开启第一个结果集 userRs
ResultSet userRs = stmt.executeQuery("SELECT id, username FROM t_user");
while (userRs.next()) {
int userId = userRs.getInt("id");
// 2. 复用同一个 stmt 执行新查询,驱动会自动关闭前一个未遍历完的 userRs
ResultSet detailRs = stmt.executeQuery("SELECT balance FROM t_user WHERE id = " + userId);
if (detailRs.next()) {
System.out.println("余额: " + detailRs.getDouble("balance"));
}
// 3. ❌ 下一轮循环调用 userRs.next() 时将抛出 SQLException: Operation not allowed after ResultSet closed
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}若业务场景确实需要在遍历外层结果集的同时发起内层查询(且无法通过 SQL JOIN 合并为单次查询),必须在同一个 Connection 下分别创建两个独立的 Statement 实例来各自维护游标生命周期。
SQL 注入漏洞
在实际业务中,查询条件往往来自前端用户的外部输入。由于 Statement 只接收完整的 SQL 字符串,开发者只能采用字符串拼接的方式将用户参数嵌入 SQL 主干中,这直接引发了高危的 SQL 注入(SQL Injection)安全漏洞。
语法树篡改原理
SQL 注入的本质是“外部数据被数据库解析器误当作可执行代码”。
由于字符串拼接发生在 SQL 发送至数据库进行词法分析之前,如果外部输入参数中精心构造了单引号(')、逻辑运算符(OR、AND)或行注释符(-- 、#),这些特殊字符就会提前闭合原有的字符串字面量边界,在词法与语法分析阶段直接改变抽象语法树(AST)的逻辑分支结构:
-- 1. 正常拼接后的预期登录校验 SQL
SELECT id, username, balance
FROM t_user
WHERE username = 'Alice' AND password = '123';
-- 2. 拼入恶意参数 [' OR '1'='1] 后发生逻辑篡改的 SQL
SELECT id, username, balance
FROM t_user
WHERE username = '' OR '1'='1' AND password = 'arbitrary_value';在被篡改后的 SQL 中,由于关系型数据库中 AND 的运算优先级高于 OR,WHERE 子句的布尔表达式实际上等价于 username = '' OR ('1' = '1' AND password = '...');或者当攻击者输入 ' OR 1=1 -- 时,-- 会将后续的密码校验子句直接注释截断。无论采用哪种变形,整个 WHERE 条件都会恒定求值为 TRUE。

登录绕过攻击演示
下面通过模拟登录认证场景,展示攻击者如何在不知道任何真实账号密码的情况下,利用 Statement 字符串拼接漏洞绕过身份校验:
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class SqlInjectionDemo {
public static void main(String[] args) {
// 1. 模拟攻击者构造的恶意用户名输入,利用单引号闭合原字面量并注入永真条件
String inputUser = "' OR '1'='1";
String inputPwd = "wrong_password";
// 2. 字符串直接拼接导致恶意输入嵌入 SQL 语法结构
String sql = "SELECT id, username, balance FROM t_user "
+ "WHERE username = '" + inputUser + "' AND balance = '" + inputPwd + "'";
System.out.println("实际执行的 SQL: " + sql);
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
// 3. 永真条件使查询返回全表数据,攻击者无需正确凭证即可越权通过校验
if (rs.next()) {
System.out.println("登录绕过成功,当前读取用户: " + rs.getString("username"));
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}硬解析性能损耗
除了引发安全漏洞外,使用 Statement 拼接动态参数在高并发 OLTP 系统中还会造成严重的数据库 CPU 与内存开销:
执行编译缓存失效:现代关系型数据库(如 Oracle 的 Shared Pool、PostgreSQL 的计划缓存)通常会以 SQL 文本的哈希值作为 Key 缓存已编译的执行计划(软解析)。当使用
Statement将不同参数值直接拼入 SQL(如依次执行SELECT * FROM t_user WHERE id = 1与SELECT * FROM t_user WHERE id = 2)时,每条 SQL 文本的字面内容完全不同,数据库将其视为全新的语句,缓存命中率降为零。高频硬解析与缓存污染:每次参数变化都会迫使数据库重新进行词法解析、语法树构建与优化器成本计算(即硬解析 Hard Parse),大量消耗数据库服务端 CPU 资源;同时成千上万条仅字面量不同的一次性执行计划会迅速填满共享池内存,将真正高频复用的核心 SQL 执行计划驱逐出缓存。
因此,在生产级开发规范中,凡是涉及动态参数传入的 SQL 语句,严禁使用 Statement 进行字符串拼接,必须统一使用预编译接口 PreparedStatement。
API: Statement
语句执行
final intStatement.RETURN_GENERATED_KEYS:返回自增主键常量。常量值为1,指示驱动在执行INSERT语句后检索数据库自动生成的主键值,以供后续调用getGeneratedKeys()获取。final intStatement.NO_GENERATED_KEYS:忽略自增主键常量。常量值为2,指示驱动在执行更新语句后无需采集数据库自动生成的主键信息。ResultSetexecuteQuery():(String sql),静态查询语句执行。执行返回单个结果集的静态 SQL 查询语句(如SELECT),并返回封装了查询数据的ResultSet对象(永远不会返回null)。executeUpdate():静态更新语句执行。执行
INSERT、UPDATE、DELETE等 DML 数据操作语句(返回受影响的行数),或执行CREATE、ALTER等无返回值的 DDL 语句(返回0)。int:(String sql),标准更新执行。执行给定的静态 DML 或 DDL 语句并返回受影响的行数。int:(String sql, int autoGeneratedKeys),带主键回填配置更新。执行给定的静态更新语句,并通过Statement.RETURN_GENERATED_KEYS或NO_GENERATED_KEYS设置是否检索数据库自动生成的主键。int:(String sql, int[] columnIndexes),按列索引回填更新。执行更新语句,并指定需要采集返回的自增主键所在的目标列索引数组(从1开始)。int:(String sql, String[] columnNames),按列名回填更新。执行更新语句,并指定需要采集返回的自增主键所在的目标列名称数组。
executeLargeUpdate():超大行数更新执行。自 JDK 8 引入的
default默认方法,适用于单次 DML 更新受影响行数超过Integer.MAX_VALUE的海量数据场景,返回long类型的更新计数。long:(String sql),标准大行数更新。执行给定的静态 DML 或 DDL 语句并返回long类型的受影响行数。long:(String sql, int autoGeneratedKeys),带主键标志大行数更新。执行大行数更新语句并指定是否检索自动生成的主键。long:(String sql, int[] columnIndexes),按列索引回填大行数更新。执行大行数更新语句并指定需要返回自增值的目标列索引数组。long:(String sql, String[] columnNames),按列名回填大行数更新。执行大行数更新语句并指定需要返回自增值的目标列名称数组。
execute():通用动态语句执行。执行任意类型的静态 SQL 语句(尤其适用于事先未知 SQL 类型或会返回多个结果集/更新计数的动态场景);若第一个结果为
ResultSet则返回true,若为更新计数或无结果则返回false。boolean:(String sql),标准通用执行。执行任意静态 SQL 语句并返回首个结果是否为ResultSet的布尔标志。boolean:(String sql, int autoGeneratedKeys),带主键标志通用执行。执行任意静态 SQL 语句并设置是否捕获自动生成的主键。boolean:(String sql, int[] columnIndexes),按列索引回填通用执行。执行任意静态 SQL 语句并指定需返回自增值的列索引数组。boolean:(String sql, String[] columnNames),按列名回填通用执行。执行任意静态 SQL 语句并指定需返回自增值的列名称数组。
ResultSetgetGeneratedKeys():(),自增主键结果集获取。获取执行此Statement对象后由数据库自动生成的所有主键值组成的ResultSet对象;若未生成任何键则返回空的ResultSet。
注意事项:
- 同一个
Statement实例在同一时刻默认只能打开一个ResultSet对象;若直接调用该Statement执行下一条 SQL,前一个尚未关闭的ResultSet会被底层驱动隐式关闭。Statement直接拼接 SQL 字符串极易引发 SQL 注入风险,且无法复用预编译执行计划;凡是涉及外部传入参数的 SQL,均应改用子接口PreparedStatement。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class StatementExecuteDemo {
// 1. 建立数据库连接并创建静态 Statement 执行对象
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement()) {
// 2. 执行 DML 插入语句并指定返回数据库自动生成的主键
String insertSql = "INSERT INTO t_user (username, balance) VALUES ('Charlie', 800.00)";
int rows = stmt.executeUpdate(insertSql, Statement.RETURN_GENERATED_KEYS);
System.out.println("插入受影响行数: " + rows);
// 3. 获取并遍历刚刚生成的自增主键值
try (ResultSet keys = stmt.getGeneratedKeys()) {
if (keys.next()) {
System.out.println("生成的自增主键 ID: " + keys.getLong(1));
}
}
// 4. 执行 DQL 查询语句并读取结果集
String querySql = "SELECT id, username, balance FROM t_user WHERE username = 'Charlie'";
try (ResultSet rs = stmt.executeQuery(querySql)) {
while (rs.next()) {
System.out.println("查询结果: " + rs.getString("username") + " -> " + rs.getDouble("balance"));
}
}
// 5. 使用通用 execute 方法执行任意 SQL 并判断返回结果类型
boolean isResultSet = stmt.execute("DELETE FROM t_user WHERE username = 'Charlie'");
System.out.println("是否为查询结果集: " + isResultSet);
}
}
}批量处理
final intStatement.SUCCESS_NO_INFO:未知行数成功常量。常量值为-2,作为executeBatch()返回数组中的元素值,表示该条批处理指令已执行成功,但底层驱动无法获知其具体受影响的行数。final intStatement.EXECUTE_FAILED:批处理执行失败常量。常量值为-3,作为executeBatch()或BatchUpdateException.getUpdateCounts()数组中的元素值,表示该条批处理指令执行失败(仅在驱动遇到错误后仍继续执行后续批处理指令时出现)。voidaddBatch():(String sql),批处理指令追加。将给定的静态 DML 或 DDL 语句添加到当前Statement对象的本地批处理命令列表中(严禁添加返回结果集的SELECT语句)。voidclearBatch():(),批处理队列清空。清空当前Statement对象本地批处理命令列表中已缓存的所有 SQL 语句。int[]executeBatch():(),批量指令提交执行。将当前批处理队列中的所有 SQL 命令一次性提交给数据库执行;若全部执行成功,则按添加顺序返回每条命令对应的更新计数数组。long[]executeLargeBatch():(),大行数批量提交执行。自 JDK 8 引入的default默认方法,当批处理中单条语句受影响行数可能超过Integer.MAX_VALUE时调用,返回long[]类型的更新计数数组。
注意事项:
- 执行批量插入或更新时,建议先调用
conn.setAutoCommit(false)关闭自动提交,待executeBatch()完成后再统一调用conn.commit(),从而避免每条语句单独开启和提交事务带来的磁盘刷盘开销。- 若批处理队列中某一条语句执行失败,驱动会抛出
BatchUpdateException(SQLException的子类),可通过调用该异常对象的getUpdateCounts()方法排查异常发生前各语句的执行状态。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.Arrays;
public class StatementBatchDemo {
// 1. 建立数据库连接并关闭自动提交以提升批处理事务性能
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&rewriteBatchedStatements=true";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement()) {
conn.setAutoCommit(false);
// 2. 向 Statement 批处理缓存队列中添加多条静态 SQL 语句
stmt.addBatch("INSERT INTO t_user (username, balance) VALUES ('Dave', 300.00)");
stmt.addBatch("INSERT INTO t_user (username, balance) VALUES ('Eve', 450.00)");
stmt.addBatch("UPDATE t_user SET balance = balance + 50.00 WHERE username = 'Dave'");
// 3. 一次性将批处理队列发送至数据库执行并获取各语句更新计数数组
int[] updateCounts = stmt.executeBatch();
conn.commit();
System.out.println("批处理各语句受影响行数: " + Arrays.toString(updateCounts));
// 4. 清空当前 Statement 中残留的批处理指令列表
stmt.clearBatch();
}
}
}多结果集遍历
final intStatement.CLOSE_CURRENT_RESULT:关闭当前结果集常量。常量值为1,传递给getMoreResults(int)时,指示驱动在移动到下一个结果时自动关闭当前打开的ResultSet对象。final intStatement.KEEP_CURRENT_RESULT:保留当前结果集常量。常量值为2,传递给getMoreResults(int)时,指示驱动在移动到下一个结果时不关闭当前打开的ResultSet对象。final intStatement.CLOSE_ALL_RESULTS:关闭历史结果集常量。常量值为3,传递给getMoreResults(int)时,指示驱动在移动到下一个结果时一次性关闭此前通过KEEP_CURRENT_RESULT保留的所有已打开ResultSet对象。ResultSetgetResultSet():(),当前结果集提取。以ResultSet对象的形式获取execute()执行后的当前结果;若当前结果是一个更新计数或已无更多结果,则返回null(每个结果只能调用一次该方法)。intgetUpdateCount():(),当前更新计数提取。以int行数的形式获取execute()执行后的当前结果;若当前结果是一个ResultSet对象或已无更多结果,则返回-1(每个结果只能调用一次该方法)。longgetLargeUpdateCount():(),当前大行数计数提取。自 JDK 8 引入的default默认方法,以long类型返回当前结果的更新行数;若当前结果为ResultSet或已无更多结果则返回-1L。getMoreResults():下一结果游标推进。将此
Statement对象移动到下一个执行结果;若下一个结果是ResultSet对象则返回true,若为更新计数或已无更多结果则返回false。boolean:(),默认关闭推进。移动到下一个执行结果,并隐式关闭通过getResultSet()获取的当前ResultSet(等价于传入CLOSE_CURRENT_RESULT)。boolean:(int current),指定保留策略推进。移动到下一个执行结果,并根据传入的CLOSE_CURRENT_RESULT、KEEP_CURRENT_RESULT或CLOSE_ALL_RESULTS常量处理此前已打开的ResultSet。
注意事项:
- 判断多结果集是否全部遍历完毕的标准终止条件为:
((stmt.getMoreResults() == false) && (stmt.getUpdateCount() == -1))。- MySQL 驱动默认禁止在一次
execute()调用中用分号分隔执行多条 SQL 语句;若需使用多语句混合执行与多结果集遍历,必须在 JDBC URL 中显式开启allowMultiQueries=true。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class StatementMultiResultDemo {
// 1. 开启 allowMultiQueries 参数以支持单次执行多条混合 SQL 语句
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&allowMultiQueries=true";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement()) {
// 2. 一次性发送包含更新与查询的复合 SQL 语句
String multiSql = "UPDATE t_user SET balance = balance + 10.00 WHERE id = 1; "
+ "SELECT id, username, balance FROM t_user WHERE id = 1;";
boolean hasResultSet = stmt.execute(multiSql);
// 3. 循环遍历所有返回结果(当不再有结果集且更新计数为 -1 时终止)
while (true) {
if (hasResultSet) {
try (ResultSet rs = stmt.getResultSet()) {
while (rs.next()) {
System.out.println("查询结果集记录: " + rs.getString("username"));
}
}
} else {
int updateCount = stmt.getUpdateCount();
if (updateCount == -1) {
break;
}
System.out.println("DML 更新受影响行数: " + updateCount);
}
// 4. 移动至下一个执行结果并自动关闭当前已处理的 ResultSet
hasResultSet = stmt.getMoreResults(Statement.CLOSE_CURRENT_RESULT);
}
}
}
}执行参数配置
voidsetQueryTimeout():(int seconds),语句执行超时设置。设置驱动等待單条 SQL 语句执行完成的最大秒数(设为0表示不限制);若超出该时间仍未完成,将抛出SQLTimeoutException。intgetQueryTimeout():(),语句执行超时获取。返回当前配置的等待 SQL 执行完成的最大秒数。voidsetMaxRows():(int max),结果集最大行数设置。设置此Statement生成的任何ResultSet对象最多可包含的记录行数上限(设为0表示不限制),超出上限的行将被静默丢弃。intgetMaxRows():(),结果集最大行数获取。获取当前Statement生成的结果集所允许的最大记录行数。voidsetLargeMaxRows():(long max),超大结果集行数上限设置。自 JDK 8 引入的default默认方法,设置结果集允许包含的最大行数上限(支持超过Integer.MAX_VALUE的long值)。longgetLargeMaxRows():(),超大结果集行数上限获取。自 JDK 8 引入的default默认方法,返回当前配置的结果集最大行数上限(long类型)。voidsetMaxFieldSize():(int max),单列最大字节数设置。设置结果集中单个字符或二进制列值允许返回的最大字节数限制(仅适用于BINARY、VARBINARY、CHAR、VARCHAR等类型,设为0表示不限制)。intgetMaxFieldSize():(),单列最大字节数获取。获取当前针对单列返回值所限制的最大字节数。voidsetFetchSize():(int rows),网络预取行数设置。向 JDBC 驱动提供性能提示,指定当ResultSet需要更多行数据时每次从数据库服务器批量抓取的行数。intgetFetchSize():(),网络预取行数获取。返回当前配置的每次从数据库抓取的结果集行数。voidsetFetchDirection():(int direction),游标抓取方向设置。向驱动提示后续处理ResultSet数据行的遍历方向(可选值为ResultSet.FETCH_FORWARD、FETCH_REVERSE或FETCH_UNKNOWN)。intgetFetchDirection():(),游标抓取方向获取。获取当前配置的默认结果集行抓取方向常量。intgetResultSetType():(),结果集滚动类型获取。返回由此Statement对象生成的ResultSet的滚动类型常量(如ResultSet.TYPE_FORWARD_ONLY)。intgetResultSetConcurrency():(),结果集并发模式获取。返回由此Statement对象生成的ResultSet的并发修改模式常量(如ResultSet.CONCUR_READ_ONLY)。intgetResultSetHoldability():(),结果集游标保持性获取。返回由此Statement对象生成的ResultSet在事务提交后的游标保持策略常量。voidsetEscapeProcessing():(boolean enable),转义语法扫描开关。启用或禁用驱动在将 SQL 发送至数据库之前的标准 JDBC 转义语法({...})解析器(默认开启)。voidsetCursorName():(String name),定位更新游标命名。设置后续executeQuery生成的结果集所使用的底层 SQL 游标名称,用于配合WHERE CURRENT OF <cursorName>执行定位更新或删除。StringenquoteLiteral():(String val),字符串字面量转义封装。自 JDK 9 引入的default默认方法,将传入的字符串用单引号包裹,并自动将内部包含的所有单引号转义为双单引号(''),防止静态 SQL 拼接语法错误或注入。StringenquoteIdentifier():(String identifier, boolean alwaysQuote),数据库标识符转义封装。自 JDK 9 引入的default默认方法,校验并返回合法的 SQL 标识符(如动态表名或列名),根据alwaysQuote参数或特殊字符情况自动包裹双引号。StringenquoteNCharLiteral():(String val),国家字符集字面量转义。自 JDK 9 引入的default默认方法,将传入的字符串转换为符合 SQL 标准的国家字符集字面量格式(即N'...')并转义内部单引号。booleanisSimpleIdentifier():(String identifier),简单标识符校验。自 JDK 9 引入的default默认方法,判断给定的字符串是否为无需引号包裹的标准简单 SQL 标识符(仅由字母开头并包含字母、数字和下划线)。
注意事项:
- MySQL 驱动在默认情况下执行
executeQuery()时会将整个查询结果集一次性全部读入客户端内存中;当查询百万级大表为防止 OOM 内存溢出时,必须调用stmt.setFetchSize(Integer.MIN_VALUE)开启流式结果集逐行读取,或在连接 URL 中配置useCursorFetch=true后再设置正整数的fetchSize。enquoteIdentifier()与enquoteLiteral()对于无法使用?占位符的动态表名、动态ORDER BY列名等场景非常实用,能够有效阻断标识符层面的 SQL 注入。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class StatementConfigDemo {
// 1. 演示 Statement 执行超时、行数限制、抓取大小与安全转义配置
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement()) {
// 2. 设置 SQL 执行超时秒数、单列最大字节数与结果集最大返回行数
stmt.setQueryTimeout(5);
stmt.setMaxFieldSize(1024);
stmt.setMaxRows(50);
System.out.println("超时秒数: " + stmt.getQueryTimeout() + ", 最大行数: " + stmt.getMaxRows());
// 3. 配置结果集游标抓取方向与每次网络交互预取的行数
stmt.setFetchDirection(ResultSet.FETCH_FORWARD);
stmt.setFetchSize(20);
System.out.println("预取行数: " + stmt.getFetchSize() + ", 结果集类型: " + stmt.getResultSetType());
// 4. 使用 JDK 9 引入的转义辅助方法安全构造动态标识符与字符串字面量
String safeColumn = stmt.enquoteIdentifier("username", false);
String safeValue = stmt.enquoteLiteral("Alice");
System.out.println("安全转义条件: " + safeColumn + " = " + safeValue);
}
}
}生命周期管理
voidclose():(),语句对象关闭。立即释放当前Statement对象的数据库游标与底层 JDBC 资源,并同时隐式关闭由该对象打开的所有ResultSet结果集。booleanisClosed():(),关闭状态判断。检查当前Statement对象是否已被调用close()关闭。voidcancel():(),异步中断执行。当另一个线程正在执行该Statement的耗时 SQL 时,可由监控线程调用此方法向数据库服务端发送中断请求以取消正在运行的 SQL 语句。voidcloseOnCompletion():(),结果集联动关闭开启。自 JDK 7 引入,声明当此Statement生成的所有依赖ResultSet对象全部被关闭时,自动触发关闭当前Statement对象。booleanisCloseOnCompletion():(),联动关闭状态查询。判断当前Statement是否已启用当结果集关闭时自动随之关闭的联动策略。voidsetPoolable():(boolean poolable),语句池化状态设置。向语句池(Statement Pool)管理器提供提示,指定当前语句对象是否允许被缓存复用(Statement默认为false,PreparedStatement默认为true)。booleanisPoolable():(),语句池化状态获取。返回当前Statement对象是否具备可池化缓存标记。ConnectiongetConnection():(),所属连接对象获取。返回创建了当前Statement实例的父级Connection连接对象。SQLWarninggetWarnings():(),语句执行告警获取。获取当前Statement执行期间数据库报告的第一个SQLWarning告警对象;每次执行新 SQL 时会自动清空上一次的告警。voidclearWarnings():(),语句执行告警清空。显式清除当前Statement对象上记录的所有SQLWarning告警链。
注意事项:
- 当方法需要将查询得到的
ResultSet直接作为返回值交给上层调用者遍历时,不能在方法内部使用try-with-resources关闭Statement(否则返回的ResultSet会立刻失效);此时应在返回前调用stmt.closeOnCompletion(),这样当上层调用者关闭ResultSet时,底层的Statement便会自动随之关闭。cancel()方法要求底层驱动和目标数据库同时支持异步网络取消指令,且必须从不同于正在执行 SQL 的另一个独立线程发起调用。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class StatementLifecycleDemo {
// 1. 演示 Statement 关联关闭策略、池化提示与资源释放
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
Statement stmt = conn.createStatement();
// 2. 开启语句池化缓存提示并校验其所属的 Connection 对象
stmt.setPoolable(true);
System.out.println("是否允许池化: " + stmt.isPoolable() + ", 所属连接: " + stmt.getConnection());
// 3. 启用结果集关闭联动策略:当关联的 ResultSet 关闭时自动关闭当前 Statement
stmt.closeOnCompletion();
System.out.println("是否启用自动关联关闭: " + stmt.isCloseOnCompletion());
try (ResultSet rs = stmt.executeQuery("SELECT id, username FROM t_user")) {
if (rs.next()) {
System.out.println("读取首行用户: " + rs.getString("username"));
}
}
// 4. 验证 ResultSet 关闭后 Statement 是否已随之自动关闭
System.out.println("ResultSet 关闭后 Statement 是否已关闭: " + stmt.isClosed());
}
}
}继承: Wrapper
isWrapperFor, unwrap
PreparedStatement
是 java.sql.PreparedStatementStatement 接口的子接口,表示预编译的 SQL 语句对象。
与 Statement 在执行阶段才传入完整 SQL 字符串不同,PreparedStatement 在创建阶段就需要将带有问号(?)参数占位符的 SQL 模板提交给驱动或数据库服务端,待参数值按类型逐个绑定到对应占位符后,再触发语句执行。它从机制上解决了动态 SQL 拼接引发的 SQL 注入漏洞与高频硬解析开销。
参数化防注入机制
PreparedStatement 能够防御 SQL 注入的核心在于实现了“SQL 语法结构(代码)”与“动态参数值(数据)”在解析周期上的严格分离。
语法树固化与类型转义
当使用 ? 占位符编写 SQL 模板时,无论是采用服务端二进制预编译还是客户端模拟预编译,外部传入的参数都无法篡改 SQL 的抽象语法树(AST)结构:
服务端预编译下的语法树固化:数据库服务端在接收参数之前,已经对含有
?占位符的 SQL 模板完成了词法分析、语法分析并生成了固定的 AST 与执行计划。后续传入的参数值仅通过二进制协议直接填入 AST 叶子节点的变量槽位中,数据库不会对参数值再次执行词法解析,因此参数中的' OR '1'='1只会被视为普通的字符串内容,而不会变成OR逻辑语法节点。客户端预编译下的强制类型转义:当驱动在本地组装 SQL 时,类型化的参数绑定操作会根据目标数据类型执行严格的边界校验与特殊字符转义。例如绑定数值类型时若传入非数字字符会直接在 JVM 端抛出类型转换异常;绑定字符串类型时,驱动会自动在参数外层包裹单引号,并将参数内部出现的所有单引号(
')强制转义为\'或'',使其彻底丧失提前闭合 SQL 字面量的能力:sql-- 1. 定义带有 ? 占位符的参数化 SQL 模板 SELECT id, username, balance FROM t_user WHERE username = ? AND balance = ?; -- 2. 绑定恶意字符串 [' OR '1'='1] 后经转义生成的安全 SQL SELECT id, username, balance FROM t_user WHERE username = '\' OR \'1\'=\'1' AND balance = 1000.00;

参数绑定执行流程
使用 PreparedStatement 执行参数化查询时,占位符索引从 1 开始从左至右依次递增。所有占位符必须在执行前完成赋值,否则驱动将抛出 SQLException: No value specified for parameter ... 异常;且在最终调用执行方法时,需调用无参重载方法(不要再次传入 SQL 模板字符串,否则会退化为调用父接口 Statement 的静态执行方法):
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
public class PreparedStatementSafeDemo {
public static void main(String[] args) {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
// 1. 使用 ? 占位符定义参数化 SQL 模板,预先固定语法结构
String sql = "SELECT id, username, balance FROM t_user WHERE username = ? AND balance = ?";
// 2. 创建 PreparedStatement 实例,传入含占位符的 SQL 模板
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
PreparedStatement pstmt = conn.prepareStatement(sql)) {
// 3. 按从 1 开始的索引绑定参数,恶意单引号将被转义为普通字面量字符
pstmt.setString(1, "' OR '1'='1");
pstmt.setDouble(2, 1000.00);
// 4. 执行查询时无需再次传入 SQL 字符串
try (ResultSet rs = pstmt.executeQuery()) {
if (rs.next()) {
System.out.println("查询成功: " + rs.getString("username"));
} else {
System.out.println("未匹配到任何记录,SQL 注入已被拦截");
}
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}预编译模式
以 MySQL 驱动(mysql-connector-j)为例,调用 Connection.prepareStatement 时并非默认触发数据库服务端的二进制预编译,而是根据 JDBC URL 参数衍生出两种截然不同的底层通信机制。
客户端模拟预编译
在默认配置下(即 useServerPrepStmts=false),MySQL 驱动创建的是 ClientPreparedStatement 实例,采用客户端本地模拟预编译机制:
本地模板切分:调用
prepareStatement(sql)时,驱动并不会向 MySQL 服务端发送任何网络请求,而是僅在 JVM 内存中将 SQL 模板按?占位符切分为静态文本片段数组。单次文本协议发送:当绑定完参数并调用执行方法时,驱动在本地内存中将转义后的参数值与静态文本片段拼接成完整的 SQL 字节流,底层依然通过与
Statement相同的COM_QUERY文本协议一次性发送给服务端执行。这种方式省去了一次预编译网络往返(RTT),适合只执行一次的单次查询,但无法在数据库服务端复用执行计划。
服务端二进制预编译
当在 JDBC URL 中显式配置 useServerPrepStmts=true 时,MySQL 驱动会创建 ServerPreparedStatement 实例,启用真正的服务端二进制预编译协议:
预编译阶段(COM_STMT_PREPARE):调用
prepareStatement(sql)时,驱动立即向 MySQL 服务端发送COM_STMT_PREPARE指令包。服务端解析 SQL 模板生成 AST,并在当前会话中缓存预编译结构,向客户端返回唯一的语句句柄statement_id以及参数与结果列的元数据信息。执行阶段(COM_STMT_EXECUTE):调用执行方法时,驱动无需再发送 SQL 文本,只需发送
COM_STMT_EXECUTE指令包,携带statement_id与紧凑的二进制参数值,服务端直接套用已编译好的执行计划完成运算。预编译缓存复用:在生产环境中,若每次关闭
PreparedStatement都触发服务端发送COM_STMT_CLOSE销毁预编译句柄,反而会因为每次执行都需要两次网络通信而降低性能。因此开启服务端预编译时,必须同步配置cachePrepStmts=true(开启客户端预编译句柄缓存)、prepStmtCacheSize=250(缓存句柄数量上限)与prepStmtCacheSqlLimit=2048(允许缓存的最大 SQL 长度),使同一连接上重复执行的相同 SQL 模板直接复用已分配的statement_id。

批量执行机制
在需要向数据库批量插入或更新成千上万条记录的场景下,如果在循环体内逐条调用 executeUpdate,每条记录都会产生一次独立的网络往返(RTT)与磁盘刷写开销,网络延迟会成为严重的性能瓶颈。
累积缓冲与网络重写
JDBC 提供了批处理(Batch Processing)机制,允许将多组参数缓存在本地内存中,通过单次网络请求集中提交:
本地参数队列累积:每次在循环中绑定完一行记录的占位符参数后,将当前参数组封装追加到
PreparedStatement内部的批处理集合(batchedArgs)中,此时不会产生任何网络 I/O。分批提交与内存清理:当批处理集合累积到指定阈值(如每 500 或 1000 条)时,统一触发批量发送,并返回每一条语句受影响行数组成的
int[]数组;每批次发送完毕后必须显式清空本地批处理缓存列表,防止海量数据堆积引发 JVM 堆内存溢出(OOM)。多值语句重写优化:对于 MySQL 而言,即使使用了批处理 API,默认情况下驱动仍只是在同一批次中连续发送多条独立的
INSERT指令。只有同时在 JDBC URL 中配置rewriteBatchedStatements=true,MySQL 驱动才会在底层将多条INSERT INTO t_user (username, balance) VALUES (?, ?)自动合并重写为单条多值插入语句INSERT INTO t_user (username, balance) VALUES ('u1', 100), ('u2', 200), ...,从而实现数十倍的吞吐量提升:javaimport java.sql.Connection; import java.sql.DriverManager; import java.sql.PreparedStatement; import java.sql.SQLException; public class PreparedStatementBatchDemo { public static void main(String[] args) { // 1. 开启 rewriteBatchedStatements 参数以激活驱动层多值 INSERT 合并重写 String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&rewriteBatchedStatements=true"; String sql = "INSERT INTO t_user (username, balance) VALUES (?, ?)"; try (Connection conn = DriverManager.getConnection(url, "root", "123456"); PreparedStatement pstmt = conn.prepareStatement(sql)) { for (int i = 1; i <= 1000; i++) { pstmt.setString(1, "User_" + i); pstmt.setDouble(2, 500.00); // 2. 将当前绑定好的一组参数追加到本地批处理缓存队列 pstmt.addBatch(); // 3. 每累积满 500 条统一发送执行一次,并清空本地缓存防止内存溢出 if (i % 500 == 0) { pstmt.executeBatch(); pstmt.clearBatch(); } } // 4. 提交剩余未满 500 条的尾批参数队列 pstmt.executeBatch(); pstmt.clearBatch(); } catch (SQLException e) { e.printStackTrace(); } } }
自增主键回填机制
在主从关联表写入场景(如先插入订单主表 t_order 获取生成的自增订单 ID,再将该 ID 作为外键插入订单明细表 t_order_item)中,应用程序需要在执行 INSERT 后立即拿到数据库分配的自增主键值。
MySQL 服务端在执行完 INSERT 语句后,其实已经将新生成的自增主键值(insert_id)随同受影响行数一起封装在底层的 OK Packet 响应报文中返回给了客户端驱动。开发者只需在创建 PreparedStatement 时传入 Statement.RETURN_GENERATED_KEYS 标志位,驱动便会解析保留该主键值并封装为单列 ResultSet 供应用直接读取,无需额外发起一次 SELECT LAST_INSERT_ID() 查询:
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class GeneratedKeysDemo {
public static void main(String[] args) {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String sql = "INSERT INTO t_user (username, balance) VALUES (?, ?)";
// 1. 预编译时传入 RETURN_GENERATED_KEYS 常量,声明提取数据库生成的自增主键
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
PreparedStatement pstmt = conn.prepareStatement(sql, Statement.RETURN_GENERATED_KEYS)) {
pstmt.setString(1, "David");
pstmt.setDouble(2, 1500.00);
pstmt.executeUpdate();
// 2. 从响应报文中提取封装了自增主键值的结果集并按列索引读取
try (ResultSet keysRs = pstmt.getGeneratedKeys()) {
if (keysRs.next()) {
long generatedId = keysRs.getLong(1);
System.out.println("回填自增主键 ID: " + generatedId);
}
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}占位符使用边界
PreparedStatement 的 ? 占位符仅能用于替代 SQL 中的标量数据字面量(如 WHERE 条件值、VALUES 插入值、SET 更新值、LIMIT 偏移量),严禁用于替代表名、列名、排序方向等 SQL 语法结构标识符。
表名与列名动态拼接
如果在表名、ORDER BY 列名或排序关键字(ASC / DESC)位置强行使用 ? 占位符并绑定字符串,驱动会在标识符外层加上单引号,导致语义错误或语法报错:
-- 1. 错误用法:在表名与 ORDER BY 列名位置使用 ? 占位符
SELECT id, username FROM ? ORDER BY ? DESC;
-- 2. 绑定字符串参数后生成的实际 SQL:表名加单引号触发语法异常,ORDER BY 字符串常量导致排序彻底失效
SELECT id, username
FROM 't_user'
ORDER BY 'balance' DESC;数据库优化器必须先确定查询的目标表名与列名,才能检查数据字典并生成执行计划。对于分表路由(如 t_order_2026)或前端动态字段排序场景,只能经过严格的白名单校验(如通过枚举或 Set 集合校验传入的列名是否合法)后,再将合法的表名或列名拼接到 SQL 模板中。
IN 子句动态参数扩展
在编写包含 IN 子句的多值匹配查询时,不能将多个值拼接为逗号分隔的单个字符串(如 "1, 2, 3")绑定到单个 WHERE id IN (?) 占位符上。否则驱动会将其整体转义为单个字符串字面量 WHERE id IN ('1, 2, 3'),不仅无法匹配多个 ID,还会引发隐式类型转换。
正确的做法是根据传入集合的元素个数,动态生成对应数量的 ? 占位符(如 WHERE id IN (?, ?, ?)),再通过循环依次为每个占位符单独绑定参数。
API: PreparedStatement
语句执行
ResultSetexecuteQuery():(),预编译查询执行。执行当前PreparedStatement对象中已完成参数绑定的预编译SELECT查询语句,并返回封装查询结果的ResultSet对象(永不为null)。intexecuteUpdate():(),预编译更新执行。执行当前PreparedStatement中的预编译INSERT、UPDATE、DELETE等 DML 语句(返回int型受影响行数)或无返回值的 DDL 语句(返回0)。longexecuteLargeUpdate():(),预编译大表更新执行。自 JDK 8 引入的default默认方法,执行预编译 DML 更新语句并返回long类型的受影响行数,适用于受影响行数超过Integer.MAX_VALUE的海量数据表更新。booleanexecute():(),预编译通用语句执行。执行当前PreparedStatement中任意种类的预编译 SQL 语句;若首个执行结果为ResultSet则返回true,若为更新计数或无结果则返回false。voidaddBatch():(),预编译参数组入队。将当前PreparedStatement已绑定的整组参数值打包追加到内部批处理命令队列中,随后可继续修改参数并重复调用该方法累积多组参数,最后通过继承自Statement的executeBatch()一次性提交执行。
注意事项:
- 在
PreparedStatement实例上必须且只能调用无参版本的executeQuery()、executeUpdate()、execute()和addBatch();虽然PreparedStatement从父接口Statement继承了接收String sql参数的同名重载方法,但在PreparedStatement上调用任何带String sql参数的执行方法,按 JDBC 规范都会直接抛出SQLException。- 使用 MySQL 驱动执行
PreparedStatement批量插入时,务必在 JDBC URL 中添加rewriteBatchedStatements=true参数,驱动才会将多组INSERT INTO ... VALUES (?, ?)批处理参数在底层自动重写合并为一条多值插入语句INSERT INTO ... VALUES (a, b), (c, d),从而获得数十倍的批处理性能提升。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.Arrays;
public class PreparedExecuteDemo {
// 1. 演示预编译语句的无参查询、单条更新与参数化批处理执行
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&rewriteBatchedStatements=true";
try (Connection conn = DriverManager.getConnection(url, "root", "123456")) {
// 2. 绑定查询参数并调用无参 executeQuery 获取结果集
String querySql = "SELECT id, username, balance FROM t_user WHERE balance > ?";
try (PreparedStatement qStmt = conn.prepareStatement(querySql)) {
qStmt.setDouble(1, 300.00);
try (ResultSet rs = qStmt.executeQuery()) {
while (rs.next()) {
System.out.println("查询到用户: " + rs.getString("username"));
}
}
}
// 3. 复用预编译 SQL 模板,循环绑定多组参数并加入批处理队列
String insertSql = "INSERT INTO t_user (username, balance) VALUES (?, ?)";
try (PreparedStatement uStmt = conn.prepareStatement(insertSql)) {
uStmt.setString(1, "Ivan");
uStmt.setDouble(2, 400.00);
uStmt.addBatch();
uStmt.setString(1, "Judy");
uStmt.setDouble(2, 550.00);
uStmt.addBatch();
// 4. 提交批处理队列并执行单条大表更新方法 executeLargeUpdate
int[] batchCounts = uStmt.executeBatch();
System.out.println("预编译批处理结果: " + Arrays.toString(batchCounts));
uStmt.setString(1, "Karl");
uStmt.setDouble(2, 900.00);
long updated = uStmt.executeLargeUpdate();
System.out.println("单条新增受影响行数: " + updated);
}
}
}
}参数绑定
setNull():空值参数绑定。将指定索引位置的
?占位符参数设置为SQL NULL,调用时必须显式传入目标列的 JDBCTypes类型常量。void:(int parameterIndex, int sqlType),按标准类型置空。将指定位置参数设为SQL NULL,并声明目标数据库列的标准java.sql.Types类型代码。void:(int parameterIndex, int sqlType, String typeName),按自定义类型名置空。将指定位置参数设为SQL NULL,专门用于绑定REF、STRUCT、DISTINCT等用户自定义命名类型(UDT)或特定数据库扩展类型。
voidsetBoolean():(int parameterIndex, boolean x),布尔参数绑定。将指定索引的参数设置为给定的 Javaboolean值,驱动会将其转换为 SQLBIT、BOOLEAN或对应的整数值(1/0)。voidsetByte():(int parameterIndex, byte x),单字节整数参数绑定。将指定索引的参数设置为给定的 Javabyte值(映射为 SQLTINYINT)。voidsetShort():(int parameterIndex, short x),短整型参数绑定。将指定索引的参数设置为给定的 Javashort值(映射为 SQLSMALLINT)。voidsetInt():(int parameterIndex, int x),整型参数绑定。将指定索引的参数设置为给定的 Javaint值(映射为 SQLINTEGER)。voidsetLong():(int parameterIndex, long x),长整型参数绑定。将指定索引的参数设置为给定的 Javalong值(映射为 SQLBIGINT)。voidsetFloat():(int parameterIndex, float x),单精度浮点参数绑定。将指定索引的参数设置为给定的 Javafloat值(映射为 SQLREAL)。voidsetDouble():(int parameterIndex, double x),双精度浮点参数绑定。将指定索引的参数设置为给定的 Javadouble值(映射为 SQLDOUBLE或FLOAT)。voidsetBigDecimal():(int parameterIndex, BigDecimal x),高精度十进制参数绑定。将指定索引的参数设置为给定的BigDecimal值(映射为 SQLDECIMAL或NUMERIC,若传入null则绑定为SQL NULL)。voidsetString():(int parameterIndex, String x),字符串参数绑定。将指定索引的参数设置为给定的 JavaString值(映射为 SQLVARCHAR、CHAR或LONGVARCHAR),并由驱动自动对特殊字符执行防注入转义。voidsetNString():(int parameterIndex, String value),国家字符集参数绑定。将指定索引的参数设置为给定的String值,驱动将其作为NCHAR、NVARCHAR或LONGNVARCHAR类型发送给数据库。voidsetBytes():(int parameterIndex, byte[] x),字节数组参数绑定。将指定索引的参数设置为给定的 Javabyte[]原始字节数组(映射为 SQLVARBINARY或LONGVARBINARY)。setDate():日期参数绑定。将指定索引的参数设置为
java.sql.Date值(映射为 SQLDATE),支持指定计算日期毫秒偏移所使用的时区日历。void:(int parameterIndex, Date x),默认时区绑定日期。使用运行当前应用程序的 JVM 默认时区将Date参数绑定到指定占位符。void:(int parameterIndex, Date x, Calendar cal),指定日历时区绑定日期。当底层数据库未存储时区信息时,使用给定Calendar对象的时区解析并构造数据库端存储的日期值。
setTime():时间参数绑定。将指定索引的参数设置为
java.sql.Time值(映射为 SQLTIME),支持指定时区日历。void:(int parameterIndex, Time x),默认时区绑定时间。使用 JVM 默认时区将Time参数绑定到指定占位符。void:(int parameterIndex, Time x, Calendar cal),指定日历时区绑定时间。使用给定Calendar对象的时区将Time参数转换为目标数据库时间格式。
setTimestamp():时间戳参数绑定。将指定索引的参数设置为
java.sql.Timestamp值(映射为 SQLTIMESTAMP或DATETIME),支持指定时区日历。void:(int parameterIndex, Timestamp x),默认时区绑定时间戳。使用 JVM 默认时区将Timestamp参数绑定到指定占位符。void:(int parameterIndex, Timestamp x, Calendar cal),指定日历时区绑定时间戳。使用给定Calendar对象的时区将Timestamp转换为目标数据库的时间戳字面量。
setObject():通用对象参数绑定。使用给定的 Java
Object实例设置指定索引的参数值,支持直接绑定LocalDate、LocalDateTime等 JSR-310 日期时间类型或显式指定目标 SQL 类型与小数精度。void:(int parameterIndex, Object x),按标准映射自动绑定对象。根据传入对象x的运行时 Java 类型自动推断对应的标准 JDBC 类型并完成绑定。void:(int parameterIndex, Object x, int targetSqlType),指定 Types 常量绑定对象。在发送给数据库前,将对象x显式转换为java.sql.Types常量targetSqlType所指定的 SQL 类型。void:(int parameterIndex, Object x, int targetSqlType, int scaleOrLength),指定 Types 常量与精度绑定对象。将对象转换为目标targetSqlType类型,同时通过scaleOrLength指定数值类型的小数点后位数或流对象的字节/字符长度。void:(int parameterIndex, Object x, SQLType targetSqlType),指定 SQLType 接口绑定对象。自 JDK 8 引入的default默认方法,使用JDBCType枚举或厂商自定义的SQLType实例指定目标 SQL 类型。void:(int parameterIndex, Object x, SQLType targetSqlType, int scaleOrLength),指定 SQLType 接口与精度绑定对象。自 JDK 8 引入的default默认方法,在指定SQLType的基础上同时声明数值小数精度或流数据长度。
voidclearParameters():(),已绑定参数清空。立即清空当前PreparedStatement实例中所有已绑定的参数值,以便重新绑定新一轮参数。
注意事项:
- 预编译 SQL 中的
?占位符索引parameterIndex严格从1开始按从左到右的顺序编号;在执行 SQL 前,每一个?占位符都必须完成绑定,若遗漏任何一个占位符且未调用setNull(),执行时将直接抛出SQLException。- 已绑定的参数值在调用
executeUpdate()、executeQuery()或addBatch()后依然保留在当前PreparedStatement中;若后续循环执行时某几个位置的参数值保持不变,无需重复绑定,也可调用clearParameters()将全部参数重置后再重新赋值。
import java.math.BigDecimal;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;
import java.sql.Timestamp;
import java.sql.Types;
import java.time.LocalDateTime;
public class PreparedParamBindDemo {
// 1. 演示预编译 SQL 占位符的基础类型、日期时间、空值及通用对象绑定
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String sql = "INSERT INTO t_user (username, balance) VALUES (?, ?)";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
PreparedStatement pstmt = conn.prepareStatement(sql)) {
// 2. 按从 1 开始的占位符序号绑定字符串与高精度十进制数值
pstmt.setString(1, "Grace");
pstmt.setBigDecimal(2, new BigDecimal("1800.50"));
pstmt.executeUpdate();
// 3. 演示清空已绑定参数、使用 setObject 绑定值及显式置为 SQL NULL
pstmt.clearParameters();
pstmt.setObject(1, "Henry", Types.VARCHAR);
pstmt.setNull(2, Types.DECIMAL);
Timestamp now = Timestamp.valueOf(LocalDateTime.now());
System.out.println("参数绑定完成,当前时间戳: " + now);
}
}
}大对象绑定
setCharacterStream():字符流参数绑定。将指定索引的参数设置为
java.io.Reader字符输入流,适用于向LONGVARCHAR或TEXT大文本字段流式写入超长字符数据。void:(int parameterIndex, Reader reader),未知长度字符流绑定。从reader流中持续读取字符直至到达流末尾(EOF),无需预先计算字符总长度。void:(int parameterIndex, Reader reader, int length),指定 int 字符长度绑定。从reader流中读取指定int length个字符并绑定到目标占位符。void:(int parameterIndex, Reader reader, long length),指定 long 字符长度绑定。从reader流中读取指定long length个字符并绑定到目标占位符,支持超大文本流。
setNCharacterStream():国家字符集流参数绑定。将指定索引的参数设置为
Reader字符流,映射为数据库的NCHAR、NVARCHAR或LONGNVARCHAR宽字符大字段。void:(int parameterIndex, Reader value),未知长度国家字符流绑定。流式读取国家字符集数据直至到达流末尾。void:(int parameterIndex, Reader value, long length),指定 long 长度国家字符流绑定。读取指定long length个宽字符并绑定到目标占位符。
setAsciiStream():ASCII 字节流参数绑定。将指定索引的参数设置为包含单字节 ASCII 字符的
InputStream输入流(映射为 SQLLONGVARCHAR)。void:(int parameterIndex, InputStream x),未知长度 ASCII 流绑定。从输入流持续读取 ASCII 字节直至流末尾。void:(int parameterIndex, InputStream x, int length),指定 int 字节长度 ASCII 流绑定。从输入流读取指定int length字节的 ASCII 数据。void:(int parameterIndex, InputStream x, long length),指定 long 字节长度 ASCII 流绑定。从输入流读取指定long length字节的 ASCII 数据。
setBinaryStream():二进制字节流参数绑定。将指定索引的参数设置为未加工的二进制
InputStream输入流,适用于向BLOB或LONGVARBINARY字段流式写入文件或图片数据。void:(int parameterIndex, InputStream x),未知长度二进制流绑定。从输入流持续读取原始字节直至到达流末尾。void:(int parameterIndex, InputStream x, int length),指定 int 字节数二进制流绑定。从输入流读取指定int length个字节并绑定到目标占位符。void:(int parameterIndex, InputStream x, long length),指定 long 字节数二进制流绑定。从输入流读取指定long length个字节并绑定到目标占位符。
voidsetUnicodeStream():(int parameterIndex, InputStream x, int length),Unicode 字节流绑定(已废弃)。将指定参数设置为双字节 UTF-16 编码的输入流;该方法已被标记为@Deprecated废弃,应当改用setCharacterStream()。setBlob():二进制大对象参数绑定。将指定索引的参数设置为
Blob定位器对象,或直接使用InputStream流构造数据库端的BLOB数据。void:(int parameterIndex, Blob x),直接绑定 Blob 实例。将已创建的java.sql.Blob对象直接绑定到指定占位符。void:(int parameterIndex, InputStream inputStream),以未知长度输入流绑定 Blob。从inputStream流读取字节直至流末尾并写入数据库的BLOB列。void:(int parameterIndex, InputStream inputStream, long length),以指定长度输入流绑定 Blob。从inputStream流读取指定long length个字节并写入数据库的BLOB列。
setClob():字符大对象参数绑定。将指定索引的参数设置为
Clob定位器对象,或直接使用Reader字符流构造数据库端的CLOB数据。void:(int parameterIndex, Clob x),直接绑定 Clob 实例。将已创建的java.sql.Clob对象直接绑定到指定占位符。void:(int parameterIndex, Reader reader),以未知长度字符流绑定 Clob。从reader字符流持续读取文本直至流末尾并写入数据库的CLOB列。void:(int parameterIndex, Reader reader, long length),以指定长度字符流绑定 Clob。从reader字符流读取指定long length个字符并写入数据库的CLOB列。
setNClob():国家字符大对象参数绑定。将指定索引的参数设置为
NClob对象或Reader字符流(映射为 SQLNCLOB)。void:(int parameterIndex, NClob value),直接绑定 NClob 实例。将已创建的NClob对象直接绑定到指定占位符。void:(int parameterIndex, Reader reader),以未知长度字符流绑定 NClob。从reader流读取宽字符文本直至流末尾并写入NCLOB列。void:(int parameterIndex, Reader reader, long length),以指定长度字符流绑定 NClob。从reader流读取指定long length个宽字符并写入NCLOB列。
voidsetSQLXML():(int parameterIndex, SQLXML xmlObject),XML 对象参数绑定。将指定索引的参数设置为java.sql.SQLXML实例(映射为数据库原生的SQLXML类型)。voidsetArray():(int parameterIndex, Array x),SQL 数组参数绑定。将指定索引的参数设置为由Connection.createArrayOf()创建的java.sql.Array数组实例。voidsetRef():(int parameterIndex, Ref x),结构化引用参数绑定。将指定索引的参数设置为 SQLREF(<结构化类型>)引用实例。voidsetURL():(int parameterIndex, URL x),URL 链接参数绑定。将指定索引的参数设置为给定的java.net.URL实例(映射为 SQLDATALINK)。voidsetRowId():(int parameterIndex, RowId x),物理行标识参数绑定。将指定索引的参数设置为数据库底层的java.sql.RowId行地址标识符。
注意事项:
- 使用
setBinaryStream、setCharacterStream、setBlob(int, InputStream)等流式绑定方法时,传入的InputStream或Reader会在后续调用executeUpdate()时才被驱动真正读取;因此在executeUpdate()执行完成前,切勿提前关闭传入的数据流。- 向数据库写入超大文件或长文本时,优先使用流式绑定方法而非
setBytes()或setString(),以避免在 JVM 堆内存中一次性分配庞大的字节或字符数组引发内存溢出。
import java.io.ByteArrayInputStream;
import java.io.StringReader;
import java.nio.charset.StandardCharsets;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;
public class PreparedLobBindDemo {
// 1. 演示通过字符流与二进制流向预编译语句流式绑定大字段参数
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String sql = "UPDATE t_user SET username = ? WHERE id = ?";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
PreparedStatement pstmt = conn.prepareStatement(sql)) {
// 2. 使用 StringReader 以字符流形式绑定文本参数
String text = "StreamUser";
pstmt.setCharacterStream(1, new StringReader(text), text.length());
pstmt.setInt(2, 1);
pstmt.executeUpdate();
// 3. 使用 ByteArrayInputStream 演示二进制流与 Clob 流式绑定接口
byte[] bytes = text.getBytes(StandardCharsets.UTF_8);
pstmt.setBinaryStream(1, new ByteArrayInputStream(bytes), bytes.length);
pstmt.setClob(1, new StringReader(text));
System.out.println("流式大对象参数绑定完毕");
}
}
}元数据探测
ResultSetMetaDatagetMetaData():(),预期结果集元数据获取。返回描述当前PreparedStatement执行后将生成的ResultSet列的名称、类型与数量等结构元数据的ResultSetMetaData对象;若当前语句不是查询语句或驱动无法预先探测,则返回null。ParameterMetaDatagetParameterMetaData():(),占位符参数元数据获取。返回描述当前PreparedStatement中所有?占位符参数的个数、预期 SQL 类型与可空性等信息的ParameterMetaData对象。
注意事项:
- 在
PreparedStatement尚未调用executeQuery()之前直接调用getMetaData(),可以在不真正扫描表数据的前提下探测查询返回列的元信息,但可能会触发驱动向数据库服务端发起一次额外的预编译结构解析网络往返。- MySQL 驱动在默认客户端预编译模式下调用
getParameterMetaData()时,仅能准确返回?占位符的个数(getParameterCount()),若直接调用getParameterType(1)获取参数类型可能抛出SQLException;需在 URL 中配置generateSimpleParameterMetadata=true(统一返回VARCHAR)或开启服务端预编译useServerPrepStmts=true才能读取参数类型。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ParameterMetaData;
import java.sql.PreparedStatement;
import java.sql.ResultSetMetaData;
import java.sql.SQLException;
public class PreparedMetaDemo {
// 1. 演示在未实际执行 SQL 前探测预编译参数元数据与结果集列元数据
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&generateSimpleParameterMetadata=true";
String sql = "SELECT id, username, balance FROM t_user WHERE username = ? AND balance > ?";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
PreparedStatement pstmt = conn.prepareStatement(sql)) {
// 2. 获取预编译 SQL 中占位符参数的个数与元数据信息
ParameterMetaData paramMeta = pstmt.getParameterMetaData();
System.out.println("占位符参数总数: " + paramMeta.getParameterCount());
// 3. 在未调用 executeQuery 的情况下预先获取查询结果集的列结构元数据
ResultSetMetaData rsMeta = pstmt.getMetaData();
if (rsMeta != null) {
System.out.println("预计返回结果集列数: " + rsMeta.getColumnCount());
}
}
}
}继承: Wrapper
isWrapperFor, unwrap
继承: Statement
addBatch, cancel, clearBatch, clearWarnings, close, closeOnCompletion, enquoteIdentifier, enquoteLiteral, enquoteNCharLiteral, execute, execute, execute, execute, executeBatch, executeLargeBatch, executeLargeUpdate, executeLargeUpdate, executeLargeUpdate, executeLargeUpdate, executeQuery, executeUpdate, executeUpdate, executeUpdate, executeUpdate, getConnection, getFetchDirection, getFetchSize, getGeneratedKeys, getLargeMaxRows, getLargeUpdateCount, getMaxFieldSize, getMaxRows, getMoreResults, getMoreResults, getQueryTimeout, getResultSet, getResultSetConcurrency, getResultSetHoldability, getResultSetType, getUpdateCount, getWarnings, isClosed, isCloseOnCompletion, isPoolable, isSimpleIdentifier, setCursorName, setEscapeProcessing, setFetchDirection, setFetchSize, setLargeMaxRows, setMaxFieldSize, setMaxRows, setPoolable, setQueryTimeout
CallableStatement+
java.sql.CallableStatement 是 PreparedStatement 接口的子接口,专门用于调用数据库服务端预定义的存储过程(Stored Procedure)与存储函数(Stored Function),由 Connection 实例调用 prepareCall 方法创建。
由于它继承自 PreparedStatement,因此天然具备预编译参数绑定的能力;同时在此基础上扩展了标准转义语法解析与双向参数(输出参数、输入输出参数)处理机制。
存储过程与转义语法
存储过程与存储函数是事先经过编译并存储在数据库服务端数据字典中的一组 SQL 语句集合。将复杂的多步数据计算、校验与更新封装为存储过程,能够减少 Java 应用与数据库之间的网络往返次数(RTT)。
然而,不同数据库厂商调用存储过程的原生 SQL 语法存在差异(例如 MySQL 使用 CALL proc(),SQL Server 使用 EXEC proc,Oracle 在 PL/SQL 块中调用)。为了屏蔽底层方言差异,JDBC 定义了统一的花括号 {...} 转义语法(Escape Syntax)。当驱动接收到转义字符串时,内部的词法解析器(Escape Processor)会将其翻译为目标数据库的原生调用指令。
无返回值调用语法
调用存储过程(无论是否包含参数)时,使用 {call 过程名(?, ...)} 语法结构:
- 无参存储过程:
{call sp_archive_logs()} - 带参存储过程:
{call sp_upgrade_balance(?, ?, ?)}
带返回值调用语法
调用具有独立返回值的存储函数时,需要在 call 关键字前通过 ? = 接收函数返回值,格式为 {? = call 函数名(?, ...)}。此时最左侧代表返回值的 ? 占据第 1 个参数索引位置,函数括号内的参数索引顺延从 2 开始计算。

参数传递模式
与 PreparedStatement 仅支持单向向数据库传入参数不同,CallableStatement 中的 ? 占位符支持三种不同的数据流向模式。
IN
输入参数模式(默认模式),数据仅从 Java 应用程序单向流向数据库存储过程。在执行前直接复用父接口 PreparedStatement 的类型化赋值方法完成绑定即可,执行完毕后无法从中读取返回值。
OUT
输出参数模式,数据仅从数据库存储过程单向返回给 Java 应用程序,类似于方法调用中的引用传递返回值。
在使用 OUT 参数时,必须在调用执行方法之前,显式告知 JDBC 驱动该占位符期望接收的数据库标准类型(定义在 java.sql.Types 或 java.sql.JDBCType 中),以便驱动为其分配相应的数据缓冲区;待存储过程执行完毕后,再按对应的参数索引位置从 CallableStatement 中提取返回的数据。
在底层实现上(以 MySQL mysql-connector-j 驱动为例),由于 MySQL 协议层面要求通过用户会话变量接收存储过程的 OUT 参数,驱动在解析 {call sp_demo(?)} 时,会自动将其改写为传入会话变量(如 CALL sp_demo(@com_mysql_jdbc_outparam_1)),并在存储过程执行后自动检索该会话变量的值封装回客户端。
INOUT
输入输出双向参数模式,同一个 ? 占位符既负责向存储过程传入初始值,又负责在存储过程执行结束后带回修改后的新值。
处理 INOUT 参数时,必须在执行前同时完成两步操作:既要为其绑定初始输入值,又要注册其输出的 SQL 数据类型;执行完毕后再按该占位符索引读取更新后的结果值。

存储过程调用流程
下面通过一个完整的账户余额升级业务场景,演示包含 IN、OUT、INOUT 三种参数模式的存储过程定义与 JDBC 调用过程。
创建测试存储过程
在 MySQL 数据库 test_db 中创建存储过程 sp_upgrade_balance,接收用户 ID(IN)与奖励金额(INOUT),将奖励累加到原余额后,通过 OUT 参数返回用户名,并通过 INOUT 参数覆盖返回累加后的最新余额:
-- 1. 创建包含 IN、OUT、INOUT 三种参数模式的存储过程
CREATE PROCEDURE sp_upgrade_balance(
IN p_user_id INT,
OUT p_username VARCHAR(50),
INOUT p_balance DECIMAL(10, 2)
)
BEGIN
-- 2. 将传入的奖励金额累加到用户原有余额上
UPDATE t_user
SET balance = balance + p_balance
WHERE id = p_user_id;
-- 3. 查询更新后的用户名与最新余额,分别赋值给 OUT 与 INOUT 参数
SELECT username, balance
INTO p_username, p_balance
FROM t_user
WHERE id = p_user_id;
END;标准调用步骤
在 Java 中通过 CallableStatement 调用含输出参数的存储过程遵循以下五个步骤:
解析转义模板:调用
Connection的prepareCall方法,传入{call ...}格式的转义调用字符串,创建CallableStatement对象。绑定输入参数:按从
1开始的占位符序号,为所有IN和INOUT参数绑定输入值。注册输出类型:按占位符序号,为所有
OUT和INOUT参数注册对应的java.sql.Types类型标识。发送执行指令:调用无参执行方法触发存储过程运行。
提取输出参数:按
OUT和INOUT参数对应的占位符序号读取返回结果。
综合调用示例
以下代码演示了调用 sp_upgrade_balance 存储过程并提取 OUT 与 INOUT 参数值的完整过程:
import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Types;
public class CallableStatementDemo {
public static void main(String[] args) {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
// 1. 使用标准 JDBC 转义语法定义存储过程调用模板
String sql = "{call sp_upgrade_balance(?, ?, ?)}";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
// 2. 通过 Connection 创建 CallableStatement 实例
CallableStatement cstmt = conn.prepareCall(sql)) {
// 3. 为第 1 个参数(IN)和第 3 个参数(INOUT)绑定输入值
cstmt.setInt(1, 1);
cstmt.setDouble(3, 200.00);
// 4. 为第 2 个参数(OUT)和第 3 个参数(INOUT)注册输出 SQL 类型
cstmt.registerOutParameter(2, Types.VARCHAR);
cstmt.registerOutParameter(3, Types.DECIMAL);
// 5. 执行存储过程并按参数索引提取返回结果
cstmt.execute();
String username = cstmt.getString(2);
double latestBalance = cstmt.getDouble(3);
System.out.println("用户: " + username + ", 升级后余额: " + latestBalance);
} catch (SQLException e) {
e.printStackTrace();
}
}
}多结果集与输出参数提取顺序
存储过程内部可以包含多条 SELECT 查询语句与 UPDATE 更新语句,因此一次存储过程调用可能同时向客户端返回多个 ResultSet 结果集、多个更新计数以及末尾的 OUT 输出参数。
在主流数据库的底层网络通信协议(如 MySQL Protocol、SQL Server TDS 协议)中,服务端采用流式顺序发送响应报文:先依次发送各个 SELECT 产生的 ResultSet 数据行包,最后才在数据流末尾附加 OUT 参数的值报文。
因此,JDBC 规范明确要求:为了保证最高的可移植性,当存储过程既返回结果集又包含 OUT 参数时,应用程序必须先遍历处理完所有的 ResultSet 结果集与更新计数,最后再去读取 OUT 参数的值。如果在结果集尚未读取完毕时提前提取 OUT 参数,部分数据库驱动会直接抛出异常,或者被迫将未消费的海量结果集全部读入 JVM 内存缓冲区中。
import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Types;
public class MultiResultCallableDemo {
public static void main(String[] args) {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String sql = "{call sp_multi_query_and_count(?)}";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
CallableStatement cstmt = conn.prepareCall(sql)) {
// 1. 注册 OUT 输出参数的 SQL 类型
cstmt.registerOutParameter(1, Types.INTEGER);
// 2. 执行存储过程,返回值表示第一个结果是否为 ResultSet
boolean hasResultSet = cstmt.execute();
while (hasResultSet) {
try (ResultSet rs = cstmt.getResultSet()) {
while (rs.next()) {
System.out.println("记录行: " + rs.getString(1));
}
}
// 3. 移动到下一个结果集,并自动关闭当前已遍历完毕的 ResultSet
hasResultSet = cstmt.getMoreResults();
}
// 4. 待所有 ResultSet 遍历完毕后,安全提取末尾的 OUT 参数值
int totalCount = cstmt.getInt(1);
System.out.println("统计总数: " + totalCount);
} catch (SQLException e) {
e.printStackTrace();
}
}
}API: CallableStatement
出参注册
- registerOutParameter():存储过程出参注册。在执行存储过程或数据库函数之前,按占位符位置索引(从
1开始)或参数名称,将指定的OUT或INOUT参数注册为预期的 SQL 类型,以便执行后通过getXxx方法提取返回值。void:(int parameterIndex, int sqlType),按索引与 Types 常量注册。将指定位置序号的OUT参数注册为java.sql.Types定义的标准 SQL 类型码。void:(int parameterIndex, int sqlType, int scale),按索引、Types 常量与小数位数注册。专用于注册Types.NUMERIC或Types.DECIMAL类型的数值出参,并通过scale指定小数点右边的保留位数。void:(int parameterIndex, int sqlType, String typeName),按索引与自定义类型名注册。将指定位置序号的出参注册为用户自定义结构化类型(STRUCT、DISTINCT、REF),并传入数据库的完整类型名称typeName。void:(String parameterName, int sqlType),按参数名与 Types 常量注册。按存储过程定义的参数名称将出参注册为标准Types类型码。void:(String parameterName, int sqlType, int scale),按参数名、Types 常量与小数位数注册。按参数名称注册定点小数出参并指定小数点后保留位数scale。void:(String parameterName, int sqlType, String typeName),按参数名与自定义类型名注册。按参数名称将出参注册为指定数据库类型名typeName的自定义复合类型。void:(int parameterIndex, SQLType sqlType),按索引与 SQLType 接口注册。自 JDK 8 引入的default默认方法,使用JDBCType枚举或厂商自定义的SQLType实例按位置索引注册出参。void:(int parameterIndex, SQLType sqlType, int scale),按索引、SQLType 与小数位数注册。自 JDK 8 引入的default默认方法,按位置索引注册带小数精度scale的SQLType出参。void:(int parameterIndex, SQLType sqlType, String typeName),按索引、SQLType 与自定义类型名注册。自 JDK 8 引入的default默认方法,按位置索引注册指定typeName的自定义类型出参。void:(String parameterName, SQLType sqlType),按参数名与 SQLType 接口注册。自 JDK 8 引入的default默认方法,按参数名称使用SQLType实例注册出参。void:(String parameterName, SQLType sqlType, int scale),按参数名、SQLType 与小数位数注册。自 JDK 8 引入的default默认方法,按参数名称注册带小数位数scale的SQLType出参。void:(String parameterName, SQLType sqlType, String typeName),按参数名、SQLType 与自定义类型名注册。自 JDK 8 引入的default默认方法,按参数名称注册指定typeName的SQLType出参。
注意事项:
- 存储过程的所有
OUT和INOUT参数必须在调用execute()执行存储过程之前调用registerOutParameter()完成类型注册,否则执行时将直接抛出SQLException。- 对于既是输入又是输出的
INOUT双向参数,在调用execute()前既要调用setXxx()绑定输入值,也必须调用registerOutParameter()注册输出类型;对于采用{? = call func_name(?)}语法的数据库函数调用,返回值占据第1个?占位符,同样必须通过registerOutParameter(1, ...)注册。
import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.JDBCType;
import java.sql.SQLException;
import java.sql.Types;
public class CallableOutRegisterDemo {
// 1. 建立数据库连接并创建调用存储过程的 CallableStatement 对象
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String callSql = "{call sp_calc_bonus(?, ?, ?)}";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
CallableStatement cstmt = conn.prepareCall(callSql)) {
// 2. 绑定第 1 个 IN 输入参数(员工 ID)
cstmt.setInt(1, 101);
// 3. 按位置索引与 Types 常量注册第 2 个 OUT 输出参数(姓名)
cstmt.registerOutParameter(2, Types.VARCHAR);
// 4. 按参数名称与 JDBCType 枚举注册带小数精度的第 3 个 OUT 参数(奖金)
cstmt.registerOutParameter("out_bonus", JDBCType.DECIMAL, 2);
System.out.println("OUT 输出参数注册完成");
}
}
}出参读取
booleanwasNull():(),出参空值状态检测。判断最后一次通过getXxx方法读取的OUT输出参数在数据库中返回的值是否为SQL NULL;若是则返回true,否则返回false。getString():字符串出参读取。以 Java
String形式获取指定OUT参数返回的字符类型数据(适用于CHAR、VARCHAR、LONGVARCHAR);若值为SQL NULL则返回null。String:(int parameterIndex),按索引读取字符串出参。根据从1开始的占位符序号读取字符串返回值。String:(String parameterName),按参数名读取字符串出参。根据存储过程定义的参数名称读取字符串返回值。
getNString():国家字符集字符串出参读取。以 Java
String形式读取NCHAR、NVARCHAR或LONGNVARCHAR类型的国家字符集出参。String:(int parameterIndex),按索引读取国家字符串出参。根据占位符索引读取宽字符字符串。String:(String parameterName),按参数名读取国家字符串出参。根据参数名称读取宽字符字符串。
getBoolean():布尔型出参读取。以
boolean形式读取指定OUT参数的值;若数据库返回SQL NULL则返回false。boolean:(int parameterIndex),按索引读取布尔出参。根据占位符索引读取boolean返回值。boolean:(String parameterName),按参数名读取布尔出参。根据参数名称读取boolean返回值。
getByte():字节整数出参读取。以
byte形式读取指定TINYINT出参的值;若为SQL NULL则返回0。byte:(int parameterIndex),按索引读取单字节整数出参。根据占位符索引读取byte返回值。byte:(String parameterName),按参数名读取单字节整数出参。根据参数名称读取byte返回值。
getShort():短整型出参读取。以
short形式读取指定SMALLINT出参的值;若为SQL NULL则返回0。short:(int parameterIndex),按索引读取短整数出参。根据占位符索引读取short返回值。short:(String parameterName),按参数名读取短整数出参。根据参数名称读取short返回值。
getInt():整型出参读取。以
int形式读取指定INTEGER出参的值;若为SQL NULL则返回0。int:(int parameterIndex),按索引读取整数出参。根据占位符索引读取int返回值。int:(String parameterName),按参数名读取整数出参。根据参数名称读取int返回值。
getLong():长整型出参读取。以
long形式读取指定BIGINT出参的值;若为SQL NULL则返回0L。long:(int parameterIndex),按索引读取长整数出参。根据占位符索引读取long返回值。long:(String parameterName),按参数名读取长整数出参。根据参数名称读取long返回值。
getFloat():单精度浮点出参读取。以
float形式读取指定REAL出参的值;若为SQL NULL则返回0.0f。float:(int parameterIndex),按索引读取单精度浮点出参。根据占位符索引读取float返回值。float:(String parameterName),按参数名读取单精度浮点出参。根据参数名称读取float返回值。
getDouble():双精度浮点出参读取。以
double形式读取指定DOUBLE或FLOAT出参的值;若为SQL NULL则返回0.0d。double:(int parameterIndex),按索引读取双精度浮点出参。根据占位符索引读取double返回值。double:(String parameterName),按参数名读取双精度浮点出参。根据参数名称读取double返回值。
getBigDecimal():高精度十进制出参读取。以
BigDecimal形式读取指定DECIMAL或NUMERIC出参的值;若为SQL NULL则返回null。BigDecimal:(int parameterIndex),按索引读取全精度十进制出参。根据占位符索引读取完整精度的BigDecimal对象。BigDecimal:(String parameterName),按参数名读取全精度十进制出参。根据参数名称读取完整精度的BigDecimal对象。BigDecimal:(int parameterIndex, int scale),按索引与小数位数读取(已废弃)。按指定小数位数截断读取BigDecimal,已被标记为@Deprecated废弃。
getBytes():字节数组出参读取。以
byte[]数组形式读取指定BINARY或VARBINARY出参的二进制数据。byte[]:(int parameterIndex),按索引读取字节数组出参。根据占位符索引读取byte[]返回值。byte[]:(String parameterName),按参数名读取字节数组出参。根据参数名称读取byte[]返回值。
getDate():日期出参读取。以
java.sql.Date形式读取指定DATE出参的值,支持传入Calendar指定时区。Date:(int parameterIndex),按索引读取日期出参。使用 JVM 默认时区根据占位符索引读取Date对象。Date:(String parameterName),按参数名读取日期出参。使用 JVM 默认时区根据参数名称读取Date对象。Date:(int parameterIndex, Calendar cal),按索引与日历时区读取日期出参。结合给定Calendar的时区根据占位符索引构造Date对象。Date:(String parameterName, Calendar cal),按参数名与日历时区读取日期出参。结合给定Calendar的时区根据参数名称构造Date对象。
getTime():时间出参读取。以
java.sql.Time形式读取指定TIME出参的值,支持传入Calendar指定时区。Time:(int parameterIndex),按索引读取时间出参。使用默认时区根据占位符索引读取Time对象。Time:(String parameterName),按参数名读取时间出参。使用默认时区根据参数名称读取Time对象。Time:(int parameterIndex, Calendar cal),按索引与日历时区读取时间出参。结合给定Calendar的时区根据索引构造Time对象。Time:(String parameterName, Calendar cal),按参数名与日历时区读取时间出参。结合给定Calendar的时区根据参数名构造Time对象。
getTimestamp():时间戳出参读取。以
java.sql.Timestamp形式读取指定TIMESTAMP出参的值,支持传入Calendar指定时区。Timestamp:(int parameterIndex),按索引读取时间戳出参。使用默认时区根据占位符索引读取Timestamp对象。Timestamp:(String parameterName),按参数名读取时间戳出参。使用默认时区根据参数名称读取Timestamp对象。Timestamp:(int parameterIndex, Calendar cal),按索引与日历时区读取时间戳出参。结合给定Calendar的时区根据索引构造Timestamp对象。Timestamp:(String parameterName, Calendar cal),按参数名与日历时区读取时间戳出参。结合给定Calendar的时区根据参数名构造Timestamp对象。
getObject():通用对象与泛型出参读取。将指定
OUT参数读取为注册类型对应的默认 JavaObject,或按指定的Class<T>强类型转换返回。Object:(int parameterIndex),按索引读取默认对象出参。根据占位符索引返回与registerOutParameter注册类型对应的动态 Java 对象。Object:(String parameterName),按参数名读取默认对象出参。根据参数名称返回与注册类型对应的动态 Java 对象。<T> T:(int parameterIndex, Class<T> type),按索引与泛型类型读取出参。根据占位符索引读取出参并直接转换为type指定的目标 Java 类型实例。<T> T:(String parameterName, Class<T> type),按参数名与泛型类型读取出参。根据参数名称读取出参并直接转换为type指定的目标 Java 类型实例。Object:(int parameterIndex, Map<String, Class<?>> map),按索引与自定义类型表读取出参。使用给定的自定义类型映射表map解析指定索引的 SQL 结构化出参。Object:(String parameterName, Map<String, Class<?>> map),按参数名与自定义类型表读取出参。使用给定的自定义类型映射表map解析指定名称的 SQL 结构化出参。
getCharacterStream():字符流出参读取。以
java.io.Reader字符流形式流式读取指定OUT参数的大文本返回值。Reader:(int parameterIndex),按索引读取字符流出参。根据占位符索引获取Reader字符流。Reader:(String parameterName),按参数名读取字符流出参。根据参数名称获取Reader字符流。
getNCharacterStream():国家字符集流出参读取。以
Reader字符流形式读取国家字符集类型的OUT参数值。Reader:(int parameterIndex),按索引读取国家字符流出参。根据占位符索引获取宽字符Reader流。Reader:(String parameterName),按参数名读取国家字符流出参。根据参数名称获取宽字符Reader流。
getBlob():二进制大对象出参读取。以
Blob接口实例形式读取指定BLOB类型的输出参数。Blob:(int parameterIndex),按索引读取 Blob 出参。根据占位符索引获取Blob对象。Blob:(String parameterName),按参数名读取 Blob 出参。根据参数名称获取Blob对象。
getClob():字符大对象出参读取。以
Clob接口实例形式读取指定CLOB类型的输出参数。Clob:(int parameterIndex),按索引读取 Clob 出参。根据占位符索引获取Clob对象。Clob:(String parameterName),按参数名读取 Clob 出参。根据参数名称获取Clob对象。
getNClob():国家字符大对象出参读取。以
NClob接口实例形式读取指定NCLOB类型的输出参数。NClob:(int parameterIndex),按索引读取 NClob 出参。根据占位符索引获取NClob对象。NClob:(String parameterName),按参数名读取 NClob 出参。根据参数名称获取NClob对象。
getSQLXML():XML 对象出参读取。以
SQLXML接口实例形式读取指定SQLXML类型的输出参数。SQLXML:(int parameterIndex),按索引读取 SQLXML 出参。根据占位符索引获取SQLXML对象。SQLXML:(String parameterName),按参数名读取 SQLXML 出参。根据参数名称获取SQLXML对象。
getArray():SQL 数组出参读取。以
java.sql.Array实例形式读取指定ARRAY类型的输出参数。Array:(int parameterIndex),按索引读取 Array 出参。根据占位符索引获取 SQLArray对象。Array:(String parameterName),按参数名读取 Array 出参。根据参数名称获取 SQLArray对象。
getRef():SQL 引用出参读取。以
Ref实例形式读取指定REF结构化引用类型的输出参数。Ref:(int parameterIndex),按索引读取 Ref 出参。根据占位符索引获取Ref对象。Ref:(String parameterName),按参数名读取 Ref 出参。根据参数名称获取Ref对象。
getURL():URL 链接出参读取。以
java.net.URL实例形式读取指定DATALINK类型的输出参数。URL:(int parameterIndex),按索引读取 URL 出参。根据占位符索引解析并返回URL对象。URL:(String parameterName),按参数名读取 URL 出参。根据参数名称解析并返回URL对象。
getRowId():物理行标识出参读取。以
RowId实例形式读取指定ROWID类型的输出参数。RowId:(int parameterIndex),按索引读取 RowId 出参。根据占位符索引获取RowId对象。RowId:(String parameterName),按参数名读取 RowId 出参。根据参数名称获取RowId对象。
注意事项:
- 当存储过程同时返回多个
ResultSet查询结果集、更新计数以及OUT输出参数时,为了达到最高的可移植性,JDBC 规范要求必须先使用getResultSet()和getMoreResults()处理完所有的结果集与更新计数后,最后再调用CallableStatement.getXxx()提取OUT参数值。- 在 Oracle 等数据库中,若存储过程通过
SYS_REFCURSOR(引用游标)类型的OUT参数返回结果集,可在注册为Types.REF_CURSOR(或JDBCType.REF_CURSOR)后,直接调用cstmt.getObject(index, ResultSet.class)将该出参读取为ResultSet遍历。
import java.math.BigDecimal;
import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Types;
public class CallableOutReadDemo {
// 1. 执行存储过程并演示从 CallableStatement 提取各类 OUT 输出参数
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String callSql = "{call sp_get_user_summary(?, ?, ?)}";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
CallableStatement cstmt = conn.prepareCall(callSql)) {
// 2. 设置 IN 入参并注册两个 OUT 出参
cstmt.setInt(1, 1);
cstmt.registerOutParameter(2, Types.VARCHAR);
cstmt.registerOutParameter(3, Types.DECIMAL);
cstmt.execute();
// 3. 按占位符索引与泛型 Class 提取 OUT 参数值
String username = cstmt.getString(2);
BigDecimal balance = cstmt.getObject(3, BigDecimal.class);
// 4. 检测最后一次读取的 OUT 参数是否为 SQL NULL
if (cstmt.wasNull()) {
System.out.println("用户 " + username + " 的余额出参为 NULL");
} else {
System.out.println("用户: " + username + ", 余额: " + balance);
}
}
}
}命名入参
setNull():命名空值入参绑定。按存储过程定义的参数名称将指定
IN参数设置为SQL NULL(按位置索引绑定的重载继承自PreparedStatement)。void:(String parameterName, int sqlType),按参数名与标准类型置空。将指定名称的参数设为SQL NULL,并声明目标参数的java.sql.Types类型码。void:(String parameterName, int sqlType, String typeName),按参数名与自定义类型名置空。将指定名称的自定义复合类型参数设为SQL NULL,并声明数据库类型名typeName。
voidsetBoolean():(String parameterName, boolean x),命名布尔入参绑定。按参数名称将指定参数设置为给定的 Javaboolean值。voidsetByte():(String parameterName, byte x),命名单字节整数入参绑定。按参数名称将指定参数设置为给定的 Javabyte值。voidsetShort():(String parameterName, short x),命名短整型入参绑定。按参数名称将指定参数设置为给定的 Javashort值。voidsetInt():(String parameterName, int x),命名整型入参绑定。按参数名称将指定参数设置为给定的 Javaint值。voidsetLong():(String parameterName, long x),命名长整型入参绑定。按参数名称将指定参数设置为给定的 Javalong值。voidsetFloat():(String parameterName, float x),命名单精度浮点入参绑定。按参数名称将指定参数设置为给定的 Javafloat值。voidsetDouble():(String parameterName, double x),命名双精度浮点入参绑定。按参数名称将指定参数设置为给定的 Javadouble值。voidsetBigDecimal():(String parameterName, BigDecimal x),命名高精度十进制入参绑定。按参数名称将指定参数设置为给定的BigDecimal值。voidsetString():(String parameterName, String x),命名字符串入参绑定。按参数名称将指定参数设置为给定的 JavaString值。voidsetNString():(String parameterName, String value),命名国家字符集入参绑定。按参数名称将指定参数设置为国家字符集String值。voidsetBytes():(String parameterName, byte[] x),命名字节数组入参绑定。按参数名称将指定参数设置为给定的byte[]原始字节数组。setDate():命名日期入参绑定。按参数名称将指定参数设置为
java.sql.Date日期值,支持传入Calendar指定时区。void:(String parameterName, Date x),按参数名默认时区绑定日期。使用 JVM 默认时区将Date绑定到指定名称的参数。void:(String parameterName, Date x, Calendar cal),按参数名与日历时区绑定日期。使用给定Calendar的时区将Date绑定到指定名称的参数。
setTime():命名时间入参绑定。按参数名称将指定参数设置为
java.sql.Time时间值,支持传入Calendar指定时区。void:(String parameterName, Time x),按参数名默认时区绑定时间。使用 JVM 默认时区将Time绑定到指定名称的参数。void:(String parameterName, Time x, Calendar cal),按参数名与日历时区绑定时间。使用给定Calendar的时区将Time绑定到指定名称的参数。
setTimestamp():命名时间戳入参绑定。按参数名称将指定参数设置为
java.sql.Timestamp时间戳值,支持传入Calendar指定时区。void:(String parameterName, Timestamp x),按参数名默认时区绑定时间戳。使用 JVM 默认时区将Timestamp绑定到指定名称的参数。void:(String parameterName, Timestamp x, Calendar cal),按参数名与日历时区绑定时间戳。使用给定Calendar的时区将Timestamp绑定到指定名称的参数。
setObject():命名通用对象入参绑定。按参数名称(或位置索引与
SQLType)将给定的 JavaObject绑定为存储过程入参,支持指定目标 SQL 类型与小数精度。void:(String parameterName, Object x),按参数名自动推断绑定对象。根据传入对象x的运行时类型自动映射为标准 SQL 类型并按名称完成绑定。void:(String parameterName, Object x, int targetSqlType),按参数名与 Types 常量绑定对象。将对象x转换为targetSqlType指定的Types类型后绑定到指定参数名。void:(String parameterName, Object x, int targetSqlType, int scale),按参数名、Types 常量与精度绑定对象。将对象转换为目标Types类型并按scale指定小数位数后绑定到指定参数名。void:(String parameterName, Object x, SQLType targetSqlType),按参数名与 SQLType 绑定对象。自 JDK 8 引入的default默认方法,使用SQLType指定目标类型并按名称绑定对象。void:(String parameterName, Object x, SQLType targetSqlType, int scaleOrLength),按参数名、SQLType 与精度绑定对象。自 JDK 8 引入的default默认方法,按名称绑定对象并指定目标SQLType及精度或流长度。void:(int parameterIndex, Object x, SQLType targetSqlType),按索引与 SQLType 绑定对象。自 JDK 8 引入并重写的default默认方法,按位置索引与目标SQLType绑定对象。void:(int parameterIndex, Object x, SQLType targetSqlType, int scaleOrLength),按索引、SQLType 与精度绑定对象。自 JDK 8 引入并重写的default默认方法,按位置索引、目标SQLType及精度绑定对象。
注意事项:
- 按参数名称(
parameterName)绑定或注册参数前,可通过DatabaseMetaData.supportsNamedParameters()检测底层驱动是否支持命名参数;在 MySQL 中使用命名参数时,驱动需要查询information_schema.PARAMETERS元数据表来解析参数名与位置的映射关系,因此当前数据库账号必须具备对该存储过程元数据的读取权限。- 在同一个
CallableStatement调用中,切勿将基于位置索引(int parameterIndex)和基于参数名称(String parameterName)的绑定方式混用,应保持整条调用统一使用索引或统一使用参数名。
import java.math.BigDecimal;
import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.JDBCType;
import java.sql.SQLException;
import java.sql.Types;
public class CallableNamedParamDemo {
// 1. 演示按存储过程定义的参数名称绑定基础类型、对象及空值入参
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String callSql = "{call sp_update_user_balance(?, ?, ?)}";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
CallableStatement cstmt = conn.prepareCall(callSql)) {
// 2. 通过存储过程参数名直接绑定整型、字符串与高精度十进制入参
cstmt.setInt("in_user_id", 1);
cstmt.setString("in_username", "Alice");
cstmt.setBigDecimal("in_balance", new BigDecimal("2500.00"));
// 3. 演示按参数名使用 setObject 绑定值及 setNull 显式置空
cstmt.setObject("in_balance", new BigDecimal("3000.00"), JDBCType.DECIMAL, 2);
cstmt.setNull("in_username", Types.VARCHAR);
System.out.println("存储过程命名入参绑定完成");
}
}
}命名大对象
setCharacterStream():命名字符流入参绑定。按参数名称将指定参数设置为
java.io.Reader字符流,用于向存储过程的TEXT或LONGVARCHAR参数流式传入长文本。void:(String parameterName, Reader reader),按参数名绑定未知长度字符流。从reader流持续读取字符直至流末尾并绑定到指定参数名。void:(String parameterName, Reader reader, int length),按参数名与 int 长度绑定字符流。从reader流读取指定int length个字符并绑定到指定参数名。void:(String parameterName, Reader reader, long length),按参数名与 long 长度绑定字符流。从reader流读取指定long length个字符并绑定到指定参数名。
setNCharacterStream():命名国家字符集流入参绑定。按参数名称将指定参数设置为
Reader宽字符流(映射为NCHAR、NVARCHAR或LONGNVARCHAR)。void:(String parameterName, Reader value),按参数名绑定未知长度国家字符流。流式读取宽字符数据直至流末尾并绑定到指定参数名。void:(String parameterName, Reader value, long length),按参数名与 long 长度绑定国家字符流。读取指定long length个宽字符并绑定到指定参数名。
setAsciiStream():命名 ASCII 字节流入参绑定。按参数名称将指定参数设置为单字节 ASCII
InputStream输入流。void:(String parameterName, InputStream x),按参数名绑定未知长度 ASCII 流。从输入流持续读取 ASCII 字节直至流末尾。void:(String parameterName, InputStream x, int length),按参数名与 int 长度绑定 ASCII 流。从输入流读取指定int length字节的 ASCII 数据。void:(String parameterName, InputStream x, long length),按参数名与 long 长度绑定 ASCII 流。从输入流读取指定long length字节的 ASCII 数据。
setBinaryStream():命名二进制字节流入参绑定。按参数名称将指定参数设置为原始二进制
InputStream输入流。void:(String parameterName, InputStream x),按参数名绑定未知长度二进制流。从输入流持续读取二进制字节直至流末尾。void:(String parameterName, InputStream x, int length),按参数名与 int 长度绑定二进制流。从输入流读取指定int length个字节并绑定到指定参数名。void:(String parameterName, InputStream x, long length),按参数名与 long 长度绑定二进制流。从输入流读取指定long length个字节并绑定到指定参数名。
setBlob():命名二进制大对象入参绑定。按参数名称将指定参数设置为
Blob对象或二进制InputStream流。void:(String parameterName, Blob x),按参数名直接绑定 Blob 实例。将已创建的Blob对象绑定到指定参数名。void:(String parameterName, InputStream inputStream),按参数名以未知长度输入流绑定 Blob。从inputStream读取字节直至流末尾并作为BLOB绑定到指定参数名。void:(String parameterName, InputStream inputStream, long length),按参数名与流长度绑定 Blob。从inputStream读取指定long length个字节并作为BLOB绑定到指定参数名。
setClob():命名字符大对象入参绑定。按参数名称将指定参数设置为
Clob对象或Reader字符流。void:(String parameterName, Clob x),按参数名直接绑定 Clob 实例。将已创建的Clob对象绑定到指定参数名。void:(String parameterName, Reader reader),按参数名以未知长度字符流绑定 Clob。从reader流读取文本直至流末尾并作为CLOB绑定到指定参数名。void:(String parameterName, Reader reader, long length),按参数名与字符数绑定 Clob。从reader流读取指定long length个字符并作为CLOB绑定到指定参数名。
setNClob():命名国家字符大对象入参绑定。按参数名称将指定参数设置为
NClob对象或宽字符Reader流。void:(String parameterName, NClob value),按参数名直接绑定 NClob 实例。将已创建的NClob对象绑定到指定参数名。void:(String parameterName, Reader reader),按参数名以未知长度字符流绑定 NClob。从reader流读取宽字符直至流末尾并作为NCLOB绑定到指定参数名。void:(String parameterName, Reader reader, long length),按参数名与字符数绑定 NClob。从reader流读取指定long length个宽字符并作为NCLOB绑定到指定参数名。
voidsetSQLXML():(String parameterName, SQLXML xmlObject),命名 XML 对象入参绑定。按参数名称将指定参数设置为java.sql.SQLXML实例。voidsetURL():(String parameterName, URL val),命名 URL 链接入参绑定。按参数名称将指定参数设置为给定的java.net.URL实例。voidsetRowId():(String parameterName, RowId x),命名物理行标识入参绑定。按参数名称将指定参数设置为数据库底层的java.sql.RowId行地址标识符。
注意事项:
CallableStatement未提供按参数名绑定 SQL 数组的setArray(String, Array)与绑定引用的setRef(String, Ref)方法;若存储过程包含ARRAY或REF类型入参,必须使用从PreparedStatement继承的按位置索引绑定方法setArray(int, Array)与setRef(int, Ref)。
import java.io.ByteArrayInputStream;
import java.io.StringReader;
import java.nio.charset.StandardCharsets;
import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
public class CallableNamedLobDemo {
// 1. 演示按参数名称向存储过程流式绑定字符流、二进制流及大对象参数
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String callSql = "{call sp_save_user_profile(?, ?, ?)}";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
CallableStatement cstmt = conn.prepareCall(callSql)) {
// 2. 按参数名绑定定长字符流与 Clob 文本流
String bio = "Java Backend Developer";
cstmt.setCharacterStream("in_bio", new StringReader(bio), bio.length());
cstmt.setClob("in_resume", new StringReader(bio));
// 3. 按参数名绑定二进制字节流与 Blob 输入流
byte[] avatarBytes = bio.getBytes(StandardCharsets.UTF_8);
cstmt.setBinaryStream("in_avatar", new ByteArrayInputStream(avatarBytes), avatarBytes.length);
cstmt.setBlob("in_avatar", new ByteArrayInputStream(avatarBytes));
System.out.println("存储过程命名大对象流绑定完成");
}
}
}继承: Wrapper
isWrapperFor, unwrap
继承: Statement
addBatch, cancel, clearBatch, clearWarnings, close, closeOnCompletion, enquoteIdentifier, enquoteLiteral, enquoteNCharLiteral, execute, execute, execute, execute, executeBatch, executeLargeBatch, executeLargeUpdate, executeLargeUpdate, executeLargeUpdate, executeLargeUpdate, executeQuery, executeUpdate, executeUpdate, executeUpdate, executeUpdate, getConnection, getFetchDirection, getFetchSize, getGeneratedKeys, getLargeMaxRows, getLargeUpdateCount, getMaxFieldSize, getMaxRows, getMoreResults, getMoreResults, getQueryTimeout, getResultSet, getResultSetConcurrency, getResultSetHoldability, getResultSetType, getUpdateCount, getWarnings, isClosed, isCloseOnCompletion, isPoolable, isSimpleIdentifier, setCursorName, setEscapeProcessing, setFetchDirection, setFetchSize, setLargeMaxRows, setMaxFieldSize, setMaxRows, setPoolable, setQueryTimeout
继承: PreparedStatement
addBatch, clearParameters, execute, executeLargeUpdate, executeQuery, executeUpdate, getMetaData, getParameterMetaData, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBoolean, setByte, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setDate, setDate, setDouble, setFloat, setInt, setLong, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNString, setNull, setNull, setObject, setObject, setObject, setRef, setRowId, setShort, setSQLXML, setString, setTime, setTime, setTimestamp, setTimestamp, setUnicodeStream, setURL
ResultSet
是 JDBC 中用于封装数据库查询(DQL)返回结果的表格数据对象,由 java.sql.ResultSetStatement、PreparedStatement 或 CallableStatement 执行查询后创建并返回。
在逻辑结构上,ResultSet 表现为一个由行(Row)与列(Column)组成的二维关系表,其内部维护了一个指向当前数据行的游标(Cursor)。应用程序通过移动游标定位目标行,并按照列索引或列标签提取当前行各字段的数据值。
游标定位
ResultSet 对象在刚创建完成时,其内部游标并非直接指向第一行数据,而是停留在第一行数据之前的初始越界位置(Before First)。
初始越界位置与行推进
游标在生命周期内会依次经历三个逻辑区域:
首行前区域(Before First):
ResultSet初始化后的默认位置。此时游标未指向任何有效数据行,如果在未移动游标的情况下直接读取列数据,驱动会立即抛出SQLException: Before start of result set异常。有效数据行区域(Data Rows):每调用一次游标前移方法,游标向下推进一行。若推进后指向的是有效数据行,方法返回
true,此时允许安全读取该行的所有列值。末行后区域(After Last):当游标越过最后一行有效数据后,进入末行后越界区域,推进方法返回
false(若结果集本身为空表,则首次推进即直接从 Before First 跳入 After Last 并返回false)。在此区域继续读取列数据同样会触发SQLException: After end of result set异常。

列数据提取
当游标停留在有效数据行上时,ResultSet 支持通过“列索引”与“列标签”两种寻址方式提取当前行的字段值,并在底层完成数据库 SQL 类型向 Java 数据类型的映射转换。
列索引
按列在 SELECT 查询结果集中的排列序号提取数据,序号从 1 开始从左至右递增(而非 Java 数组的 0 起始索引)。
由于 JDBC 驱动底层通常使用一维数组(如 byte[][] 或 Value[])存储当前行的各列数据,传入整型列索引可以直接通过数组下标 index - 1 一步寻址,无需进行字符串哈希计算与列名比对,因此在所有提取方式中性能最高。但其缺点是与 SQL 语句中字段的书写顺序强耦合,一旦 SQL 调整了字段顺序或使用了 SELECT * 且表结构发生变更,Java 代码就会读错列或抛出类型转换异常。
列标签
按字符串名称匹配目标列并提取数据。
在 JDBC 4.0 规范中,传入的字符串参数匹配的是 SQL 查询的列标签(Column Label)——即当 SQL 中使用 AS 定义了列别名时,必须传入别名;未定义别名时才传入原始列名。
优化:在底层实现上,当首次按列标签读取数据时,驱动会遍历结果集元数据构建一个 “列标签(大小写不敏感)到列索引”的哈希映射缓存 (如 MySQL 驱动中的 ColumnNameToIndexCache),后续行循环读取时直接从缓存中查找对应的列索引,兼顾了代码可读性与维护性。
数据库 NULL 值转换陷阱
在关系型数据库中,任何字段都可能存储 NULL 值。当通过 ResultSet 提取列数据时,Java 基本数据类型与引用数据类型对 SQL 存在显著差异:NULL 的映射行为
引用类型直接映射为 null:当提取为
String、BigDecimal、LocalDateTime等引用类型时,若数据库字段值为NULL,方法会直接返回 Java 的null引用。基本类型退化为零值:由于 Java 基本数据类型(
int、long、double、boolean)无法接收null,JDBC 规范规定当数据库字段为NULL时,数值型读取方法会静默返回0(或0.0),布尔型读取方法会返回false。这会导致业务层无法直接区分数据库中存储的究竟是真实数值0,还是缺失值NULL。安全判空与泛型提取:若必须在基本类型读取后识别
NULL,需紧接着检查结果集最近一次读取的列是否为空值;而在现代 JDK(JDBC 4.1+)开发中,更推荐直接传入包装类的Class对象(如Integer.class、Double.class)进行泛型提取,此时 SQLNULL会直接返回null而不会退化为0:javaimport java.sql.Connection; import java.sql.DriverManager; import java.sql.PreparedStatement; import java.sql.ResultSet; import java.sql.SQLException; public class ResultSetExtractDemo { public static void main(String[] args) { String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC"; // 1. 定义带列别名的查询语句,用于演示列索引与列标签提取 String sql = "SELECT id, username AS uname, balance FROM t_user WHERE id = ?"; try (Connection conn = DriverManager.getConnection(url, "root", "123456"); PreparedStatement pstmt = conn.prepareStatement(sql)) { pstmt.setInt(1, 1); // 2. 执行查询获取 ResultSet,初始游标位于第一行数据之前 try (ResultSet rs = pstmt.executeQuery()) { // 3. 向下推进游标,返回 true 表示成功指向有效数据行 while (rs.next()) { // 4. 通过从 1 开始的列索引提取第 1 列数据,通过列标签别名提取第 2 列数据 int id = rs.getInt(1); String username = rs.getString("uname"); // 5. 读取基本类型后调用 wasNull 判断数据库原始值是否为 SQL NULL double rawBalance = rs.getDouble("balance"); if (rs.wasNull()) { System.out.println(id + " - " + username + " -> 余额为 NULL"); } else { System.out.println(id + " - " + username + " -> " + rawBalance); } // 6. 推荐使用泛型 getObject 直接提取包装类型,SQL NULL 会安全映射为 Java null Double safeBalance = rs.getObject("balance", Double.class); System.out.println("安全提取包装类型余额: " + safeBalance); } } } catch (SQLException e) { e.printStackTrace(); } } }
结果集滚动与并发模式+
默认情况下,由 Connection 创建的语句对象生成的 ResultSet 仅支持单向向前遍历且不可修改。
开发者可以在创建 Statement 或 PreparedStatement 时显式传入结果集类型(resultSetType)与并发模式(resultSetConcurrency)常量,扩展游标的移动与写回能力。
单向只读模式
默认组合为 (仅向前滚动)与 ResultSet.TYPE_FORWARD_ONLY(只读并发)。在此模式下,游标只能从首行前向末行后单向递增推进,不支持后退或随机行跳转,也不允许直接通过结果集修改数据,资源开销最小,适合绝大多数常规业务查询。ResultSet.CONCUR_READ_ONLY
双向滚动模式
当结果集类型指定为 (双向滚动,对其他事务提交的底层数据变更不敏感,基于内存静态快照)或 ResultSet.TYPE_SCROLL_INSENSITIVE(双向滚动,动态感知底层数据修改,取决于驱动是否支持)时,游标可以在结果集中自由前进、后退、直接跳转到首尾行,或按绝对行号与相对偏移量随机定位。ResultSet.TYPE_SCROLL_SENSITIVE
可更新结果集模式
当并发模式指定为 时,应用程序可以直接在当前游标指向的行上修改列值缓冲区,或将游标移动到专门的“插入行(Insert Row)”缓冲区构建新记录,并由驱动在底层自动生成并发送对应的 ResultSet.CONCUR_UPDATABLEUPDATE、INSERT 或 DELETE 语句同步回数据库。
要使可更新结果集生效,执行的 SELECT 查询语句必须满足严格的语法限制:只能查询单张物理表(不能包含 JOIN 连接、分组 GROUP BY、DISTINCT 或聚合函数),且查询的字段列表中必须包含该表的主键列,否则驱动无法定位底层物理数据行,会将结果集静默降级为只读模式:
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
public class ScrollableUpdatableDemo {
public static void main(String[] args) {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
// 1. 可更新结果集的查询语句必须针对单表且包含主键列
String sql = "SELECT id, username, balance FROM t_user";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
// 2. 创建支持双向滚动且可同步更新的 PreparedStatement
PreparedStatement pstmt = conn.prepareStatement(
sql,
ResultSet.TYPE_SCROLL_INSENSITIVE,
ResultSet.CONCUR_UPDATABLE);
ResultSet rs = pstmt.executeQuery()) {
// 3. 将游标直接跳转到最后一行,并读取当前行号以获取结果集总行数
if (rs.last()) {
System.out.println("结果集总行数: " + rs.getRow());
}
// 4. 将游标绝对定位到第 1 行,修改当前行的 balance 列缓冲区并同步回数据库
if (rs.absolute(1)) {
rs.updateDouble("balance", 2500.00);
rs.updateRow();
System.out.println("第 1 行更新后余额: " + rs.getDouble("balance"));
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}全量缓冲与流式读取机制+
在处理包含百万级记录的大表导出或全表扫描任务时,理解 JDBC 驱动底层如何从网络套接字(Socket)读取并缓存 ResultSet 数据至关重要,不当的默认配置极易导致生产环境发生 JVM 堆内存溢出(OutOfMemoryError)。

默认全量内存缓冲
以 MySQL 驱动(mysql-connector-j)为例,在默认配置下,当应用程序调用 executeQuery 时,驱动并不会等待后续调用 rs.next() 时才去网络流中按行读取数据,而是會在 executeQuery 方法内部阻塞,一次性将数据库服务端返回的所有匹配行全部从 TCP Socket 缓冲区读出,反序列化封装进 JVM 堆内存的 ArrayList(即 ResultSetRowsStatic)中。
这意味着在 executeQuery 返回 ResultSet 实例的那一刻,全量结果数据已经完全驻留在 JVM 堆内存中,后续调用 rs.next() 仅仅是在移动内存集合的数组下标。如果单次查询命中了数百万行数据,JVM 堆内存会在 executeQuery 执行期间被瞬间撑爆并抛出 OutOfMemoryError: Java heap space。
客户端流式逐行读取
当需要将海量数据流式导出且不希望占用大量 JVM 内存时,可以启用 MySQL 驱动的流式结果集():将结果集模式设为 ResultSetRowsStreamingTYPE_FORWARD_ONLY 与 CONCUR_READ_ONLY,并将语句对象的 fetchSize 显式设置为特殊标志值 Integer.MIN_VALUE。
开启流式读取后,executeQuery 仅读取响应头元数据即刻返回,每次调用 rs.next() 时驱动才从底层 Socket 输入流中按需读取下一行数据。但需注意其核心边界约束:在流式结果集的所有数据行被全部读完或显式调用 rs.close() 之前,当前 Connection 的底层 TCP 通道处于持续占用状态,期间严禁复用该连接执行任何其他 SQL 语句,否则会触发流冲突异常。
服务端游标分批拉取
若希望按固定批次大小(如每次 500 或 1000 行)分段从数据库拉取数据,在 MySQL 中仅调用 setFetchSize(500) 默认是无效的(驱动会直接忽略正数 fetchSize 并退回全量内存缓冲)。必须同时在 JDBC URL 中配置 useCursorFetch=true(底层会自动开启服务端预编译 useServerPrepStmts=true),然后再设置正数的 fetchSize。
在此模式下,MySQL 服务端在执行查询后会将结果暂存在服务端临时表(服务端游标)中。每当客户端消费完本地批次的 500 行数据并继续调用 rs.next() 时,驱动会自动向服务端发送 COM_STMT_FETCH 二进制指令拉取下一批 500 行记录,从而在内存安全与网络吞吐量之间取得平衡:
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
public class StreamingResultSetDemo {
public static void main(String[] args) {
// 1. 若使用服务端游标分批拉取,需在 URL 中配置 useCursorFetch=true
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&useCursorFetch=true";
String sql = "SELECT id, username, balance FROM t_user";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
// 2. 显式指定单向只读结果集模式
PreparedStatement pstmt = conn.prepareStatement(
sql,
ResultSet.TYPE_FORWARD_ONLY,
ResultSet.CONCUR_READ_ONLY)) {
// 3. 设置每次从服务端游标批量拉取 500 行(若设为 Integer.MIN_VALUE 则开启逐行流式读取)
pstmt.setFetchSize(500);
// 4. 按批次流式遍历海量结果集,避免单次全量加载引发 JVM 堆内存溢出
try (ResultSet rs = pstmt.executeQuery()) {
while (rs.next()) {
System.out.println(rs.getInt(1) + " - " + rs.getString(2));
}
}
} catch (SQLException e) {
e.printStackTrace();
}
}
}API: ResultSet
游标定位
final intResultSet.TYPE_FORWARD_ONLY:仅向前滚动常量。常量值为1003,标识结果集游标仅支持从首行向末行单向顺序调用next()推进,不支持反向或随机跳行定位。final intResultSet.TYPE_SCROLL_INSENSITIVE:双向滚动不敏感常量。常量值为1004,标识结果集支持双向滚动与随机定位,但底层数据通常为静态快照,对其他事务在结果集打开期间提交的数据更改不敏感。final intResultSet.TYPE_SCROLL_SENSITIVE:双向滚动敏感常量。常量值为1005,标识结果集支持双向滚动与随机定位,且能够动态感知并反映底层数据库在结果集打开期间发生的数据变更。final intResultSet.FETCH_FORWARD:正向预取方向常量。常量值为1000,向驱动提示结果集行数据将按从首行到末行的正向顺序处理。final intResultSet.FETCH_REVERSE:反向预取方向常量。常量值为1001,向驱动提示结果集行数据将按从末行到首行的反向顺序处理。final intResultSet.FETCH_UNKNOWN:未知预取方向常量。常量值为1002,表示结果集行数据的处理顺序未知。booleannext():(),游标下移一行。将当前游标从当前位置向下移动一行(初始位于第一行之前,首次调用移至第一行);若移动后指向有效数据行则返回true,若已越过最后一行则返回false。booleanprevious():(),游标上移一行。将游标从当前位置向上回退一行;若移动后位于有效数据行则返回true,若已退至第一行之前则返回false。booleanfirst():(),游标移至首行。将游标直接移动到当前ResultSet的第一行数据;若结果集包含数据则返回true,若结果集为空则返回false。booleanlast():(),游标移至末行。将游标直接移动到当前ResultSet的最后一行数据;若结果集非空则返回true,否则返回false。voidbeforeFirst():(),游标移至首行前。将游标重置到结果集的第一行之前(初始位置);若结果集为空则该方法不产生任何效果。voidafterLast():(),游标移至末行后。将游标移动到结果集的最后一行之后;若结果集为空则该方法不产生任何效果。booleanabsolute():(int row),游标绝对行号定位。将游标直接定位到指定的行号row(正数表示从首行1开始正向计数,负数表示从末行-1开始倒数计数,0表示移至首行之前);指向有效行时返回true。booleanrelative():(int rows),游标相对行数偏移。相对于当前游标所在行正向(正数)或反向(负数)偏移指定的行数rows;传入0时游标保持原地不动。booleanisBeforeFirst():(),首行前位置判断。判断游标当前是否位于结果集的第一行之前;对于空结果集固定返回false。booleanisAfterLast():(),末行后位置判断。判断游标当前是否位于结果集的最后一行之后;对于空结果集固定返回false。booleanisFirst():(),首行位置判断。判断游标当前是否正好指向结果集的第一行数据。booleanisLast():(),末行位置判断。判断游标当前是否正好指向结果集的最后一行数据。intgetRow():(),当前行号获取。获取游标当前指向的数据行编号(从1开始计数);若游标位于首行之前、末行之后或结果集为空,则返回0。voidsetFetchDirection():(int direction),结果集预取方向设置。向 JDBC 驱动提供性能提示,指定当前ResultSet后续遍历行数据的主要方向。intgetFetchDirection():(),结果集预取方向获取。获取当前ResultSet实例生效的数据预取方向常量。voidsetFetchSize():(int rows),网络预取行数设置。设置当前ResultSet每次需要更多数据时从数据库通过网络批量拉取的行数(设为0则交由驱动自行决定)。intgetFetchSize():(),网络预取行数获取。返回当前ResultSet配置的单次网络预取行数。
注意事项:
- 默认创建的
ResultSet类型为TYPE_FORWARD_ONLY,此时仅允许调用next()向下推进游标;若调用previous()、first()、last()、absolute()等反向或随机定位方法,将抛出SQLException。- 在单向滚动结果集中调用
isLast()可能触发驱动预先读取下一行数据以判断当前行是否为末尾,在大结果集流式处理场景下应直接依赖while (rs.next())的返回值控制循环。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class ResultSetCursorDemo {
// 1. 演示可滚动结果集的创建、游标绝对与相对定位及边界状态判断
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement(
ResultSet.TYPE_SCROLL_INSENSITIVE,
ResultSet.CONCUR_READ_ONLY);
ResultSet rs = stmt.executeQuery("SELECT id, username FROM t_user")) {
// 2. 配置结果集预取方向与单次网络预取行数
rs.setFetchDirection(ResultSet.FETCH_FORWARD);
rs.setFetchSize(20);
// 3. 将游标直接跳至最后一行并获取当前行号
if (rs.last()) {
System.out.println("末行行号: " + rs.getRow() + ", 是否末行: " + rs.isLast());
}
// 4. 使用绝对定位与相对偏移移动游标并重置至首行之前
if (rs.absolute(1)) {
System.out.println("首行用户: " + rs.getString("username"));
}
rs.relative(1);
rs.beforeFirst();
System.out.println("是否重置回首行之前: " + rs.isBeforeFirst());
}
}
}数据读取
getObject():通用对象与泛型类型读取。将当前行指定列的值读取为默认映射的 Java
Object,或按指定的Class<T>(如LocalDateTime.class)强类型转换返回。Object:(int columnIndex),按列索引读取默认对象。根据列索引返回遵循 JDBC 标准类型映射关系的 Java 对象。Object:(String columnLabel),按列标签读取默认对象。根据列标签返回遵循标准类型映射关系的 Java 对象。<T> T:(int columnIndex, Class<T> type),按列索引与泛型类型读取。根据列索引读取列值并直接转换为type指定的目标 Java 类型实例(无需强制类型转换)。<T> T:(String columnLabel, Class<T> type),按列标签与泛型类型读取。根据列标签读取列值并直接转换为type指定的目标 Java 类型实例。Object:(int columnIndex, Map<String, Class<?>> map),按列索引与自定义类型表读取。使用给定的自定义类型映射字典map解析列索引对应的 SQL 结构化值。Object:(String columnLabel, Map<String, Class<?>> map),按列标签与自定义类型表读取。使用给定的自定义类型映射字典map解析列标签对应的 SQL 结构化值。
intfindColumn():(String columnLabel),列名转列索引。将给定的结果集列标签(或列名)映射为对应的1起始列索引编号;若未找到匹配列名则抛出SQLException。booleanwasNull():(),空值读取状态检测。报告当前行最近一次通过getXxx方法读取的列值在数据库中是否为SQL NULL;若是则返回true,否则返回false。getString():字符串列值读取。以 Java
String形式提取当前行指定列的值(适用于CHAR、VARCHAR、TEXT等字符类型);若数据库值为SQL NULL则返回null。String:(int columnIndex),按列索引读取字符串。根据从1开始的列序号读取字符串值。String:(String columnLabel),按列标签读取字符串。根据 SQL 查询结果的列别名或字段名读取字符串值。
getNString():国家字符集字符串读取(过时)。以 Java
String形式读取NCHAR、NVARCHAR或LONGNVARCHAR类型的国家字符集列值。String:(int columnIndex),按列索引读取国家字符串。根据列索引读取国家字符集字符串。String:(String columnLabel),按列标签读取国家字符串。根据列标签读取国家字符集字符串。
getBoolean():布尔型列值读取。以
boolean形式读取当前行指定列的值;若列值为SQL NULL、数值0或字符串"false",则返回false。boolean:(int columnIndex),按列索引读取布尔值。根据列索引读取boolean值。boolean:(String columnLabel),按列标签读取布尔值。根据列标签读取boolean值。
getByte():字节整数列值读取。以
byte形式读取当前行指定列的值;若列值为SQL NULL则返回0。byte:(int columnIndex),按列索引读取单字节整数。根据列索引读取byte值。byte:(String columnLabel),按列标签读取单字节整数。根据列标签读取byte值。
getShort():短整型列值读取。以
short形式读取当前行指定列的值;若列值为SQL NULL则返回0。short:(int columnIndex),按列索引读取短整数。根据列索引读取short值。short:(String columnLabel),按列标签读取短整数。根据列标签读取short值。
getInt():整型列值读取。以
int形式读取当前行指定列的值;若列值为SQL NULL则返回0。int:(int columnIndex),按列索引读取整数。根据列索引读取int值。int:(String columnLabel),按列标签读取整数。根据列标签读取int值。
getLong():长整型列值读取。以
long形式读取当前行指定列的值(适用于BIGINT主键列);若列值为SQL NULL则返回0L。long:(int columnIndex),按列索引读取长整数。根据列索引读取long值。long:(String columnLabel),按列标签读取长整数。根据列标签读取long值。
getFloat():单精度浮点列值读取。以
float形式读取当前行指定列的值;若列值为SQL NULL则返回0.0f。float:(int columnIndex),按列索引读取单精度浮点数。根据列索引读取float值。float:(String columnLabel),按列标签读取单精度浮点数。根据列标签读取float值。
getDouble():双精度浮点列值读取。以
double形式读取当前行指定列的值;若列值为SQL NULL则返回0.0d。double:(int columnIndex),按列索引读取双精度浮点数。根据列索引读取double值。double:(String columnLabel),按列标签读取双精度浮点数。根据列标签读取double值。
getBigDecimal():高精度十进制列值读取。以全精度
BigDecimal形式读取当前行指定列的值(适用于DECIMAL、NUMERIC金额字段);若列值为SQL NULL则返回null。BigDecimal:(int columnIndex),按列索引读取高精度十进制数。根据列索引读取完整精度的BigDecimal对象。BigDecimal:(String columnLabel),按列标签读取高精度十进制数。根据列标签读取完整精度的BigDecimal对象。
getBytes():字节数组列值读取。以
byte[]形式读取当前行指定列的原始二进制字节数组;若列值为SQL NULL则返回null。byte[]:(int columnIndex),按列索引读取字节数组。根据列索引读取byte[]数组。byte[]:(String columnLabel),按列标签读取字节数组。根据列标签读取byte[]数组。
getDate():日期列值读取。以
java.sql.Date形式读取当前行指定列的日期值;支持传入Calendar指定时区转换规则。Date:(int columnIndex),按列索引读取日期。使用 JVM 默认时区根据列索引读取日期对象。Date:(String columnLabel),按列标签读取日期。使用 JVM 默认时区根据列标签读取日期对象。Date:(int columnIndex, Calendar cal),按列索引与日历时区读取日期。当底层数据库未存储时区信息时,使用给定Calendar的时区构造Date对象。Date:(String columnLabel, Calendar cal),按列标签与日历时区读取日期。使用给定Calendar的时区根据列标签构造Date对象。
getTime():时间列值读取。以
java.sql.Time形式读取当前行指定列的时间值;支持传入Calendar指定时区转换规则。Time:(int columnIndex),按列索引读取时间。使用默认时区根据列索引读取时间对象。Time:(String columnLabel),按列标签读取时间。使用默认时区根据列标签读取时间对象。Time:(int columnIndex, Calendar cal),按列索引与日历时区读取时间。结合给定Calendar的时区根据列索引构造Time对象。Time:(String columnLabel, Calendar cal),按列标签与日历时区读取时间。结合给定Calendar的时区根据列标签构造Time对象。
getTimestamp():时间戳列值读取。以
java.sql.Timestamp形式读取当前行指定列的日期时间戳值;支持传入Calendar指定时区转换规则。Timestamp:(int columnIndex),按列索引读取时间戳。使用默认时区根据列索引读取时间戳对象。Timestamp:(String columnLabel),按列标签读取时间戳。使用默认时区根据列标签读取时间戳对象。Timestamp:(int columnIndex, Calendar cal),按列索引与日历时区读取时间戳。结合给定Calendar的时区根据列索引构造Timestamp对象。Timestamp:(String columnLabel, Calendar cal),按列标签与日历时区读取时间戳。结合给定Calendar的时区根据列标签构造Timestamp对象。
getCharacterStream():字符流列值读取。以
java.io.Reader字符输入流形式流式读取当前行指定列的大文本内容。Reader:(int columnIndex),按列索引读取字符流。根据列索引获取Reader字符流。Reader:(String columnLabel),按列标签读取字符流。根据列标签获取Reader字符流。
getNCharacterStream():国家字符集流读取。以
Reader字符输入流形式流式读取NCHAR、NVARCHAR、NCLOB列的内容。Reader:(int columnIndex),按列索引读取国家字符流。根据列索引获取国家字符集Reader流。Reader:(String columnLabel),按列标签读取国家字符流。根据列标签获取国家字符集Reader流。
getAsciiStream():ASCII 字节流读取。以单字节 ASCII
InputStream流的形式读取当前行指定列的字符数据。InputStream:(int columnIndex),按列索引读取 ASCII 流。根据列索引获取 ASCII 字节输入流。InputStream:(String columnLabel),按列标签读取 ASCII 流。根据列标签获取 ASCII 字节输入流。
getBinaryStream():二进制字节流读取。以未加工的
InputStream二进制输入流形式读取当前行指定列的二进制字节数据。InputStream:(int columnIndex),按列索引读取二进制流。根据列索引获取二进制InputStream。InputStream:(String columnLabel),按列标签读取二进制流。根据列标签获取二进制InputStream。
getBlob():二进制大对象读取。以
Blob接口实例形式读取当前行指定列的二进制大对象定位器。Blob:(int columnIndex),按列索引读取 Blob。根据列索引获取Blob对象。Blob:(String columnLabel),按列标签读取 Blob。根据列标签获取Blob对象。
getClob():字符大对象读取。以
Clob接口实例形式读取当前行指定列的字符大对象定位器。Clob:(int columnIndex),按列索引读取 Clob。根据列索引获取Clob对象。Clob:(String columnLabel),按列标签读取 Clob。根据列标签获取Clob对象。
getNClob():国家字符大对象读取。以
NClob接口实例形式读取当前行指定列的国家字符集大对象。NClob:(int columnIndex),按列索引读取 NClob。根据列索引获取NClob对象。NClob:(String columnLabel),按列标签读取 NClob。根据列标签获取NClob对象。
getSQLXML():XML 对象读取。以
SQLXML接口实例形式读取当前行指定列的数据库原生 XML 数据。SQLXML:(int columnIndex),按列索引读取 SQLXML。根据列索引获取SQLXML对象。SQLXML:(String columnLabel),按列标签读取 SQLXML。根据列标签获取SQLXML对象。
getArray():SQL 数组列值读取。以
java.sql.Array实例形式读取当前行指定列的 SQLARRAY数组类型数据。Array:(int columnIndex),按列索引读取 Array。根据列索引获取 SQLArray对象。Array:(String columnLabel),按列标签读取 Array。根据列标签获取 SQLArray对象。
getRef():SQL 引用列值读取。以
Ref实例形式读取当前行指定列的 SQLREF结构化类型引用。Ref:(int columnIndex),按列索引读取 Ref。根据列索引获取Ref引用对象。Ref:(String columnLabel),按列标签读取 Ref。根据列标签获取Ref引用对象。
getURL():URL 列值读取。以
java.net.URL实例形式读取当前行指定列的DATALINK或链接文本值。URL:(int columnIndex),按列索引读取 URL。根据列索引解析并返回URL对象。URL:(String columnLabel),按列标签读取 URL。根据列标签解析并返回URL对象。
getRowId():物理行标识符读取。以
RowId实例形式读取当前行指定列的数据库底层行地址标识符。RowId:(int columnIndex),按列索引读取 RowId。根据列索引获取RowId对象。RowId:(String columnLabel),按列标签读取 RowId。根据列标签获取RowId对象。
注意事项:
- JDBC 的列索引
columnIndex严格从1开始计数(而非0);传入columnLabel时,若 SQL 查询中为字段指定了AS别名,则必须传入对应的列别名。- 当数据库字段值为
SQL NULL时,getInt()、getDouble()、getBoolean()等基本数据类型方法会返回零值(0、0.0、false);若业务需要区分真实零值与NULL,必须在读取后立即调用wasNull(),或直接使用getObject(columnLabel, Integer.class)读取为可空包装类型。
import java.math.BigDecimal;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class ResultSetReadDemo {
// 1. 演示按列名或列索引提取字段值、空值检测与泛型类型映射
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT id, username, balance FROM t_user")) {
// 2. 将字段名解析为对应的列索引编号(从 1 开始)
int balanceIdx = rs.findColumn("balance");
// 3. 向下移动游标并按列索引、列名及泛型 Class 读取列值
while (rs.next()) {
int id = rs.getInt(1);
String username = rs.getString("username");
BigDecimal balance = rs.getObject(balanceIdx, BigDecimal.class);
// 4. 检测最近一次读取的列值在数据库中是否为 SQL NULL
if (rs.wasNull()) {
System.out.println("用户 " + username + " 的余额字段为 NULL");
} else {
System.out.println(id + " - " + username + " - " + balance);
}
}
}
}
}行级更新
final intResultSet.CONCUR_READ_ONLY:只读并发模式常量。常量值为1007,标识当前ResultSet对象仅支持读取数据,禁止通过结果集直接修改底层表数据。final intResultSet.CONCUR_UPDATABLE:可更新并发模式常量。常量值为1008,标识当前ResultSet对象支持通过updateXxx、updateRow、insertRow、deleteRow原位增删改底层表数据。voidmoveToInsertRow():(),游标移至插入缓冲区。记住当前游标所在行位置,并将游标切换到专用于构建新数据行的特殊缓冲区“插入行(Insert Row)”。voidmoveToCurrentRow():(),游标返回原先数据行。当游标当前位于“插入行”缓冲区时,将其恢复到调用moveToInsertRow()之前所指向的正常数据行。voidinsertRow():(),提交插入缓冲区新行。将“插入行”缓冲区中已通过updateXxx填充完毕的整行数据正式写入结果集与底层数据库中(仅当游标位于插入行时可调用)。voidupdateRow():(),提交当前行修改。将当前数据行中通过updateXxx修改的列缓冲区内容正式发送并同步至底层数据库。voiddeleteRow():(),删除当前数据行。从当前ResultSet结果集以及底层数据库表中同步删除游标当前指向的数据行(不可在插入行上调用)。voidrefreshRow():(),重读刷新当前行。从数据库重新拉取当前行的最新数据以覆盖结果集本地行缓存。voidcancelRowUpdates():(),撤销当前行未提交修改。回退当前行通过updateXxx写入本地缓冲区但尚未调用updateRow()提交的所有列修改;若已调用过updateRow()则该方法无效。booleanrowUpdated():(),当前行已更新检测。判断当前行是否已被更新(取决于数据库与结果集类型能否检测到自身或外部更新)。booleanrowInserted():(),当前行属新增检测。判断当前行是否为结果集打开期间新插入的行。booleanrowDeleted():(),当前行已删除检测。判断当前行是否已被删除并在结果集中留有空洞占位(Hole)。updateNull():置空指定列缓冲区。将当前行指定列的待更新值设置为
SQL NULL。void:(int columnIndex),按列索引置为 NULL。将指定列索引的缓冲区置为SQL NULL。void:(String columnLabel),按列标签置为 NULL。将指定列标签的缓冲区置为SQL NULL。
updateBoolean():更新布尔型列缓冲区。使用
boolean值更新当前行指定列的本地缓冲区。void:(int columnIndex, boolean x),按列索引更新布尔值。更新指定列索引的boolean值。void:(String columnLabel, boolean x),按列标签更新布尔值。更新指定列标签的boolean值。
updateByte():更新字节整数列缓冲区。使用
byte值更新当前行指定列的本地缓冲区。void:(int columnIndex, byte x),按列索引更新单字节整数。更新指定列索引的byte值。void:(String columnLabel, byte x),按列标签更新单字节整数。更新指定列标签的byte值。
updateShort():更新短整型列缓冲区。使用
short值更新当前行指定列的本地缓冲区。void:(int columnIndex, short x),按列索引更新短整数。更新指定列索引的short值。void:(String columnLabel, short x),按列标签更新短整数。更新指定列标签的short值。
updateInt():更新整型列缓冲区。使用
int值更新当前行指定列的本地缓冲区。void:(int columnIndex, int x),按列索引更新整数。更新指定列索引的int值。void:(String columnLabel, int x),按列标签更新整数。更新指定列标签的int值。
updateLong():更新长整型列缓冲区。使用
long值更新当前行指定列的本地缓冲区。void:(int columnIndex, long x),按列索引更新长整数。更新指定列索引的long值。void:(String columnLabel, long x),按列标签更新长整数。更新指定列标签的long值。
updateFloat():更新单精度浮点列缓冲区。使用
float值更新当前行指定列的本地缓冲区。void:(int columnIndex, float x),按列索引更新单精度浮点数。更新指定列索引的float值。void:(String columnLabel, float x),按列标签更新单精度浮点数。更新指定列标签的float值。
updateDouble():更新双精度浮点列缓冲区。使用
double值更新当前行指定列的本地缓冲区。void:(int columnIndex, double x),按列索引更新双精度浮点数。更新指定列索引的double值。void:(String columnLabel, double x),按列标签更新双精度浮点数。更新指定列标签的double值。
updateBigDecimal():更新高精度十进制列缓冲区。使用
BigDecimal对象更新当前行指定列的本地缓冲区。void:(int columnIndex, BigDecimal x),按列索引更新 BigDecimal。更新指定列索引的BigDecimal值。void:(String columnLabel, BigDecimal x),按列标签更新 BigDecimal。更新指定列标签的BigDecimal值。
updateString():更新字符串列缓冲区。使用
String值更新当前行指定列的本地缓冲区。void:(int columnIndex, String x),按列索引更新字符串。更新指定列索引的字符串值。void:(String columnLabel, String x),按列标签更新字符串。更新指定列标签的字符串值。
updateNString():更新国家字符集字符串列缓冲区。使用
String值更新NCHAR或NVARCHAR列的本地缓冲区。void:(int columnIndex, String nString),按列索引更新国家字符串。更新指定列索引的国家字符集字符串。void:(String columnLabel, String nString),按列标签更新国家字符串。更新指定列标签的国家字符集字符串。
updateBytes():更新字节数组列缓冲区。使用
byte[]数组更新当前行指定列的本地缓冲区。void:(int columnIndex, byte[] x),按列索引更新字节数组。更新指定列索引的字节数组。void:(String columnLabel, byte[] x),按列标签更新字节数组。更新指定列标签的字节数组。
updateDate():更新日期列缓冲区。使用
java.sql.Date值更新当前行指定列的本地缓冲区。void:(int columnIndex, Date x),按列索引更新日期。更新指定列索引的Date值。void:(String columnLabel, Date x),按列标签更新日期。更新指定列标签的Date值。
updateTime():更新时间列缓冲区。使用
java.sql.Time值更新当前行指定列的本地缓冲区。void:(int columnIndex, Time x),按列索引更新时间。更新指定列索引的Time值。void:(String columnLabel, Time x),按列标签更新时间。更新指定列标签的Time值。
updateTimestamp():更新时间戳列缓冲区。使用
java.sql.Timestamp值更新当前行指定列的本地缓冲区。void:(int columnIndex, Timestamp x),按列索引更新时间戳。更新指定列索引的Timestamp值。void:(String columnLabel, Timestamp x),按列标签更新时间戳。更新指定列标签的Timestamp值。
updateObject():更新通用对象列缓冲区。使用任意 Java
Object(及可选的目标SQLType与小数精度)更新当前行指定列的本地缓冲区。void:(int columnIndex, Object x),按列索引更新对象。将指定列索引更新为给定的Object值。void:(String columnLabel, Object x),按列标签更新对象。将指定列标签更新为给定的Object值。void:(int columnIndex, Object x, int scaleOrLength),按列索引与精度或流长度更新对象。指定十进制小数位数或输入流字节/字符长度更新列索引。void:(String columnLabel, Object x, int scaleOrLength),按列标签与精度或流长度更新对象。指定十进制小数位数或输入流长度更新列标签。void:(int columnIndex, Object x, SQLType targetSqlType),按列索引与目标 SQLType 更新。自 JDK 8 引入的default默认方法,显式指定目标SQLType更新列索引。void:(String columnLabel, Object x, SQLType targetSqlType),按列标签与目标 SQLType 更新。自 JDK 8 引入的default默认方法,显式指定目标SQLType更新列标签。void:(int columnIndex, Object x, SQLType targetSqlType, int scaleOrLength),按列索引、目标类型与精度更新。自 JDK 8 引入的default默认方法,同时指定目标SQLType与精度或长度更新列索引。void:(String columnLabel, Object x, SQLType targetSqlType, int scaleOrLength),按列标签、目标类型与精度更新。自 JDK 8 引入的default默认方法,同时指定目标SQLType与精度或长度更新列标签。
updateCharacterStream():更新字符流列缓冲区。使用
Reader字符输入流更新当前行指定列的本地缓冲区。void:(int columnIndex, Reader x),按列索引无长度更新字符流。根据列索引写入未知长度的字符流。void:(String columnLabel, Reader reader),按列标签无长度更新字符流。根据列标签写入未知长度的字符流。void:(int columnIndex, Reader x, int length),按列索引与 int 长度更新字符流。指定字符数int length更新列索引。void:(String columnLabel, Reader reader, int length),按列标签与 int 长度更新字符流。指定字符数int length更新列标签。void:(int columnIndex, Reader x, long length),按列索引与 long 长度更新字符流。指定字符数long length更新列索引。void:(String columnLabel, Reader reader, long length),按列标签与 long 长度更新字符流。指定字符数long length更新列标签。
updateNCharacterStream():更新国家字符集流列缓冲区。使用
Reader字符流更新当前行国家字符集列的本地缓冲区。void:(int columnIndex, Reader x),按列索引无长度更新国家字符流。根据列索引写入国家字符流。void:(String columnLabel, Reader reader),按列标签无长度更新国家字符流。根据列标签写入国家字符流。void:(int columnIndex, Reader x, long length),按列索引与 long 长度更新国家字符流。指定long型字符长度更新列索引。void:(String columnLabel, Reader reader, long length),按列标签与 long 长度更新国家字符流。指定long型字符长度更新列标签。
updateAsciiStream():更新 ASCII 流列缓冲区。使用 ASCII 字节流
InputStream更新当前行指定列的本地缓冲区。void:(int columnIndex, InputStream x),按列索引无长度更新 ASCII 流。根据列索引写入 ASCII 流。void:(String columnLabel, InputStream x),按列标签无长度更新 ASCII 流。根据列标签写入 ASCII 流。void:(int columnIndex, InputStream x, int length),按列索引与 int 长度更新 ASCII 流。指定int型字节长度更新列索引。void:(String columnLabel, InputStream x, int length),按列标签与 int 长度更新 ASCII 流。指定int型字节长度更新列标签。void:(int columnIndex, InputStream x, long length),按列索引与 long 长度更新 ASCII 流。指定long型字节长度更新列索引。void:(String columnLabel, InputStream x, long length),按列标签与 long 长度更新 ASCII 流。指定long型字节长度更新列标签。
updateBinaryStream():更新二进制流列缓冲区。使用二进制
InputStream更新当前行指定列的本地缓冲区。void:(int columnIndex, InputStream x),按列索引无长度更新二进制流。根据列索引写入二进制输入流。void:(String columnLabel, InputStream x),按列标签无长度更新二进制流。根据列标签写入二进制输入流。void:(int columnIndex, InputStream x, int length),按列索引与 int 长度更新二进制流。指定int型字节数更新列索引。void:(String columnLabel, InputStream x, int length),按列标签与 int 长度更新二进制流。指定int型字节数更新列标签。void:(int columnIndex, InputStream x, long length),按列索引与 long 长度更新二进制流。指定long型字节数更新列索引。void:(String columnLabel, InputStream x, long length),按列标签与 long 长度更新二进制流。指定long型字节数更新列标签。
updateBlob():更新二进制大对象列缓冲区。使用
Blob对象或二进制输入流InputStream更新当前行指定列的本地缓冲区。void:(int columnIndex, Blob x),按列索引更新 Blob 对象。使用Blob实例更新列索引。void:(String columnLabel, Blob x),按列标签更新 Blob 对象。使用Blob实例更新列标签。void:(int columnIndex, InputStream inputStream),按列索引以输入流更新 Blob。使用未知长度的InputStream更新列索引。void:(String columnLabel, InputStream inputStream),按列标签以输入流更新 Blob。使用未知长度的InputStream更新列标签。void:(int columnIndex, InputStream inputStream, long length),按列索引与流长度更新 Blob。指定long型字节数写入InputStream更新列索引。void:(String columnLabel, InputStream inputStream, long length),按列标签与流长度更新 Blob。指定long型字节数写入InputStream更新列标签。
updateClob():更新字符大对象列缓冲区。使用
Clob对象或Reader字符流更新当前行指定列的本地缓冲区。void:(int columnIndex, Clob x),按列索引更新 Clob 对象。使用Clob实例更新列索引。void:(String columnLabel, Clob x),按列标签更新 Clob 对象。使用Clob实例更新列标签。void:(int columnIndex, Reader reader),按列索引以字符流更新 Clob。使用Reader流更新列索引。void:(String columnLabel, Reader reader),按列标签以字符流更新 Clob。使用Reader流更新列标签。void:(int columnIndex, Reader reader, long length),按列索引与字符数更新 Clob。指定long型字符长度更新列索引。void:(String columnLabel, Reader reader, long length),按列标签与字符数更新 Clob。指定long型字符长度更新列标签。
updateNClob():更新国家字符大对象列缓冲区。使用
NClob对象或Reader流更新当前行国家字符集大对象列的本地缓冲区。void:(int columnIndex, NClob nClob),按列索引更新 NClob 对象。使用NClob实例更新列索引。void:(String columnLabel, NClob nClob),按列标签更新 NClob 对象。使用NClob实例更新列标签。void:(int columnIndex, Reader reader),按列索引以字符流更新 NClob。使用Reader流更新列索引。void:(String columnLabel, Reader reader),按列标签以字符流更新 NClob。使用Reader流更新列标签。void:(int columnIndex, Reader reader, long length),按列索引与字符数更新 NClob。指定long型字符长度更新列索引。void:(String columnLabel, Reader reader, long length),按列标签与字符数更新 NClob。指定long型字符长度更新列标签。
updateSQLXML():更新 XML 列缓冲区。使用
SQLXML实例更新当前行指定列的本地缓冲区。void:(int columnIndex, SQLXML xmlObject),按列索引更新 SQLXML。更新指定列索引的SQLXML对象。void:(String columnLabel, SQLXML xmlObject),按列标签更新 SQLXML。更新指定列标签的SQLXML对象。
updateArray():更新 SQL 数组列缓冲区。使用
java.sql.Array实例更新当前行指定列的本地缓冲区。void:(int columnIndex, Array x),按列索引更新 Array。更新指定列索引的 SQLArray对象。void:(String columnLabel, Array x),按列标签更新 Array。更新指定列标签的 SQLArray对象。
updateRef():更新 SQL 引用列缓冲区。使用
Ref实例更新当前行指定列的本地缓冲区。void:(int columnIndex, Ref x),按列索引更新 Ref。更新指定列索引的Ref对象。void:(String columnLabel, Ref x),按列标签更新 Ref。更新指定列标签的Ref对象。
updateRowId():更新物理行标识列缓冲区。使用
RowId实例更新当前行指定列的本地缓冲区。void:(int columnIndex, RowId x),按列索引更新 RowId。更新指定列索引的RowId对象。void:(String columnLabel, RowId x),按列标签更新 RowId。更新指定列标签的RowId对象。
注意事项:
- 仅当创建
Statement时显式指定并发模式为ResultSet.CONCUR_UPDATABLE,且 SQL 查询针对单表、未包含聚合函数或JOIN、并在SELECT列表中包含主键列时,ResultSet才支持原位行更新。- 调用
updateXxx()方法仅修改客户端当前行的内存缓冲区,不会直接触发数据库写操作;必须在修改完列值后显式调用updateRow()(更新现有行)或insertRow()(提交插入行),若在调用updateRow()前移动了游标,此前未提交的缓冲区修改将直接丢失。
import java.math.BigDecimal;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
public class ResultSetUpdateDemo {
// 1. 演示可更新结果集的原位行更新、新行插入与修改取消
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement(
ResultSet.TYPE_SCROLL_SENSITIVE,
ResultSet.CONCUR_UPDATABLE);
ResultSet rs = stmt.executeQuery("SELECT id, username, balance FROM t_user")) {
// 2. 定位到第一行,修改列缓冲区并调用 updateRow 同步至数据库
if (rs.first()) {
rs.updateBigDecimal("balance", new BigDecimal("1500.00"));
rs.updateRow();
}
// 3. 演示在调用 updateRow 前通过 cancelRowUpdates 回退本地列修改
if (rs.next()) {
rs.updateString("username", "TempName");
rs.cancelRowUpdates();
}
// 4. 移动至插入行缓冲区,填充列值并调用 insertRow 插入新记录
rs.moveToInsertRow();
rs.updateString("username", "Frank");
rs.updateDouble("balance", 650.00);
rs.insertRow();
rs.moveToCurrentRow();
}
}
}状态管理
final intResultSet.HOLD_CURSORS_OVER_COMMIT:跨事务提交保持游标常量。常量值为1,标识当所属连接调用Connection.commit()提交事务时,当前打开的ResultSet游标保持开启状态而不被关闭。final intResultSet.CLOSE_CURSORS_AT_COMMIT:事务提交时关闭游标常量。常量值为2,标识当所属连接调用Connection.commit()提交事务时,当前打开的ResultSet游标将被自动关闭。voidclose():(),结果集资源释放。立即释放当前ResultSet占用的数据库游标与客户端内存缓冲区资源;在已关闭的结果集上重复调用该方法为空操作。booleanisClosed():(),关闭状态检测。判断当前ResultSet对象是否已被显式或隐式关闭。ResultSetMetaDatagetMetaData():(),结果集列元数据获取。返回描述当前ResultSet列的编号、名称、数据类型与精度等结构信息的ResultSetMetaData对象。StatementgetStatement():(),所属语句对象获取。返回生成当前ResultSet结果集的父级Statement对象;若该结果集是由数据库元数据方法(如DatabaseMetaData.getTables)内部生成的,则可能返回null。intgetType():(),结果集滚动类型获取。返回当前ResultSet的滚动类型常量(如TYPE_FORWARD_ONLY、TYPE_SCROLL_INSENSITIVE或TYPE_SCROLL_SENSITIVE)。intgetConcurrency():(),结果集并发模式获取。返回当前ResultSet的并发修改模式常量(CONCUR_READ_ONLY或CONCUR_UPDATABLE)。intgetHoldability():(),游标保持策略获取。返回当前ResultSet在事务提交后的游标保持策略常量(HOLD_CURSORS_OVER_COMMIT或CLOSE_CURSORS_AT_COMMIT)。StringgetCursorName():(),底层游标名称获取。返回驱动或底层数据库赋予当前ResultSet的 SQL 游标名称,用于定位更新或删除语句。SQLWarninggetWarnings():(),结果集告警链获取。返回当前ResultSet上报告的第一个SQLWarning告警对象;无告警时返回null。voidclearWarnings():(),结果集告警清空。清空当前ResultSet对象上累积的所有SQLWarning告警链。
注意事项:
- 每次在
ResultSet上调用next()(或其他游标定位方法)移动到新行时,前一行读取过程中产生的SQLWarning告警会被自动清空;因此若需检查特定行的读取截断或精度告警,必须在移动至下一行之前调用getWarnings()。- 当创建该
ResultSet的父级Statement被关闭、重新执行新 SQL 或调用getMoreResults()切换到下一个结果时,当前ResultSet会被底层驱动自动关闭。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.SQLException;
import java.sql.Statement;
public class ResultSetLifecycleDemo {
// 1. 演示结果集元数据提取、自身属性查询与关闭状态检测
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement()) {
ResultSet rs = stmt.executeQuery("SELECT id, username, balance FROM t_user");
// 2. 获取结果集列结构元数据 ResultSetMetaData 与所属 Statement
ResultSetMetaData metaData = rs.getMetaData();
System.out.println("结果集列数: " + metaData.getColumnCount());
System.out.println("所属 Statement 是否一致: " + (rs.getStatement() == stmt));
// 3. 查询当前结果集的滚动类型、并发模式与事务提交游标保持策略
System.out.println("滚动类型: " + rs.getType()
+ ", 并发模式: " + rs.getConcurrency()
+ ", 保持策略: " + rs.getHoldability());
// 4. 清空告警并显式关闭结果集,验证关闭状态
rs.clearWarnings();
rs.close();
System.out.println("结果集是否已关闭: " + rs.isClosed());
}
}
}继承: Wrapper
isWrapperFor, unwrap
API: ResultSetMetaData
标识定位
intgetColumnCount():(),结果集总列数获取。返回当前ResultSet对象中包含的列总数;遍历列元数据时列索引从1开始直至该返回值。StringgetColumnName():(int column),物理列名获取。获取指定列在数据库表定义中的原始物理字段名称;若该列是由表达式或聚合函数计算生成且无物理列名,则返回空字符串。StringgetColumnLabel():(int column),列别名标签获取。获取用于打印输出或对象属性映射的推荐列标题;若 SQL 查询中通过AS为该列指定了别名,则返回该别名,否则返回原始物理列名。StringgetTableName():(int column),所属表名获取。返回指定列所属的数据库表名称;若该列为表达式计算列或无法追溯来源表,则返回空字符串""。StringgetCatalogName():(int column),所属目录名获取。返回指定列所属表所在的数据库目录(Catalog)名称;在 MySQL 中对应具体的数据库名(Database)。StringgetSchemaName():(int column),所属模式名获取。返回指定列所属表所在的数据库命名空间模式(Schema)名称;若底层数据库不支持 Schema 则返回空字符串""。
注意事项:
- 严格区分
getColumnName()与getColumnLabel():getColumnName()返回数据库表中的原始字段名(如user_name),而getColumnLabel()返回 SQL 语句中通过AS指定的别名(如SELECT user_name AS userName中的userName)。在编写通用反射结果集映射工具(如自定义BasicDAO或BeanUtils封装)时,必须始终调用getColumnLabel(),否则 SQL 别名将无法匹配 JavaBean 属性。- 所有接收
int column参数的方法,其列序号严格从1开始计数,传入0或超过getColumnCount()的值将直接抛出SQLException。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.SQLException;
import java.sql.Statement;
public class ResultSetMetaIdentityDemo {
// 1. 查询带 AS 别名的结果集并提取 ResultSetMetaData 实例
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String sql = "SELECT id AS userId, username AS userName FROM t_user";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
// 2. 获取结果集总列数并按从 1 开始的列索引遍历各列
ResultSetMetaData meta = rs.getMetaData();
int count = meta.getColumnCount();
for (int i = 1; i <= count; i++) {
// 3. 对比原始物理列名与 AS 列标签,并读取所属库名和表名
System.out.println("原始列名: " + meta.getColumnName(i)
+ ", 列别名标签: " + meta.getColumnLabel(i)
+ ", 所属表名: " + meta.getTableName(i)
+ ", 所属 Catalog: " + meta.getCatalogName(i)
+ ", 所属 Schema: " + meta.getSchemaName(i));
}
}
}
}类型规格
intgetColumnType():(int column),标准 SQL 类型码获取。返回指定列的 JDBC 标准 SQL 类型整型编码,对应java.sql.Types类中定义的静态常量(如Types.INTEGER、Types.VARCHAR)。StringgetColumnTypeName():(int column),数据库原生类型名获取。返回指定列在底层特定数据库方言中的原生数据类型名称字符串(例如 MySQL 中的"VARCHAR"、"DECIMAL"或"INT UNSIGNED")。StringgetColumnClassName():(int column),映射 Java 类全限定名获取。返回当调用ResultSet.getObject(int)读取该列时,JDBC 驱动默认实例化并返回的 Java 类的全限定名称(如"java.lang.Integer"、"java.math.BigDecimal")。intgetPrecision():(int column),列数据精度获取。返回指定列的大小或精度:对于数值型数据表示有效数字总位数,对于字符型数据表示最大字符长度,对于二进制数据表示最大字节长度。intgetScale():(int column),小数点后位数获取。返回指定列在小数点右边的数字位数(如DECIMAL(10, 2)返回2);对于整数、字符串或不支持小数标度的列类型默认返回0。intgetColumnDisplaySize():(int column),最大显示字符宽度获取。返回将指定列的值格式化为字符串展示时建议预留的正常最大字符宽度(常用于命令行表格对齐打印)。
注意事项:
- 在 MySQL 数据库中,当字段被定义为无符号整型(如
INT UNSIGNED)时,为防止正数范围溢出 Javaint上限,驱动的getColumnClassName()会自动升级映射为"java.lang.Long";同理,BIGINT UNSIGNED会升级映射为"java.math.BigInteger"。- 对于
BLOB、TEXT等超大变长大对象列,getPrecision()返回的是该类型在数据库中支持的最大理论上限字节数或字符数,而非当前行实际存储的数据长度。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.SQLException;
import java.sql.Statement;
public class ResultSetMetaTypeDemo {
// 1. 查询包含整型、字符串与定点小数的表结构元数据
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String sql = "SELECT id, username, balance FROM t_user";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
ResultSetMetaData meta = rs.getMetaData();
for (int i = 1; i <= meta.getColumnCount(); i++) {
// 2. 获取每一列的 JDBC 标准类型码、数据库原生类型名及映射的 Java 类名
System.out.println("列名: " + meta.getColumnLabel(i)
+ ", JDBC 类型码: " + meta.getColumnType(i)
+ ", 数据库类型名: " + meta.getColumnTypeName(i)
+ ", 映射 Java 类: " + meta.getColumnClassName(i));
// 3. 获取每一列的精度、小数位数及最大显示字符宽度
System.out.println("精度: " + meta.getPrecision(i)
+ ", 小数位数: " + meta.getScale(i)
+ ", 最大显示宽度: " + meta.getColumnDisplaySize(i));
}
}
}
}属性约束
final intResultSetMetaData.columnNoNulls:禁止空值常量。常量值为0,作为isNullable()的返回值,标识该列在数据库定义中受NOT NULL约束,不允许存储SQL NULL值。final intResultSetMetaData.columnNullable:允许空值常量。常量值为1,作为isNullable()的返回值,标识该列允许存储SQL NULL值。final intResultSetMetaData.columnNullableUnknown:空值约束未知常量。常量值为2,作为isNullable()的返回值,标识驱动无法判定该列是否允许为空(常见于复杂计算列或视图列)。intisNullable():(int column),空值约束状态检测。检索指定列是否允许存储SQL NULL值,返回值为columnNoNulls、columnNullable或columnNullableUnknown常量之一。booleanisAutoIncrement():(int column),自增列属性检测。判断指定列是否为数据库自动编号的递增列(如 MySQL 的AUTO_INCREMENT主键列),若是则通常在插入时无需显式赋值。booleanisSigned():(int column),带符号数值检测。判断指定列中的数值是否允许包含正负符号;对于无符号列(UNSIGNED)或非数值列返回false。booleanisCurrency():(int column),货币金额类型检测。判断指定列是否为数据库专用的现金货币数据类型(如 SQL Server 的MONEY类型)。booleanisCaseSensitive():(int column),大小写敏感检测。判断指定列的字符比较与排序规则(Collation)是否区分字母大小写。booleanisSearchable():(int column),条件检索支持检测。判断指定列是否允许出现在 SQL 语句的WHERE条件子句中进行过滤匹配。booleanisReadOnly():(int column),只读列状态检测。判断指定列是否绝对不可写入(例如常量计算列、聚合函数列或无写权限的视图列)。booleanisWritable():(int column),可写列可能性检测。判断针对指定列发起写操作在逻辑上是否有可能成功。booleanisDefinitelyWritable():(int column),确定可写状态检测。判断针对指定列发起的写操作是否确定能够成功落盘。
注意事项:
isNullable(int column)尽管以is开头,但其返回值类型是int而非boolean;判断某列是否允许为空时,必须将其返回值与ResultSetMetaData.columnNoNulls或columnNullable常量进行比较。- 在 MySQL 中,
VARCHAR列调用isCaseSensitive()的返回值取决于该列绑定的字符集排序规则(Collation):若使用默认的utf8mb4_0900_ai_ci或utf8mb4_general_ci(以_ci结尾表示大小写不敏感),则返回false;若使用_bin或_cs排序规则,则返回true。
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.SQLException;
import java.sql.Statement;
public class ResultSetMetaConstraintDemo {
// 1. 探测结果集首列(主键 id)的空值约束、自增属性与读写特征
public static void main(String[] args) throws SQLException {
String url = "jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC";
String sql = "SELECT id, username, balance FROM t_user";
try (Connection conn = DriverManager.getConnection(url, "root", "123456");
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(sql)) {
ResultSetMetaData meta = rs.getMetaData();
// 2. 检测第 1 列是否允许写入 NULL 值并与标准常量对比
int nullability = meta.isNullable(1);
boolean notNull = (nullability == ResultSetMetaData.columnNoNulls);
System.out.println("首列是否禁止为 NULL: " + notNull);
// 3. 探测首列的自增特性、正负符号支持及大小写敏感性
System.out.println("是否自增列: " + meta.isAutoIncrement(1)
+ ", 是否带符号数值: " + meta.isSigned(1)
+ ", 用户名是否大小写敏感: " + meta.isCaseSensitive(2));
// 4. 探测列的条件检索支持情况与只读、可写权限状态
System.out.println("是否可用于 WHERE 子句: " + meta.isSearchable(1)
+ ", 是否只读: " + meta.isReadOnly(1)
+ ", 是否可写: " + meta.isWritable(1));
}
}
}继承: Wrapper
isWrapperFor, unwrap
JDBCUtils 封装
在标准的 JDBC 操作流程中,每次执行增删改查都需要重复编写加载配置文件、获取数据库连接(Connection)以及在 finally 块中逐一判空释放资源(ResultSet、Statement、Connection)的样板代码。
通过将这些通用的生命周期管理逻辑抽离封装为自定义静态工具类,业务数据访问层(DAO)只需关注 SQL 编写与参数绑定。根据底层连接管理机制的演进,自定义工具类通常分为基于 DriverManager 的直连版本()与基于 JDBCUtilsDataSource 连接池的池化版本()。JDBCUtilsByDruid
核心设计要点
在设计自定义 JDBC 工具类时,主要围绕以下三个工程机制展开:
静态代码块单次初始化:配置文件的 I/O 读取、驱动类的反射加载或连接池(
DataSource)的创建均属于高开销操作,且在整个 JVM 进程生命周期内只需执行一次。将其放置在工具类的static {}静态代码块中,可确保在类首次被加载时自动完成单次初始化。受检异常转运行期异常:JDBC 原生 API 大量抛出编译期受检异常(
SQLException)与 IO 异常(IOException)。在工具类内部捕获这些受检异常后,将其包装转换为运行期非受检异常(throw new RuntimeException(e))向上抛出。这样调用方既可以选择显式捕获处理,也可以交由上层统一异常处理器兜底,避免在业务层方法签名上层层声明throws SQLException。统一逆序判空释放接口:对外提供统一的
close(ResultSet, Statement, Connection)静态方法,内部严格按照“先开后关”的逆序依次判空并释放资源。得益于多态机制,第二个形参声明为父接口Statement,因此调用方无论是传入静态Statement、预编译PreparedStatement还是存储过程CallableStatement均可直接兼容;若执行的是无结果集的 DML 语句,第一个参数直接传入null即可。
JDBCUtils
直连版工具类 基于 JDBCUtilsDriverManager 实现,每次调用 getConnection 都会新建一条物理数据库连接,调用 close 时则直接断开底层 TCP 物理连接。
mysql.properties
在类路径(src 或 resources 目录)下创建 mysql.properties 配置文件,集中维护数据库连接四要素:
# 1. 数据库连接账号与密码
user=root
password=123456
# 2. 数据库连接地址与驱动类全限定名
url=jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC
driver=com.mysql.cj.jdbc.DriverJDBCUtils
工具类内部通过四个静态属性保存连接参数,在 static 代码块中利用类加载器读取配置文件并加载驱动,对外暴露静态的 getConnection 与 close 方法:
package com.hspedu.jdbc.utils;
import java.io.InputStream;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.Properties;
// 1. 封装基于 DriverManager 的数据库直连与资源释放工具类
public class JDBCUtils {
// 2. 定义静态属性保存数据库连接四要素,全局仅需一份
private static String user;
private static String password;
private static String url;
private static String driver;
// 3. 在静态代码块中完成配置文件读取与驱动类加载初始化
static {
try {
Properties properties = new Properties();
InputStream is = JDBCUtils.class.getClassLoader().getResourceAsStream("mysql.properties");
properties.load(is);
user = properties.getProperty("user");
password = properties.getProperty("password");
url = properties.getProperty("url");
driver = properties.getProperty("driver");
Class.forName(driver);
} catch (Exception e) {
// 4. 将编译期受检异常转换为运行期异常抛出,调用方无需强制捕获
throw new RuntimeException(e);
}
}
// 5. 获取并返回底层物理数据库连接
public static Connection getConnection() {
try {
return DriverManager.getConnection(url, user, password);
} catch (SQLException e) {
throw new RuntimeException(e);
}
}
// 6. 按先开后关的逆序统一释放数据库资源,无某个资源时传入 null 即可
public static void close(ResultSet set, Statement statement, Connection connection) {
try {
if (set != null) {
set.close();
}
if (statement != null) {
statement.close();
}
if (connection != null) {
connection.close();
}
} catch (SQLException e) {
throw new RuntimeException(e);
}
}
}调用示例
使用封装后的 JDBCUtils 执行 DML 更新与 DQL 查询操作,大幅精简了获取连接与 finally 块中的关闭模板代码:
package com.hspedu.jdbc.utils;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
public class JDBCUtilsUseDemo {
// 1. 使用 JDBCUtils 执行 DML 更新操作
public static void testDML() {
Connection conn = null;
PreparedStatement pstmt = null;
String sql = "UPDATE t_user SET balance = ? WHERE username = ?";
try {
// 2. 通过工具类一行代码获取连接,省去重复配置加载
conn = JDBCUtils.getConnection();
pstmt = conn.prepareStatement(sql);
pstmt.setDouble(1, 3000.00);
pstmt.setString(2, "Alice");
pstmt.executeUpdate();
} catch (SQLException e) {
throw new RuntimeException(e);
} finally {
// 3. DML 操作未产生结果集,首个参数直接传入 null 释放资源
JDBCUtils.close(null, pstmt, conn);
}
}
// 4. 使用 JDBCUtils 执行 DQL 查询操作
public static void testDQL() {
Connection conn = null;
PreparedStatement pstmt = null;
ResultSet rs = null;
String sql = "SELECT id, username, balance FROM t_user WHERE id = ?";
try {
conn = JDBCUtils.getConnection();
pstmt = conn.prepareStatement(sql);
pstmt.setInt(1, 1);
rs = pstmt.executeQuery();
while (rs.next()) {
System.out.println(rs.getInt("id") + " - " + rs.getString("username"));
}
} catch (SQLException e) {
throw new RuntimeException(e);
} finally {
// 5. DQL 操作按逆序统一关闭 ResultSet、PreparedStatement 与 Connection
JDBCUtils.close(rs, pstmt, conn);
}