build: 升级版本至 1.0.0-RC3

test: 重构测试类 UpdateTest，补全 Statement 路径覆盖
- 按 update / updateAndReturnKeys 分组，内部再按 PreparedStatement （有参数）和 Statement（无参数）子路径组织，提升可维护性 - 重命名 3 个测试方法以消除歧义： testUpdateWithNullParams → testUpdateWithNullElement testUpdateWithParamsIsNull → testUpdateWithParamsNull testUpdateAndReturnKeysWithParamsIsNull → testUpdateAndReturnKeysWithParamsNull - 新增 2 个测试用例补全 params=null 的 Statement 路径覆盖： testUpdateWithParamsNull testUpdateAndReturnKeysWithParamsNull
2026-06-05 21:30:21 +08:00 · 2026-06-05 21:17:12 +08:00 · 2026-06-05 21:12:25 +08:00 · 2026-06-05 20:49:17 +08:00 · 2026-06-05 20:28:16 +08:00 · 2026-06-05 20:08:08 +08:00
7 changed files with 333 additions and 214 deletions
--- a/README.md
+++ b/README.md
@@ -1,12 +1,30 @@
-# SimpleJDBC
+# Simple JDBC

-SimpleJDBC 是一个轻量级 JDBC 工具库，提供简洁的 API 用于执行 SQL 查询、更新、批量操作及事务管理，适用于未引入 ORM 框架、直接使用原生 JDBC 的项目。
+`Simple JDBC` 提供了一套轻量级的 JDBC 封装工具类，是作者在对传统遗留项目进行改造时设计。该项目未引入 ORM 框架，原本的数据库交互高度依赖原生 JDBC API，导致存在大量冗余的样板代码（Boilerplate Code）。本项目通过抽象底层数据库操作，简化了连接管理、SQL 执行与结果集处理流程，提升数据访问层的开发效率与代码可维护性。

-## 1. 快速开始
+> 注：本项目基于 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 开源协议发布。

-**要求 JDK 8+。**
+---

-Maven 依赖：
+## ✨ 核心特性
+
+- **轻量无依赖**：基于原生 JDBC 封装，无第三方重量级依赖。
+- **API 简洁**：提供丰富的快捷方法，大幅减少样板代码。
+- **灵活的映射**：支持自定义 `ResultHandler` 与 `RowMapper`，内置默认 Bean 映射策略。
+- **事务与批处理**：提供声明式的事务模板与完善的批量更新错误处理机制。
+- **线程安全**：核心模板类无状态设计，天然支持多线程环境。
+
+---
+
+## 📦 快速开始
+
+### 环境要求
+
+- **JDK 8** 或更高版本
+
+### 添加 Maven 依赖
+
+将以下配置添加到您的 `pom.xml` 中：

 ```xml
 <dependency>
@@ -16,106 +34,16 @@ Maven 依赖：
 </dependency>
 ```

-> 本项目基于 **Apache License 2.0** 开源。
-
-## 2. 查询
-
-### 2.1 查询方法
-
-所有查询方法均使用 `Object[]` 作为参数，并提供了无参便捷重载（适用于不含占位符的 SQL）。
-
-| 方法 | 说明 |
-|---|---|
-| `query(sql, params, resultHandler)` | 最基础的查询，通过 `ResultHandler` 自定义映射逻辑 |
-| `queryList(sql, params, rowMapper)` | 查询列表，通过 `RowMapper` 逐行映射 |
-| `queryList(sql, params, Class)` | 单列查询列表，每行取第一列转为指定类型 |
-| `queryList(sql, params)` | 查询列表，每行转为 `Map<String, Object>` |
-| `queryFirst(sql, params, rowMapper)` | 查询第一行，通过 `RowMapper` 映射，返回 `Optional` |
-| `queryFirst(sql, params, Class)` | 查询第一行第一列，返回 `Optional<T>` |
-| `queryFirst(sql, params)` | 查询第一行，返回 `Optional<Map<String, Object>>` |
-| `queryBoolean(sql, params)` | 查询第一行第一列并转为 boolean，结果为空返回 `false` |
-
-> 以上方法均有不含 `params` 的便捷重载，例如 `queryList(sql, rowMapper)`、`queryFirst(sql, Class)` 等，适用于无参数 SQL。
-
-### 2.2 结果映射
-
- **`ResultHandler`**：处理完整的 `ResultSet`，自定义逻辑将结果映射为任意类型（包括集合）。
- **`RowMapper`**：将 `ResultSet` 中的一行数据映射为 Java 对象。
-  - `RowMapper.HASH_MAP_MAPPER`：每行映射为 `HashMap<String, Object>`。
-  - `RowMapper.beanRowMapper(Class)`：默认的 Bean 映射，属性名（小驼峰） ↔ 列名（小写蛇形）。
-  - `RowMapper.beanRowMapper(Class, Map<String, String>)`：自定义属性名与列名映射的 Bean 映射。
-
-## 3. 更新
-
-所有更新方法同样提供了无参便捷重载。
-
-| 方法 | 说明 |
-|---|---|
-| `update(sql, params)` | 执行 DML（INSERT / UPDATE / DELETE），返回受影响行数 |
-| `updateAndReturnKeys(sql, params, rowMapper)` | 执行 DML 并返回自动生成的键，通过 `RowMapper` 映射 |
-| `batchUpdate(sql, params, batchSize)` | 分批执行 DML，遇错即中断 |
-| `batchUpdate(sql, params, batchSize, quietly)` | 分批执行 DML；`quietly=true` 遇错不中断，全部执行完毕 |
-
-### BatchUpdateResult
-
-`batchUpdate` 返回 `BatchUpdateResult`，包含：
-
- `getStatus()`：批次状态（`SUCCESS` / `COMPLETED_WITH_ERRORS` / `INTERRUPTED`）
- `getTotal()`：总数据量
- `getBatchCount()`：总批次数
- `getSuccessBatchCount()` / `getErrorBatchCount()`：成功/失败批次数
- `getBatchUpdateErrorInfo(batchIndex)`：获取指定批次的错误详情
-
-## 4. 事务
-
-通过 `TransactionTemplate` 管理事务，可直接创建或通过 `SimpleJdbcTemplate.transaction()` 获取。
-
- **`execute(consumer)`**：执行事务。传入 `ThrowingConsumer<JdbcOperations>`，若内部无异常则提交，有异常则回滚。
- **`commitIfTrue(predicate)`**：执行事务。传入 `ThrowingPredicate<JdbcOperations>`，返回 `true` 提交，返回 `false` 或抛异常则回滚。
-
-## 5. 参数构建
-
-此项目中所有方法都**不使用可变长参数**，避免强制将参数列表放在 SQL 语句末尾，也避免与数组产生歧义。
-
-### 5.1 构建参数列表
-
-使用 `ParamBuilder.buildParams(...)` 构建 `Object[]` 作为 SQL 参数。该方法会自动将 `Optional` 值拆箱。
-
-```java
-import static xyz.zhouxy.jdbc.ParamBuilder.buildParams;
-
-buildParams("admin%", "0000");           // → Object[]{"admin%", "0000"}
-buildParams(Optional.of("hello"));        // → Object[]{"hello"}
-buildParams(Optional.empty());            // → Object[]{null}
-```
-
-### 5.2 批量构建参数列表
-
-使用 `ParamBuilder.buildBatchParams(collection, func)` 将集合中每个元素转为 `Object[]`，返回 `List<Object[]>`。
-
-```java
-import static xyz.zhouxy.jdbc.ParamBuilder.buildBatchParams;
-import static xyz.zhouxy.jdbc.ParamBuilder.buildParams;
-
-buildBatchParams(accountList, account -> buildParams(
-    account.getUsername(),
-    account.getPassword(),
-    account.getOrgNo()
-));
-```
-
-## 6. 示例
-
-创建 `SimpleJdbcTemplate` 对象：
+### 初始化

 ```java
 SimpleJdbcTemplate jdbcTemplate = new SimpleJdbcTemplate(dataSource);
 ```

-### 6.1 查询
+### 1. 查询操作

 ```java
-// 查询（使用 ResultHandler 处理全部结果）
+// 1.1 基础查询（使用 ResultHandler 处理全部结果）
 List<Account> accounts = jdbcTemplate.query(
    "SELECT * FROM account WHERE deleted = 0 AND username LIKE ? AND org_no = ?",
    buildParams("admin%", "0000"),
@@ -135,22 +63,22 @@ List<Account> accounts = jdbcTemplate.query(
    }
 );

-// 查询列表（单列）
+// 1.2 查询列表（单列）
 List<String> usernames = jdbcTemplate.queryList(
    "SELECT username FROM account WHERE deleted = 0 AND username LIKE ? AND org_no = ?",
    buildParams("admin%", "0000"),
    String.class
 );

-// 查询列表（使用 DefaultBeanRowMapper 进行映射）
-List<Account> accounts = jdbcTemplate.queryList(
+// 1.3 查询列表（使用内置 Bean 映射）
+List<Account> mappedAccounts = jdbcTemplate.queryList(
    "SELECT * FROM account WHERE deleted = 0 AND username LIKE ? AND org_no = ?",
    buildParams("admin%", "0000"),
    RowMapper.beanRowMapper(Account.class)
 );

-// 查询列表（使用自定义 RowMapper 进行映射）
-List<Account> accounts = jdbcTemplate.queryList(
+// 1.4 查询列表（使用自定义 RowMapper 映射）
+List<Account> customMappedAccounts = jdbcTemplate.queryList(
    "SELECT * FROM account WHERE deleted = 0 AND username LIKE ? AND org_no = ?",
    buildParams("admin%", "0000"),
    (rs, rowNum) -> new Account(
@@ -163,57 +91,55 @@ List<Account> accounts = jdbcTemplate.queryList(
    )
 );

-// 查询一行数据
+// 1.5 查询单行数据
 Optional<Account> account = jdbcTemplate.queryFirst(
    "SELECT * FROM account WHERE deleted = 0 AND id = ?",
    buildParams(10000L),
    (rs, rowNum) -> new Account(
        rs.getLong("id"),
-        rs.getString("username"),
-        rs.getString("password"),
-        rs.getString("org_no"),
-        rs.getTimestamp("create_time"),
-        rs.getTimestamp("update_time")
+        rs.getString("username")
+        // ... 省略其他字段
    )
 );

-// 查询 boolean
+// 1.6 查询 Boolean 值
 boolean exists = jdbcTemplate.queryBoolean(
    "SELECT EXISTS(SELECT 1 FROM account WHERE deleted = 0 AND id = ?)",
    buildParams(10000L)
 );

-// 无参数 SQL 可直接省略 params
+// 1.7 无参数 SQL 可直接省略 params 参数
 List<Account> allAccounts = jdbcTemplate.queryList(
    "SELECT * FROM account WHERE deleted = 0",
    RowMapper.beanRowMapper(Account.class)
 );
 ```

-### 6.2 更新
+### 2. 更新操作

 ```java
-// 执行 DML
+// 2.1 执行常规 DML
 int affectedRows = jdbcTemplate.update(
    "UPDATE account SET deleted = 1 WHERE id = ?",
    buildParams(10000L)
 );

-// 执行 DML，并获取生成的主键
+// 2.2 执行 DML 并获取生成的主键
+// 注：按 JDBC 规范可获取自增 ID，能否获取其他值取决于具体数据库及其 JDBC Driver 实现。
 List<Pair<Long, LocalDateTime>> keys = jdbcTemplate.updateAndReturnKeys(
    "INSERT INTO account (username, password, org_no) VALUES (?, ?, ?)",
    buildParams("admin", "123456", "0000"),
    (rs, rowNum) -> Pair.of(
-      rs.getLong("id"),
-      rs.getObject("create_time", LocalDateTime.class)
+        rs.getLong("id"),
+        rs.getObject("create_time", LocalDateTime.class)
    )
 );
 ```

-### 6.3 批量更新
+### 3. 批量更新操作

 ```java
-// 默认：遇错即中断
+// 3.1 默认模式：遇错即中断
 BatchUpdateResult result = jdbcTemplate.batchUpdate(
    "INSERT INTO account (username, password, org_no) VALUES (?, ?, ?)",
    buildBatchParams(accountList, account -> buildParams(
@@ -221,11 +147,11 @@ BatchUpdateResult result = jdbcTemplate.batchUpdate(
        account.getPassword(),
        account.getOrgNo()
    )),
-    100 // 每 100 条数据一个批次
+    100 // 每 100 条数据为一个批次
 );

-// 静默模式：遇错不中断，全部执行完毕后统一检查结果
-BatchUpdateResult result = jdbcTemplate.batchUpdate(
+// 3.2 静默模式：遇错不中断，全部执行完毕后统一检查
+BatchUpdateResult quietResult = jdbcTemplate.batchUpdate(
    "INSERT INTO account (username, password, org_no) VALUES (?, ?, ?)",
    buildBatchParams(accountList, account -> buildParams(
        account.getUsername(),
@@ -236,27 +162,29 @@ BatchUpdateResult result = jdbcTemplate.batchUpdate(
    true // quietly = true，遇错不中断
 );

-// 检查批量更新结果
-if (result.getStatus() == BatchUpdateStatus.COMPLETED_WITH_ERRORS) {
-    for (int idx : result.getErrorBatchIndexes()) {
-        BatchUpdateErrorInfo err = result.getBatchUpdateErrorInfo(idx);
+// 3.3 检查批量更新结果
+if (quietResult.getStatus() == BatchUpdateStatus.COMPLETED_WITH_ERRORS) {
+    for (int idx : quietResult.getErrorBatchIndexes()) {
+        BatchUpdateErrorInfo err = quietResult.getBatchUpdateErrorInfo(idx);
        System.err.println("批次 " + idx + " 失败: " + err.getCause().getMessage());
    }
 }
 ```

-### 6.4 事务
+### 4. 事务管理

 ```java
+// 4.1 自动提交/回滚事务
 jdbcTemplate.transaction().execute(jdbc -> {
    ...
    jdbc.update(...);
    ...
    jdbc.update(...);
    ...
-    // 无异常则自动提交
+    // 内部无异常抛出则自动提交，抛出异常则自动回滚
 });

+// 4.2 根据返回值控制事务
 jdbcTemplate.transaction().commitIfTrue(jdbc -> {
    ...
    jdbc.update(...);
@@ -278,8 +206,112 @@ jdbcTemplate.transaction().commitIfTrue(jdbc -> {
 });
 ```

-> **！！！本项目不比成熟的工具，如若使用请自行承担风险。**
->
-> - **线程安全**：`SimpleJdbcTemplate` 无内部状态，线程安全。但所依赖的 `DataSource` 需自行保证线程安全。
-> - **连接管理**：每次操作自动从 `DataSource` 获取连接并在操作完成后关闭，无需手动管理。
-> - **适用场景**：不适合高并发或大数据量场景，建议仅用于学习参考或小型项目。
+---
+
+## 🛠️ 参数构建
+
+为避免与数组产生歧义并规范 API 设计，`JdbcOperations` 中的所有方法均不使用可变长参数（Varargs），而是统一使用 `Object[]` 作为参数传递。您可以使用内置的 `ParamBuilder` 快速构建参数。
+
+### 1. 构建单条参数列表
+
+使用 `ParamBuilder.buildParams(...)` 构建 `Object[]`。该方法会自动将 `Optional` 值进行拆箱处理。
+
+```java
+import static xyz.zhouxy.jdbc.ParamBuilder.buildParams;
+
+buildParams("admin%", "0000");           // 返回 Object[]{"admin%", "0000"}
+buildParams(Optional.of("hello"));       // 返回 Object[]{"hello"}
+buildParams(Optional.empty());           // 返回 Object[]{null}
+```
+
+### 2. 批量构建参数列表
+
+使用 `ParamBuilder.buildBatchParams(collection, func)` 将集合中的每个元素转换为 `Object[]`，最终返回 `List<Object[]>`。
+
+```java
+import static xyz.zhouxy.jdbc.ParamBuilder.buildBatchParams;
+import static xyz.zhouxy.jdbc.ParamBuilder.buildParams;
+
+List<Object[]> batchParams = buildBatchParams(accountList, account -> buildParams(
+    account.getUsername(),
+    account.getPassword(),
+    account.getOrgNo()
+));
+```
+
+---
+
+## 🔍 数据查询 (Query)
+
+### 查询方法列表
+
+| 方法签名 | 说明 |
+| :--- | :--- |
+| `query(sql, params, resultHandler)` | 最基础的查询，通过 `ResultHandler` 自定义完整的映射逻辑。 |
+| `queryList(sql, params, rowMapper)` | 查询列表，通过 `RowMapper` 逐行映射。 |
+| `queryList(sql, params, Class)` | 单列查询列表，每行提取第一列并转换为指定类型。 |
+| `queryList(sql, params)` | 查询列表，每行自动转换为 `Map<String, Object>`。 |
+| `queryFirst(sql, params, rowMapper)` | 查询第一行，通过 `RowMapper` 映射，返回 `Optional<T>`。 |
+| `queryFirst(sql, params, Class)` | 查询第一行第一列，返回 `Optional<T>`。 |
+| `queryFirst(sql, params)` | 查询第一行，返回 `Optional<Map<String, Object>>`。 |
+| `queryBoolean(sql, params)` | 查询第一行第一列并转换为 `boolean`，若结果为空则返回 `false`。 |
+
+*💡 提示：以上方法均有省略 `params` 的重载（如 `queryList(sql, rowMapper)`），适用于不含占位符的 SQL 语句。*
+
+### 结果映射策略
+
+- **`ResultHandler`**：处理完整的 `ResultSet`，允许自定义逻辑将结果集映射为任意类型（包括集合）。
+- **`RowMapper`**：将 `ResultSet` 中的单行数据映射为 Java 对象。内置以下默认实现：
+  - `RowMapper.HASH_MAP_MAPPER`：将每行数据映射为 `HashMap<String, Object>`。
+  - `DefaultBeanRowMapper`：将 `ResultSet` 中的一行数据映射为 Java Bean 的默认实现。使用反射获取类型信息、调用无参构造器和 `setter` 方法。**（注：实际生产中更建议针对目标类型自定义 `RowMapper` 以提升性能）**
+    - `RowMapper.beanRowMapper(Class)`：自动匹配 **属性名（小驼峰） ↔ 列名（小写蛇形）**。
+    - `RowMapper.beanRowMapper(Class, Map<String, String>)`：通过 `Map` 自定义属性名与列名映射关系。
+
+---
+
+## ✏️ 数据更新 (Update)
+
+所有更新方法同样提供了无参重载。
+
+### 更新方法列表
+
+| 方法签名 | 说明 |
+| :--- | :--- |
+| `update(sql, params)` | 执行 DML（INSERT / UPDATE / DELETE），返回受影响的行数。 |
+| `updateAndReturnKeys(sql, params, rowMapper)` | 执行 DML 并返回自动生成的键（如自增 ID），通过 `RowMapper` 进行映射。 |
+| `batchUpdate(sql, params, batchSize)` | 分批执行 DML，遇到错误立即中断。 |
+| `batchUpdate(sql, params, batchSize, quietly)` | 分批执行 DML；若 `quietly=true`，则遇到错误不中断，直至全部执行完毕。 |
+
+### 批量更新结果 (`BatchUpdateResult`)
+
+`batchUpdate` 方法返回 `BatchUpdateResult` 对象，包含以下信息：
+
+- `getStatus()`：批量更新的总状态（`SUCCESS` / `COMPLETED_WITH_ERRORS` / `INTERRUPTED`）。
+- `getTotal()`：总数据量。
+- `getBatchSize()`：批次大小
+- `getBatchCount()`：总批次数。
+- `getCompleteBatchCount()`：已完成的批次数。
+- `getSuccessBatchCount()` / `getErrorBatchCount()`：成功 / 失败的批次数。
+- `getRemainingBatchCount()`：（中断后）未执行的剩余批次数。
+- `getUpdateCounts(batchIndex)`：获取指定批次更新结果。
+- `getErrorBatchIndexes()`：获取所有出错的批次号.
+- `getBatchUpdateErrorInfo(batchIndex)`：获取指定批次的详细错误信息。
+- `getAllErrorsInfo()`：获取所有出错的批次的错误信息。
+
+---
+
+## 🔄 事务管理 (Transaction)
+
+通过 `TransactionTemplate` 管理事务，可直接实例化或通过 `SimpleJdbcTemplate.transaction()` 获取。
+
+- **`execute(consumer)`**：执行事务。传入 `ThrowingConsumer<JdbcOperations>`，若内部代码无异常抛出则自动提交，发生异常则回滚。
+- **`commitIfTrue(predicate)`**：执行事务。传入 `ThrowingPredicate<JdbcOperations>`，根据返回值决定事务走向：返回 `true` 提交，返回 `false` 或抛出异常则回滚。
+
+---
+
+## ⚠️ 注意事项与适用场景
+
+1. **风险提示**：本项目定位为轻量级工具，相较于成熟的 ORM 框架（如 MyBatis、Hibernate），其功能覆盖面和生态相对有限。**在生产环境使用前，请务必进行充分的测试，使用风险自行承担。**
+2. **线程安全**：`SimpleJdbcTemplate` 本身无内部状态，是**线程安全**的。但请确保其底层依赖的 `DataSource`（如 HikariCP、Druid 等连接池）已正确配置并保证线程安全。
+3. **连接管理**：每次数据库操作均会自动从 `DataSource` 获取连接，并在操作完成（或发生异常）后自动关闭，开发者无需手动管理连接的释放。
+4. **适用场景**：中小型项目、内部工具、快速原型开发、未引入 ORM 框架的遗留系统改造、学习 JDBC 原理。
--- a/pom.xml
+++ b/pom.xml
@@ -5,7 +5,7 @@

    <groupId>xyz.zhouxy.jdbc</groupId>
    <artifactId>simple-jdbc</artifactId>
-    <version>1.0.0-SNAPSHOT</version>
+    <version>1.0.0-RC3</version>

    <name>Simple JDBC</name>
    <description>对 JDBC 的简单封装。</description>
--- a/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java
+++ b/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java
@@ -42,7 +42,7 @@ import xyz.zhouxy.plusone.commons.annotation.StaticFactoryMethod;
 * DefaultBeanRowMapper
 *
 * <p>
- * 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。
+ * 将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper} 的基础实现。
 * </p>
 *
 * <p>
--- a/src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java
+++ b/src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java
@@ -37,7 +37,7 @@ import java.util.List;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;

-import com.google.common.collect.Lists;
+import xyz.zhouxy.plusone.commons.util.ArrayTools;

 /**
 * JdbcOperationSupport
@@ -162,9 +162,16 @@ class JdbcOperationSupport {
            throws SQLException {
        assertConnectionNotNull(conn);
        assertSqlNotNull(sql);
-        try (PreparedStatement stmt = conn.prepareStatement(sql)) {
-            fillStatement(stmt, params);
-            return stmt.executeUpdate();
+        if (ArrayTools.isNotEmpty(params)) {
+            try (PreparedStatement stmt = conn.prepareStatement(sql)) {
+                fillStatement(stmt, params);
+                return stmt.executeUpdate();
+            }
+        }
+        else {
+            try (Statement stmt = conn.createStatement()) {
+                return stmt.executeUpdate(sql);
+            }
        }
    }

@@ -184,18 +191,24 @@ class JdbcOperationSupport {
        assertConnectionNotNull(conn);
        assertSqlNotNull(sql);
        assertRowMapperNotNull(rowMapper);
-        final List<T> result = Lists.newArrayListWithCapacity(4);
-        try (PreparedStatement stmt = conn.prepareStatement(sql, Statement.RETURN_GENERATED_KEYS)) {
-            fillStatement(stmt, params);
-            stmt.executeUpdate();
-            try (ResultSet generatedKeys = stmt.getGeneratedKeys()) {
-                int rowNumber = 0;
-                while (generatedKeys.next()) {
-                    T e = rowMapper.mapRow(generatedKeys, rowNumber++);
-                    result.add(e);
+        if (ArrayTools.isNotEmpty(params)) {
+            try (PreparedStatement stmt = conn.prepareStatement(sql, Statement.RETURN_GENERATED_KEYS)) {
+                fillStatement(stmt, params);
+                stmt.executeUpdate();
+                try (ResultSet generatedKeys = stmt.getGeneratedKeys()) {
+                    final ResultHandler<List<T>> resultHandler = ResultHandler.mapToList(rowMapper);
+                    return resultHandler.handle(generatedKeys);
+                }
+            }
+        }
+        else {
+            try (Statement stmt = conn.createStatement()) {
+                stmt.executeUpdate(sql, Statement.RETURN_GENERATED_KEYS);
+                try (ResultSet generatedKeys = stmt.getGeneratedKeys()) {
+                    final ResultHandler<List<T>> resultHandler = ResultHandler.mapToList(rowMapper);
+                    return resultHandler.handle(generatedKeys);
                }
            }
-            return result;
        }
    }

@@ -295,9 +308,17 @@ class JdbcOperationSupport {
                                       @Nullable Object[] params,
                                       @Nonnull ResultHandler<T> resultHandler)
            throws SQLException {
-        try (PreparedStatement stmt = createPreparedStatementInternal(conn, sql, params);
-             ResultSet rs = stmt.executeQuery()) {
-            return resultHandler.handle(rs);
+        if (ArrayTools.isNotEmpty(params)) {
+            try (PreparedStatement stmt = createPreparedStatementInternal(conn, sql, params);
+                 ResultSet rs = stmt.executeQuery()) {
+                return resultHandler.handle(rs);
+            }
+        }
+        else {
+            try (Statement stmt = conn.createStatement();
+                 ResultSet rs = stmt.executeQuery(sql)) {
+                return resultHandler.handle(rs);
+            }
        }
    }

@@ -324,15 +345,7 @@ class JdbcOperationSupport {
                                                 @Nullable Object[] params,
                                                 @Nonnull RowMapper<T> rowMapper)
            throws SQLException {
-        return queryInternal(conn, sql, params, rs -> {
-            List<T> result = Lists.newArrayList();
-            int rowNumber = 0;
-            while (rs.next()) {
-                T e = rowMapper.mapRow(rs, rowNumber++);
-                result.add(e);
-            }
-            return result;
-        });
+        return queryInternal(conn, sql, params, ResultHandler.mapToList(rowMapper));
    }

    /**
--- a/src/main/java/xyz/zhouxy/jdbc/ParamBuilder.java
+++ b/src/main/java/xyz/zhouxy/jdbc/ParamBuilder.java
@@ -17,6 +17,7 @@
 package xyz.zhouxy.jdbc;

 import java.sql.PreparedStatement;
+import java.time.temporal.Temporal;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
@@ -51,24 +52,41 @@ public class ParamBuilder {
            return EMPTY_OBJECT_ARRAY;
        }
        return Arrays.stream(params)
-                .map(param -> {
-                    if (param instanceof Optional) {
-                        return OptionalTools.orElseNull((Optional<?>) param);
-                    }
-                    if (param instanceof OptionalInt) {
-                        return OptionalTools.toInteger((OptionalInt) param);
-                    }
-                    if (param instanceof OptionalLong) {
-                        return OptionalTools.toLong((OptionalLong) param);
-                    }
-                    if (param instanceof OptionalDouble) {
-                        return OptionalTools.toDouble((OptionalDouble) param);
-                    }
-                    return param;
-                })
+                .map(ParamBuilder::handleItem)
                .toArray();
    }

+    private static Object handleItem(Object param) {
+        if (param == null) {
+            return null;
+        }
+        if (param instanceof CharSequence) {
+            return param.toString();
+        }
+        if (param instanceof Number) {
+            return param;
+        }
+        if (param instanceof Boolean) {
+            return param;
+        }
+        if (param instanceof Temporal) {
+            return param;
+        }
+        if (param instanceof Optional) {
+            return OptionalTools.orElseNull((Optional<?>) param);
+        }
+        if (param instanceof OptionalInt) {
+            return OptionalTools.toInteger((OptionalInt) param);
+        }
+        if (param instanceof OptionalLong) {
+            return OptionalTools.toLong((OptionalLong) param);
+        }
+        if (param instanceof OptionalDouble) {
+            return OptionalTools.toDouble((OptionalDouble) param);
+        }
+        return param;
+    }
+
    public static <T> List<Object[]> buildBatchParams(final Collection<T> c, final Function<T, Object[]> func) {
        AssertTools.checkNotNull(c, "The collection can not be null.");
        AssertTools.checkNotNull(func, "The func can not be null.");
--- a/src/main/java/xyz/zhouxy/jdbc/ResultHandler.java
+++ b/src/main/java/xyz/zhouxy/jdbc/ResultHandler.java
@@ -18,6 +18,8 @@ package xyz.zhouxy.jdbc;

 import java.sql.ResultSet;
 import java.sql.SQLException;
+import java.util.ArrayList;
+import java.util.List;

 /**
 * ResultHandler
@@ -41,4 +43,26 @@ public interface ResultHandler<T> {
     * @throws SQLException 数据库执行异常
     */
    T handle(ResultSet resultSet) throws SQLException;
+
+    /**
+     * 创建一个返回 {@link List} 的 {@link ResultHandler}，将 {@link ResultSet} 中的每一行
+     * 通过指定的 {@link RowMapper} 映射为对象，最终收集为一个 {@link List}。
+     *
+     * @param <T>        列表元素类型
+     * @param rowMapper  行映射器，用于将 {@link ResultSet} 的单行转换为对象
+     * @return 返回 {@code List<T>} 的 {@code ResultHandler}
+     * @since 1.0.0
+     * @see RowMapper
+     */
+    static <T> ResultHandler<List<T>> mapToList(RowMapper<T> rowMapper) {
+        return resultSet -> {
+            List<T> result = new ArrayList<>();
+            int rowNumber = 0;
+            while (resultSet.next()) {
+                T e = rowMapper.mapRow(resultSet, rowNumber++);
+                result.add(e);
+            }
+            return result;
+        };
+    }
 }
--- a/src/test/java/xyz/zhouxy/jdbc/test/UpdateTest.java
+++ b/src/test/java/xyz/zhouxy/jdbc/test/UpdateTest.java
@@ -21,6 +21,8 @@ import xyz.zhouxy.jdbc.SimpleJdbcTemplate;

 /**
 * 更新 API 测试：update、updateAndReturnKeys。
+ *
+ * <p>内部按 PreparedStatement（有参数）和 Statement（无参数）路径组织。</p>
 */
@DisplayName("SimpleJdbcTemplate 更新操作")
 class UpdateTest extends BaseH2Test {
@@ -33,6 +35,7 @@ class UpdateTest extends BaseH2Test {
    }

    // ==================== update ====================
+    // --- PreparedStatement 路径（有参数） ---

    @Test
    @DisplayName("update：INSERT 操作返回影响行数 1")
@@ -121,54 +124,18 @@ class UpdateTest extends BaseH2Test {
    }

    @Test
-    @DisplayName("update：DELETE 全表")
-    void testUpdateDeleteAll() throws SQLException {
-        SimpleJdbcTemplate template = createTemplate();
-
-        int rows = template.update("DELETE FROM users");
-
-        logger.info("DELETE 全表影响行数: {}", rows);
-        assertEquals(5, rows);
-
-        // 验证表为空
-        int count = template.query("SELECT COUNT(*) FROM users",
-                rs -> { rs.next(); return rs.getInt(1); });
-        assertEquals(0, count);
-    }
-
-    @Test
-    @DisplayName("update：null 参数数组")
-    void testUpdateWithNullParams() throws SQLException {
+    @DisplayName("update：参数中包含 null 元素")
+    void testUpdateWithNullElement() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

        int rows = template.update(
                "DELETE FROM users WHERE username = ?",
                new Object[]{ null });

-        // 因为 DELETE ? 中参数 null 不会匹配任何行
+        // 参数 null 不匹配任何行
        assertEquals(0, rows);
    }

-    @Test
-    @DisplayName("update：无参数重载")
-    void testUpdateNoParams() throws SQLException {
-        SimpleJdbcTemplate template = createTemplate();
-
-        int rows = template.update(
-                "UPDATE users SET balance = 9999 WHERE username = 'alice'");
-
-        assertEquals(1, rows);
-    }
-
-    @Test
-    @DisplayName("update：语法错误抛出 SQLException")
-    void testUpdateInvalidSql() {
-        SimpleJdbcTemplate template = createTemplate();
-
-        assertThrows(SQLException.class, () ->
-                template.update("UPDAT users SET x = 1"));
-    }
-
    @Test
    @DisplayName("update：使用 Instant 类型参数填充 TIMESTAMP 列")
    void testUpdateWithInstantParam() throws SQLException {
@@ -195,7 +162,56 @@ class UpdateTest extends BaseH2Test {
        assertEquals(java.sql.Timestamp.from(now), stored);
    }

+    // --- update / Statement 路径（无参数） ---
+
+    @Test
+    @DisplayName("update：无参数重载")
+    void testUpdateNoParams() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        int rows = template.update(
+                "UPDATE users SET balance = 9999 WHERE username = 'alice'");
+
+        assertEquals(1, rows);
+    }
+
+    @Test
+    @DisplayName("update：DELETE 全表（无参数）")
+    void testUpdateDeleteAll() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        int rows = template.update("DELETE FROM users");
+
+        logger.info("DELETE 全表影响行数: {}", rows);
+        assertEquals(5, rows);
+
+        // 验证表为空
+        int count = template.query("SELECT COUNT(*) FROM users",
+                rs -> { rs.next(); return rs.getInt(1); });
+        assertEquals(0, count);
+    }
+
+    @Test
+    @DisplayName("update：params 为 null，走 Statement 路径")
+    void testUpdateWithParamsNull() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        int rows = template.update("DELETE FROM users", (Object[]) null);
+
+        assertEquals(5, rows);
+    }
+
+    @Test
+    @DisplayName("update：语法错误抛出 SQLException")
+    void testUpdateInvalidSql() {
+        SimpleJdbcTemplate template = createTemplate();
+
+        assertThrows(SQLException.class, () ->
+                template.update("UPDAT users SET x = 1"));
+    }
+
    // ==================== updateAndReturnKeys ====================
+    // --- PreparedStatement 路径（有参数） ---

    @Test
    @DisplayName("updateAndReturnKeys：INSERT 返回自增主键")
@@ -231,6 +247,8 @@ class UpdateTest extends BaseH2Test {
        assertEquals(2, keys.size());
    }

+    // --- updateAndReturnKeys / Statement 路径（无参数） ---
+
    @Test
    @DisplayName("updateAndReturnKeys：无参数重载")
    void testUpdateAndReturnKeysNoParams() throws SQLException {
@@ -243,4 +261,18 @@ class UpdateTest extends BaseH2Test {
        assertEquals(1, keys.size());
        assertTrue(keys.get(0) > 0);
    }
+
+    @Test
+    @DisplayName("updateAndReturnKeys：params 为 null，走 Statement 路径")
+    void testUpdateAndReturnKeysWithParamsNull() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        RowMapper<Long> rowMapper = (rs, rowNumber) -> rs.getLong(1);
+        List<Long> keys = template.updateAndReturnKeys(
+                "INSERT INTO users (username) VALUES ('null_test')",
+                null, rowMapper);
+
+        assertEquals(1, keys.size());
+        assertTrue(keys.get(0) > 0);
+    }
 }
Author	SHA1	Message	Date
ZhouXY108	24ed544f97	build: 升级版本至 1.0.0-RC3	2026-06-05 21:30:21 +08:00
ZhouXY108	8b4f5bac65	test: 重构测试类 `UpdateTest`，补全 Statement 路径覆盖 - 按 update / updateAndReturnKeys 分组，内部再按 PreparedStatement （有参数）和 Statement（无参数）子路径组织，提升可维护性 - 重命名 3 个测试方法以消除歧义： testUpdateWithNullParams → testUpdateWithNullElement testUpdateWithParamsIsNull → testUpdateWithParamsNull testUpdateAndReturnKeysWithParamsIsNull → testUpdateAndReturnKeysWithParamsNull - 新增 2 个测试用例补全 params=null 的 Statement 路径覆盖： testUpdateWithParamsNull testUpdateAndReturnKeysWithParamsNull	2026-06-05 21:17:12 +08:00
ZhouXY108	486d0c98c7	fix: 修复 `updateAndReturnKeys` 执行无参 SQL 无法获取生成的 key 的问题	2026-06-05 21:12:25 +08:00
ZhouXY108	f5909818c3	refactor: `JdbcOperationSupport` 中无参数 SQL 改用 `Statement` 执行 update、updateAndReturnKeys、queryInternal 三个方法根据是否有参数，分别走 PreparedStatement（有参数）或 Statement（无参数），避免无参数时不必要的预编译开销	2026-06-05 20:49:17 +08:00
ZhouXY108	3753aafd61	refactor: 提取 ResultHandler.mapToList 消除 ResultSet 遍历重复代码	2026-06-05 20:28:16 +08:00
ZhouXY108	f323d04d57	refactor: `ParamBuilder#buildParams` 中为常用数据类型添加短路处理提取 buildParams 中的 lambda 为 handleItem 方法，并在 Optional 系列检测之前，为 null、CharSequence、Number、Boolean、Temporal 等高频类型增加提前返回逻辑，提升批量参数构建时的处理效率。附带行为变化：CharSequence 实现类（如 StringBuilder/StringBuffer）现在会通过 toString() 转为 String 后再传递。	2026-06-05 20:08:08 +08:00
ZhouXY108	eabd5d7f77	docs: 更新项目简介	2026-06-02 23:31:24 +08:00
ZhouXY108	152094029e	docs: 更新 `DefaultBeanRowMapper` 的描述以避免歧义	2026-06-02 23:21:26 +08:00
ZhouXY108	5b643291eb	docs: 更新 README.md	2026-06-02 23:21:12 +08:00