Skip to content

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),并将数据库服务端返回的字节流解析封装为标准结果集对象。

image-20261030224942098

示例: 模拟 JDBC ​

为了直观理解 JDBC 的解耦思想,可以通过 myjdbc 的四段核心代码模拟“Java 官方标准接口”、“数据库厂商驱动实现”与“Java 应用程序调用”三方之间的协作关系。

1. JdbcInterface

模拟 Java 官方制定的 JDBC 标准接口,仅声明获取连接、执行增删改查和关闭连接的统一方法签名,不包含任何特定数据库的底层实现:

java
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 底层协议的具体连接与操作逻辑:

java
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 接口,使不同厂商的驱动在调用层面保持完全一致的形态:

java
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 时,只需替换实例化的驱动对象,后续所有的业务调用代码均无需改动:

java
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 并插入初始数据:

sql
-- 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 包:

  1. 拷贝驱动包:在项目根目录下新建 lib(或 libs)目录,将下载的驱动文件(如 mysql-connector-j-8.3.0.jar)复制到该目录下。

  2. 添加至类路径:在 IDE(如 IntelliJ IDEA)中右键点击该 lib 目录或驱动 Jar 包,选择 Add as Library... 将其加入到当前模块的编译与运行类路径中。

Maven 坐标引入 ​

若使用 Maven 构建项目,只需在 pom.xml 中添加 mysql-connector-j 坐标依赖,由 Maven 自动下载并管理类路径:

xml
<!-- 引入 MySQL 8.x JDBC 驱动依赖 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.3.0</version>
</dependency>

标准执行流程 ​

使用 JDBC 操作关系型数据库遵循固定的五步标准流程:

  1. 注册并加载驱动:将数据库厂商的 Driver 实现类加载到内存中,向 DriverManager 完成注册(自 JDBC 4.0 起支持通过 SPI 自动加载,无需手动编写 Class.forName)。

  2. 获取数据库连接:调用 DriverManager.getConnection 方法,传入数据库新连接地址(URL)、用户名与密码,获取 Connection 连接实例。

  3. 创建 SQL 语句执行对象:调用 Connection 对象的 createStatement 或 prepareStatement 方法,获取用于发送 SQL 的执行对象。

  4. 执行 SQL 并处理结果:调用 executeUpdate 执行增删改(DML)或建表(DDL)语句并获取受影响行数;或调用 executeQuery 执行查询(DQL)语句,通过 ResultSet 游标遍历提取字段值。

  5. 释放数据库资源:数据库底层连接、游标与语句缓冲区均属于昂贵的外部系统资源,使用完毕后必须按“先开后关”的逆序(ResultSet → Statement → Connection)显式关闭。

image-20261030225005777

手动释放资源 ​

在传统的异常处理结构中,为了确保发生 SQLException 时底层连接依然能够被正常回收,必须在 finally 代码块中逐一判空并关闭资源:

java
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 方法,大幅简化资源释放模板代码:

java
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 ​

java.sql.DriverManager 是 JDBC 规范提供的驱动管理核心类,充当管理所有数据库驱动(java.sql.Driver)并创建数据库连接(java.sql.Connection)的工厂组件。

在内部实现中,DriverManager 维护了一个线程安全的 CopyOnWriteArrayList<DriverInfo> 静态集合(registeredDrivers),用于存储当前 JVM 中已注册的所有驱动实例。当应用程序请求建立连接时,DriverManager 会遍历该集合,寻找能够识别目标数据库 URL 的驱动并委托其创建底层物理连接。

Driver.connect ​

在不借助 DriverManager 管理器的情况下,最底层的方式是直接实例化数据库厂商提供的 Driver 实现类(或通过反射 Class.forName 动态创建实例),将数据库账号与密码封装在 Properties 集合中,直接调用 driver.connect(url, info) 方法获取连接:

java
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 完成注册:

java
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 的方式,原因有二:

  1. 编译期硬编码耦合:代码中直接 import 了 com.mysql.cj.jdbc.Driver,导致业务代码在编译期强依赖特定数据库驱动包;若切换数据库,必须修改 Java 源码并重新编译。

  2. 重复注册两次驱动:查看 com.mysql.cj.jdbc.Driver 的源码可以发现,其类内部的 static 静态代码块已经调用了一次 DriverManager.registerDriver。当外部执行 new Driver() 时,类加载初始化会先触发一次静态代码块注册,随后外部方法调用又会注册第二个 Driver 实例:

    java
    package 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.forName 加载驱动类的全限定名。Class.forName 默认会将目标类加载到内存并执行类初始化(即触发 com.mysql.cj.jdbc.Driver 中的 static 静态代码块),从而仅完成一次驱动注册,且类名字符串可以抽取到外部配置文件中读取:

java
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 即可直接获取连接:

image-20261031103751088

java
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 配置文件中需转义为 &amp;):

  • 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)。其底层驱动匹配与连接创建逻辑如下:

java
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 子协议是否匹配:

  1. 协议不匹配:若当前遍历到的是 PostgreSQL 驱动,而传入的是 jdbc:mysql:...,则 connect 方法不会抛出异常,而是直接返回 null,DriverManager 继续遍历下一个驱动。

  2. 协议匹配:若当前驱动能够识别该 URL,则向目标数据库发起 TCP 握手与身份认证,认证成功后返回创建的 Connection 对象并终止循环。

  3. 全部不匹配:若遍历完 registeredDrivers 中所有驱动均返回 null,则最终抛出 SQLException: No suitable driver found for ...(常见于未引入驱动 Jar 包或 JDBC URL 协议头拼写错误)。

image-20261031103848432

Properties ​

调用 getConnection(String url, Properties info) 时,开发者可以将数据库用户名(固定键名 user)、密码(固定键名 password)以及其他驱动级连接属性统一封装在 java.util.Properties 对象中传入,适合从外部 .properties 配置文件直接加载连接信息的场景:

java
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 动态读取以消除硬编码:

ini
# src/jdbc.properties
url=jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC
user=root
password=123456
connectTimeout=3000
java
import 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 方法执行:

java
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 ​

构造方法 ​

  • Driver Driver():(),驱动实例构造。创建数据库驱动实现类实例,用于直接发起底层数据库连接或向 DriverManager 注册驱动。

注意事项:

  1. java.sql.Driver 本身为标准接口,实际代码中调用的 new Driver() 属于各数据库厂商提供的具体驱动实现类(如 MySQL 的 com.mysql.cj.jdbc.Driver)。
  2. com.mysql.cj.jdbc.Driver 的无参构造方法声明抛出了 SQLException,且在其类加载阶段会通过 static 静态代码块自动调用 DriverManager.registerDriver(new Driver()) 完成注册。
java
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);
  }
}

连接建立 ​

  • boolean acceptsURL():(String url),URL 协议校验。判断当前数据库驱动是否能够识别并打开指定格式的 JDBC URL;若协议头匹配则返回 true,否则返回 false。

  • Connection connect():(String url, Properties info),物理连接创建。使用给定的 JDBC URL 和包含认证及配置参数的 Properties 集合尝试建立数据库连接;若当前驱动不支持该 URL 协议,则直接返回 null 而非抛出异常。

  • DriverPropertyInfo[] getPropertyInfo():(String url, Properties info),连接属性探测。解析给定的 URL 与初始属性集合,返回连接目标数据库可配置的完整属性元数据数组,供可视化数据库客户端工具动态生成连接配置表单。

注意事项:

  1. 当传入的 url 不属于当前驱动支持的协议时,connect() 按规范必须返回 null 而不是抛出 SQLException;只有当驱动识别了该 URL 但因网络故障或凭证错误导致建连失败时,才会抛出 SQLException。
  2. 实际业务开发中通常通过 DriverManager.getConnection() 间接调用驱动,但直接实例化特定厂商的 Driver 实现类并调用 connect() 也是完全合法的底层连接获取方式。
java
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);
    }
  }
}

驱动元数据 ​

  • int getMajorVersion():(),主版本号获取。返回当前数据库驱动的主版本号(例如 MySQL Connector/J 8.3.0 返回 8)。

  • int getMinorVersion():(),次版本号获取。返回当前数据库驱动的次版本号(例如 MySQL Connector/J 8.3.0 返回 3)。

  • boolean jdbcCompliant():(),规范兼容性检测。标识当前驱动是否完全通过了官方 JDBC 兼容性测试并完整支持 SQL-92 Entry Level 标准;仅当完全达标时返回 true。

  • Logger getParentLogger():(),根日志器获取。返回当前驱动所使用的所有 JUL(java.util.logging.Logger)日志记录器的父级根日志器;若驱动未使用 JUL 日志体系,则抛出 SQLFeatureNotSupportedException。

注意事项:

  1. 主流数据库驱动(如 MySQL 的 com.mysql.cj.jdbc.Driver)因底层 SQL 方言差异且未默认绑定 java.util.logging 日志体系,调用 jdbcCompliant() 会固定返回 false,调用 getParentLogger() 会抛出 SQLFeatureNotSupportedException。
java
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() 回调方法。
  • void DriverManager.deregisterDriver():(Driver driver),数据库驱动注销。从 DriverManager 的已注册驱动列表中移除指定的驱动实例;出于类加载器隔离安全考虑,仅允许注销由当前调用方类加载器所加载的驱动。

  • Driver DriverManager.getDriver():(String url),协议匹配驱动获取。遍历当前已注册的驱动列表,查找并返回第一个调用 acceptsURL(url) 返回 true 的 Driver 实例;若无任何驱动匹配则抛出 SQLException。

  • Enumeration<Driver> DriverManager.getDrivers():(),已注册驱动枚举。返回当前调用方类加载器有权限访问的所有已注册 JDBC 驱动的 Enumeration 枚举器。

  • Stream<Driver> DriverManager.drivers():(),已注册驱动流获取。返回当前调用方类加载器可访问的所有已注册 JDBC 驱动的顺序流(Stream),自 JDK 9 引入以替代传统的 Enumeration 遍历。

注意事项:

  1. DriverManager 的构造方法被 private 修饰,无法通过 new DriverManager() 实例化,所有功能均通过静态方法对外提供。
  2. 在 Web 容器(如 Tomcat)中,若应用 WEB-INF/lib 下引入了数据库驱动,应在应用停止(ServletContextListener.contextDestroyed)时主动调用 DriverManager.deregisterDriver() 注销驱动,否则系统类加载器中的 DriverManager 强引用应用类加载器创建的 Driver,会导致 Web 应用卸载时发生 ClassLoader 内存泄漏。
java
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 查询参数中的场景。

注意事项:

  1. 三个重载方法在底层最终都会汇总调用私有方法 getConnection(String url, Properties info, Class<?> caller)。
  2. 当遍历完所有已注册驱动后,connect() 均返回 null(即没有任何驱动能够识别该 URL 协议头),getConnection() 会抛出异常信息为 No suitable driver found for ... 的 SQLException。
java
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);
    }
  }
}

全局配置 ​

  • void DriverManager.setLoginTimeout():(int seconds),连接超时设置。设置驱动尝试连接数据库服务器时允许等待的最大秒数;设为 0 表示无超时限制。

  • int DriverManager.getLoginTimeout():(),连接超时获取。获取当前驱动建立数据库连接所允许的最大等待秒数。

  • void DriverManager.setLogWriter():(PrintWriter out),日志字符流设置。设置 DriverManager 和所有驱动共用的全局日志追踪字符输出流;传入 null 将禁用全局 JDBC 日志记录。

  • PrintWriter DriverManager.getLogWriter():(),日志字符流获取。返回当前全局配置的 JDBC 日志追踪字符输出流 PrintWriter。

  • void DriverManager.println():(String message),日志消息打印。若当前已通过 setLogWriter 配置了全局日志流,则向该流中输出一行指定的追踪消息并自动刷新缓冲区。

注意事项:

  1. 早期基于字节流的 setLogStream(PrintStream) 与 getLogStream() 方法已标记为 @Deprecated 废弃,应当统一使用字符流版本的 setLogWriter() 与 getLogWriter()。
java
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 实例。
  • String nativeSQL():(String sql),原生方言语法转换。将包含标准 JDBC 转义语法(如 {fn ...}、{d ...})的 SQL 字符串翻译为底层目标数据库的原生 SQL 方言字符串并返回。

注意事项:

  1. 除非业务明确需要双向滚动或直接通过结果集更新数据,否则应优先使用无参 createStatement() 或单参数 prepareStatement(String sql),避免因开启高级游标特性带来额外的数据库内存与性能开销。
  2. MySQL 驱动默认在客户端模拟预编译,若需开启真正的数据库服务端预编译,需在 JDBC URL 中显式添加 useServerPrepStmts=true 参数。
java
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 int Connection.TRANSACTION_NONE:不支持事务常量。常量值为 0,标识当前底层数据源不支持事务机制。

  • final int Connection.TRANSACTION_READ_UNCOMMITTED:读未提交隔离常量。常量值为 1,允许读取其他事务尚未提交的脏数据,无法避免脏读、不可重复读与幻读。

  • final int Connection.TRANSACTION_READ_COMMITTED:读已提交隔离常量。常量值为 2,仅允许读取其他事务已提交的数据,可避免脏读,但仍可能出现不可重复读与幻读(Oracle、PostgreSQL 默认级别)。

  • final int Connection.TRANSACTION_REPEATABLE_READ:可重复读隔离常量。常量值为 4,保证同一事务内多次读取同一行记录的结果一致,可避免脏读与不可重复读(MySQL InnoDB 默认级别)。

  • final int Connection.TRANSACTION_SERIALIZABLE:串行化隔离常量。常量值为 8,最高事务隔离级别,强制事务串行执行以彻底规避脏读、不可重复读与幻读,但并发性能最低。

  • void setAutoCommit():(boolean autoCommit),自动提交模式设置。开启或关闭当前连接的事务自动提交模式;设为 false 时将开启手动事务,后续 DML 操作需显式调用 commit() 才会持久化。

  • boolean getAutoCommit():(),自动提交状态获取。检索当前 Connection 对象是否处于事务自动提交模式(新创建的连接默认返回 true)。

  • void commit():(),事务正式提交。使自上次提交或回滚以来在当前事务中执行的所有数据更改永久生效,并释放当前 Connection 持有的数据库锁。

  • rollback():事务数据回滚。撤销当前事务中的全部更改,或局部回滚至指定的事务保存点(Savepoint)。

    • void:(),全量事务回滚。撤销当前事务中的所有未提交更改,并释放当前连接持有的所有数据库锁,只能在 autoCommit 为 false 时调用。
    • void:(Savepoint savepoint),保存点局部回滚。撤销在设置给定 Savepoint 保存点之后执行的所有数据更改,保留该保存点之前的事务操作。
  • void setTransactionIsolation():(int level),事务隔离级别设置。将当前连接的事务隔离级别修改为指定的 Connection.TRANSACTION_* 常量值。

  • int getTransactionIsolation():(),事务隔离级别获取。获取当前连接会话正在生效的事务隔离级别常量值。

  • setSavepoint():事务保存点创建。在当前手动事务内部设置一个回滚标记点,以便后续通过 rollback(Savepoint) 实现细粒度的局部事务回滚。

    • Savepoint:(),匿名保存点创建。在当前事务中创建一个未命名的保存点并返回代表该节点的 Savepoint 实例。
    • Savepoint:(String name),命名保存点创建。在当前事务中创建一个具有指定名称的保存点并返回对应的 Savepoint 实例。
  • void releaseSavepoint():(Savepoint savepoint),事务保存点释放。从当前事务中移除指定的 Savepoint 保存点对象;释放后若再次针对该保存点执行回滚将抛出 SQLException。

注意事项:

  1. 当连接处于自动提交模式(getAutoCommit() == true)时,直接调用 commit()、rollback() 或 setSavepoint() 均会抛出 SQLException。
  2. 若在未完成手动事务期间调用 setAutoCommit(true) 切换回自动提交模式,JDBC 规范要求底层驱动自动将该连接上挂起的事务立即提交。
java
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;
      }
    }
  }
}

会话配置 ​

  • DatabaseMetaData getMetaData():(),数据库元数据获取。返回封装了底层数据库产品信息、驱动版本、表结构定义及功能支持情况的 DatabaseMetaData 对象。

  • void setReadOnly():(boolean readOnly),只读会话模式设置。将当前连接设置为只读模式,作为驱动与数据库启用只读查询优化或路由至只读从库的提示。

  • boolean isReadOnly():(),只读会话状态查询。判断当前 Connection 对象是否处于只读模式。

  • void setCatalog():(String catalog),数据库目录设置。设置当前连接操作的子数据库(Catalog)名称;在 MySQL 中对应切换具体的 Database。

  • String getCatalog():(),数据库目录获取。获取当前连接正在生效的 Catalog 名称。

  • void setSchema():(String schema),数据库模式设置。设置当前连接默认访问的命名空间模式(Schema)名称。

  • String getSchema():(),数据库模式获取。获取当前连接正在生效的 Schema 名称。

  • void setHoldability():(int holdability),游标保持策略设置。修改当前连接创建的 ResultSet 在调用 commit() 提交事务后的默认游标保持策略(HOLD_CURSORS_OVER_COMMIT 或 CLOSE_CURSORS_AT_COMMIT)。

  • int getHoldability():(),游标保持策略获取。获取当前连接默认的 ResultSet 游标保持性常量。

  • setClientInfo():客户端元数据写入。向连接会话写入客户端上下文信息(如应用名称、主机名、调用方用户),便于数据库服务端在会话监控视图或审计日志中追踪连接来源。

    • void:(String name, String value),单属性元数据设置。按指定的属性名与属性值设置单条客户端追踪信息,失败时抛出 SQLClientInfoException。
    • void:(Properties properties),集合元数据批量替换。使用给定的 Properties 集合完整替换当前连接的全部客户端属性,未包含在集合中的已有属性将被清空。
  • getClientInfo():客户端元数据读取。读取当前连接已配置的客户端追踪属性。

    • String:(String name),按名称读取客户端属性。返回指定客户端信息属性名称对应的字符串值。
    • Properties:(),读取全部客户端属性。返回包含当前连接所有受支持客户端信息键值对的 Properties 集合。
  • void setTypeMap():(Map<String, Class<?>> map),自定义类型映射设置。安装自定义 SQL 结构化类型(UDT)名称与 Java SQLData 实现类之间的映射字典表。

  • Map<String, Class<?>> getTypeMap():(),自定义类型映射获取。获取当前连接绑定的 SQL 自定义类型映射表 Map。

注意事项:

  1. setReadOnly(boolean) 不能在事务执行中途调用,必须在事务开启前切换,否则会抛出 SQLException。
  2. 在 MySQL 中,Catalog 等价于数据库名(Database),而 getSchema() 默认返回 null;在 PostgreSQL 或 Oracle 中,则主要通过 Schema 区分同一实例下的不同逻辑命名空间。
java
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"));
    }
  }
}

类型工厂 ​

  • Clob createClob():(),字符大对象创建。创建并返回一个初始为空的 Clob(Character Large Object)实例,用于向数据库写入超长文本数据。

  • Blob createBlob():(),二进制大对象创建。创建并返回一个初始为空的 Blob(Binary Large Object)实例,用于向数据库写入二进制字节数组或流数据。

  • NClob createNClob():(),国家字符集大对象创建。创建并返回一个初始为空的 NClob 实例,用于存储基于国家字符集(如 UTF-16/Unicode)的大文本数据。

  • SQLXML createSQLXML():(),XML 类型对象创建。创建并返回一个初始为空的 SQLXML 实例,用于读写数据库原生的 XML 字段类型。

  • Array createArrayOf():(String typeName, Object[] elements),SQL 数组对象创建。将给定的 Java 对象数组封装为对应数据库元素类型名称 typeName 的 java.sql.Array 实例。

  • Struct createStruct():(String typeName, Object[] attributes),SQL 结构体对象创建。使用给定的属性数组创建映射数据库指定自定义复合类型 typeName 的 Struct 实例。

注意事项:

  1. 通过工厂方法创建的 Clob、Blob、NClob 与 SQLXML 对象在内存中持有数据缓冲区,使用完毕后应主动调用其 free() 方法释放底层资源。
  2. MySQL 数据库原生不支持 SQL 标准数组与複合结构体类型,因此在 MySQL 驱动上调用 createArrayOf() 或 createStruct() 会直接抛出 SQLFeatureNotSupportedException。
java
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();
    }
  }
}

状态管理 ​

  • void close():(),物理连接关闭。立即释放当前 Connection 对象的数据库会话与底层 JDBC 资源(若是由连接池代理的 Connection,则将其归还至连接池中复用)。

  • boolean isClosed():(),连接关闭状态判断。检查当前 Connection 对象是否已被调用 close() 关闭;该判断仅检查本地状态标记,不能用于探测网络异常断开。

  • boolean isValid():(int timeout),连接存活探测。向数据库发送轻量级探测包(如 MySQL PING 命令)以验证连接是否真实有效;参数 timeout 指定等待验证响应的最大秒数(0 表示不限制)。

  • void abort():(Executor executor),连接强制终止。使用给定的异步线程池 Executor 强制终止并销毁出现挂起或死锁的物理连接,即使当前连接正在执行 SQL 操作也会立即标记为关闭。

  • void setNetworkTimeout():(Executor executor, int milliseconds),网络读写超时设置。设置当前连接等待数据库网络 I/O 响应的最大毫秒数;超时触发后将由传入的 Executor 异步关闭该连接。

  • int getNetworkTimeout():(),网络读写超时获取。返回当前连接配置的底层 Socket 等待响应的最大毫秒数。

  • SQLWarning getWarnings():(),连接告警链获取。返回当前连接会话上报告的第一个 SQLWarning 告警对象;后续告警可通过 SQLWarning.getNextWarning() 链式遍历。

  • void clearWarnings():(),连接告警清空。清除当前 Connection 对象上累积的所有 SQLWarning 告警记录。

  • void beginRequest():(),请求边界开启。自 JDK 9 引入的 default 默认方法,向驱动提示一个独立业务请求工作单元的开始,供连接池或驱动执行会话级初始化与状态绑定。

  • void endRequest():(),请求边界结束。自 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。

注意事项:

  1. 永远不要使用 !conn.isClosed() 来校验连接池中的连接是否可用,因为当数据库服务端主动断开空闲连接或网络闪断时,客户端未调用过 close(),isClosed() 依然返回 false;必须调用 conn.isValid(timeout) 发起实际网络探测。
  2. 在已经关闭的 Connection 上重复调用 close() 方法是幂等安全的(空操作),不会抛出异常。
java
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 ​

java.sql.Statement 是 JDBC 中用于向数据库发送静态 SQL 语句并获取执行结果的基础接口,由 Connection 实例调用 createStatement 方法创建。

在底层通信层面,Statement 对应数据库的纯文本传输协议(如 MySQL 的 COM_QUERY 文本协议包)。它不具备参数占位与预编译能力,所有动态条件都必须在 Java 内存中预先拼接成完整的 SQL 字符串,再一次性发送给数据库服务端解析执行。

静态文本协议执行 ​

当应用程序通过 Statement 发送一条 SQL 字符串时,JDBC 驱动不会对 SQL 的语法结构进行拆解,而是直接将该字符串编码为字节流封装进网络报文,通过 TCP 连接原样发送给数据库服务端。

服务端解析流程 ​

数据库服务端接收到完整的 SQL 文本后,必须依次执行以下四个标准阶段才能完成响应:

  1. 词法与语法分析:解析器(Parser) 对传入的 SQL 字符串进行分词,识别出关键字(如 SELECT、WHERE)、表名、列名与字面量参数,校验语法规则并构建抽象语法树(AST)。

  2. 语义与权限检查:预处理器检查语法树中引用的表和列在数据字典中是否真实存在,并验证当前连接账户是否具备相应的表级或列级操作权限。

  3. 生成执行计划:查询优化器(Optimizer) 基于统计信息计算不同索引路径与连接顺序的访问成本(CBO),为当前语法树选出最优的物理执行计划。

  4. 引擎调用与结果封装:执行器(Executor) 按照生成的执行计划调用底层存储引擎读写数据。若是增删改(DML)或结构定义(DDL)操作,服务端向驱动返回受影响行数数据包(OK Packet);若是查询(DQL)操作,服务端将匹配的记录行流式返回给驱动,由驱动封装为 ResultSet 对象。

静态 SQL 执行示例 ​

对于不含外部动态参数、结构完全固定的 DDL 建表语句或静态数据操作,可直接通过 Statement 发送执行:

java
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 异常:

image-20261031104026779

java
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)的逻辑分支结构:

sql
-- 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。

image-20261031104100996

登录绕过攻击演示 ​

下面通过模拟登录认证场景,展示攻击者如何在不知道任何真实账号密码的情况下,利用 Statement 字符串拼接漏洞绕过身份校验:

java
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 与内存开销:

  1. 执行编译缓存失效:现代关系型数据库(如 Oracle 的 Shared Pool、PostgreSQL 的计划缓存)通常会以 SQL 文本的哈希值作为 Key 缓存已编译的执行计划(软解析)。当使用 Statement 将不同参数值直接拼入 SQL(如依次执行 SELECT * FROM t_user WHERE id = 1 与 SELECT * FROM t_user WHERE id = 2)时,每条 SQL 文本的字面内容完全不同,数据库将其视为全新的语句,缓存命中率降为零。

  2. 高频硬解析与缓存污染:每次参数变化都会迫使数据库重新进行词法解析、语法树构建与优化器成本计算(即硬解析 Hard Parse),大量消耗数据库服务端 CPU 资源;同时成千上万条仅字面量不同的一次性执行计划会迅速填满共享池内存,将真正高频复用的核心 SQL 执行计划驱逐出缓存。

因此,在生产级开发规范中,凡是涉及动态参数传入的 SQL 语句,严禁使用 Statement 进行字符串拼接,必须统一使用预编译接口 PreparedStatement。

API: Statement ​

语句执行 ​

  • final int Statement.RETURN_GENERATED_KEYS:返回自增主键常量。常量值为 1,指示驱动在执行 INSERT 语句后检索数据库自动生成的主键值,以供后续调用 getGeneratedKeys() 获取。

  • final int Statement.NO_GENERATED_KEYS:忽略自增主键常量。常量值为 2,指示驱动在执行更新语句后无需采集数据库自动生成的主键信息。

  • ResultSet executeQuery():(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 语句并指定需返回自增值的列名称数组。
  • ResultSet getGeneratedKeys():(),自增主键结果集获取。获取执行此 Statement 对象后由数据库自动生成的所有主键值组成的 ResultSet 对象;若未生成任何键则返回空的 ResultSet。

注意事项:

  1. 同一个 Statement 实例在同一时刻默认只能打开一个 ResultSet 对象;若直接调用该 Statement 执行下一条 SQL,前一个尚未关闭的 ResultSet 会被底层驱动隐式关闭。
  2. Statement 直接拼接 SQL 字符串极易引发 SQL 注入风险,且无法复用预编译执行计划;凡是涉及外部传入参数的 SQL,均应改用子接口 PreparedStatement。
java
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 int Statement.SUCCESS_NO_INFO:未知行数成功常量。常量值为 -2,作为 executeBatch() 返回数组中的元素值,表示该条批处理指令已执行成功,但底层驱动无法获知其具体受影响的行数。

  • final int Statement.EXECUTE_FAILED:批处理执行失败常量。常量值为 -3,作为 executeBatch() 或 BatchUpdateException.getUpdateCounts() 数组中的元素值,表示该条批处理指令执行失败(仅在驱动遇到错误后仍继续执行后续批处理指令时出现)。

  • void addBatch():(String sql),批处理指令追加。将给定的静态 DML 或 DDL 语句添加到当前 Statement 对象的本地批处理命令列表中(严禁添加返回结果集的 SELECT 语句)。

  • void clearBatch():(),批处理队列清空。清空当前 Statement 对象本地批处理命令列表中已缓存的所有 SQL 语句。

  • int[] executeBatch():(),批量指令提交执行。将当前批处理队列中的所有 SQL 命令一次性提交给数据库执行;若全部执行成功,则按添加顺序返回每条命令对应的更新计数数组。

  • long[] executeLargeBatch():(),大行数批量提交执行。自 JDK 8 引入的 default 默认方法,当批处理中单条语句受影响行数可能超过 Integer.MAX_VALUE 时调用,返回 long[] 类型的更新计数数组。

注意事项:

  1. 执行批量插入或更新时,建议先调用 conn.setAutoCommit(false) 关闭自动提交,待 executeBatch() 完成后再统一调用 conn.commit(),从而避免每条语句单独开启和提交事务带来的磁盘刷盘开销。
  2. 若批处理队列中某一条语句执行失败,驱动会抛出 BatchUpdateException(SQLException 的子类),可通过调用该异常对象的 getUpdateCounts() 方法排查异常发生前各语句的执行状态。
java
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 int Statement.CLOSE_CURRENT_RESULT:关闭当前结果集常量。常量值为 1,传递给 getMoreResults(int) 时,指示驱动在移动到下一个结果时自动关闭当前打开的 ResultSet 对象。

  • final int Statement.KEEP_CURRENT_RESULT:保留当前结果集常量。常量值为 2,传递给 getMoreResults(int) 时,指示驱动在移动到下一个结果时不关闭当前打开的 ResultSet 对象。

  • final int Statement.CLOSE_ALL_RESULTS:关闭历史结果集常量。常量值为 3,传递给 getMoreResults(int) 时,指示驱动在移动到下一个结果时一次性关闭此前通过 KEEP_CURRENT_RESULT 保留的所有已打开 ResultSet 对象。

  • ResultSet getResultSet():(),当前结果集提取。以 ResultSet 对象的形式获取 execute() 执行后的当前结果;若当前结果是一个更新计数或已无更多结果,则返回 null(每个结果只能调用一次该方法)。

  • int getUpdateCount():(),当前更新计数提取。以 int 行数的形式获取 execute() 执行后的当前结果;若当前结果是一个 ResultSet 对象或已无更多结果,则返回 -1(每个结果只能调用一次该方法)。

  • long getLargeUpdateCount():(),当前大行数计数提取。自 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。

注意事项:

  1. 判断多结果集是否全部遍历完毕的标准终止条件为:((stmt.getMoreResults() == false) && (stmt.getUpdateCount() == -1))。
  2. MySQL 驱动默认禁止在一次 execute() 调用中用分号分隔执行多条 SQL 语句;若需使用多语句混合执行与多结果集遍历,必须在 JDBC URL 中显式开启 allowMultiQueries=true。
java
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);
      }
    }
  }
}

执行参数配置 ​

  • void setQueryTimeout():(int seconds),语句执行超时设置。设置驱动等待單条 SQL 语句执行完成的最大秒数(设为 0 表示不限制);若超出该时间仍未完成,将抛出 SQLTimeoutException。

  • int getQueryTimeout():(),语句执行超时获取。返回当前配置的等待 SQL 执行完成的最大秒数。

  • void setMaxRows():(int max),结果集最大行数设置。设置此 Statement 生成的任何 ResultSet 对象最多可包含的记录行数上限(设为 0 表示不限制),超出上限的行将被静默丢弃。

  • int getMaxRows():(),结果集最大行数获取。获取当前 Statement 生成的结果集所允许的最大记录行数。

  • void setLargeMaxRows():(long max),超大结果集行数上限设置。自 JDK 8 引入的 default 默认方法,设置结果集允许包含的最大行数上限(支持超过 Integer.MAX_VALUE 的 long 值)。

  • long getLargeMaxRows():(),超大结果集行数上限获取。自 JDK 8 引入的 default 默认方法,返回当前配置的结果集最大行数上限(long 类型)。

  • void setMaxFieldSize():(int max),单列最大字节数设置。设置结果集中单个字符或二进制列值允许返回的最大字节数限制(仅适用于 BINARY、VARBINARY、CHAR、VARCHAR 等类型,设为 0 表示不限制)。

  • int getMaxFieldSize():(),单列最大字节数获取。获取当前针对单列返回值所限制的最大字节数。

  • void setFetchSize():(int rows),网络预取行数设置。向 JDBC 驱动提供性能提示,指定当 ResultSet 需要更多行数据时每次从数据库服务器批量抓取的行数。

  • int getFetchSize():(),网络预取行数获取。返回当前配置的每次从数据库抓取的结果集行数。

  • void setFetchDirection():(int direction),游标抓取方向设置。向驱动提示后续处理 ResultSet 数据行的遍历方向(可选值为 ResultSet.FETCH_FORWARD、FETCH_REVERSE 或 FETCH_UNKNOWN)。

  • int getFetchDirection():(),游标抓取方向获取。获取当前配置的默认结果集行抓取方向常量。

  • int getResultSetType():(),结果集滚动类型获取。返回由此 Statement 对象生成的 ResultSet 的滚动类型常量(如 ResultSet.TYPE_FORWARD_ONLY)。

  • int getResultSetConcurrency():(),结果集并发模式获取。返回由此 Statement 对象生成的 ResultSet 的并发修改模式常量(如 ResultSet.CONCUR_READ_ONLY)。

  • int getResultSetHoldability():(),结果集游标保持性获取。返回由此 Statement 对象生成的 ResultSet 在事务提交后的游标保持策略常量。

  • void setEscapeProcessing():(boolean enable),转义语法扫描开关。启用或禁用驱动在将 SQL 发送至数据库之前的标准 JDBC 转义语法({...})解析器(默认开启)。

  • void setCursorName():(String name),定位更新游标命名。设置后续 executeQuery 生成的结果集所使用的底层 SQL 游标名称,用于配合 WHERE CURRENT OF <cursorName> 执行定位更新或删除。

  • String enquoteLiteral():(String val),字符串字面量转义封装。自 JDK 9 引入的 default 默认方法,将传入的字符串用单引号包裹,并自动将内部包含的所有单引号转义为双单引号(''),防止静态 SQL 拼接语法错误或注入。

  • String enquoteIdentifier():(String identifier, boolean alwaysQuote),数据库标识符转义封装。自 JDK 9 引入的 default 默认方法,校验并返回合法的 SQL 标识符(如动态表名或列名),根据 alwaysQuote 参数或特殊字符情况自动包裹双引号。

  • String enquoteNCharLiteral():(String val),国家字符集字面量转义。自 JDK 9 引入的 default 默认方法,将传入的字符串转换为符合 SQL 标准的国家字符集字面量格式(即 N'...')并转义内部单引号。

  • boolean isSimpleIdentifier():(String identifier),简单标识符校验。自 JDK 9 引入的 default 默认方法,判断给定的字符串是否为无需引号包裹的标准简单 SQL 标识符(仅由字母开头并包含字母、数字和下划线)。

注意事项:

  1. MySQL 驱动在默认情况下执行 executeQuery() 时会将整个查询结果集一次性全部读入客户端内存中;当查询百万级大表为防止 OOM 内存溢出时,必须调用 stmt.setFetchSize(Integer.MIN_VALUE) 开启流式结果集逐行读取,或在连接 URL 中配置 useCursorFetch=true 后再设置正整数的 fetchSize。
  2. enquoteIdentifier() 与 enquoteLiteral() 对于无法使用 ? 占位符的动态表名、动态 ORDER BY 列名等场景非常实用,能够有效阻断标识符层面的 SQL 注入。
java
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);
    }
  }
}

生命周期管理 ​

  • void close():(),语句对象关闭。立即释放当前 Statement 对象的数据库游标与底层 JDBC 资源,并同时隐式关闭由该对象打开的所有 ResultSet 结果集。

  • boolean isClosed():(),关闭状态判断。检查当前 Statement 对象是否已被调用 close() 关闭。

  • void cancel():(),异步中断执行。当另一个线程正在执行该 Statement 的耗时 SQL 时,可由监控线程调用此方法向数据库服务端发送中断请求以取消正在运行的 SQL 语句。

  • void closeOnCompletion():(),结果集联动关闭开启。自 JDK 7 引入,声明当此 Statement 生成的所有依赖 ResultSet 对象全部被关闭时,自动触发关闭当前 Statement 对象。

  • boolean isCloseOnCompletion():(),联动关闭状态查询。判断当前 Statement 是否已启用当结果集关闭时自动随之关闭的联动策略。

  • void setPoolable():(boolean poolable),语句池化状态设置。向语句池(Statement Pool)管理器提供提示,指定当前语句对象是否允许被缓存复用(Statement 默认为 false,PreparedStatement 默认为 true)。

  • boolean isPoolable():(),语句池化状态获取。返回当前 Statement 对象是否具备可池化缓存标记。

  • Connection getConnection():(),所属连接对象获取。返回创建了当前 Statement 实例的父级 Connection 连接对象。

  • SQLWarning getWarnings():(),语句执行告警获取。获取当前 Statement 执行期间数据库报告的第一个 SQLWarning 告警对象;每次执行新 SQL 时会自动清空上一次的告警。

  • void clearWarnings():(),语句执行告警清空。显式清除当前 Statement 对象上记录的所有 SQLWarning 告警链。

注意事项:

  1. 当方法需要将查询得到的 ResultSet 直接作为返回值交给上层调用者遍历时,不能在方法内部使用 try-with-resources 关闭 Statement(否则返回的 ResultSet 会立刻失效);此时应在返回前调用 stmt.closeOnCompletion(),这样当上层调用者关闭 ResultSet 时,底层的 Statement 便会自动随之关闭。
  2. cancel() 方法要求底层驱动和目标数据库同时支持异步网络取消指令,且必须从不同于正在执行 SQL 的另一个独立线程发起调用。
java
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.PreparedStatement 是 Statement 接口的子接口,表示预编译的 SQL 语句对象。

与 Statement 在执行阶段才传入完整 SQL 字符串不同,PreparedStatement 在创建阶段就需要将带有问号(?)参数占位符的 SQL 模板提交给驱动或数据库服务端,待参数值按类型逐个绑定到对应占位符后,再触发语句执行。它从机制上解决了动态 SQL 拼接引发的 SQL 注入漏洞与高频硬解析开销。

参数化防注入机制 ​

PreparedStatement 能够防御 SQL 注入的核心在于实现了“SQL 语法结构(代码)”与“动态参数值(数据)”在解析周期上的严格分离。

语法树固化与类型转义 ​

当使用 ? 占位符编写 SQL 模板时,无论是采用服务端二进制预编译还是客户端模拟预编译,外部传入的参数都无法篡改 SQL 的抽象语法树(AST)结构:

  1. 服务端预编译下的语法树固化:数据库服务端在接收参数之前,已经对含有 ? 占位符的 SQL 模板完成了词法分析、语法分析并生成了固定的 AST 与执行计划。后续传入的参数值仅通过二进制协议直接填入 AST 叶子节点的变量槽位中,数据库不会对参数值再次执行词法解析,因此参数中的 ' OR '1'='1 只会被视为普通的字符串内容,而不会变成 OR 逻辑语法节点。

  2. 客户端预编译下的强制类型转义:当驱动在本地组装 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;

image-20261031104232569

参数绑定执行流程 ​

使用 PreparedStatement 执行参数化查询时,占位符索引从 1 开始从左至右依次递增。所有占位符必须在执行前完成赋值,否则驱动将抛出 SQLException: No value specified for parameter ... 异常;且在最终调用执行方法时,需调用无参重载方法(不要再次传入 SQL 模板字符串,否则会退化为调用父接口 Statement 的静态执行方法):

java
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 实例,采用客户端本地模拟预编译机制:

  1. 本地模板切分:调用 prepareStatement(sql) 时,驱动并不会向 MySQL 服务端发送任何网络请求,而是僅在 JVM 内存中将 SQL 模板按 ? 占位符切分为静态文本片段数组。

  2. 单次文本协议发送:当绑定完参数并调用执行方法时,驱动在本地内存中将转义后的参数值与静态文本片段拼接成完整的 SQL 字节流,底层依然通过与 Statement 相同的 COM_QUERY 文本协议一次性发送给服务端执行。这种方式省去了一次预编译网络往返(RTT),适合只执行一次的单次查询,但无法在数据库服务端复用执行计划。

服务端二进制预编译 ​

当在 JDBC URL 中显式配置 useServerPrepStmts=true 时,MySQL 驱动会创建 ServerPreparedStatement 实例,启用真正的服务端二进制预编译协议:

  1. 预编译阶段(COM_STMT_PREPARE):调用 prepareStatement(sql) 时,驱动立即向 MySQL 服务端发送 COM_STMT_PREPARE 指令包。服务端解析 SQL 模板生成 AST,并在当前会话中缓存预编译结构,向客户端返回唯一的语句句柄 statement_id 以及参数与结果列的元数据信息。

  2. 执行阶段(COM_STMT_EXECUTE):调用执行方法时,驱动无需再发送 SQL 文本,只需发送 COM_STMT_EXECUTE 指令包,携带 statement_id 与紧凑的二进制参数值,服务端直接套用已编译好的执行计划完成运算。

  3. 预编译缓存复用:在生产环境中,若每次关闭 PreparedStatement 都触发服务端发送 COM_STMT_CLOSE 销毁预编译句柄,反而会因为每次执行都需要两次网络通信而降低性能。因此开启服务端预编译时,必须同步配置 cachePrepStmts=true(开启客户端预编译句柄缓存)、prepStmtCacheSize=250(缓存句柄数量上限)与 prepStmtCacheSqlLimit=2048(允许缓存的最大 SQL 长度),使同一连接上重复执行的相同 SQL 模板直接复用已分配的 statement_id。

image-20261031104259132

批量执行机制 ​

在需要向数据库批量插入或更新成千上万条记录的场景下,如果在循环体内逐条调用 executeUpdate,每条记录都会产生一次独立的网络往返(RTT)与磁盘刷写开销,网络延迟会成为严重的性能瓶颈。

累积缓冲与网络重写 ​

JDBC 提供了批处理(Batch Processing)机制,允许将多组参数缓存在本地内存中,通过单次网络请求集中提交:

  1. 本地参数队列累积:每次在循环中绑定完一行记录的占位符参数后,将当前参数组封装追加到 PreparedStatement 内部的批处理集合(batchedArgs)中,此时不会产生任何网络 I/O。

  2. 分批提交与内存清理:当批处理集合累积到指定阈值(如每 500 或 1000 条)时,统一触发批量发送,并返回每一条语句受影响行数组成的 int[] 数组;每批次发送完毕后必须显式清空本地批处理缓存列表,防止海量数据堆积引发 JVM 堆内存溢出(OOM)。

  3. 多值语句重写优化:对于 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), ...,从而实现数十倍的吞吐量提升:

    java
    import 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() 查询:

java
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)位置强行使用 ? 占位符并绑定字符串,驱动会在标识符外层加上单引号,导致语义错误或语法报错:

sql
-- 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 ​

语句执行 ​

  • ResultSet executeQuery():(),预编译查询执行。执行当前 PreparedStatement 对象中已完成参数绑定的预编译 SELECT 查询语句,并返回封装查询结果的 ResultSet 对象(永不为 null)。

  • int executeUpdate():(),预编译更新执行。执行当前 PreparedStatement 中的预编译 INSERT、UPDATE、DELETE 等 DML 语句(返回 int 型受影响行数)或无返回值的 DDL 语句(返回 0)。

  • long executeLargeUpdate():(),预编译大表更新执行。自 JDK 8 引入的 default 默认方法,执行预编译 DML 更新语句并返回 long 类型的受影响行数,适用于受影响行数超过 Integer.MAX_VALUE 的海量数据表更新。

  • boolean execute():(),预编译通用语句执行。执行当前 PreparedStatement 中任意种类的预编译 SQL 语句;若首个执行结果为 ResultSet 则返回 true,若为更新计数或无结果则返回 false。

  • void addBatch():(),预编译参数组入队。将当前 PreparedStatement 已绑定的整组参数值打包追加到内部批处理命令队列中,随后可继续修改参数并重复调用该方法累积多组参数,最后通过继承自 Statement 的 executeBatch() 一次性提交执行。

注意事项:

  1. 在 PreparedStatement 实例上必须且只能调用无参版本的 executeQuery()、executeUpdate()、execute() 和 addBatch();虽然 PreparedStatement 从父接口 Statement 继承了接收 String sql 参数的同名重载方法,但在 PreparedStatement 上调用任何带 String sql 参数的执行方法,按 JDBC 规范都会直接抛出 SQLException。
  2. 使用 MySQL 驱动执行 PreparedStatement 批量插入时,务必在 JDBC URL 中添加 rewriteBatchedStatements=true 参数,驱动才会将多组 INSERT INTO ... VALUES (?, ?) 批处理参数在底层自动重写合并为一条多值插入语句 INSERT INTO ... VALUES (a, b), (c, d),从而获得数十倍的批处理性能提升。
java
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,调用时必须显式传入目标列的 JDBC Types 类型常量。

    • void:(int parameterIndex, int sqlType),按标准类型置空。将指定位置参数设为 SQL NULL,并声明目标数据库列的标准 java.sql.Types 类型代码。
    • void:(int parameterIndex, int sqlType, String typeName),按自定义类型名置空。将指定位置参数设为 SQL NULL,专门用于绑定 REF、STRUCT、DISTINCT 等用户自定义命名类型(UDT)或特定数据库扩展类型。
  • void setBoolean():(int parameterIndex, boolean x),布尔参数绑定。将指定索引的参数设置为给定的 Java boolean 值,驱动会将其转换为 SQL BIT、BOOLEAN 或对应的整数值(1/0)。

  • void setByte():(int parameterIndex, byte x),单字节整数参数绑定。将指定索引的参数设置为给定的 Java byte 值(映射为 SQL TINYINT)。

  • void setShort():(int parameterIndex, short x),短整型参数绑定。将指定索引的参数设置为给定的 Java short 值(映射为 SQL SMALLINT)。

  • void setInt():(int parameterIndex, int x),整型参数绑定。将指定索引的参数设置为给定的 Java int 值(映射为 SQL INTEGER)。

  • void setLong():(int parameterIndex, long x),长整型参数绑定。将指定索引的参数设置为给定的 Java long 值(映射为 SQL BIGINT)。

  • void setFloat():(int parameterIndex, float x),单精度浮点参数绑定。将指定索引的参数设置为给定的 Java float 值(映射为 SQL REAL)。

  • void setDouble():(int parameterIndex, double x),双精度浮点参数绑定。将指定索引的参数设置为给定的 Java double 值(映射为 SQL DOUBLE 或 FLOAT)。

  • void setBigDecimal():(int parameterIndex, BigDecimal x),高精度十进制参数绑定。将指定索引的参数设置为给定的 BigDecimal 值(映射为 SQL DECIMAL 或 NUMERIC,若传入 null 则绑定为 SQL NULL)。

  • void setString():(int parameterIndex, String x),字符串参数绑定。将指定索引的参数设置为给定的 Java String 值(映射为 SQL VARCHAR、CHAR 或 LONGVARCHAR),并由驱动自动对特殊字符执行防注入转义。

  • void setNString():(int parameterIndex, String value),国家字符集参数绑定。将指定索引的参数设置为给定的 String 值,驱动将其作为 NCHAR、NVARCHAR 或 LONGNVARCHAR 类型发送给数据库。

  • void setBytes():(int parameterIndex, byte[] x),字节数组参数绑定。将指定索引的参数设置为给定的 Java byte[] 原始字节数组(映射为 SQL VARBINARY 或 LONGVARBINARY)。

  • setDate():日期参数绑定。将指定索引的参数设置为 java.sql.Date 值(映射为 SQL DATE),支持指定计算日期毫秒偏移所使用的时区日历。

    • void:(int parameterIndex, Date x),默认时区绑定日期。使用运行当前应用程序的 JVM 默认时区将 Date 参数绑定到指定占位符。
    • void:(int parameterIndex, Date x, Calendar cal),指定日历时区绑定日期。当底层数据库未存储时区信息时,使用给定 Calendar 对象的时区解析并构造数据库端存储的日期值。
  • setTime():时间参数绑定。将指定索引的参数设置为 java.sql.Time 值(映射为 SQL TIME),支持指定时区日历。

    • void:(int parameterIndex, Time x),默认时区绑定时间。使用 JVM 默认时区将 Time 参数绑定到指定占位符。
    • void:(int parameterIndex, Time x, Calendar cal),指定日历时区绑定时间。使用给定 Calendar 对象的时区将 Time 参数转换为目标数据库时间格式。
  • setTimestamp():时间戳参数绑定。将指定索引的参数设置为 java.sql.Timestamp 值(映射为 SQL TIMESTAMP 或 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 的基础上同时声明数值小数精度或流数据长度。
  • void clearParameters():(),已绑定参数清空。立即清空当前 PreparedStatement 实例中所有已绑定的参数值,以便重新绑定新一轮参数。

注意事项:

  1. 预编译 SQL 中的 ? 占位符索引 parameterIndex 严格从 1 开始按从左到右的顺序编号;在执行 SQL 前,每一个 ? 占位符都必须完成绑定,若遗漏任何一个占位符且未调用 setNull(),执行时将直接抛出 SQLException。
  2. 已绑定的参数值在调用 executeUpdate()、executeQuery() 或 addBatch() 后依然保留在当前 PreparedStatement 中;若后续循环执行时某几个位置的参数值保持不变,无需重复绑定,也可调用 clearParameters() 将全部参数重置后再重新赋值。
java
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 输入流(映射为 SQL LONGVARCHAR)。

    • 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 个字节并绑定到目标占位符。
  • void setUnicodeStream():(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 字符流(映射为 SQL NCLOB)。

    • 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 列。
  • void setSQLXML():(int parameterIndex, SQLXML xmlObject),XML 对象参数绑定。将指定索引的参数设置为 java.sql.SQLXML 实例(映射为数据库原生的 SQLXML 类型)。

  • void setArray():(int parameterIndex, Array x),SQL 数组参数绑定。将指定索引的参数设置为由 Connection.createArrayOf() 创建的 java.sql.Array 数组实例。

  • void setRef():(int parameterIndex, Ref x),结构化引用参数绑定。将指定索引的参数设置为 SQL REF(<结构化类型>) 引用实例。

  • void setURL():(int parameterIndex, URL x),URL 链接参数绑定。将指定索引的参数设置为给定的 java.net.URL 实例(映射为 SQL DATALINK)。

  • void setRowId():(int parameterIndex, RowId x),物理行标识参数绑定。将指定索引的参数设置为数据库底层的 java.sql.RowId 行地址标识符。

注意事项:

  1. 使用 setBinaryStream、setCharacterStream、setBlob(int, InputStream) 等流式绑定方法时,传入的 InputStream 或 Reader 会在后续调用 executeUpdate() 时才被驱动真正读取;因此在 executeUpdate() 执行完成前,切勿提前关闭传入的数据流。
  2. 向数据库写入超大文件或长文本时,优先使用流式绑定方法而非 setBytes() 或 setString(),以避免在 JVM 堆内存中一次性分配庞大的字节或字符数组引发内存溢出。
java
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("流式大对象参数绑定完毕");
    }
  }
}

元数据探测 ​

  • ResultSetMetaData getMetaData():(),预期结果集元数据获取。返回描述当前 PreparedStatement 执行后将生成的 ResultSet 列的名称、类型与数量等结构元数据的 ResultSetMetaData 对象;若当前语句不是查询语句或驱动无法预先探测,则返回 null。

  • ParameterMetaData getParameterMetaData():(),占位符参数元数据获取。返回描述当前 PreparedStatement 中所有 ? 占位符参数的个数、预期 SQL 类型与可空性等信息的 ParameterMetaData 对象。

注意事项:

  1. 在 PreparedStatement 尚未调用 executeQuery() 之前直接调用 getMetaData(),可以在不真正扫描表数据的前提下探测查询返回列的元信息,但可能会触发驱动向数据库服务端发起一次额外的预编译结构解析网络往返。
  2. MySQL 驱动在默认客户端预编译模式下调用 getParameterMetaData() 时,仅能准确返回 ? 占位符的个数(getParameterCount()),若直接调用 getParameterType(1) 获取参数类型可能抛出 SQLException;需在 URL 中配置 generateSimpleParameterMetadata=true(统一返回 VARCHAR)或开启服务端预编译 useServerPrepStmts=true 才能读取参数类型。
java
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 开始计算。

image-20261031104500745

参数传递模式 ​

与 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 数据类型;执行完毕后再按该占位符索引读取更新后的结果值。

image-20261031104516868

存储过程调用流程 ​

下面通过一个完整的账户余额升级业务场景,演示包含 IN、OUT、INOUT 三种参数模式的存储过程定义与 JDBC 调用过程。

创建测试存储过程 ​

在 MySQL 数据库 test_db 中创建存储过程 sp_upgrade_balance,接收用户 ID(IN)与奖励金额(INOUT),将奖励累加到原余额后,通过 OUT 参数返回用户名,并通过 INOUT 参数覆盖返回累加后的最新余额:

sql
-- 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 调用含输出参数的存储过程遵循以下五个步骤:

  1. 解析转义模板:调用 Connection 的 prepareCall 方法,传入 {call ...} 格式的转义调用字符串,创建 CallableStatement 对象。

  2. 绑定输入参数:按从 1 开始的占位符序号,为所有 IN 和 INOUT 参数绑定输入值。

  3. 注册输出类型:按占位符序号,为所有 OUT 和 INOUT 参数注册对应的 java.sql.Types 类型标识。

  4. 发送执行指令:调用无参执行方法触发存储过程运行。

  5. 提取输出参数:按 OUT 和 INOUT 参数对应的占位符序号读取返回结果。

综合调用示例 ​

以下代码演示了调用 sp_upgrade_balance 存储过程并提取 OUT 与 INOUT 参数值的完整过程:

java
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 内存缓冲区中。

java
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 出参。

注意事项:

  1. 存储过程的所有 OUT 和 INOUT 参数必须在调用 execute() 执行存储过程之前调用 registerOutParameter() 完成类型注册,否则执行时将直接抛出 SQLException。
  2. 对于既是输入又是输出的 INOUT 双向参数,在调用 execute() 前既要调用 setXxx() 绑定输入值,也必须调用 registerOutParameter() 注册输出类型;对于采用 {? = call func_name(?)} 语法的数据库函数调用,返回值占据第 1 个 ? 占位符,同样必须通过 registerOutParameter(1, ...) 注册。
java
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 输出参数注册完成");
    }
  }
}

出参读取 ​

  • boolean wasNull():(),出参空值状态检测。判断最后一次通过 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 参数读取为注册类型对应的默认 Java Object,或按指定的 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 出参。根据占位符索引获取 SQL Array 对象。
    • Array:(String parameterName),按参数名读取 Array 出参。根据参数名称获取 SQL Array 对象。
  • 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 对象。

注意事项:

  1. 当存储过程同时返回多个 ResultSet 查询结果集、更新计数以及 OUT 输出参数时,为了达到最高的可移植性,JDBC 规范要求必须先使用 getResultSet() 和 getMoreResults() 处理完所有的结果集与更新计数后,最后再调用 CallableStatement.getXxx() 提取 OUT 参数值。
  2. 在 Oracle 等数据库中,若存储过程通过 SYS_REFCURSOR(引用游标)类型的 OUT 参数返回结果集,可在注册为 Types.REF_CURSOR(或 JDBCType.REF_CURSOR)后,直接调用 cstmt.getObject(index, ResultSet.class) 将该出参读取为 ResultSet 遍历。
java
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。
  • void setBoolean():(String parameterName, boolean x),命名布尔入参绑定。按参数名称将指定参数设置为给定的 Java boolean 值。

  • void setByte():(String parameterName, byte x),命名单字节整数入参绑定。按参数名称将指定参数设置为给定的 Java byte 值。

  • void setShort():(String parameterName, short x),命名短整型入参绑定。按参数名称将指定参数设置为给定的 Java short 值。

  • void setInt():(String parameterName, int x),命名整型入参绑定。按参数名称将指定参数设置为给定的 Java int 值。

  • void setLong():(String parameterName, long x),命名长整型入参绑定。按参数名称将指定参数设置为给定的 Java long 值。

  • void setFloat():(String parameterName, float x),命名单精度浮点入参绑定。按参数名称将指定参数设置为给定的 Java float 值。

  • void setDouble():(String parameterName, double x),命名双精度浮点入参绑定。按参数名称将指定参数设置为给定的 Java double 值。

  • void setBigDecimal():(String parameterName, BigDecimal x),命名高精度十进制入参绑定。按参数名称将指定参数设置为给定的 BigDecimal 值。

  • void setString():(String parameterName, String x),命名字符串入参绑定。按参数名称将指定参数设置为给定的 Java String 值。

  • void setNString():(String parameterName, String value),命名国家字符集入参绑定。按参数名称将指定参数设置为国家字符集 String 值。

  • void setBytes():(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)将给定的 Java Object 绑定为存储过程入参,支持指定目标 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 及精度绑定对象。

注意事项:

  1. 按参数名称(parameterName)绑定或注册参数前,可通过 DatabaseMetaData.supportsNamedParameters() 检测底层驱动是否支持命名参数;在 MySQL 中使用命名参数时,驱动需要查询 information_schema.PARAMETERS 元数据表来解析参数名与位置的映射关系,因此当前数据库账号必须具备对该存储过程元数据的读取权限。
  2. 在同一个 CallableStatement 调用中,切勿将基于位置索引(int parameterIndex)和基于参数名称(String parameterName)的绑定方式混用,应保持整条调用统一使用索引或统一使用参数名。
java
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 绑定到指定参数名。
  • void setSQLXML():(String parameterName, SQLXML xmlObject),命名 XML 对象入参绑定。按参数名称将指定参数设置为 java.sql.SQLXML 实例。

  • void setURL():(String parameterName, URL val),命名 URL 链接入参绑定。按参数名称将指定参数设置为给定的 java.net.URL 实例。

  • void setRowId():(String parameterName, RowId x),命名物理行标识入参绑定。按参数名称将指定参数设置为数据库底层的 java.sql.RowId 行地址标识符。

注意事项:

  1. CallableStatement 未提供按参数名绑定 SQL 数组的 setArray(String, Array) 与绑定引用的 setRef(String, Ref) 方法;若存储过程包含 ARRAY 或 REF 类型入参,必须使用从 PreparedStatement 继承的按位置索引绑定方法 setArray(int, Array) 与 setRef(int, Ref)。
java
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 ​

java.sql.ResultSet 是 JDBC 中用于封装数据库查询(DQL)返回结果的表格数据对象,由 Statement、PreparedStatement 或 CallableStatement 执行查询后创建并返回。

在逻辑结构上,ResultSet 表现为一个由行(Row)与列(Column)组成的二维关系表,其内部维护了一个指向当前数据行的游标(Cursor)。应用程序通过移动游标定位目标行,并按照列索引或列标签提取当前行各字段的数据值。

游标定位 ​

ResultSet 对象在刚创建完成时,其内部游标并非直接指向第一行数据,而是停留在第一行数据之前的初始越界位置(Before First)。

初始越界位置与行推进 ​

游标在生命周期内会依次经历三个逻辑区域:

  1. 首行前区域(Before First):ResultSet 初始化后的默认位置。此时游标未指向任何有效数据行,如果在未移动游标的情况下直接读取列数据,驱动会立即抛出 SQLException: Before start of result set 异常。

  2. 有效数据行区域(Data Rows):每调用一次游标前移方法,游标向下推进一行。若推进后指向的是有效数据行,方法返回 true,此时允许安全读取该行的所有列值。

  3. 末行后区域(After Last):当游标越过最后一行有效数据后,进入末行后越界区域,推进方法返回 false(若结果集本身为空表,则首次推进即直接从 Before First 跳入 After Last 并返回 false)。在此区域继续读取列数据同样会触发 SQLException: After end of result set 异常。

image-20261031104653520

列数据提取 ​

当游标停留在有效数据行上时,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 的映射行为存在显著差异:

  1. 引用类型直接映射为 null:当提取为 String、BigDecimal、LocalDateTime 等引用类型时,若数据库字段值为 NULL,方法会直接返回 Java 的 null 引用。

  2. 基本类型退化为零值:由于 Java 基本数据类型(int、long、double、boolean)无法接收 null,JDBC 规范规定当数据库字段为 NULL 时,数值型读取方法会静默返回 0(或 0.0),布尔型读取方法会返回 false。这会导致业务层无法直接区分数据库中存储的究竟是真实数值 0,还是缺失值 NULL。

  3. 安全判空与泛型提取:若必须在基本类型读取后识别 NULL,需紧接着检查结果集最近一次读取的列是否为空值;而在现代 JDK(JDBC 4.1+)开发中,更推荐直接传入包装类的 Class 对象(如 Integer.class、Double.class)进行泛型提取,此时 SQL NULL 会直接返回 null 而不会退化为 0:

    java
    import 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(双向滚动,动态感知底层数据修改,取决于驱动是否支持)时,游标可以在结果集中自由前进、后退、直接跳转到首尾行,或按绝对行号与相对偏移量随机定位。

可更新结果集模式 ​

当并发模式指定为 ResultSet.CONCUR_UPDATABLE 时,应用程序可以直接在当前游标指向的行上修改列值缓冲区,或将游标移动到专门的“插入行(Insert Row)”缓冲区构建新记录,并由驱动在底层自动生成并发送对应的 UPDATE、INSERT 或 DELETE 语句同步回数据库。

要使可更新结果集生效,执行的 SELECT 查询语句必须满足严格的语法限制:只能查询单张物理表(不能包含 JOIN 连接、分组 GROUP BY、DISTINCT 或聚合函数),且查询的字段列表中必须包含该表的主键列,否则驱动无法定位底层物理数据行,会将结果集静默降级为只读模式:

java
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)。

image-20261031104708086

默认全量内存缓冲 ​

以 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 驱动的流式结果集(ResultSetRowsStreaming):将结果集模式设为 TYPE_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 行记录,从而在内存安全与网络吞吐量之间取得平衡:

java
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 int ResultSet.TYPE_FORWARD_ONLY:仅向前滚动常量。常量值为 1003,标识结果集游标仅支持从首行向末行单向顺序调用 next() 推进,不支持反向或随机跳行定位。

  • final int ResultSet.TYPE_SCROLL_INSENSITIVE:双向滚动不敏感常量。常量值为 1004,标识结果集支持双向滚动与随机定位,但底层数据通常为静态快照,对其他事务在结果集打开期间提交的数据更改不敏感。

  • final int ResultSet.TYPE_SCROLL_SENSITIVE:双向滚动敏感常量。常量值为 1005,标识结果集支持双向滚动与随机定位,且能够动态感知并反映底层数据库在结果集打开期间发生的数据变更。

  • final int ResultSet.FETCH_FORWARD:正向预取方向常量。常量值为 1000,向驱动提示结果集行数据将按从首行到末行的正向顺序处理。

  • final int ResultSet.FETCH_REVERSE:反向预取方向常量。常量值为 1001,向驱动提示结果集行数据将按从末行到首行的反向顺序处理。

  • final int ResultSet.FETCH_UNKNOWN:未知预取方向常量。常量值为 1002,表示结果集行数据的处理顺序未知。

  • boolean next():(),游标下移一行。将当前游标从当前位置向下移动一行(初始位于第一行之前,首次调用移至第一行);若移动后指向有效数据行则返回 true,若已越过最后一行则返回 false。

  • boolean previous():(),游标上移一行。将游标从当前位置向上回退一行;若移动后位于有效数据行则返回 true,若已退至第一行之前则返回 false。

  • boolean first():(),游标移至首行。将游标直接移动到当前 ResultSet 的第一行数据;若结果集包含数据则返回 true,若结果集为空则返回 false。

  • boolean last():(),游标移至末行。将游标直接移动到当前 ResultSet 的最后一行数据;若结果集非空则返回 true,否则返回 false。

  • void beforeFirst():(),游标移至首行前。将游标重置到结果集的第一行之前(初始位置);若结果集为空则该方法不产生任何效果。

  • void afterLast():(),游标移至末行后。将游标移动到结果集的最后一行之后;若结果集为空则该方法不产生任何效果。

  • boolean absolute():(int row),游标绝对行号定位。将游标直接定位到指定的行号 row(正数表示从首行 1 开始正向计数,负数表示从末行 -1 开始倒数计数,0 表示移至首行之前);指向有效行时返回 true。

  • boolean relative():(int rows),游标相对行数偏移。相对于当前游标所在行正向(正数)或反向(负数)偏移指定的行数 rows;传入 0 时游标保持原地不动。

  • boolean isBeforeFirst():(),首行前位置判断。判断游标当前是否位于结果集的第一行之前;对于空结果集固定返回 false。

  • boolean isAfterLast():(),末行后位置判断。判断游标当前是否位于结果集的最后一行之后;对于空结果集固定返回 false。

  • boolean isFirst():(),首行位置判断。判断游标当前是否正好指向结果集的第一行数据。

  • boolean isLast():(),末行位置判断。判断游标当前是否正好指向结果集的最后一行数据。

  • int getRow():(),当前行号获取。获取游标当前指向的数据行编号(从 1 开始计数);若游标位于首行之前、末行之后或结果集为空,则返回 0。

  • void setFetchDirection():(int direction),结果集预取方向设置。向 JDBC 驱动提供性能提示,指定当前 ResultSet 后续遍历行数据的主要方向。

  • int getFetchDirection():(),结果集预取方向获取。获取当前 ResultSet 实例生效的数据预取方向常量。

  • void setFetchSize():(int rows),网络预取行数设置。设置当前 ResultSet 每次需要更多数据时从数据库通过网络批量拉取的行数(设为 0 则交由驱动自行决定)。

  • int getFetchSize():(),网络预取行数获取。返回当前 ResultSet 配置的单次网络预取行数。

注意事项:

  1. 默认创建的 ResultSet 类型为 TYPE_FORWARD_ONLY,此时仅允许调用 next() 向下推进游标;若调用 previous()、first()、last()、absolute() 等反向或随机定位方法,将抛出 SQLException。
  2. 在单向滚动结果集中调用 isLast() 可能触发驱动预先读取下一行数据以判断当前行是否为末尾,在大结果集流式处理场景下应直接依赖 while (rs.next()) 的返回值控制循环。
java
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 结构化值。
  • int findColumn():(String columnLabel),列名转列索引。将给定的结果集列标签(或列名)映射为对应的 1 起始列索引编号;若未找到匹配列名则抛出 SQLException。

  • boolean wasNull():(),空值读取状态检测。报告当前行最近一次通过 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 实例形式读取当前行指定列的 SQL ARRAY 数组类型数据。

    • Array:(int columnIndex),按列索引读取 Array。根据列索引获取 SQL Array 对象。
    • Array:(String columnLabel),按列标签读取 Array。根据列标签获取 SQL Array 对象。
  • getRef():SQL 引用列值读取。以 Ref 实例形式读取当前行指定列的 SQL REF 结构化类型引用。

    • 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 对象。

注意事项:

  1. JDBC 的列索引 columnIndex 严格从 1 开始计数(而非 0);传入 columnLabel 时,若 SQL 查询中为字段指定了 AS 别名,则必须传入对应的列别名。
  2. 当数据库字段值为 SQL NULL 时,getInt()、getDouble()、getBoolean() 等基本数据类型方法会返回零值(0、0.0、false);若业务需要区分真实零值与 NULL,必须在读取后立即调用 wasNull(),或直接使用 getObject(columnLabel, Integer.class) 读取为可空包装类型。
java
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 int ResultSet.CONCUR_READ_ONLY:只读并发模式常量。常量值为 1007,标识当前 ResultSet 对象仅支持读取数据,禁止通过结果集直接修改底层表数据。

  • final int ResultSet.CONCUR_UPDATABLE:可更新并发模式常量。常量值为 1008,标识当前 ResultSet 对象支持通过 updateXxx、updateRow、insertRow、deleteRow 原位增删改底层表数据。

  • void moveToInsertRow():(),游标移至插入缓冲区。记住当前游标所在行位置,并将游标切换到专用于构建新数据行的特殊缓冲区“插入行(Insert Row)”。

  • void moveToCurrentRow():(),游标返回原先数据行。当游标当前位于“插入行”缓冲区时,将其恢复到调用 moveToInsertRow() 之前所指向的正常数据行。

  • void insertRow():(),提交插入缓冲区新行。将“插入行”缓冲区中已通过 updateXxx 填充完毕的整行数据正式写入结果集与底层数据库中(仅当游标位于插入行时可调用)。

  • void updateRow():(),提交当前行修改。将当前数据行中通过 updateXxx 修改的列缓冲区内容正式发送并同步至底层数据库。

  • void deleteRow():(),删除当前数据行。从当前 ResultSet 结果集以及底层数据库表中同步删除游标当前指向的数据行(不可在插入行上调用)。

  • void refreshRow():(),重读刷新当前行。从数据库重新拉取当前行的最新数据以覆盖结果集本地行缓存。

  • void cancelRowUpdates():(),撤销当前行未提交修改。回退当前行通过 updateXxx 写入本地缓冲区但尚未调用 updateRow() 提交的所有列修改;若已调用过 updateRow() 则该方法无效。

  • boolean rowUpdated():(),当前行已更新检测。判断当前行是否已被更新(取决于数据库与结果集类型能否检测到自身或外部更新)。

  • boolean rowInserted():(),当前行属新增检测。判断当前行是否为结果集打开期间新插入的行。

  • boolean rowDeleted():(),当前行已删除检测。判断当前行是否已被删除并在结果集中留有空洞占位(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。更新指定列索引的 SQL Array 对象。
    • void:(String columnLabel, Array x),按列标签更新 Array。更新指定列标签的 SQL Array 对象。
  • 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 对象。

注意事项:

  1. 仅当创建 Statement 时显式指定并发模式为 ResultSet.CONCUR_UPDATABLE,且 SQL 查询针对单表、未包含聚合函数或 JOIN、并在 SELECT 列表中包含主键列时,ResultSet 才支持原位行更新。
  2. 调用 updateXxx() 方法仅修改客户端当前行的内存缓冲区,不会直接触发数据库写操作;必须在修改完列值后显式调用 updateRow()(更新现有行)或 insertRow()(提交插入行),若在调用 updateRow() 前移动了游标,此前未提交的缓冲区修改将直接丢失。
java
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 int ResultSet.HOLD_CURSORS_OVER_COMMIT:跨事务提交保持游标常量。常量值为 1,标识当所属连接调用 Connection.commit() 提交事务时,当前打开的 ResultSet 游标保持开启状态而不被关闭。

  • final int ResultSet.CLOSE_CURSORS_AT_COMMIT:事务提交时关闭游标常量。常量值为 2,标识当所属连接调用 Connection.commit() 提交事务时,当前打开的 ResultSet 游标将被自动关闭。

  • void close():(),结果集资源释放。立即释放当前 ResultSet 占用的数据库游标与客户端内存缓冲区资源;在已关闭的结果集上重复调用该方法为空操作。

  • boolean isClosed():(),关闭状态检测。判断当前 ResultSet 对象是否已被显式或隐式关闭。

  • ResultSetMetaData getMetaData():(),结果集列元数据获取。返回描述当前 ResultSet 列的编号、名称、数据类型与精度等结构信息的 ResultSetMetaData 对象。

  • Statement getStatement():(),所属语句对象获取。返回生成当前 ResultSet 结果集的父级 Statement 对象;若该结果集是由数据库元数据方法(如 DatabaseMetaData.getTables)内部生成的,则可能返回 null。

  • int getType():(),结果集滚动类型获取。返回当前 ResultSet 的滚动类型常量(如 TYPE_FORWARD_ONLY、TYPE_SCROLL_INSENSITIVE 或 TYPE_SCROLL_SENSITIVE)。

  • int getConcurrency():(),结果集并发模式获取。返回当前 ResultSet 的并发修改模式常量(CONCUR_READ_ONLY 或 CONCUR_UPDATABLE)。

  • int getHoldability():(),游标保持策略获取。返回当前 ResultSet 在事务提交后的游标保持策略常量(HOLD_CURSORS_OVER_COMMIT 或 CLOSE_CURSORS_AT_COMMIT)。

  • String getCursorName():(),底层游标名称获取。返回驱动或底层数据库赋予当前 ResultSet 的 SQL 游标名称,用于定位更新或删除语句。

  • SQLWarning getWarnings():(),结果集告警链获取。返回当前 ResultSet 上报告的第一个 SQLWarning 告警对象;无告警时返回 null。

  • void clearWarnings():(),结果集告警清空。清空当前 ResultSet 对象上累积的所有 SQLWarning 告警链。

注意事项:

  1. 每次在 ResultSet 上调用 next()(或其他游标定位方法)移动到新行时,前一行读取过程中产生的 SQLWarning 告警会被自动清空;因此若需检查特定行的读取截断或精度告警,必须在移动至下一行之前调用 getWarnings()。
  2. 当创建该 ResultSet 的父级 Statement 被关闭、重新执行新 SQL 或调用 getMoreResults() 切换到下一个结果时,当前 ResultSet 会被底层驱动自动关闭。
java
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 ​

标识定位 ​

  • int getColumnCount():(),结果集总列数获取。返回当前 ResultSet 对象中包含的列总数;遍历列元数据时列索引从 1 开始直至该返回值。

  • String getColumnName():(int column),物理列名获取。获取指定列在数据库表定义中的原始物理字段名称;若该列是由表达式或聚合函数计算生成且无物理列名,则返回空字符串。

  • String getColumnLabel():(int column),列别名标签获取。获取用于打印输出或对象属性映射的推荐列标题;若 SQL 查询中通过 AS 为该列指定了别名,则返回该别名,否则返回原始物理列名。

  • String getTableName():(int column),所属表名获取。返回指定列所属的数据库表名称;若该列为表达式计算列或无法追溯来源表,则返回空字符串 ""。

  • String getCatalogName():(int column),所属目录名获取。返回指定列所属表所在的数据库目录(Catalog)名称;在 MySQL 中对应具体的数据库名(Database)。

  • String getSchemaName():(int column),所属模式名获取。返回指定列所属表所在的数据库命名空间模式(Schema)名称;若底层数据库不支持 Schema 则返回空字符串 ""。

注意事项:

  1. 严格区分 getColumnName() 与 getColumnLabel():getColumnName() 返回数据库表中的原始字段名(如 user_name),而 getColumnLabel() 返回 SQL 语句中通过 AS 指定的别名(如 SELECT user_name AS userName 中的 userName)。在编写通用反射结果集映射工具(如自定义 BasicDAO 或 BeanUtils 封装)时,必须始终调用 getColumnLabel(),否则 SQL 别名将无法匹配 JavaBean 属性。
  2. 所有接收 int column 参数的方法,其列序号严格从 1 开始计数,传入 0 或超过 getColumnCount() 的值将直接抛出 SQLException。
java
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));
      }
    }
  }
}

类型规格 ​

  • int getColumnType():(int column),标准 SQL 类型码获取。返回指定列的 JDBC 标准 SQL 类型整型编码,对应 java.sql.Types 类中定义的静态常量(如 Types.INTEGER、Types.VARCHAR)。

  • String getColumnTypeName():(int column),数据库原生类型名获取。返回指定列在底层特定数据库方言中的原生数据类型名称字符串(例如 MySQL 中的 "VARCHAR"、"DECIMAL" 或 "INT UNSIGNED")。

  • String getColumnClassName():(int column),映射 Java 类全限定名获取。返回当调用 ResultSet.getObject(int) 读取该列时,JDBC 驱动默认实例化并返回的 Java 类的全限定名称(如 "java.lang.Integer"、"java.math.BigDecimal")。

  • int getPrecision():(int column),列数据精度获取。返回指定列的大小或精度:对于数值型数据表示有效数字总位数,对于字符型数据表示最大字符长度,对于二进制数据表示最大字节长度。

  • int getScale():(int column),小数点后位数获取。返回指定列在小数点右边的数字位数(如 DECIMAL(10, 2) 返回 2);对于整数、字符串或不支持小数标度的列类型默认返回 0。

  • int getColumnDisplaySize():(int column),最大显示字符宽度获取。返回将指定列的值格式化为字符串展示时建议预留的正常最大字符宽度(常用于命令行表格对齐打印)。

注意事项:

  1. 在 MySQL 数据库中,当字段被定义为无符号整型(如 INT UNSIGNED)时,为防止正数范围溢出 Java int 上限,驱动的 getColumnClassName() 会自动升级映射为 "java.lang.Long";同理,BIGINT UNSIGNED 会升级映射为 "java.math.BigInteger"。
  2. 对于 BLOB、TEXT 等超大变长大对象列,getPrecision() 返回的是该类型在数据库中支持的最大理论上限字节数或字符数,而非当前行实际存储的数据长度。
java
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 int ResultSetMetaData.columnNoNulls:禁止空值常量。常量值为 0,作为 isNullable() 的返回值,标识该列在数据库定义中受 NOT NULL 约束,不允许存储 SQL NULL 值。

  • final int ResultSetMetaData.columnNullable:允许空值常量。常量值为 1,作为 isNullable() 的返回值,标识该列允许存储 SQL NULL 值。

  • final int ResultSetMetaData.columnNullableUnknown:空值约束未知常量。常量值为 2,作为 isNullable() 的返回值,标识驱动无法判定该列是否允许为空(常见于复杂计算列或视图列)。

  • int isNullable():(int column),空值约束状态检测。检索指定列是否允许存储 SQL NULL 值,返回值为 columnNoNulls、columnNullable 或 columnNullableUnknown 常量之一。

  • boolean isAutoIncrement():(int column),自增列属性检测。判断指定列是否为数据库自动编号的递增列(如 MySQL 的 AUTO_INCREMENT 主键列),若是则通常在插入时无需显式赋值。

  • boolean isSigned():(int column),带符号数值检测。判断指定列中的数值是否允许包含正负符号;对于无符号列(UNSIGNED)或非数值列返回 false。

  • boolean isCurrency():(int column),货币金额类型检测。判断指定列是否为数据库专用的现金货币数据类型(如 SQL Server 的 MONEY 类型)。

  • boolean isCaseSensitive():(int column),大小写敏感检测。判断指定列的字符比较与排序规则(Collation)是否区分字母大小写。

  • boolean isSearchable():(int column),条件检索支持检测。判断指定列是否允许出现在 SQL 语句的 WHERE 条件子句中进行过滤匹配。

  • boolean isReadOnly():(int column),只读列状态检测。判断指定列是否绝对不可写入(例如常量计算列、聚合函数列或无写权限的视图列)。

  • boolean isWritable():(int column),可写列可能性检测。判断针对指定列发起写操作在逻辑上是否有可能成功。

  • boolean isDefinitelyWritable():(int column),确定可写状态检测。判断针对指定列发起的写操作是否确定能够成功落盘。

注意事项:

  1. isNullable(int column) 尽管以 is 开头,但其返回值类型是 int 而非 boolean;判断某列是否允许为空时,必须将其返回值与 ResultSetMetaData.columnNoNulls 或 columnNullable 常量进行比较。
  2. 在 MySQL 中,VARCHAR 列调用 isCaseSensitive() 的返回值取决于该列绑定的字符集排序规则(Collation):若使用默认的 utf8mb4_0900_ai_ci 或 utf8mb4_general_ci(以 _ci 结尾表示大小写不敏感),则返回 false;若使用 _bin 或 _cs 排序规则,则返回 true。
java
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 的直连版本(JDBCUtils)与基于 DataSource 连接池的池化版本(JDBCUtilsByDruid)。

核心设计要点 ​

在设计自定义 JDBC 工具类时,主要围绕以下三个工程机制展开:

  1. 静态代码块单次初始化:配置文件的 I/O 读取、驱动类的反射加载或连接池(DataSource)的创建均属于高开销操作,且在整个 JVM 进程生命周期内只需执行一次。将其放置在工具类的 static {} 静态代码块中,可确保在类首次被加载时自动完成单次初始化。

  2. 受检异常转运行期异常:JDBC 原生 API 大量抛出编译期受检异常(SQLException)与 IO 异常(IOException)。在工具类内部捕获这些受检异常后,将其包装转换为运行期非受检异常(throw new RuntimeException(e))向上抛出。这样调用方既可以选择显式捕获处理,也可以交由上层统一异常处理器兜底,避免在业务层方法签名上层层声明 throws SQLException。

  3. 统一逆序判空释放接口:对外提供统一的 close(ResultSet, Statement, Connection) 静态方法,内部严格按照“先开后关”的逆序依次判空并释放资源。得益于多态机制,第二个形参声明为父接口 Statement,因此调用方无论是传入静态 Statement、预编译 PreparedStatement 还是存储过程 CallableStatement 均可直接兼容;若执行的是无结果集的 DML 语句,第一个参数直接传入 null 即可。

JDBCUtils ​

直连版工具类 JDBCUtils 基于 DriverManager 实现,每次调用 getConnection 都会新建一条物理数据库连接,调用 close 时则直接断开底层 TCP 物理连接。

mysql.properties ​

在类路径(src 或 resources 目录)下创建 mysql.properties 配置文件,集中维护数据库连接四要素:

properties
# 1. 数据库连接账号与密码
user=root
password=123456

# 2. 数据库连接地址与驱动类全限定名
url=jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC
driver=com.mysql.cj.jdbc.Driver

JDBCUtils ​

工具类内部通过四个静态属性保存连接参数,在 static 代码块中利用类加载器读取配置文件并加载驱动,对外暴露静态的 getConnection 与 close 方法:

java
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 块中的关闭模板代码:

java
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);
    }

JDBCUtilsByDruid↗ ​