refactor: 将单列查询 Class 重载标记为过时，新增语义明确的方法

- 新增 queryValues(sql, args, Class) 替代 queryList(sql, args, Class) - 新增 queryValue(sql, args, Class) 替代 queryFirst(sql, args, Class) - 新增 queryValueOrDefault(sql, args, Class, defaultVal) 聚合查询便捷方法 - 旧方法标记 @Deprecated，委托至新方法，后续版本移除 - 更新 README 方法列表和示例代码 - 补充 queryValueOrDefault 单元测试 6 个
docs: 更新设计考量章节标题并补充内容
2026-06-18 02:58:43 +08:00 · 2026-06-18 02:52:37 +08:00 · 2026-06-18 02:41:10 +08:00 · 2026-06-17 23:27:43 +08:00 · 2026-06-17 21:24:03 +08:00 · 2026-06-17 21:16:38 +08:00
27 changed files with 2871 additions and 519 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,141 @@
+# Changelog
+
+## [1.1.0] - Unreleased
+
+### ⚠️ 破坏性变更
+
+- **`DefaultBeanRowMapper.of()` 不再抛出 `SQLException`**：工厂方法在反射异常时改为抛出非受检异常 `IllegalStateException`。调用方如果 `catch (SQLException e)` 包裹 `of()` 调用，该捕获将失效，需移除相关 `catch` 块或改为捕获 `IllegalStateException`。
+
+### 新增
+
+- `queryValueOrDefault(sql, params, Class<T>, T defaultValue)`：查询单行单列，结果为空时返回指定默认值
+- `queryValueOrDefault(sql, Class<T>, T defaultValue)`：无参数重载
+- 补充 `QueryTest` 中 `queryValueOrDefault` 单元测试 6 个
+
+### 重构
+
+**将单列查询方法标记为过时，消除 Class 参数重载歧义**
+
+- `queryList(sql, params, Class<T>)` → 已过时，请使用 `queryValues(sql, params, Class<T>)`
+  语义明确为"多行单列 → 值列表"，不与整行 `RowMapper` 重载混淆
+- `queryFirst(sql, params, Class<T>)` → 已过时，请使用 `queryValue(sql, params, Class<T>)`
+  语义明确为"单行单列 → 单值"，不与整行 `RowMapper` 重载混淆
+- 同时将对应的无参数重载标记为过时：
+  - `queryList(sql, Class<T>)` → 请使用 `queryValues(sql, Class<T>)`
+  - `queryFirst(sql, Class<T>)` → 请使用 `queryValue(sql, Class<T>)`
+- 旧方法将在后续版本中移除
+
+### 文档
+
+- 优化 `DefaultBeanRowMapper` 类注释，明确性能限制和使用建议
+
+---
+
+## [1.0.0] - 2026-06-17
+
+### 重构
+- 移除 `plusone-commons` 及 Guava 依赖，内化 `AssertTools`、`NamingTools`、`ThrowingConsumer`、`ThrowingPredicate` 工具类
+- 将 `batchUpdate` 中断时对 `BatchUpdateResult` 的变更逻辑内化到 `BatchUpdateResult` 中
+
+### 测试
+- 添加 `ParamBuilderTest#buildParamsTemporal` 测试方法验证时间类型参数构建
+- 添加 `TransactionTest` 事务异常测试用例
+- 补充测试数据库初始化脚本注释
+
+### 文档
+- 新增 `CHANGELOG.md` 文件记录各版本更新内容
+- 优化 README 文档结构与内容
+- 补充 `ParamBuilder` 和 `SimpleJdbcTemplate` 的文档注释
+- 更新 `DefaultBeanRowMapper` 类文档注释，强调使用场景
+
+---
+
+## [1.0.0-RC3] - 2026-06-05
+
+### 新增
+- `ResultHandler` 新增静态工厂方法 `mapToList(RowMapper)`，消除各处 `ResultSet` 遍历重复代码
+
+### 重构
+- `JdbcOperationSupport` 中无参数 SQL 统一改用 `Statement` 执行，避免创建空参数 `PreparedStatement`
+- `ParamBuilder#buildParams` 为常用数据类型（`CharSequence`/`Number`/`Boolean`/`Temporal`）添加短路处理，优化参数构建性能
+
+### 测试
+- 重构 `UpdateTest`，补全 `Statement` 路径覆盖
+
+### 文档
+- 更新 README.md 使用说明和示例
+- 更新 `DefaultBeanRowMapper` 类文档以避免歧义
+- 更新项目简介
+
+---
+
+## [1.0.0-RC2] - 2026-05-31
+
+### 新增
+- `TransactionTemplate` 从 `SimpleJdbcTemplate` 中分离为独立类，封装事务生命周期管理（开启/提交/回滚/恢复自动提交）
+- `SimpleJdbcTemplate.transaction()` 暴露 `TransactionTemplate` 实例
+- 新增 `ParamBuilderTest` 单元测试
+- 新增 `Instant` 类型参数端到端测试
+
+### 重构
+- 简化 `ParamBuilder` 参数构建逻辑
+- 优化批量更新批次内索引计算逻辑
+
+### 文档
+- 完善 `SimpleJdbcTemplate` 类文档注释
+- 更新批量更新相关类（`BatchUpdateResult`/`BatchUpdateStatus`/`BatchUpdateErrorInfo`）的 JavaDoc
+- 更新 README 使用说明和示例
+
+### 其他
+- 版权年份由固定范围更新为包含当前时间的表述
+
+---
+
+## [1.0.0-RC1] - 2026-05-29
+
+项目首个正式发布的候选版本（2023-07 从 plusone-commons 独立开发）。
+
+### 新增
+
+**核心框架**
+- `SimpleJdbcTemplate` 核心模板类，封装 JDBC 连接管理、异常处理和资源释放
+- `JdbcOperations` 接口规范，定义统一的数据库操作 API
+- `JdbcOperationSupport` 静态工具类，封装底层 `PreparedStatement` / `Statement` 操作
+
+**查询**
+- `query` + `ResultHandler`：自定义 `ResultSet` 处理
+- `queryList`：返回列表（支持 `RowMapper`、`Class`、`Map<String, Object>` 三种变体）
+- `queryFirst`：返回 `Optional<T>`（支持 `RowMapper`、`Class`、`Map<String, Object>` 三种变体）
+- `queryBoolean`：返回 `boolean`，结果集为空时返回 `false`
+- 全部查询方法提供无参数重载
+
+**更新**
+- `update`：执行 INSERT / UPDATE / DELETE，返回影响行数
+- `updateAndReturnKeys`：执行 DML 并返回自动生成的主键，支持 `RowMapper` 映射
+- `batchUpdate`：分批执行 DML，支持非静默模式（遇错中断）和静默模式（遇错继续）
+
+**批量更新结果**
+- `BatchUpdateResult`：封装批次级粒度的执行结果（总数据量、批次计数、成功/失败/剩余批次）
+- `BatchUpdateStatus` 枚举（SUCCESS / COMPLETED_WITH_ERRORS / INTERRUPTED）
+- `BatchUpdateErrorInfo`：封装错误批次的异常详情
+
+**参数构建**
+- `ParamBuilder.buildParams`：构建 `Object[]` 参数数组，支持 `Optional` / `OptionalInt` / `OptionalLong` / `OptionalDouble` 自动拆箱
+- `ParamBuilder.buildBatchParams`：批量构建 `List<Object[]>` 参数列表
+
+**映射策略**
+- `RowMapper` 函数式接口：`ResultSet` 单行映射
+- `RowMapper.HASH_MAP_MAPPER`：将行数据映射为 `Map<String, Object>`
+- `DefaultBeanRowMapper`：默认 Bean 映射实现，自动匹配 属性名（小驼峰）↔ 列名（小写蛇形），通过反射调用 setter
+- `RowMapper.beanRowMapper(Class)` / `beanRowMapper(Class, Map)` 静态工厂方法
+
+**事务**
+- `TransactionException`：包装事务执行中的原始异常
+- `commitIfTrue` 方法：根据业务逻辑返回值（true 提交 / false 回滚）控制事务
+
+**测试**
+- 基于 H2 内存数据库的集成测试体系
+- 覆盖查询 / 更新 / 批量 / 事务 / RowMapper 全场景
+
+**许可**
+- Apache License 2.0
--- a/22
+++ b/22
@@ -5,36 +5,20 @@ This product is licensed under the Apache License, Version 2.0.
 You may obtain a copy of the License at:
 https://www.apache.org/licenses/LICENSE-2.0

-================================================================================
-Third-Party Dependencies
-================================================================================
-
-1. plusone-commons (xyz.zhouxy.plusone:plusone-commons)
-   Copyright ZhouXY
-   Licensed under the Apache License, Version 2.0
-
-2. Google Guava (com.google.guava:guava)
-   Copyright (C) The Guava Authors
-   Licensed under the Apache License, Version 2.0
-
-3. JSR-305 Annotations (com.google.code.findbugs:jsr305)
-   Copyright (C) FindBugs
-   Licensed under the Apache License, Version 2.0
-
 ================================================================================
 Test Dependencies (Not included in distribution)
 ================================================================================

-4. JUnit Jupiter (org.junit.jupiter:junit-jupiter)
+1. JUnit Jupiter (org.junit.jupiter:junit-jupiter)
   Copyright 2015-2026 JUnit Team
   Licensed under the Eclipse Public License 2.0

-5. Logback (ch.qos.logback:logback-classic)
+2. Logback (ch.qos.logback:logback-classic)
   Copyright (C) 1999-2026, QOS.ch
   Licensed under the Eclipse Public License 1.0
   and GNU Lesser General Public License 2.1

-6. H2 Database (com.h2database:h2)
+3. H2 Database (com.h2database:h2)
   Copyright 1999-2026 H2 Database Project
   Licensed under the MPL 2.0 and EPL 1.0

--- a/README.md
+++ b/README.md
@@ -1,64 +1,68 @@
-# SimpleJDBC
+# Simple JDBC

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

-之前遇到的一个老项目，没有引入任何 ORM 框架，对数据库的操作几乎都在写原生 JDBC。故自己写了几个工具类，对 JDBC 进行简单封装。
+> 注：本项目基于 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 开源协议发布。

-## 查询
+---

-### 查询方法
+## 1. 核心特性

- `query`：**最基础的查询方法**。可使用 `ResultHandler` 将查询结果映射为 Java 对象。
- `queryList`：**查询列表**。可使用 `RowMapper` 将结果的每一行数据映射为 Java 对象，返回列表。
- `queryFirst`：**查询，并获取第一行数据**。一般可以结合 `LIMIT 1` 使用。可使用 `RowMapper` 将结果的第一行数据映射为 Java 对象，返回 `Optional`。
- `queryBoolean`：**获取第一行数据的第一个字段，并转换为布尔类型**。如果结果为空，则返回 `false`。
+- **轻量无依赖**：基于原生 JDBC 封装，无第三方重量级依赖。
+- **API 简洁**：提供丰富的快捷方法，大幅减少样板代码。
+- **灵活的映射**：支持自定义 `ResultHandler` 与 `RowMapper`，内置默认 Bean 映射策略。
+- **事务与批处理**：提供声明式的事务模板与完善的批量更新错误处理机制。
+- **线程安全**：核心模板类无状态设计，天然支持多线程环境。

-### 结果映射
+---

- `ResultHandler` 用于处理查询结果，自定义逻辑将完整的 `ResultSet` 映射为 Java 对象。 *结果可以是任意类型（包括集合）。*
- `RowMapper` 用于将 `ResultSet` 中的一行数据映射为 Java 对象。
-  - `RowMapper#HASH_MAP_MAPPER`：将 `ResultSet` 中的一行数据映射为 `HashMap`。
-  - `RowMapper#beanRowMapper`：返回将 `ResultSet` 转换为 Java Bean 的默认实现。
+## 2. 设计考量与取舍

-## 更新
+`Simple JDBC` 不追求大而全，在功能设计上保持克制。以下是本项目的一些设计考量与取舍：

- `int update`：**执行 DML**，包括 `INSERT`、`UPDATE`、`DELETE` 等。返回受影响行数。
- `<T> List<T> update`：**执行 DML**，自动生成的字段将使用 `rowMapper` 进行映射，并返回列表。
- `List<int[]> batchUpdate`：**分批次执行 DML**，返回分批执行的结果。
+- 明确**不支持存储过程**：专注于基础 CRUD。
+- **不提供分页 API**：不同数据库的分页方言差异巨大，且实际业务中的分页查询往往不是简单的 `LIMIT OFFSET`（存在如游标分页、延迟关联等深度优化空间）。为了保持轻量与灵活，分页 SQL 交由开发者根据具体数据库与业务场景自行编写。
+- **不提供缓存支持**：数据缓存应当被视为一个独立的关注点，通常交由更高层的抽象模块来处理。
+- **不支持直接传入 Connection**：为确保数据库连接资源的规范获取与安全释放，Simple JDBC 舍弃了一定的连接管理灵活性，不支持直接传入 Connection，而是需要通过 `DataSource` 来获取连接（详见[8. 连接池集成](#8-连接池集成)）。常规操作由 `SimpleJdbcTemplate` 自动完成连接的获取与归还；事务场景下，由 `TransactionTemplate` 实现连接绑定，保障同一事务内所有操作的连接一致性。
+- **有限但灵活的结果映射**：为应对多样化的数据处理需求，Simple JDBC 提供了 `ResultHandler` 与 `RowMapper` 两层抽象机制。前者负责整体结果集的统筹处理，后者专注于单行数据的解析与映射（详见 [4.2 结果映射策略](#42-结果映射策略)）。两者均设计为函数式接口，支持通过 Lambda 表达式快速定制映射逻辑。

-## 事务
+---

- `executeTransaction`：**执行事务**。传入一个 `ThrowingConsumer` 函数，入参是一个 `JdbcOperations` 对象，在 `ThrowingConsumer` 内使用该入参执行 jdbc 操作。如果 `ThrowingConsumer` 内部有异常抛出，这些操作将被回滚。
+## 3. 快速开始

- `commitIfTrue`：**执行事务**。传入一个 `ThrowingPredicate` 函数，入参是一个 `JdbcOperations` 对象，在 `ThrowingPredicate` 内使用该入参执行 jdbc 操作。如果`ThrowingPredicate` 返回 `true`，则提交事务；如果返回 `false` 或有异常抛出，则回滚这些操作。
+### 3.1 环境要求

-## 参数构建
+- **JDK 8** 或更高版本

-此项目中的所有查询和更新的方法，都**不使用可变长入参**，避免强行将 SQL 语句的参数列表放在最后，也避免和数组发生歧义。
+### 3.2 添加 Maven 依赖

-### 构建参数列表
+将以下配置添加到您的 `pom.xml` 中：

-可使用 `ParamBuilder#buildParams` 构建 `Object[]` 数组作为 SQL 的参数列表。该方法会自动将 `Optional` 中的值“拆”出来。
+```xml
+<dependency>
+    <groupId>xyz.zhouxy.jdbc</groupId>
+    <artifactId>simple-jdbc</artifactId>
+    <version>${simple-jdbc.version}</version>
+</dependency>
+```

-### 批量构建参数列表
+### 3.3 初始化

-使用 `ParamBuilder#buildBatchParams`，将使用传入的函数，将集合中的每一个元素转为 `Object[]`，并返回一个 `List<Object[]>`。
-
-## 示例
-
-创建 SimpleJdbcTemplate 对象
 ```java
 SimpleJdbcTemplate jdbcTemplate = new SimpleJdbcTemplate(dataSource);
 ```

-查询
+> 💡 关于与数据库连接池（如 HikariCP、Druid、DBCP 2 等）的集成方式，请参见「[连接池集成](#8-连接池集成)」章节。
+
+### 3.4 查询操作
+
 ```java
-// 查询（使用 ResultHandler 处理全部结果）
-List<Account> list = jdbcTemplate.query(
+// 基础查询（使用 ResultHandler 处理全部结果）
+List<Account> accounts = jdbcTemplate.query(
    "SELECT * FROM account WHERE deleted = 0 AND username LIKE ? AND org_no = ?",
    buildParams("admin%", "0000"),
    rs -> {
-        List<T> result = new ArrayList<>();
+        List<Account> result = new ArrayList<>();
        while (rs.next()) {
            result.add(new Account(
                rs.getLong("id"),
@@ -74,19 +78,21 @@ List<Account> list = jdbcTemplate.query(
 );

 // 查询列表（单列）
-List<String> usernames = jdbcTemplate.queryList(
+List<String> usernames = jdbcTemplate.queryValues(
    "SELECT username FROM account WHERE deleted = 0 AND username LIKE ? AND org_no = ?",
    buildParams("admin%", "0000"),
    String.class
 );
-// 查询列表（使用 DefaultBeanRowMapper 进行映射）
-List<Account> list = jdbcTemplate.queryList(
+
+// 查询列表（使用内置 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> list = jdbcTemplate.queryList(
+
+// 查询列表（使用自定义 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(
@@ -99,35 +105,57 @@ List<Account> list = jdbcTemplate.queryList(
    )
 );

-// 查询一行数据
+// 查询单行数据
 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.getString("username")
+        // ... 省略其他字段
    )
-)
+);

-// 查询 boolean
+// 查询单个值（所有 ResultSet.getObject 支持的类型）
+Long count = jdbcTemplate.queryValue(
+    "SELECT COUNT(*) FROM account WHERE deleted = 0 AND username LIKE ? AND org_no = ?",
+    buildParams("admin%", "0000"),
+    Long.class
+).orElse(0L);
+// 或者
+Long count = jdbcTemplate.queryValueOrDefault(
+    "SELECT COUNT(*) FROM account WHERE deleted = 0 AND username LIKE ? AND org_no = ?",
+    buildParams("admin%", "0000"),
+    Long.class,
+    0L
+);
+
+// 查询 Boolean 值
 boolean exists = jdbcTemplate.queryBoolean(
-    "SELECT EXISTS(SELECT 1 FROM account WHERE deleted = 0 AND id = ? LIMIT 1)",
+    "SELECT EXISTS(SELECT 1 FROM account WHERE deleted = 0 AND id = ?)",
    buildParams(10000L)
 );
+
+// 无参数 SQL 可直接省略 params 参数
+List<Account> allAccounts = jdbcTemplate.queryList(
+    "SELECT * FROM account WHERE deleted = 0",
+    RowMapper.beanRowMapper(Account.class)
+);
 ```

-更新
+> 📖 完整的方法列表与映射策略说明请参见「[4. 数据查询](#4-数据查询-query)」章节。
+
+### 3.5 更新操作
+
 ```java
-// 执行 DML
+// 执行常规 DML
 int affectedRows = jdbcTemplate.update(
    "UPDATE account SET deleted = 1 WHERE id = ?",
    buildParams(10000L)
 );

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

-批量更新
+> 📖 完整的方法列表与批量更新结果说明请参见「[5. 数据更新](#5-数据更新-update)」章节。
+
+### 3.6 批量更新操作
+
 ```java
+// 默认模式：遇错即中断
 BatchUpdateResult result = jdbcTemplate.batchUpdate(
    "INSERT INTO account (username, password, org_no) VALUES (?, ?, ?)",
    buildBatchParams(accountList, account -> buildParams(
@@ -147,21 +179,47 @@ BatchUpdateResult result = jdbcTemplate.batchUpdate(
        account.getPassword(),
        account.getOrgNo()
    )),
-    100 // 每100条数据一个批次
+    100 // 每 100 条数据为一个批次
 );
+
+// 静默模式：遇错不中断，全部执行完毕后统一检查
+BatchUpdateResult quietResult = jdbcTemplate.batchUpdate(
+    "INSERT INTO account (username, password, org_no) VALUES (?, ?, ?)",
+    buildBatchParams(accountList, account -> buildParams(
+        account.getUsername(),
+        account.getPassword(),
+        account.getOrgNo()
+    )),
+    100,
+    true // quietly = true，遇错不中断
+);
+
+// 检查批量更新结果
+if (quietResult.getStatus() == BatchUpdateStatus.COMPLETED_WITH_ERRORS) {
+    for (int idx : quietResult.getErrorBatchIndexes()) {
+        BatchUpdateErrorInfo err = quietResult.getBatchUpdateErrorInfo(idx);
+        System.err.println("批次 " + idx + " 失败: " + err.getCause().getMessage());
+    }
+}
 ```

-事务
+> 📖 批量更新的详细结果说明请参见「[5.2 批量更新结果](#52-批量更新结果-batchupdateresult)」章节。
+
+### 3.7 事务管理
+
 ```java
-jdbcTemplate.executeTransaction(jdbc -> {
+// 自动提交/回滚事务
+jdbcTemplate.transaction().execute(jdbc -> {
    ...
    jdbc.update(...);
    ...
    jdbc.update(...);
    ...
+    // 内部无异常抛出则自动提交，抛出异常则自动回滚
 });

-jdbcTemplate.commitIfTrue(jdbc -> {
+// 根据返回值控制事务
+jdbcTemplate.transaction().commitIfTrue(jdbc -> {
    ...
    jdbc.update(...);
    ...
@@ -182,4 +240,217 @@ jdbcTemplate.commitIfTrue(jdbc -> {
 });
 ```

->**！！！本项目不比成熟的工具，如若使用请自行承担风险。建议仅作为 JDBC 的学习参考。**
+> 📖 事务方法的详细说明请参见「[6. 事务管理](#6-事务管理-transaction)」章节。
+
+---
+
+## 4. 数据查询 (Query)
+
+### 4.1 查询方法列表
+
+| 方法签名 | 说明 |
+| :--- | :--- |
+| `query(sql, params, resultHandler)` | 最基础的查询，通过 `ResultHandler` 自定义完整的映射逻辑。 |
+| `queryList(sql, params, rowMapper)` | 查询列表，通过 `RowMapper` 逐行映射。 |
+| `queryList(sql, params)` | 查询列表，每行自动转换为 `Map<String, Object>`。 |
+| `queryFirst(sql, params, rowMapper)` | 查询第一行，通过 `RowMapper` 映射，返回 `Optional<T>`。 |
+| `queryFirst(sql, params)` | 查询第一行，返回 `Optional<Map<String, Object>>`。 |
+| `queryValues(sql, params, Class)` | 单列查询列表，每行提取第一列并转换为指定类型。 |
+| `queryValue(sql, params, Class)` | 查询第一行第一列，返回 `Optional<T>`。 |
+| `queryValueOrDefault(sql, params, Class, default)` | 查询第一行第一列，结果为空时返回默认值。适用于 COUNT/SUM 等聚合查询。 |
+| `queryBoolean(sql, params)` | 查询第一行第一列并转换为 `boolean`，若结果为空则返回 `false`。 |
+
+*💡 提示：以上方法均有省略 `params` 的重载（如 `queryList(sql, rowMapper)`），适用于不含占位符的 SQL 语句。`queryValues`、`queryValue`、`queryValueOrDefault` 同理。*
+
+### 4.2 结果映射策略
+
+- **`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` 自定义属性名与列名映射关系。
+
+---
+
+## 5. 数据更新 (Update)
+
+所有更新方法同样提供了无参重载。
+
+### 5.1 更新方法列表
+
+| 方法签名 | 说明 |
+| :--- | :--- |
+| `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`，则遇到错误不中断，直至全部执行完毕。 |
+
+### 5.2 批量更新结果 (BatchUpdateResult)
+
+`batchUpdate` 方法返回 `BatchUpdateResult` 对象，包含以下信息：
+
+- `getStatus()`：批量更新的总状态（`SUCCESS` / `COMPLETED_WITH_ERRORS` / `INTERRUPTED`）。
+- `getTotal()`：总数据量。
+- `getBatchSize()`：批次大小
+- `getBatchCount()`：总批次数。
+- `getCompleteBatchCount()`：已完成的批次数。
+- `getSuccessBatchCount()` / `getErrorBatchCount()`：成功 / 失败的批次数。
+- `getRemainingBatchCount()`：（中断后）未执行的剩余批次数。
+- `getUpdateCounts(batchIndex)`：获取指定批次更新结果。
+- `getErrorBatchIndexes()`：获取所有出错的批次号.
+- `getBatchUpdateErrorInfo(batchIndex)`：获取指定批次的详细错误信息。
+- `getAllErrorsInfo()`：获取所有出错的批次的错误信息。
+
+---
+
+## 6. 事务管理 (Transaction)
+
+通过 `TransactionTemplate` 管理事务，可直接实例化或通过 `SimpleJdbcTemplate.transaction()` 获取。
+
+事务模板的核心机制如下：
+
+- **共享连接**：事务内的所有 JDBC 操作共享同一个数据库连接，确保操作在同一事务上下文中执行。
+- **自动提交管理**：进入事务时关闭连接的自动提交模式，事务结束后恢复原始状态。
+- **异常处理**：操作中抛出异常时自动执行回滚，并将原始异常包装为 `TransactionException` 抛出。
+
+### 6.1 获取事务模板
+
+```java
+// 方式一：通过 SimpleJdbcTemplate 获取
+TransactionTemplate tx = jdbcTemplate.transaction();
+
+// 方式二：直接实例化
+TransactionTemplate tx = new TransactionTemplate(dataSource);
+```
+
+### 6.2 事务方法
+
+- **`execute(consumer)`**：执行事务。传入 `ThrowingConsumer<JdbcOperations>`，若内部代码无异常抛出则自动提交，发生异常则回滚。
+- **`commitIfTrue(predicate)`**：执行事务。传入 `ThrowingPredicate<JdbcOperations>`，根据返回值决定事务走向：返回 `true` 提交，返回 `false` 或抛出异常则回滚。
+
+---
+
+## 7. 参数构建
+
+为避免与数组产生歧义并规范 API 设计，`JdbcOperations` 中的所有方法均不使用可变长参数（Varargs），而是统一使用 `Object[]` 作为参数传递。您可以使用内置的 `ParamBuilder` 快速构建参数。
+
+### 7.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}
+```
+
+### 7.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()
+));
+```
+
+---
+
+## 8. 连接池集成
+
+`SimpleJdbcTemplate` 仅依赖标准的 `javax.sql.DataSource` 接口，可与任何主流数据库连接池集成。以下为常用连接池的配置示例。
+
+### 8.1 使用 HikariCP
+
+> [HikariCP](https://github.com/brettwooldridge/HikariCP) 是目前性能最优的数据库连接池之一，推荐在新项目中优先使用。
+
+```xml
+<!-- Maven 依赖 -->
+<dependency>
+    <groupId>com.zaxxer</groupId>
+    <artifactId>HikariCP</artifactId>
+    <version>${hikaricp.version}</version>
+</dependency>
+```
+
+```java
+import com.zaxxer.hikari.HikariConfig;
+import com.zaxxer.hikari.HikariDataSource;
+
+// 配置 HikariCP 连接池
+HikariConfig config = new HikariConfig();
+config.setJdbcUrl("jdbc:mysql://localhost:3306/your_database");
+config.setUsername("your_username");
+config.setPassword("your_password");
+// 其他连接池参数按需配置
+
+DataSource dataSource = new HikariDataSource(config);
+SimpleJdbcTemplate jdbcTemplate = new SimpleJdbcTemplate(dataSource);
+```
+
+### 8.2 使用 Druid
+
+> [Druid](https://github.com/alibaba/druid) 是阿里巴巴开源的数据库连接池，提供了内置的监控和扩展能力，在中文社区中广泛采用。
+
+```xml
+<!-- Maven 依赖 -->
+<dependency>
+    <groupId>com.alibaba</groupId>
+    <artifactId>druid</artifactId>
+    <version>${druid.version}</version>
+</dependency>
+```
+
+```java
+import com.alibaba.druid.pool.DruidDataSource;
+
+DruidDataSource dataSource = new DruidDataSource();
+dataSource.setUrl("jdbc:mysql://localhost:3306/your_database");
+dataSource.setUsername("your_username");
+dataSource.setPassword("your_password");
+// 其他连接池参数按需配置
+
+SimpleJdbcTemplate jdbcTemplate = new SimpleJdbcTemplate(dataSource);
+```
+
+### 8.3 使用 DBCP 2
+
+> [DBCP 2](https://commons.apache.org/proper/commons-dbcp/) 是 Apache Commons 提供的数据库连接池，适用于需要依赖轻量的场景。
+
+```xml
+<!-- Maven 依赖 -->
+<dependency>
+    <groupId>org.apache.commons</groupId>
+    <artifactId>commons-dbcp2</artifactId>
+    <version>${dbcp2.version}</version>
+</dependency>
+```
+
+```java
+import org.apache.commons.dbcp2.BasicDataSource;
+
+BasicDataSource dataSource = new BasicDataSource();
+dataSource.setUrl("jdbc:mysql://localhost:3306/your_database");
+dataSource.setUsername("your_username");
+dataSource.setPassword("your_password");
+// 其他连接池参数按需配置
+
+SimpleJdbcTemplate jdbcTemplate = new SimpleJdbcTemplate(dataSource);
+```
+
+---
+
+## 9. 注意事项与适用场景
+
+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-RC1</version>
+    <version>1.1.0-SNAPSHOT</version>

    <name>Simple JDBC</name>
    <description>对 JDBC 的简单封装。</description>
@@ -16,7 +16,11 @@
        <maven.compiler.target>8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

-        <plusone-commons.version>1.1.0-RC2</plusone-commons.version>
+        <!-- Dependency Versions -->
+        <jsr305.version>3.0.2</jsr305.version>
+        <junit-jupiter.version>5.14.4</junit-jupiter.version>
+        <logback.version>1.3.16</logback.version>
+        <h2.version>2.2.224</h2.version>
    </properties>

    <licenses>
@@ -40,43 +44,35 @@
        <url>https://gitea.zhouxy.xyz/plusone/simple-jdbc</url>
    </scm>

-    <dependencyManagement>
    <dependencies>
        <dependency>
-                <groupId>xyz.zhouxy.plusone</groupId>
-                <artifactId>plusone-dependencies</artifactId>
-                <version>${plusone-commons.version}</version>
-                <type>pom</type>
-                <scope>import</scope>
-            </dependency>
-        </dependencies>
-    </dependencyManagement>
-
-    <dependencies>
-        <dependency>
-            <groupId>xyz.zhouxy.plusone</groupId>
-            <artifactId>plusone-commons</artifactId>
-            <version>${plusone-commons.version}</version>
+            <groupId>com.google.code.findbugs</groupId>
+            <artifactId>jsr305</artifactId>
+            <version>${jsr305.version}</version>
        </dependency>

        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
+            <version>${junit-jupiter.version}</version>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
+            <version>${logback.version}</version>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
+            <version>${h2.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
+
    <profiles>
        <profile>
            <id>release</id>
--- a/src/main/java/xyz/zhouxy/jdbc/BatchUpdateErrorInfo.java
+++ b/src/main/java/xyz/zhouxy/jdbc/BatchUpdateErrorInfo.java
@@ -16,31 +16,79 @@
 package xyz.zhouxy.jdbc;

 /**
- * 批量更新错误信息
+ * 记录批量更新操作中某个批次的执行错误信息。
+ *
+ * <p>当批量更新过程中某个批次执行失败时，该类用于封装出错批次的索引、
+ * 异常原因及其错误类型，便于调用方进行针对性的错误处理。
 *
 * @author ZhouXY
+ * @see BatchUpdateResult
 */
 public class BatchUpdateErrorInfo {

+    /**
+     * 批次索引
+     */
    private final int batchIndex;
+    /**
+     * 错误原因
+     */
    private final Throwable cause;
+    /**
+     * 错误类型
+     */
    private final Class<? extends Throwable> errorType;

+    /**
+     * 构造一个批量更新错误信息实例。
+     *
+     * @param batchIndex 出错的批次索引
+     * @param cause      导致该批次执行失败的异常
+     */
    public BatchUpdateErrorInfo(int batchIndex, Throwable cause) {
        this.batchIndex = batchIndex;
        this.cause = cause;
        this.errorType = cause.getClass();
    }

+    /**
+     * 获取批次索引
+     *
+     * @return 批次索引
+     */
    public int getBatchIndex() {
        return batchIndex;
    }

+    /**
+     * 获取错误原因
+     *
+     * @return 错误原因
+     */
    public Throwable getCause() {
        return cause;
    }

+    /**
+     * 获取错误类型
+     *
+     * @return 错误类型
+     */
    public Class<? extends Throwable> getErrorType() {
        return errorType;
    }
+
+    /**
+     * 返回该错误信息的字符串表示，包含批次索引、错误类型和错误消息。
+     *
+     * @return 格式为 {@code "BatchUpdateErrorInfo{batchIndex=..., errorType=..., message=...}"} 的字符串
+     */
+    @Override
+    public String toString() {
+        return "BatchUpdateErrorInfo{"
+                + "batchIndex=" + batchIndex
+                + ", errorType=" + errorType.getName()
+                + ", message=" + cause.getMessage()
+                + "}";
+    }
 }
--- a/src/main/java/xyz/zhouxy/jdbc/BatchUpdateResult.java
+++ b/src/main/java/xyz/zhouxy/jdbc/BatchUpdateResult.java
@@ -22,26 +22,69 @@ import java.util.Map;
 /**
 * 批量更新结果
 *
+ * <p>
+ * 封装 {@code batchUpdate} 操作的执行结果，包含：
+ * <ul>
+ *   <li>整体执行状态 {@link BatchUpdateStatus}</li>
+ *   <li>批次统计信息（总数据量、批次数、成功/失败/剩余批次数）</li>
+ *   <li>各批次的更新结果及各错误批次的异常信息</li>
+ * </ul>
+ *
 * @author ZhouXY
+ *
+ * @see BatchUpdateStatus
+ * @see BatchUpdateErrorInfo
+ * @see JdbcOperations#batchUpdate(String, java.util.Collection, int)
+ * @see JdbcOperations#batchUpdate(String, java.util.Collection, int, boolean)
 */
 public class BatchUpdateResult {
+    /**
+     * 总数据量
+     */
    private final int total;
+    /**
+     * 批次数量
+     */
    private final int batchCount;
+    /**
+     * 批次大小
+     */
    private final int batchSize;

+    /**
+     * 是否静默模式
+     */
+    private final boolean quietly;
+
+    /**
+     * 本次分批更新的状态
+     */
    private BatchUpdateStatus status = BatchUpdateStatus.SUCCESS;

+    /**
+     * 所有批次的更新结果
+     */
    private Map<Integer, int[]> allUpdateCounts;
+    /**
+     * 所有出错的批次的错误信息
+     */
    private Map<Integer, BatchUpdateErrorInfo> allErrorsInfo;

+    /**
+     * 成功批次数量
+     */
    private int successBatchCount;

+    /**
+     * 完成批次数量
+     */
    private int completeBatchCount;

-    BatchUpdateResult(int total, int batchCount, int batchSize) {
+    BatchUpdateResult(int total, int batchCount, int batchSize, boolean quietly) {
        this.total = total;
        this.batchCount = batchCount;
        this.batchSize = batchSize;
+        this.quietly = quietly;

        this.allUpdateCounts = new HashMap<>(batchCount);
        this.allErrorsInfo = new HashMap<>(batchCount);
@@ -64,19 +107,17 @@ public class BatchUpdateResult {
        this.allUpdateCounts.put(batchIndex, updateCounts);
        this.allErrorsInfo.put(batchIndex, new BatchUpdateErrorInfo(batchIndex, cause));
        if (this.status == BatchUpdateStatus.SUCCESS) {
+            if (this.quietly) {
                this.status = BatchUpdateStatus.COMPLETED_WITH_ERRORS;
            }
-    }
-
-    /**
-     * 中断
-     */
-    void interrupt() {
+            else {
                this.status = BatchUpdateStatus.INTERRUPTED;
            }
+        }
+    }

    /**
-     * 获取批次更新结果
+     * 获取指定批次更新结果
     *
     * @param batchIndex 批次号
     * @return 批次更新结果
@@ -87,7 +128,7 @@ public class BatchUpdateResult {
    }

    /**
-     * 获取错误批次号
+     * 获取所有出错的批次号
     *
     * @return 错误批次号
     */
@@ -96,7 +137,7 @@ public class BatchUpdateResult {
    }

    /**
-     * 获取错误批次信息
+     * 获取指定批次的错误信息
     *
     * @param batchIndex 批次号
     * @return 批次错误信息
@@ -106,7 +147,7 @@ public class BatchUpdateResult {
    }

    /**
-     * 获取所有错误批次信息
+     * 获取所有出错的批次的错误信息
     *
     * @return 批次错误信息
     */
@@ -142,9 +183,9 @@ public class BatchUpdateResult {
    }

    /**
-     * 获取批次更新状态
+     * 获取批量更新状态
     *
-     * @return 批次更新状态
+     * @return 批量更新状态
     */
    public BatchUpdateStatus getStatus() {
        return status;
@@ -180,19 +221,23 @@ public class BatchUpdateResult {
    /**
     * 获取剩余批次数量
     *
+     * <p>
+     * 一般是中断后未执行的批次数量
+     *
     * @return 剩余批次数量
     */
    public int getRemainingBatchCount() {
        return batchCount - successBatchCount - getErrorBatchCount();
    }

+    /** {@inheritDoc} */
    @Override
    public String toString() {
        return "BatchUpdateResult ["
-                + "total=" + total
-                + ", batchCount=" + batchCount
+                + "status=" + status
+                + ", total=" + total
                + ", batchSize=" + batchSize
-                + ", status=" + status
+                + ", batchCount=" + batchCount
                + ", completeBatchCount=" + completeBatchCount
                + ", successBatchCount=" + successBatchCount
                + ", errorBatchCount=" + getErrorBatchCount()
--- a/src/main/java/xyz/zhouxy/jdbc/BatchUpdateStatus.java
+++ b/src/main/java/xyz/zhouxy/jdbc/BatchUpdateStatus.java
@@ -15,14 +15,17 @@
 */
 package xyz.zhouxy.jdbc;

-import xyz.zhouxy.plusone.commons.base.IWithIntCode;
-
 /**
 * 批量更新状态
 *
+ * <p>
+ * 用于表示批量更新操作的整体执行状态
+ *
 * @author ZhouXY
+ * @see BatchUpdateResult
+ * @see BatchUpdateResult#getStatus()
 */
-public enum BatchUpdateStatus implements IWithIntCode {
+public enum BatchUpdateStatus {

    /**
     * 成功
@@ -30,12 +33,20 @@ public enum BatchUpdateStatus implements IWithIntCode {
    SUCCESS(0, "成功"),

    /**
-     * 部分成功
+     * 执行完成，部分批次失败
+     *
+     * <p>
+     * 通常出现在 batchUpdate 的静默模式下：遇到执行失败的批次时不中断，继续执行后续批次，最终状态为此值。
+     *
+     * @see BatchUpdateResult#getErrorBatchIndexes()
     */
-    COMPLETED_WITH_ERRORS(-1, "部分成功"),
+    COMPLETED_WITH_ERRORS(-1, "执行完成，部分批次失败"),

    /**
     * 中断
+     *
+     * <p>
+     * 通常出现在 batchUpdate 的非静默模式下：遇到执行失败的批次时立即中断，不再执行后续批次。
     */
    INTERRUPTED(-2, "中断"),
    ;
@@ -48,18 +59,27 @@ public enum BatchUpdateStatus implements IWithIntCode {
        this.description = description;
    }

-    @Override
+    /**
+     * 获取状态码
+     *
+     * @return 状态码
+     */
    public int getCode() {
        return code;
    }

    /**
-     * @return the description
+     * 获取状态的可读描述
+     *
+     * @return 描述信息
     */
    public String getDescription() {
        return description;
    }

+    /**
+     * {@inheritDoc}
+     */
    @Override
    public String toString() {
        return "BatchUpdateStatus ["
--- a/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java
+++ b/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java
@@ -34,28 +34,27 @@ import java.util.stream.Collectors;

 import javax.annotation.Nullable;

-import com.google.common.base.CaseFormat;
-
-import xyz.zhouxy.plusone.commons.annotation.StaticFactoryMethod;
+import xyz.zhouxy.jdbc.util.NamingTools;

 /**
 * DefaultBeanRowMapper
 *
 * <p>
- * 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。
- * </p>
+ * 将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper} 的基础实现。
+ * <p>
+ * <i>性能和规则上的限制都比较大，仅在对性能不敏感的场景下便捷使用，
+ * 一般情况下你应该自定义 {@link RowMapper}。</i>
 *
 * <p>
 * 说明：
 * <ul>
 * <li>使用反射获取类型信息，也是使用反射调用无参构造器和 {@code setter} 方法。</li>
- * <li>{@code propertyColMap} 未指定的列名和属性名的映射时，默认 JavaBean 的属性名为小驼峰，列名为小写蛇形命名。</li>
- * <li>从{@link ResultSet} 中获取属性值时，使用 {@link ResultSet#getObject(String, Class)} 获取。</li>
+ * <li>支持自定义列名和属性名的映射，当未指定 {@code propertyColMap} 时，默认 JavaBean 的属性名为小驼峰，列名为小写蛇形命名。</li>
+ * <li>使用 {@link ResultSet#getObject(String, Class)} 从 {@link ResultSet} 中获取属性值。</li>
 * <li>JavaBean 属性仅支持引用类型，不支持基本数据类型。</li>
- * <li>实际使用中还是建议针对目标类型自定义 {@link RowMapper}。</li>
 * </ul>
-
-* @author ZhouXY
+ *
+ * @author ZhouXY
 * @since 1.0.0
 */
 public class DefaultBeanRowMapper<T> implements RowMapper<T> {
@@ -88,10 +87,9 @@ public class DefaultBeanRowMapper<T> implements RowMapper<T> {
     * @param <T>      Bean 类型
     * @param beanType Bean 类型
     * @return DefaultBeanRowMapper 对象
-     * @throws SQLException 创建 {@code DefaultBeanRowMapper} 出现错误的异常时抛出
+     * @throws IllegalStateException 创建 {@code DefaultBeanRowMapper} 出现错误的异常时抛出
     */
-    @StaticFactoryMethod(DefaultBeanRowMapper.class)
-    public static <T> DefaultBeanRowMapper<T> of(Class<T> beanType) throws SQLException {
+    public static <T> DefaultBeanRowMapper<T> of(Class<T> beanType) {
        return of(beanType, null);
    }

@@ -102,11 +100,10 @@ public class DefaultBeanRowMapper<T> implements RowMapper<T> {
     * @param beanType       Bean 类型
     * @param propertyColMap Bean 字段与列名的映射关系。key 是字段，value 是列名。
     * @return {@code DefaultBeanRowMapper} 对象
-     * @throws SQLException 创建 {@code DefaultBeanRowMapper} 出现错误的异常时抛出
+     * @throws IllegalStateException 创建 {@code DefaultBeanRowMapper} 出现错误的异常时抛出
     */
-    @StaticFactoryMethod(DefaultBeanRowMapper.class)
-    public static <T> DefaultBeanRowMapper<T> of(Class<T> beanType, @Nullable Map<String, String> propertyColMap)
-            throws SQLException {
+    public static <T> DefaultBeanRowMapper<T> of(Class<T> beanType,
+                                                 @Nullable Map<String, String> propertyColMap) {
        try {
            // 获取无参构造器
            Constructor<T> constructor = beanType.getDeclaredConstructor();
@@ -117,10 +114,10 @@ public class DefaultBeanRowMapper<T> implements RowMapper<T> {
            return new DefaultBeanRowMapper<>(beanType, constructor, colPropertyMap, colSetterMap);
        }
        catch (IntrospectionException e) {
-            throw new SQLException("There is an exception occurs during introspection.", e);
+            throw new IllegalStateException("There is an exception occurs during introspection.", e);
        }
        catch (NoSuchMethodException e) {
-            throw new SQLException("Could not find a no-args constructor in " + beanType.getName(), e);
+            throw new IllegalStateException("Could not find a no-args constructor in " + beanType.getName(), e);
        }
    }

@@ -145,7 +142,7 @@ public class DefaultBeanRowMapper<T> implements RowMapper<T> {
            return newInstance;
        }
        catch (IllegalAccessException | InstantiationException | InvocationTargetException e) {
-            throw new SQLException("Could not map row to " + beanType.getName(), e);
+            throw new IllegalStateException("Could not map row to " + beanType.getName(), e);
        }
    }

@@ -167,14 +164,14 @@ public class DefaultBeanRowMapper<T> implements RowMapper<T> {
        // Bean 的属性名为小驼峰，对应的列名为下划线
        Function<? super PropertyDescriptor, String> keyMapper;
        if (propertyColMap == null || propertyColMap.isEmpty()) {
-            keyMapper = p -> CaseFormat.LOWER_CAMEL.to(CaseFormat.LOWER_UNDERSCORE, p.getName());
+            keyMapper = p -> NamingTools.camelToSnake(p.getName());
        }
        else {
            keyMapper = p -> {
                String propertyName = p.getName();
                String colName = propertyColMap.get(propertyName);
                return colName != null ? colName
-                    : CaseFormat.LOWER_CAMEL.to(CaseFormat.LOWER_UNDERSCORE, propertyName);
+                    : NamingTools.camelToSnake(propertyName);
            };
        }
        return Arrays.stream(propertyDescriptors)
--- a/src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java
+++ b/src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java
@@ -16,8 +16,8 @@

 package xyz.zhouxy.jdbc;

-import static xyz.zhouxy.plusone.commons.util.AssertTools.checkArgument;
-import static xyz.zhouxy.plusone.commons.util.AssertTools.checkArgumentNotNull;
+import static xyz.zhouxy.jdbc.util.AssertTools.checkArgument;
+import static xyz.zhouxy.jdbc.util.AssertTools.checkArgumentNotNull;

 import java.sql.BatchUpdateException;
 import java.sql.Connection;
@@ -37,8 +37,6 @@ import java.util.List;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;

-import com.google.common.collect.Lists;
-
 /**
 * JdbcOperationSupport
 *
@@ -95,14 +93,14 @@ class JdbcOperationSupport {
    }

    /**
-     * 执行查询，返回结果映射为指定的类型。当结果为单列时使用
+     * 执行查询，只取结果集每行第一列的值，映射为指定类型并返回列表
     *
     * @param conn   数据库连接
     * @param sql    SQL
     * @param params 参数
     * @param clazz  将结果映射为指定的类型
     */
-    static <T> List<T> queryList(Connection conn, String sql, Object[] params, Class<T> clazz)
+    static <T> List<T> queryValues(Connection conn, String sql, Object[] params, Class<T> clazz)
            throws SQLException {
        assertConnectionNotNull(conn);
        assertSqlNotNull(sql);
@@ -131,14 +129,15 @@ class JdbcOperationSupport {
    }

    /**
-     * 查询第一行第一列，并转换为指定类型
+     * 执行查询，只取结果集第一行第一列的值，映射为指定类型并返回
     *
+     * @param conn   数据库连接
     * @param <T>    目标类型
     * @param sql    SQL
     * @param params 参数
     * @param clazz  目标类型
     */
-    static <T> T queryFirst(Connection conn, String sql, Object[] params, Class<T> clazz)
+    static <T> T queryValue(Connection conn, String sql, Object[] params, Class<T> clazz)
            throws SQLException {
        assertConnectionNotNull(conn);
        assertSqlNotNull(sql);
@@ -162,11 +161,18 @@ class JdbcOperationSupport {
            throws SQLException {
        assertConnectionNotNull(conn);
        assertSqlNotNull(sql);
+        if (params != null && params.length > 0) {
            try (PreparedStatement stmt = conn.prepareStatement(sql)) {
                fillStatement(stmt, params);
                return stmt.executeUpdate();
            }
        }
+        else {
+            try (Statement stmt = conn.createStatement()) {
+                return stmt.executeUpdate(sql);
+            }
+        }
+    }

    /**
     * 执行 SQL 并返回生成的 keys
@@ -184,18 +190,24 @@ class JdbcOperationSupport {
        assertConnectionNotNull(conn);
        assertSqlNotNull(sql);
        assertRowMapperNotNull(rowMapper);
-        final List<T> result = Lists.newArrayListWithCapacity(4);
+        if (params != null && params.length > 0) {
            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);
+                    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;
        }
    }

@@ -221,32 +233,37 @@ class JdbcOperationSupport {
        assertSqlNotNull(sql);
        checkArgument(batchSize > 0, "The batch size must be greater than 0.");
        if (params == null || params.isEmpty()) {
-            return new BatchUpdateResult(0, 0, batchSize);
+            return new BatchUpdateResult(0, 0, batchSize, quietly);
        }

        final int paramsSize = params.size();
        final int batchCount = (paramsSize + batchSize - 1) / batchSize;

-        final BatchUpdateResult result = new BatchUpdateResult(paramsSize, batchCount, batchSize);
+        final BatchUpdateResult result = new BatchUpdateResult(paramsSize, batchCount, batchSize, quietly);

        try (PreparedStatement stmt = conn.prepareStatement(sql)) {
+            // 表示第几条数据，1, 2, 3, ..., paramsSize
            int itemIndex = 0;
+            // 表示第几个批次，0, 1, ..., batchCount-1
            int batchIndex = 0;
+
            for (Object[] ps : params) {
                itemIndex++;
                fillStatement(stmt, ps);
                stmt.addBatch();
-                final int indexInBatch = itemIndex % batchSize;
-                if (indexInBatch == 0 || itemIndex >= paramsSize) {
+
+                // 表示当前数据在批次中的索引，1, 2, 3, ..., batchSize-1, batchSize
+                final int indexInBatch = (itemIndex - 1) % batchSize + 1;
+
+                if (indexInBatch == batchSize || itemIndex == paramsSize) {
                    try {
                        int[] updateCounts = stmt.executeBatch();
                        result.recordSuccessBatch(batchIndex, updateCounts);
                    }
                    catch (Exception e) {
-                        final int[] updateCounts = getUpdateCountsInternal(paramsSize, batchSize, itemIndex, indexInBatch, e);
+                        final int[] updateCounts = getUpdateCountsOnError(indexInBatch, e);
                        result.recordErrorBatch(batchIndex, updateCounts, e);
                        if (!quietly) {
-                            result.interrupt();
                            break;
                        }
                    }
@@ -260,18 +277,13 @@ class JdbcOperationSupport {
        }
    }

-    private static int[] getUpdateCountsInternal(final int paramsSize,
-                                                 final int batchSize,
-                                                 final int itemIndex,
-                                                 final int indexInBatch,
-                                                 final Exception e) {
+    private static int[] getUpdateCountsOnError(final int indexInBatch, final Exception e) {
        final int[] updateCounts;
        if (e instanceof BatchUpdateException) {
            updateCounts = ((BatchUpdateException) e).getUpdateCounts();
        }
        else {
-            int n = (itemIndex >= paramsSize && indexInBatch != 0) ? indexInBatch : batchSize;
-            updateCounts = new int[n];
+            updateCounts = new int[indexInBatch];
            Arrays.fill(updateCounts, UNKNOWN_COUNT);
        }
        return updateCounts;
@@ -294,11 +306,19 @@ class JdbcOperationSupport {
                                       @Nullable Object[] params,
                                       @Nonnull ResultHandler<T> resultHandler)
            throws SQLException {
+        if (params != null && params.length > 0) {
            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);
+            }
+        }
+    }

    private static PreparedStatement createPreparedStatementInternal(
            @Nonnull Connection conn,
@@ -323,15 +343,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/JdbcOperations.java
+++ b/src/main/java/xyz/zhouxy/jdbc/JdbcOperations.java
@@ -87,17 +87,18 @@ public interface JdbcOperations {
            throws SQLException;

    /**
-     * 执行查询，返回结果映射为指定的类型。当结果为单列时使用
+     * 执行查询，只取结果集每行第一列的值，映射为指定类型并返回列表。
+     * 适用于 {@code SELECT single_column FROM ...} 单列查询场景。
     *
-     * @param <T>    目标类型
+     * @param <T>    目标类型（对应结果集第一列的 Java 类型）
     * @param sql    SQL
     * @param params 参数
     * @param clazz  目标类型
     *
-     * @return 映射结果。如果查询结果为空，则返回空列表
+     * @return 每一行第一列的值列表。如果查询结果为空，则返回空列表
     * @throws SQLException SQL异常
     */
-    <T> List<T> queryList(String sql, Object[] params, Class<T> clazz)
+    <T> List<T> queryValues(String sql, Object[] params, Class<T> clazz)
            throws SQLException;

    /**
@@ -128,18 +129,39 @@ public interface JdbcOperations {
    }

    /**
-     * 执行查询，返回结果映射为指定的类型。当结果为单列时使用
+     * 执行查询，只取结果集每行第一列的值，映射为指定类型并返回列表。
+     * 适用于 {@code SELECT single_column FROM ...} 单列查询场景。
     *
     * @param <T>   目标类型
     * @param sql   SQL
     * @param clazz 将结果映射为指定的类型
     *
-     * @return 查询结果
+     * @return 每一行第一列的值列表。如果查询结果为空，则返回空列表
     * @throws SQLException SQL 异常
     */
+    default <T> List<T> queryValues(String sql, Class<T> clazz)
+            throws SQLException {
+        return queryValues(sql, ParamBuilder.EMPTY_OBJECT_ARRAY, clazz);
+    }
+
+    /**
+     * @deprecated 自 1.1.0 起，请使用 {@link #queryValues(String, Object[], Class)}。
+     *             此方法将在后续版本中移除。
+     */
+    @Deprecated
+    default <T> List<T> queryList(String sql, Object[] params, Class<T> clazz)
+            throws SQLException {
+        return queryValues(sql, params, clazz);
+    }
+
+    /**
+     * @deprecated 自 1.1.0 起，请使用 {@link #queryValues(String, Class)}。
+     *             此方法将在后续版本中移除。
+     */
+    @Deprecated
    default <T> List<T> queryList(String sql, Class<T> clazz)
            throws SQLException {
-        return queryList(sql, ParamBuilder.EMPTY_OBJECT_ARRAY, clazz);
+        return queryValues(sql, clazz);
    }

    /**
@@ -174,17 +196,18 @@ public interface JdbcOperations {
            throws SQLException;

    /**
-     * 查询第一行第一列，并转换为指定类型
+     * 执行查询，只取结果集第一行第一列的值，映射为指定类型并返回。
+     * 适用于 {@code SELECT single_column FROM ... WHERE ...} 单列单行查询场景。
     *
     * @param <T>    目标类型
     * @param sql    SQL
     * @param params 参数
     * @param clazz  目标类型
     *
-     * @return 查询结果
+     * @return 第一行第一列的值。如果查询结果为空，则返回 {@code Optional.empty()}
     * @throws SQLException SQL 异常
     */
-    <T> Optional<T> queryFirst(String sql, Object[] params, Class<T> clazz)
+    <T> Optional<T> queryValue(String sql, Object[] params, Class<T> clazz)
            throws SQLException;

    /**
@@ -215,18 +238,39 @@ public interface JdbcOperations {
    }

    /**
-     * 查询第一行第一列，并转换为指定类型
+     * 执行查询，只取结果集第一行第一列的值，映射为指定类型并返回。
+     * 适用于 {@code SELECT single_column FROM ... WHERE ...} 单列单行查询场景。
     *
     * @param <T>   目标类型
     * @param sql   SQL
     * @param clazz 目标类型
     *
-     * @return 第一行第一列的值，如果查询结果为空，则返回 {@code Optional#empty()}
+     * @return 第一行第一列的值，如果查询结果为空，则返回 {@code Optional.empty()}
     * @throws SQLException SQL 异常
     */
+    default <T> Optional<T> queryValue(String sql, Class<T> clazz)
+            throws SQLException {
+        return queryValue(sql, ParamBuilder.EMPTY_OBJECT_ARRAY, clazz);
+    }
+
+    /**
+     * @deprecated 自 1.1.0 起，请使用 {@link #queryValue(String, Object[], Class)}。
+     *             此方法将在后续版本中移除。
+     */
+    @Deprecated
+    default <T> Optional<T> queryFirst(String sql, Object[] params, Class<T> clazz)
+            throws SQLException {
+        return queryValue(sql, params, clazz);
+    }
+
+    /**
+     * @deprecated 自 1.1.0 起，请使用 {@link #queryValue(String, Class)}。
+     *             此方法将在后续版本中移除。
+     */
+    @Deprecated
    default <T> Optional<T> queryFirst(String sql, Class<T> clazz)
            throws SQLException {
-        return queryFirst(sql, ParamBuilder.EMPTY_OBJECT_ARRAY, clazz);
+        return queryValue(sql, clazz);
    }

    /**
@@ -242,6 +286,43 @@ public interface JdbcOperations {
        return queryFirst(sql, ParamBuilder.EMPTY_OBJECT_ARRAY);
    }

+    /**
+     * 执行查询，只取结果集第一行第一列的值，映射为指定类型并返回。
+     * 如果查询结果为空，则返回指定的默认值。
+     * 适用于 {@code SELECT COUNT(*)}、{@code SELECT MAX(...)} 等聚合查询场景。
+     *
+     * @param <T>          目标类型
+     * @param sql          SQL
+     * @param params       参数
+     * @param clazz        目标类型
+     * @param defaultValue 查询结果为空时返回的默认值
+     *
+     * @return 第一行第一列的值，如果查询结果为空则返回 {@code defaultValue}
+     * @throws SQLException SQL 异常
+     */
+    default <T> T queryValueOrDefault(String sql, Object[] params, Class<T> clazz, T defaultValue)
+            throws SQLException {
+        return queryValue(sql, params, clazz).orElse(defaultValue);
+    }
+
+    /**
+     * 执行查询，只取结果集第一行第一列的值，映射为指定类型并返回。
+     * 如果查询结果为空，则返回指定的默认值。
+     * 适用于 {@code SELECT COUNT(*)}、{@code SELECT MAX(...)} 等聚合查询场景。
+     *
+     * @param <T>          目标类型
+     * @param sql          SQL
+     * @param clazz        目标类型
+     * @param defaultValue 查询结果为空时返回的默认值
+     *
+     * @return 第一行第一列的值，如果查询结果为空则返回 {@code defaultValue}
+     * @throws SQLException SQL 异常
+     */
+    default <T> T queryValueOrDefault(String sql, Class<T> clazz, T defaultValue)
+            throws SQLException {
+        return queryValueOrDefault(sql, ParamBuilder.EMPTY_OBJECT_ARRAY, clazz, defaultValue);
+    }
+
    /**
     * 查询第一行第一列并转换为 boolean
     *
--- 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;
@@ -27,12 +28,8 @@ import java.util.OptionalInt;
 import java.util.OptionalLong;
 import java.util.function.Function;
 import java.util.stream.Collectors;
-import java.util.stream.Stream;

-import xyz.zhouxy.plusone.commons.collection.CollectionTools;
-import xyz.zhouxy.plusone.commons.util.ArrayTools;
-import xyz.zhouxy.plusone.commons.util.AssertTools;
-import xyz.zhouxy.plusone.commons.util.OptionalTools;
+import xyz.zhouxy.jdbc.util.AssertTools;

 /**
 * ParamBuilder
@@ -45,39 +42,83 @@ import xyz.zhouxy.plusone.commons.util.OptionalTools;
 * @since 1.0.0
 */
 public class ParamBuilder {
+    /**
+     * 空参数数组常量
+     *
+     * <p>
+     * 用于表示无参数的 SQL 操作
+     */
    public static final Object[] EMPTY_OBJECT_ARRAY = {};

+    /**
+     * 构建 SQL 参数数组
+     *
+     * <p>
+     * 将传入的参数转换为 {@code Object[]}，用于 {@link PreparedStatement} 的参数填充。
+     * 支持自动拆箱 {@link Optional}、{@link OptionalInt}、{@link OptionalLong}、{@link OptionalDouble}。
+     * 对于 {@link CharSequence}、{@link Number}、{@link Boolean}、{@link Temporal} 类型不做转换直接透传。
+     * 如果传入的 {@code params} 为 {@code null} 或空，则返回 {@link #EMPTY_OBJECT_ARRAY}。
+     *
+     * @param params SQL 参数列表（可变参数）
+     * @return 参数数组
+     */
    public static Object[] buildParams(final Object... params) {
-        if (ArrayTools.isEmpty(params)) {
+        if (params == null || params.length == 0) {
            return EMPTY_OBJECT_ARRAY;
        }
-        return buildParamsFromStream(Arrays.stream(params));
-    }
-
-    private static Object[] buildParamsFromStream(Stream<?> stream) {
-        return stream
-                .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;
-                })
+        return Arrays.stream(params)
+                .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 ((Optional<?>) param).orElse(null);
+        }
+        if (param instanceof OptionalInt) {
+            return ((OptionalInt) param).isPresent() ? ((OptionalInt) param).getAsInt() : null;
+        }
+        if (param instanceof OptionalLong) {
+            return ((OptionalLong) param).isPresent() ? ((OptionalLong) param).getAsLong() : null;
+        }
+        if (param instanceof OptionalDouble) {
+            return ((OptionalDouble) param).isPresent() ? ((OptionalDouble) param).getAsDouble() : null;
+        }
+        return param;
+    }
+
+    /**
+     * 批量构建参数列表
+     *
+     * <p>
+     * 将集合中的每个元素通过 {@code func} 映射为 {@code Object[]}，
+     * 最终返回 {@code List<Object[]>}，用于 {@code batchUpdate} 批量操作。
+     *
+     * @param <T>  集合元素类型
+     * @param c    待转换的集合
+     * @param func 转换函数，将集合元素转换为参数数组
+     * @return 参数数组列表
+     * @throws NullPointerException 如果 {@code c} 或 {@code func} 为 {@code null}
+     */
    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.");
-        if (CollectionTools.isEmpty(c)) {
+        if (c.isEmpty()) {
            return Collections.emptyList();
        }
        return c.stream().map(func).collect(Collectors.toList());
--- 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/main/java/xyz/zhouxy/jdbc/RowMapper.java
+++ b/src/main/java/xyz/zhouxy/jdbc/RowMapper.java
@@ -60,9 +60,9 @@ public interface RowMapper<T> {
     * @param <T> Java Bean 的类型
     *
     * @return {@link DefaultBeanRowMapper}
-     * @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败
+     * @throws IllegalStateException 如果创建 {@link DefaultBeanRowMapper} 失败
     */
-    static <T> RowMapper<T> beanRowMapper(Class<T> beanType) throws SQLException {
+    static <T> RowMapper<T> beanRowMapper(Class<T> beanType) {
        return DefaultBeanRowMapper.of(beanType);
    }

@@ -74,10 +74,9 @@ public interface RowMapper<T> {
     * @param <T> Java Bean 的类型
     *
     * @return {@link DefaultBeanRowMapper}
-     * @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败
+     * @throws IllegalStateException 如果创建 {@link DefaultBeanRowMapper} 失败
     */
-    static <T> RowMapper<T> beanRowMapper(Class<T> beanType, Map<String, String> propertyColMap)
-            throws SQLException {
+    static <T> RowMapper<T> beanRowMapper(Class<T> beanType, Map<String, String> propertyColMap) {
        return DefaultBeanRowMapper.of(beanType, propertyColMap);
    }
 }
--- a/src/main/java/xyz/zhouxy/jdbc/SimpleJdbcTemplate.java
+++ b/src/main/java/xyz/zhouxy/jdbc/SimpleJdbcTemplate.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2022-2026 ZhouXY
+ * Copyright 2022-present ZhouXY
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -26,28 +26,48 @@ import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import javax.sql.DataSource;

-import xyz.zhouxy.plusone.commons.function.ThrowingConsumer;
-import xyz.zhouxy.plusone.commons.function.ThrowingPredicate;
-import xyz.zhouxy.plusone.commons.util.AssertTools;
+import xyz.zhouxy.jdbc.util.AssertTools;

 /**
- * SimpleJdbcTemplate
+ * JDBC 操作的模板类，对原生 JDBC 进行轻量封装，提供查询、更新、批量操作等便捷方法。
 *
 * <p>
- * 对 JDBC 的简单封装，方便数据库操作，支持事务，支持批量操作，支持自定义结果集映射
- * </p>
+ * 主要能力：
+ * <ul>
+ * <li>查询：支持 {@link ResultHandler} 自定义结果处理、{@link RowMapper} 行映射等多种方式</li>
+ * <li>更新：执行 INSERT / UPDATE / DELETE，支持返回自增主键</li>
+ * <li>批量操作：通过 {@link #batchUpdate} 分批执行 DML，支持静默模式（遇错继续）和
+ *     非静默模式（遇错即中断）</li>
+ * <li>事务：通过 {@link #transaction()} 获取 {@link TransactionTemplate} 执行</li>
+ * </ul>
+ *
+ * <p>
+ * 线程安全：本类无内部可变状态，线程安全。所依赖的 {@link DataSource}
+ * 需自行保证线程安全。
 *
 * @author ZhouXY
 * @since 1.0.0
+ * @see JdbcOperations
+ * @see TransactionTemplate
+ * @see ParamBuilder
 */
 public class SimpleJdbcTemplate implements JdbcOperations {

    @Nonnull
    private final DataSource dataSource;

+    @Nonnull
+    private final TransactionTemplate transactionTemplate;
+
+    /**
+     * 构造一个 {@code SimpleJdbcTemplate} 实例
+     *
+     * @param dataSource 数据源，用于获取数据库连接；不可为 {@code null}
+     */
    public SimpleJdbcTemplate(@Nonnull DataSource dataSource) {
        AssertTools.checkNotNull(dataSource);
        this.dataSource = dataSource;
+        this.transactionTemplate = new TransactionTemplate(dataSource);
    }

    // #region - query
@@ -76,10 +96,10 @@ public class SimpleJdbcTemplate implements JdbcOperations {

    /** {@inheritDoc} */
    @Override
-    public <T> List<T> queryList(String sql, Object[] params, Class<T> clazz)
+    public <T> List<T> queryValues(String sql, Object[] params, Class<T> clazz)
            throws SQLException {
        try (Connection conn = this.dataSource.getConnection()) {
-            return JdbcOperationSupport.queryList(conn, sql, params, clazz);
+            return JdbcOperationSupport.queryValues(conn, sql, params, clazz);
        }
    }

@@ -108,10 +128,10 @@ public class SimpleJdbcTemplate implements JdbcOperations {

    /** {@inheritDoc} */
    @Override
-    public <T> Optional<T> queryFirst(String sql, Object[] params, Class<T> clazz)
+    public <T> Optional<T> queryValue(String sql, Object[] params, Class<T> clazz)
            throws SQLException {
        try (Connection conn = this.dataSource.getConnection()) {
-            final T result = JdbcOperationSupport.queryFirst(conn, sql, params, clazz);
+            final T result = JdbcOperationSupport.queryValue(conn, sql, params, clazz);
            return Optional.ofNullable(result);
        }
    }
@@ -133,7 +153,7 @@ public class SimpleJdbcTemplate implements JdbcOperations {
            throws SQLException {
        try (Connection conn = this.dataSource.getConnection()) {
            final Boolean result = JdbcOperationSupport
-                    .queryFirst(conn, sql, params, Boolean.class);
+                    .queryValue(conn, sql, params, Boolean.class);
            return Boolean.TRUE.equals(result);
        }
    }
@@ -185,202 +205,17 @@ public class SimpleJdbcTemplate implements JdbcOperations {
    // #region - transaction

    /**
-     * 执行事务。如果未发生异常，则提交事务；当有异常发生时，回滚事务
+     * 获取事务模板
     *
     * <p>
-     * operations 中使用 JdbcExecutor 实参进行 JDBC 操作，这些操作在一个连接中
-     * </p>
+     * 返回的 {@link TransactionTemplate} 与当前模板共享同一个 {@link DataSource}。
     *
-     * @param <E>                   异常类型
-     * @param operations            事务操作
-     * @throws SQLException         SQL 异常
-     * @throws TransactionException 事务异常。事务中的异常会包装在该异常中。
+     * @return 事务模板
     */
-    public <E extends Exception> void executeTransaction(
-            @Nonnull final ThrowingConsumer<JdbcOperations, E> operations)
-            throws TransactionException, SQLException {
-        AssertTools.checkNotNull(operations, "Operations can not be null.");
-        try (Connection conn = this.dataSource.getConnection()) {
-            final boolean autoCommit = conn.getAutoCommit();
-            try {
-                conn.setAutoCommit(false);
-                operations.accept(new TransactionJdbcExecutor(conn));
-                conn.commit();
-            }
-            catch (Exception e) {
-                try {
-                    conn.rollback();
-                }
-                catch (SQLException ex) {
-                    e.addSuppressed(ex);
-                }
-                throw new TransactionException(e);
-            }
-            finally {
-                conn.setAutoCommit(autoCommit);
-            }
-        }
-    }
-
-    /**
-     * 执行事务。
-     * 如果 {@code operations} 返回 {@code true}，则提交事务；
-     * 如果抛出异常，或返回 {@code false}，则回滚事务
-     *
-     * @param <E>                   事务中的异常
-     * @param operations            事务操作
-     * @throws SQLException         数据库异常
-     * @throws TransactionException 事务异常。事务中的异常会包装在该异常中。
-     */
-    public <E extends Exception> void commitIfTrue(
-            @Nonnull final ThrowingPredicate<JdbcOperations, E> operations)
-            throws SQLException, TransactionException {
-        AssertTools.checkNotNull(operations, "Operations can not be null.");
-        try (Connection conn = this.dataSource.getConnection()) {
-            final boolean autoCommit = conn.getAutoCommit();
-            try {
-                conn.setAutoCommit(false);
-                if (operations.test(new TransactionJdbcExecutor(conn))) {
-                    conn.commit();
-                }
-                else {
-                    conn.rollback();
-                }
-            }
-            catch (Exception e) {
-                try {
-                    conn.rollback();
-                }
-                catch (SQLException ex) {
-                    e.addSuppressed(ex);
-                }
-                throw new TransactionException(e);
-            }
-            finally {
-                conn.setAutoCommit(autoCommit);
-            }
-        }
+    public TransactionTemplate transaction() {
+        return this.transactionTemplate;
    }

    // #endregion

-    private static final class TransactionJdbcExecutor implements JdbcOperations {
-
-        private final Connection conn;
-
-        private TransactionJdbcExecutor(Connection conn) {
-            this.conn = conn;
-        }
-
-        // #region - query
-
-        /** {@inheritDoc} */
-        @Override
-        public <T> T query(String sql, Object[] params, ResultHandler<T> resultHandler)
-                throws SQLException {
-            return JdbcOperationSupport.query(this.conn, sql, params, resultHandler);
-        }
-
-        // #endregion
-
-        // #region - queryList
-
-        /** {@inheritDoc} */
-        @Override
-        public <T> List<T> queryList(String sql, Object[] params, RowMapper<T> rowMapper)
-                throws SQLException {
-            return JdbcOperationSupport.queryList(this.conn, sql, params, rowMapper);
-        }
-
-        /** {@inheritDoc} */
-        @Override
-        public <T> List<T> queryList(String sql, Object[] params, Class<T> clazz)
-                throws SQLException {
-            return JdbcOperationSupport.queryList(this.conn, sql, params, clazz);
-        }
-
-        /** {@inheritDoc} */
-        @Override
-        public List<Map<String, Object>> queryList(String sql, Object[] params)
-                throws SQLException {
-            return JdbcOperationSupport.queryList(this.conn, sql, params, RowMapper.HASH_MAP_MAPPER);
-        }
-
-        // #endregion
-
-        // #region - queryFirst
-
-        /** {@inheritDoc} */
-        @Override
-        public <T> Optional<T> queryFirst(String sql, Object[] params, RowMapper<T> rowMapper)
-                throws SQLException {
-            final T result = JdbcOperationSupport.queryFirst(this.conn, sql, params, rowMapper);
-            return Optional.ofNullable(result);
-        }
-
-        /** {@inheritDoc} */
-        @Override
-        public <T> Optional<T> queryFirst(String sql, Object[] params, Class<T> clazz)
-                throws SQLException {
-            final T result = JdbcOperationSupport.queryFirst(this.conn, sql, params, clazz);
-            return Optional.ofNullable(result);
-        }
-
-        /** {@inheritDoc} */
-        @Override
-        public Optional<Map<String, Object>> queryFirst(String sql, Object[] params)
-                throws SQLException {
-            final Map<String, Object> result = JdbcOperationSupport
-                    .queryFirst(this.conn, sql, params, RowMapper.HASH_MAP_MAPPER);
-            return Optional.ofNullable(result);
-        }
-
-        /** {@inheritDoc} */
-        @Override
-        public boolean queryBoolean(String sql, Object[] params)
-                throws SQLException {
-            final Boolean result = JdbcOperationSupport
-                    .queryFirst(this.conn, sql, params, Boolean.class);
-            return Boolean.TRUE.equals(result);
-        }
-
-        // #endregion
-
-        // #region - update & batchUpdate
-
-        /** {@inheritDoc} */
-        @Override
-        public int update(String sql, Object[] params)
-                throws SQLException {
-            return JdbcOperationSupport.update(this.conn, sql, params);
-        }
-
-        /** {@inheritDoc} */
-        @Override
-        public <T> List<T> updateAndReturnKeys(String sql, Object[] params, RowMapper<T> rowMapper)
-                throws SQLException {
-            return JdbcOperationSupport.updateAndReturnKeys(this.conn, sql, params, rowMapper);
-        }
-
-        /** {@inheritDoc} */
-        @Override
-        public BatchUpdateResult batchUpdate(String sql, @Nullable Collection<Object[]> params, int batchSize)
-                throws SQLException {
-            return JdbcOperationSupport.batchUpdate(this.conn, sql, params, batchSize, false);
-        }
-
-        /** {@inheritDoc} */
-        @Override
-        public BatchUpdateResult batchUpdate(String sql,
-                @Nullable Collection<Object[]> params,
-                int batchSize,
-                boolean quietly) throws SQLException {
-            return JdbcOperationSupport
-                    .batchUpdate(this.conn, sql, params, batchSize, quietly);
-        }
-
-        // #endregion
-
-    }
-
 }
--- a/src/main/java/xyz/zhouxy/jdbc/ThrowingConsumer.java
+++ b/src/main/java/xyz/zhouxy/jdbc/ThrowingConsumer.java
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2026-present ZhouXY
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package xyz.zhouxy.jdbc;
+
+/**
+ * 可抛出受检异常的函数式接口。
+ *
+ * <p>
+ * 类似于 {@link java.util.function.Consumer}，但 {@code accept} 方法允许抛出受检异常。
+ * </p>
+ *
+ * @param <T> 输入类型
+ * @param <E> 允许抛出的异常类型
+ * @author ZhouXY
+ * @since 1.1.0
+ */
+@FunctionalInterface
+public interface ThrowingConsumer<T, E extends Exception> {
+
+    /**
+     * 对给定参数执行此操作。
+     *
+     * @param t 输入参数
+     * @throws E 异常
+     */
+    void accept(T t) throws E;
+}
--- a/src/main/java/xyz/zhouxy/jdbc/ThrowingPredicate.java
+++ b/src/main/java/xyz/zhouxy/jdbc/ThrowingPredicate.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright 2026-present ZhouXY
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package xyz.zhouxy.jdbc;
+
+/**
+ * 可抛出受检异常的谓词函数式接口。
+ *
+ * <p>
+ * 类似于 {@link java.util.function.Predicate}，但 {@code test} 方法允许抛出受检异常。
+ * </p>
+ *
+ * @param <T> 输入类型
+ * @param <E> 允许抛出的异常类型
+ * @author ZhouXY
+ * @since 1.1.0
+ */
+@FunctionalInterface
+public interface ThrowingPredicate<T, E extends Exception> {
+
+    /**
+     * 对给定参数执行此谓词判断。
+     *
+     * @param t 输入参数
+     * @return 谓词判断结果
+     * @throws E 异常
+     */
+    boolean test(T t) throws E;
+}
--- a/src/main/java/xyz/zhouxy/jdbc/TransactionTemplate.java
+++ b/src/main/java/xyz/zhouxy/jdbc/TransactionTemplate.java
@@ -0,0 +1,274 @@
+/*
+ * Copyright 2026-present ZhouXY
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package xyz.zhouxy.jdbc;
+
+import java.sql.Connection;
+import java.sql.SQLException;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import javax.sql.DataSource;
+
+import xyz.zhouxy.jdbc.util.AssertTools;
+
+/**
+ * 事务模板，提供事务执行能力。
+ *
+ * <p>
+ * 负责管理事务的生命周期：开启、提交、回滚、恢复自动提交。
+ * 事务内的 JDBC 操作通过 {@link JdbcOperations} 接口进行，
+ * 所有操作共享同一个数据库连接。
+ * </p>
+ *
+ * <p>使用示例：</p>
+ * <pre>{@code
+ * TransactionTemplate tx = new TransactionTemplate(dataSource);
+ *
+ * // 消费者模式：无异常自动提交
+ * tx.execute(ops -> {
+ *     ops.update("INSERT INTO ...", buildParams(...));
+ *     ops.update("UPDATE ...", buildParams(...));
+ * });
+ *
+ * // 谓词模式：返回 true 提交，false 回滚
+ * tx.commitIfTrue(ops -> {
+ *     ops.update("UPDATE ...", buildParams(...));
+ *     return ops.queryBoolean("SELECT ...", buildParams(...));
+ * });
+ * }</pre>
+ *
+ * @author ZhouXY
+ * @since 1.1.0
+ */
+public class TransactionTemplate {
+
+    @Nonnull
+    private final DataSource dataSource;
+
+    /**
+     * 构造一个 {@code TransactionTemplate} 实例
+     *
+     * @param dataSource 数据源，用于获取数据库连接；不可为 {@code null}
+     */
+    public TransactionTemplate(DataSource dataSource) {
+        AssertTools.checkNotNull(dataSource);
+        this.dataSource = dataSource;
+    }
+
+    /**
+     * 执行事务。如果未发生异常，则提交事务；当有异常发生时，回滚事务
+     *
+     * <p>
+     * operations 中使用 JdbcExecutor 实参进行 JDBC 操作，这些操作在一个连接中
+     * </p>
+     *
+     * @param <E>                   异常类型
+     * @param operations            事务操作
+     * @throws SQLException         SQL 异常
+     * @throws TransactionException 事务异常。事务中的异常会包装在该异常中。
+     */
+    public <E extends Exception> void execute(
+            @Nonnull final ThrowingConsumer<JdbcOperations, E> operations)
+            throws TransactionException, SQLException {
+        AssertTools.checkNotNull(operations, "Operations can not be null.");
+        try (Connection conn = this.dataSource.getConnection()) {
+            final boolean autoCommit = conn.getAutoCommit();
+            try {
+                conn.setAutoCommit(false);
+                operations.accept(new TransactionJdbcExecutor(conn));
+                conn.commit();
+            }
+            catch (Exception e) {
+                rollbackSilently(conn, e);
+                throw new TransactionException(e);
+            }
+            finally {
+                conn.setAutoCommit(autoCommit);
+            }
+        }
+    }
+
+    /**
+     * 执行事务。
+     * 如果 {@code operations} 返回 {@code true}，则提交事务；
+     * 如果抛出异常，或返回 {@code false}，则回滚事务
+     *
+     * @param <E>                   事务中的异常
+     * @param operations            事务操作
+     * @throws SQLException         数据库异常
+     * @throws TransactionException 事务异常。事务中的异常会包装在该异常中。
+     */
+    public <E extends Exception> void commitIfTrue(
+            @Nonnull final ThrowingPredicate<JdbcOperations, E> operations)
+            throws SQLException, TransactionException {
+        AssertTools.checkNotNull(operations, "Operations can not be null.");
+        try (Connection conn = this.dataSource.getConnection()) {
+            final boolean autoCommit = conn.getAutoCommit();
+            try {
+                conn.setAutoCommit(false);
+                if (operations.test(new TransactionJdbcExecutor(conn))) {
+                    conn.commit();
+                }
+                else {
+                    conn.rollback();
+                }
+            }
+            catch (Exception e) {
+                rollbackSilently(conn, e);
+                throw new TransactionException(e);
+            }
+            finally {
+                conn.setAutoCommit(autoCommit);
+            }
+        }
+    }
+
+    private void rollbackSilently(Connection conn, Exception e) {
+        try {
+            conn.rollback();
+        }
+        catch (SQLException ex) {
+            e.addSuppressed(ex);
+        }
+    }
+
+    // #region - TransactionJdbcExecutor
+
+    private static final class TransactionJdbcExecutor implements JdbcOperations {
+
+        private final Connection conn;
+
+        private TransactionJdbcExecutor(Connection conn) {
+            this.conn = conn;
+        }
+
+        // #region - query
+
+        /** {@inheritDoc} */
+        @Override
+        public <T> T query(String sql, Object[] params, ResultHandler<T> resultHandler)
+                throws SQLException {
+            return JdbcOperationSupport.query(this.conn, sql, params, resultHandler);
+        }
+
+        // #endregion
+
+        // #region - queryList
+
+        /** {@inheritDoc} */
+        @Override
+        public <T> List<T> queryList(String sql, Object[] params, RowMapper<T> rowMapper)
+                throws SQLException {
+            return JdbcOperationSupport.queryList(this.conn, sql, params, rowMapper);
+        }
+
+        /** {@inheritDoc} */
+        @Override
+        public <T> List<T> queryValues(String sql, Object[] params, Class<T> clazz)
+                throws SQLException {
+            return JdbcOperationSupport.queryValues(this.conn, sql, params, clazz);
+        }
+
+        /** {@inheritDoc} */
+        @Override
+        public List<Map<String, Object>> queryList(String sql, Object[] params)
+                throws SQLException {
+            return JdbcOperationSupport.queryList(this.conn, sql, params, RowMapper.HASH_MAP_MAPPER);
+        }
+
+        // #endregion
+
+        // #region - queryFirst
+
+        /** {@inheritDoc} */
+        @Override
+        public <T> Optional<T> queryFirst(String sql, Object[] params, RowMapper<T> rowMapper)
+                throws SQLException {
+            final T result = JdbcOperationSupport.queryFirst(this.conn, sql, params, rowMapper);
+            return Optional.ofNullable(result);
+        }
+
+        /** {@inheritDoc} */
+        @Override
+        public <T> Optional<T> queryValue(String sql, Object[] params, Class<T> clazz)
+                throws SQLException {
+            final T result = JdbcOperationSupport.queryValue(this.conn, sql, params, clazz);
+            return Optional.ofNullable(result);
+        }
+
+        /** {@inheritDoc} */
+        @Override
+        public Optional<Map<String, Object>> queryFirst(String sql, Object[] params)
+                throws SQLException {
+            final Map<String, Object> result = JdbcOperationSupport
+                    .queryFirst(this.conn, sql, params, RowMapper.HASH_MAP_MAPPER);
+            return Optional.ofNullable(result);
+        }
+
+        /** {@inheritDoc} */
+        @Override
+        public boolean queryBoolean(String sql, Object[] params)
+                throws SQLException {
+            final Boolean result = JdbcOperationSupport
+                    .queryValue(this.conn, sql, params, Boolean.class);
+            return Boolean.TRUE.equals(result);
+        }
+
+        // #endregion
+
+        // #region - update & batchUpdate
+
+        /** {@inheritDoc} */
+        @Override
+        public int update(String sql, Object[] params)
+                throws SQLException {
+            return JdbcOperationSupport.update(this.conn, sql, params);
+        }
+
+        /** {@inheritDoc} */
+        @Override
+        public <T> List<T> updateAndReturnKeys(String sql, Object[] params, RowMapper<T> rowMapper)
+                throws SQLException {
+            return JdbcOperationSupport.updateAndReturnKeys(this.conn, sql, params, rowMapper);
+        }
+
+        /** {@inheritDoc} */
+        @Override
+        public BatchUpdateResult batchUpdate(String sql, @Nullable Collection<Object[]> params, int batchSize)
+                throws SQLException {
+            return JdbcOperationSupport.batchUpdate(this.conn, sql, params, batchSize, false);
+        }
+
+        /** {@inheritDoc} */
+        @Override
+        public BatchUpdateResult batchUpdate(String sql,
+                @Nullable Collection<Object[]> params,
+                int batchSize,
+                boolean quietly) throws SQLException {
+            return JdbcOperationSupport
+                    .batchUpdate(this.conn, sql, params, batchSize, quietly);
+        }
+
+        // #endregion
+
+    }
+
+    // #endregion
+}
--- a/src/main/java/xyz/zhouxy/jdbc/util/AssertTools.java
+++ b/src/main/java/xyz/zhouxy/jdbc/util/AssertTools.java
@@ -0,0 +1,334 @@
+/*
+ * Copyright 2024-present ZhouXY
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package xyz.zhouxy.jdbc.util;
+
+import java.util.function.Supplier;
+
+/**
+ * 断言工具
+ *
+ * <p>
+ * 本工具类不封装过多判断逻辑，鼓励充分使用项目中的工具类进行逻辑判断。
+ *
+ * <pre>
+ * checkArgument(StringUtils.hasText(str), "The argument cannot be blank.");
+ * checkState(ArrayUtils.isNotEmpty(result), "The result cannot be empty.");
+ * checkCondition(!CollectionUtils.isEmpty(roles),
+ *     () -&gt; new InvalidInputException("The roles cannot be empty."));
+ * checkCondition(RegexTools.matches(email, PatternConsts.EMAIL),
+ *     "must be a well-formed email address");
+ * </pre>
+ *
+ * @author ZhouXY
+ */
+public class AssertTools {
+
+    // ================================
+    // #region - Argument
+    // ================================
+
+    /**
+     * 检查实参
+     *
+     * @param condition 判断参数是否符合条件的结果
+     * @throws IllegalArgumentException 当条件不满足时抛出
+     */
+    public static void checkArgument(boolean condition) {
+        if (!condition) {
+            throw new IllegalArgumentException();
+        }
+    }
+
+    /**
+     * 检查实参
+     *
+     * @param condition 判断参数是否符合条件的结果
+     * @param errorMessage 异常信息
+     * @throws IllegalArgumentException 当条件不满足时抛出
+     */
+    public static void checkArgument(boolean condition, String errorMessage) {
+        if (!condition) {
+            throw new IllegalArgumentException(errorMessage);
+        }
+    }
+
+    /**
+     * 检查实参
+     *
+     * @param condition 判断参数是否符合条件的结果
+     * @param errorMessageSupplier 异常信息
+     * @throws IllegalArgumentException 当条件不满足时抛出
+     */
+    public static void checkArgument(boolean condition, Supplier<String> errorMessageSupplier) {
+        if (!condition) {
+            throw new IllegalArgumentException(errorMessageSupplier.get());
+        }
+    }
+
+    /**
+     * 检查实参
+     *
+     * @param condition 判断参数是否符合条件的结果
+     * @param errorMessageTemplate 异常信息模板
+     * @param errorMessageArgs 异常信息参数
+     * @throws IllegalArgumentException 当条件不满足时抛出
+     */
+    public static void checkArgument(boolean condition,
+            String errorMessageTemplate, Object... errorMessageArgs) {
+        if (!condition) {
+            throw new IllegalArgumentException(String.format(errorMessageTemplate, errorMessageArgs));
+        }
+    }
+
+    // ================================
+    // #endregion - Argument
+    // ================================
+
+    // ================================
+    // #region - ArgumentNotNull
+    // ================================
+
+    /**
+     * 判断入参不为 {@code null}
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @return 校验通过时返回入参
+     * @throws IllegalArgumentException 当 {@code obj} 为 {@code null} 时抛出
+     */
+    public static <T> T checkArgumentNotNull(T obj) {
+        if (obj == null) {
+            throw new IllegalArgumentException();
+        }
+        return obj;
+    }
+
+    /**
+     * 判断入参不为 {@code null}
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @param errorMessage 异常信息
+     * @return 校验通过时返回入参
+     * @throws IllegalArgumentException 当 {@code obj} 为 {@code null} 时抛出
+     */
+    public static <T> T checkArgumentNotNull(T obj, String errorMessage) {
+        if (obj == null) {
+            throw new IllegalArgumentException(errorMessage);
+        }
+        return obj;
+    }
+
+    /**
+     * 判断入参不为 {@code null}
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @param errorMessageSupplier 异常信息
+     * @return 校验通过时返回入参
+     * @throws IllegalArgumentException 当 {@code obj} 为 {@code null} 时抛出
+     */
+    public static <T> T checkArgumentNotNull(T obj, Supplier<String> errorMessageSupplier) {
+        if (obj == null) {
+            throw new IllegalArgumentException(errorMessageSupplier.get());
+        }
+        return obj;
+    }
+
+    /**
+     * 判断入参不为 {@code null}
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @param errorMessageTemplate 异常信息模板
+     * @param errorMessageArgs 异常信息参数
+     * @return 校验通过时返回入参
+     * @throws IllegalArgumentException 当 {@code obj} 为 {@code null} 时抛出
+     */
+    public static <T> T checkArgumentNotNull(T obj,
+            String errorMessageTemplate, Object... errorMessageArgs) {
+        if (obj == null) {
+            throw new IllegalArgumentException(String.format(errorMessageTemplate, errorMessageArgs));
+        }
+        return obj;
+    }
+
+    // ================================
+    // #endregion - ArgumentNotNull
+    // ================================
+
+    // ================================
+    // #region - State
+    // ================================
+
+    /**
+     * 检查状态
+     *
+     * @param condition 判断状态是否符合条件的结果
+     * @throws IllegalStateException 当条件不满足时抛出
+     */
+    public static void checkState(boolean condition) {
+        if (!condition) {
+            throw new IllegalStateException();
+        }
+    }
+
+    /**
+     * 检查状态
+     *
+     * @param condition 判断状态是否符合条件的结果
+     * @param errorMessage 异常信息
+     * @throws IllegalStateException 当条件不满足时抛出
+     */
+    public static void checkState(boolean condition, String errorMessage) {
+        if (!condition) {
+            throw new IllegalStateException(errorMessage);
+        }
+    }
+
+    /**
+     * 检查状态
+     *
+     * @param condition 判断状态是否符合条件的结果
+     * @param errorMessageSupplier 异常信息
+     * @throws IllegalStateException 当条件不满足时抛出
+     */
+    public static void checkState(boolean condition, Supplier<String> errorMessageSupplier) {
+        if (!condition) {
+            throw new IllegalStateException(errorMessageSupplier.get());
+        }
+    }
+
+    /**
+     * 检查状态
+     *
+     * @param condition 判断状态是否符合条件的结果
+     * @param errorMessageTemplate 异常信息模板
+     * @param errorMessageArgs 异常信息参数
+     * @throws IllegalStateException 当条件不满足时抛出
+     */
+    public static void checkState(boolean condition,
+            String errorMessageTemplate, Object... errorMessageArgs) {
+        if (!condition) {
+            throw new IllegalStateException(String.format(errorMessageTemplate, errorMessageArgs));
+        }
+    }
+
+    // ================================
+    // #endregion - State
+    // ================================
+
+    // ================================
+    // #region - NotNull
+    // ================================
+
+    /**
+     * 判空
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
+     */
+    public static <T> void checkNotNull(T obj) {
+        if (obj == null) {
+            throw new NullPointerException();
+        }
+    }
+
+    /**
+     * 判空
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @param errorMessage 异常信息
+     * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
+     */
+    public static <T> void checkNotNull(T obj, String errorMessage) {
+        if (obj == null) {
+            throw new NullPointerException(errorMessage);
+        }
+    }
+
+    /**
+     * 判空
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @param errorMessageSupplier 异常信息
+     * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
+     */
+    public static <T> void checkNotNull(T obj, Supplier<String> errorMessageSupplier) {
+        if (obj == null) {
+            throw new NullPointerException(errorMessageSupplier.get());
+        }
+    }
+
+    /**
+     * 判空
+     *
+     * @param <T> 入参类型
+     * @param obj 入参
+     * @param errorMessageTemplate 异常信息模板
+     * @param errorMessageArgs 异常信息参数
+     * @throws NullPointerException 当 {@code obj} 为 {@code null} 时抛出
+     */
+    public static <T> void checkNotNull(T obj,
+            String errorMessageTemplate, Object... errorMessageArgs) {
+        if (obj == null) {
+            throw new NullPointerException(String.format(errorMessageTemplate, errorMessageArgs));
+        }
+    }
+
+    // ================================
+    // #endregion - NotNull
+    // ================================
+
+    // ================================
+    // #region - Condition
+    // ================================
+
+    /**
+     * 当条件不满足时抛出异常。
+     *
+     * @param <T> 异常类型
+     * @param condition 条件
+     * @param e 异常
+     * @throws T 当条件不满足时抛出异常
+     */
+    public static <T extends Exception> void checkCondition(boolean condition, Supplier<T> e)
+            throws T {
+        if (!condition) {
+            throw e.get();
+        }
+    }
+
+    // ================================
+    // #endregion
+    // ================================
+
+    // ================================
+    // #region - constructor
+    // ================================
+
+    private AssertTools() {
+        throw new IllegalStateException("Utility class");
+    }
+
+    // ================================
+    // #endregion
+    // ================================
+}
--- a/src/main/java/xyz/zhouxy/jdbc/util/NamingTools.java
+++ b/src/main/java/xyz/zhouxy/jdbc/util/NamingTools.java
@@ -0,0 +1,96 @@
+/*
+ * Copyright 2026-present ZhouXY
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package xyz.zhouxy.jdbc.util;
+
+/**
+ * 字符串工具
+ *
+ * @author ZhouXY
+ * @since 1.0.0
+ */
+public class NamingTools {
+
+    /**
+     * 将小驼峰命名转换为小写下划线命名（snake_case）。
+     *
+     * <p>转换规则：
+     * <ul>
+     * <li>小写→大写边界插入下划线：{@code userName → user_name}</li>
+     * <li>连续大写缩写视为整体，在其末尾小写边界插入下划线：{@code XMLParser → xml_parser}</li>
+     * <li>纯小写保持不变：{@code username → username}</li>
+     * <li>{@code null} 或空字符串返回原值</li>
+     * </ul>
+     *
+     * @param camelCase 小驼峰命名字符串，可空
+     * @return snake_case 命名字符串；{@code null} 输入返回 {@code null}
+     */
+    public static String camelToSnake(String camelCase) {
+        if (camelCase == null || camelCase.isEmpty()) {
+            return camelCase;
+        }
+
+        StringBuilder sb = new StringBuilder(camelCase.length() * 2);
+        int len = camelCase.length();
+
+        for (int i = 0; i < len; i++) {
+            char c = camelCase.charAt(i);
+            if (isUpperCaseAscii(c)) {
+                if (shouldInsertUnderscore(camelCase, i)) {
+                    sb.append('_');
+                }
+                sb.append((char) (c + 32)); // 转小写
+            } else {
+                sb.append(c);
+            }
+        }
+        return sb.toString();
+    }
+
+    private static boolean shouldInsertUnderscore(String str, int index) {
+        if (index == 0) {
+            return false;
+        }
+
+        char prev = str.charAt(index - 1);
+        char next = (index + 1 < str.length()) ? str.charAt(index + 1) : 0;
+
+        boolean prevIsBoundary = !isUpperCaseAscii(prev);
+        boolean nextIsLower = isLowerCaseAscii(next);
+
+        return prevIsBoundary || nextIsLower;
+    }
+
+    private static boolean isUpperCaseAscii(char c) {
+        return c >= 'A' && c <= 'Z';
+    }
+
+    private static boolean isLowerCaseAscii(char c) {
+        return c >= 'a' && c <= 'z';
+    }
+
+    // ================================
+    // #region - constructor
+    // ================================
+
+    private NamingTools() {
+        throw new IllegalStateException("Utility class");
+    }
+
+    // ================================
+    // #endregion
+    // ================================
+}
--- a/src/test/java/xyz/zhouxy/jdbc/test/BatchUpdateTest.java
+++ b/src/test/java/xyz/zhouxy/jdbc/test/BatchUpdateTest.java
@@ -6,6 +6,7 @@ import static xyz.zhouxy.jdbc.ParamBuilder.*;
 import java.sql.SQLException;
 import java.sql.Statement;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
@@ -16,8 +17,6 @@ import org.junit.jupiter.api.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;

-import com.google.common.collect.Lists;
-
 import xyz.zhouxy.jdbc.BatchUpdateErrorInfo;
 import xyz.zhouxy.jdbc.BatchUpdateResult;
 import xyz.zhouxy.jdbc.BatchUpdateStatus;
@@ -170,7 +169,7 @@ class BatchUpdateTest extends BaseH2Test {
    // #region - 包含错误数据
    // ================================

-    final List<User> userListContainingInvalidData = Lists.newArrayList(
+    final List<User> userListContainingInvalidData = Arrays.asList(
            // batch 0
            new User("test_0001", "test_0001@example.com", 1, 1L, true),
            new User("test_0002", "test_0002@example.com", 1, 1L, true),
@@ -200,7 +199,7 @@ class BatchUpdateTest extends BaseH2Test {
    void testBatchUpdateQuietlyFalseInterrupted() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

-        int count0 = template.queryFirst("SELECT COUNT(*) FROM users", Integer.class)
+        int count0 = template.queryValue("SELECT COUNT(*) FROM users", Integer.class)
                .orElse(0);

        List<Object[]> params = buildBatchParams(userListContainingInvalidData, a -> new Object[] { a.getUsername(), a.getEmail(), a.getAge(), a.getBalance(), a.getActive() });
@@ -232,7 +231,7 @@ class BatchUpdateTest extends BaseH2Test {
        assertNull(result.getUpdateCounts(3));
        assertNull(result.getUpdateCounts(4));

-        Optional<Integer> count8 = template.queryFirst("SELECT COUNT(*) FROM users", Integer.class);
+        Optional<Integer> count8 = template.queryValue("SELECT COUNT(*) FROM users", Integer.class);
        assertEquals(count0 + 8, count8.get().intValue());
    }

@@ -243,7 +242,7 @@ class BatchUpdateTest extends BaseH2Test {
    void testBatchUpdateQuietlyTrue() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

-        int count0 = template.queryFirst("SELECT COUNT(*) FROM users", Integer.class)
+        int count0 = template.queryValue("SELECT COUNT(*) FROM users", Integer.class)
                .orElse(0);

        List<Object[]> params = buildBatchParams(userListContainingInvalidData, a -> new Object[] { a.getUsername(), a.getEmail(), a.getAge(), a.getBalance(), a.getActive() });
@@ -262,7 +261,7 @@ class BatchUpdateTest extends BaseH2Test {
        assertArrayEquals(new int[] { Statement.EXECUTE_FAILED, 1, 1 }, result.getUpdateCounts(3));
        assertArrayEquals(new int[] { 1 }, result.getUpdateCounts(4));

-        Optional<Integer> count11 = template.queryFirst("SELECT COUNT(*) FROM users", Integer.class);
+        Optional<Integer> count11 = template.queryValue("SELECT COUNT(*) FROM users", Integer.class);
        assertEquals(count0 + 11, count11.get().intValue());
    }

--- a/src/test/java/xyz/zhouxy/jdbc/test/ParamBuilderTest.java
+++ b/src/test/java/xyz/zhouxy/jdbc/test/ParamBuilderTest.java
@@ -0,0 +1,253 @@
+package xyz.zhouxy.jdbc.test;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static xyz.zhouxy.jdbc.ParamBuilder.*;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+import java.util.OptionalDouble;
+import java.util.OptionalInt;
+import java.util.OptionalLong;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.LocalTime;
+import java.util.function.Function;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import xyz.zhouxy.jdbc.ParamBuilder;
+
+/**
+ * ParamBuilder 单元测试。
+ *
+ * <p>验证 {@code buildParams} 对各种 Optional 类型的拆箱处理，
+ * 以及 {@code buildBatchParams} 对集合的批量映射逻辑。</p>
+ *
+ * @see xyz.zhouxy.jdbc.ParamBuilder
+ */
+@DisplayName("ParamBuilder 参数构建测试")
+class ParamBuilderTest {
+
+    // ====================================================================
+    // #region - buildParams：空参数
+    // --------------------------------------------------------------------
+
+    @Test
+    @DisplayName("buildParams：无参 / null / 空数组均返回 EMPTY_OBJECT_ARRAY")
+    void testBuildParamsEmpty() {
+        assertSame(EMPTY_OBJECT_ARRAY, buildParams());
+        assertSame(EMPTY_OBJECT_ARRAY, buildParams((Object[]) null));
+        assertSame(EMPTY_OBJECT_ARRAY, buildParams(new Object[0]));
+    }
+
+    // --------------------------------------------------------------------
+    // #endregion
+    // ====================================================================
+
+    // ====================================================================
+    // #region - buildParams：普通参数
+    // --------------------------------------------------------------------
+
+    @Test
+    @DisplayName("buildParams：普通参数原样返回，null 元素保留（README 示例）")
+    void testBuildParamsPlain() {
+        Object[] result = buildParams("admin%", "0000", null, 100, 200L, 3.14, true);
+
+        assertEquals(7, result.length);
+        assertEquals("admin%", result[0]);
+        assertEquals("0000", result[1]);
+        assertNull(result[2]);
+        assertEquals(100, result[3]);
+        assertEquals(200L, result[4]);
+        assertEquals(3.14, result[5]);
+        assertEquals(true, result[6]);
+    }
+
+    // --------------------------------------------------------------------
+    // #endregion
+    // ====================================================================
+
+    // ====================================================================
+    // #region - buildParams：Optional<?>
+    // --------------------------------------------------------------------
+
+    @Test
+    @DisplayName("buildParams：Optional.of 拆箱为值，Optional.empty 拆箱为 null（README 示例）")
+    void testBuildParamsOptional() {
+        // README: Optional.of("hello") → "hello", Optional.empty() → null
+        Object[] result = buildParams(Optional.of("hello"), Optional.empty(), Optional.of(42));
+
+        assertEquals(3, result.length);
+        assertEquals("hello", result[0]);
+        assertNull(result[1]);
+        assertEquals(42, result[2]);
+    }
+
+    // --------------------------------------------------------------------
+    // #endregion
+    // ====================================================================
+
+    // ====================================================================
+    // #region - buildParams：OptionalInt / OptionalLong / OptionalDouble
+    // --------------------------------------------------------------------
+
+    @Test
+    @DisplayName("buildParams：OptionalInt.of → Integer，empty → null")
+    void testBuildParamsOptionalInt() {
+        Object[] result = buildParams(OptionalInt.of(42), OptionalInt.empty());
+
+        assertEquals(2, result.length);
+        assertEquals(42, result[0]);
+        assertInstanceOf(Integer.class, result[0]);
+        assertNull(result[1]);
+    }
+
+    @Test
+    @DisplayName("buildParams：OptionalLong.of → Long，empty → null")
+    void testBuildParamsOptionalLong() {
+        Object[] result = buildParams(OptionalLong.of(100L), OptionalLong.empty());
+
+        assertEquals(2, result.length);
+        assertEquals(100L, result[0]);
+        assertInstanceOf(Long.class, result[0]);
+        assertNull(result[1]);
+    }
+
+    @Test
+    @DisplayName("buildParams：OptionalDouble.of → Double，empty → null")
+    void testBuildParamsOptionalDouble() {
+        Object[] result = buildParams(OptionalDouble.of(3.14), OptionalDouble.empty());
+
+        assertEquals(2, result.length);
+        assertEquals(3.14, result[0]);
+        assertInstanceOf(Double.class, result[0]);
+        assertNull(result[1]);
+    }
+
+    // --------------------------------------------------------------------
+    // #endregion
+    // ====================================================================
+
+    // ====================================================================
+    // #region - buildParams：混合所有类型
+    // --------------------------------------------------------------------
+
+    @Test
+    @DisplayName("buildParams：混合所有 Optional + 普通类型 + null")
+    void testBuildParamsMixedAll() {
+        Object[] result = buildParams(
+                Optional.of("present"), Optional.empty(),
+                OptionalInt.of(10), OptionalInt.empty(),
+                OptionalLong.of(200L), OptionalLong.empty(),
+                OptionalDouble.of(1.5), OptionalDouble.empty(),
+                "plain", 999, null);
+
+        assertEquals(11, result.length);
+        assertEquals("present", result[0]);
+        assertNull(result[1]);
+        assertEquals(10, result[2]);
+        assertNull(result[3]);
+        assertEquals(200L, result[4]);
+        assertNull(result[5]);
+        assertEquals(1.5, result[6]);
+        assertNull(result[7]);
+        assertEquals("plain", result[8]);
+        assertEquals(999, result[9]);
+        assertNull(result[10]);
+    }
+
+    // --------------------------------------------------------------------
+    // #endregion
+    // ====================================================================
+
+    // ====================================================================
+    // #region - buildParams：Temporal 时间类型
+    // --------------------------------------------------------------------
+
+    @Test
+    @DisplayName("buildParams：Temporal 类型（LocalDate / LocalTime / LocalDateTime）")
+    void testBuildParamsTemporal() {
+        LocalDate date = LocalDate.of(2024, 6, 15);
+        LocalTime time = LocalTime.of(14, 30, 0);
+        LocalDateTime dateTime = LocalDateTime.of(date, time);
+
+        Object[] result = buildParams(date, time, dateTime);
+
+        assertEquals(3, result.length);
+        assertSame(date, result[0]);
+        assertSame(time, result[1]);
+        assertSame(dateTime, result[2]);
+    }
+
+    // --------------------------------------------------------------------
+    // #endregion
+    // ====================================================================
+
+    // ====================================================================
+    // #region - buildBatchParams
+    // --------------------------------------------------------------------
+
+    @Test
+    @DisplayName("buildBatchParams：集合映射为 List<Object[]>，配合 buildParams 使用（README 示例风格）")
+    void testBuildBatchParams() {
+        List<String[]> data = Arrays.asList(
+                new String[]{"admin", "123456", "0000"},
+                new String[]{"user1", "pass1", "0001"},
+                new String[]{"user2", "pass2", "0002"});
+
+        // README 风格: buildBatchParams(collection, item -> buildParams(...))
+        List<Object[]> result = buildBatchParams(data,
+                row -> buildParams(row[0], row[1], row[2]));
+
+        assertEquals(3, result.size());
+        assertArrayEquals(new Object[]{"admin", "123456", "0000"}, result.get(0));
+        assertArrayEquals(new Object[]{"user1", "pass1", "0001"}, result.get(1));
+        assertArrayEquals(new Object[]{"user2", "pass2", "0002"}, result.get(2));
+    }
+
+    @Test
+    @DisplayName("buildBatchParams：边界情况——空集合 / null collection / null func")
+    void testBuildBatchParamsBoundary() {
+        // 空集合返回 Collections.emptyList()
+        List<Object[]> emptyResult = buildBatchParams(Collections.emptyList(),
+                (Function<Object, Object[]>) obj -> new Object[]{obj});
+        assertTrue(emptyResult.isEmpty());
+        assertSame(Collections.emptyList(), emptyResult);
+
+        // null collection 抛异常
+        assertThrows(Exception.class, () ->
+                buildBatchParams(null, (Function<Object, Object[]>) obj -> new Object[]{obj}));
+
+        // null func 抛异常
+        assertThrows(Exception.class, () ->
+                buildBatchParams(Arrays.asList("a", "b"), null));
+    }
+
+    // --------------------------------------------------------------------
+    // #endregion
+    // ====================================================================
+
+    // ====================================================================
+    // #region - 私有构造器
+    // --------------------------------------------------------------------
+
+    @Test
+    @DisplayName("私有构造器抛 IllegalStateException")
+    void testPrivateConstructor() throws Exception {
+        java.lang.reflect.Constructor<ParamBuilder> ctor =
+                ParamBuilder.class.getDeclaredConstructor();
+        ctor.setAccessible(true);
+
+        java.lang.reflect.InvocationTargetException ex = assertThrows(
+                java.lang.reflect.InvocationTargetException.class, ctor::newInstance);
+        assertInstanceOf(IllegalStateException.class, ex.getCause());
+        assertEquals("Utility class", ex.getCause().getMessage());
+    }
+
+    // --------------------------------------------------------------------
+    // #endregion
+    // ====================================================================
+}
--- a/src/test/java/xyz/zhouxy/jdbc/test/QueryTest.java
+++ b/src/test/java/xyz/zhouxy/jdbc/test/QueryTest.java
@@ -18,7 +18,7 @@ import xyz.zhouxy.jdbc.ResultHandler;
 import xyz.zhouxy.jdbc.SimpleJdbcTemplate;

 /**
- * 查询 API 测试：query、queryList、queryFirst、queryBoolean。
+ * 查询 API 测试：query、queryList、queryFirst、queryValues、queryValue、queryBoolean。
 */
@DisplayName("SimpleJdbcTemplate 查询操作")
 class QueryTest extends BaseH2Test {
@@ -119,28 +119,28 @@ class QueryTest extends BaseH2Test {
        assertEquals(5, users.size());
    }

-    // ==================== queryList(Class) ====================
+    // ==================== queryValues(Class) ====================

    @Test
-    @DisplayName("queryList(Class)：单列查询返回 String 列表")
-    void testQueryListWithClassString() throws SQLException {
+    @DisplayName("queryValues(Class)：单列查询返回 String 列表")
+    void testQueryValuesWithClassString() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

-        List<String> usernames = template.queryList(
+        List<String> usernames = template.queryValues(
                "SELECT username FROM users ORDER BY id",
                String.class);

-        logger.info("queryList(Class) 返回用户名: {}", usernames);
+        logger.info("queryValues(Class) 返回用户名: {}", usernames);
        assertEquals(5, usernames.size());
        assertTrue(usernames.contains("alice"));
    }

    @Test
-    @DisplayName("queryList(Class)：空结果集返回空列表")
-    void testQueryListEmptyResult() throws SQLException {
+    @DisplayName("queryValues(Class)：空结果集返回空列表")
+    void testQueryValuesEmptyResult() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

-        List<String> result = template.queryList(
+        List<String> result = template.queryValues(
                "SELECT username FROM users WHERE id = ?",
                buildParams(999), String.class);

@@ -215,14 +215,14 @@ class QueryTest extends BaseH2Test {
        assertTrue(user.isPresent());
    }

-    // ==================== queryFirst(Class) ====================
+    // ==================== queryValue(Class) ====================

    @Test
-    @DisplayName("queryFirst(Class)：查询第一行第一列")
-    void testQueryFirstWithClass() throws SQLException {
+    @DisplayName("queryValue(Class)：查询第一行第一列")
+    void testQueryValueWithClass() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

-        Optional<String> username = template.queryFirst(
+        Optional<String> username = template.queryValue(
                "SELECT username FROM users ORDER BY id",
                String.class);

@@ -231,11 +231,11 @@ class QueryTest extends BaseH2Test {
    }

    @Test
-    @DisplayName("queryFirst(Class)：空结果返回 Optional.empty()")
-    void testQueryFirstClassEmpty() throws SQLException {
+    @DisplayName("queryValue(Class)：空结果返回 Optional.empty()")
+    void testQueryValueClassEmpty() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

-        Optional<String> result = template.queryFirst(
+        Optional<String> result = template.queryValue(
                "SELECT username FROM users WHERE id = ?",
                buildParams(999), String.class);

@@ -244,11 +244,11 @@ class QueryTest extends BaseH2Test {


    @Test
-    @DisplayName("queryFirst + Class：统计总行数")
-    void testQueryFirstWithClass_queryCount() throws SQLException {
+    @DisplayName("queryValue + Class：统计总行数")
+    void testQueryValueWithClass_queryCount() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

-        int count = template.queryFirst(
+        int count = template.queryValue(
                "SELECT COUNT(*) FROM users",
                new Object[0],
                Integer.class)
@@ -259,11 +259,11 @@ class QueryTest extends BaseH2Test {
    }

    @Test
-    @DisplayName("queryFirst + Class：聚合求和")
-    void testQueryFirstWithClass_queryAggregation() throws SQLException {
+    @DisplayName("queryValue + Class：聚合求和")
+    void testQueryValueWithClass_queryAggregation() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

-        Long totalBalance = template.queryFirst(
+        Long totalBalance = template.queryValue(
                "SELECT SUM(balance) FROM users",
                new Object[0],
                Long.class)
@@ -273,6 +273,81 @@ class QueryTest extends BaseH2Test {
        assertNotNull(totalBalance);
    }

+    // ==================== queryValueOrDefault ====================
+
+    @Test
+    @DisplayName("queryValueOrDefault：有结果时返回值")
+    void testQueryValueOrDefaultWithResult() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        String username = template.queryValueOrDefault(
+                "SELECT username FROM users WHERE id = ?",
+                new Object[]{1}, String.class, "default");
+
+        assertEquals("alice", username);
+    }
+
+    @Test
+    @DisplayName("queryValueOrDefault：无结果时返回默认值")
+    void testQueryValueOrDefaultWithDefault() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        String username = template.queryValueOrDefault(
+                "SELECT username FROM users WHERE id = ?",
+                new Object[]{999}, String.class, "unknown");
+
+        assertEquals("unknown", username);
+    }
+
+    @Test
+    @DisplayName("queryValueOrDefault：COUNT 聚合查询")
+    void testQueryValueOrDefaultCount() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        long count = template.queryValueOrDefault(
+                "SELECT COUNT(*) FROM users",
+                new Object[0], Long.class, 0L);
+
+        assertEquals(5L, count);
+    }
+
+    @Test
+    @DisplayName("queryValueOrDefault：SUM 聚合查询")
+    void testQueryValueOrDefaultSum() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        long totalBalance = template.queryValueOrDefault(
+                "SELECT SUM(balance) FROM users",
+                new Object[0], Long.class, 0L);
+
+        assertTrue(totalBalance > 0);
+        logger.info("queryValueOrDefault SUM 结果: {}", totalBalance);
+    }
+
+    @Test
+    @DisplayName("queryValueOrDefault：无参数重载")
+    void testQueryValueOrDefaultNoParams() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        long count = template.queryValueOrDefault(
+                "SELECT COUNT(*) FROM users",
+                Long.class, 0L);
+
+        assertEquals(5L, count);
+    }
+
+    @Test
+    @DisplayName("queryValueOrDefault：空表 COUNT 返回默认值 0")
+    void testQueryValueOrDefaultEmptyTable() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        long count = template.queryValueOrDefault(
+                "SELECT COUNT(*) FROM users WHERE id = ?",
+                new Object[]{999}, Long.class, 0L);
+
+        assertEquals(0L, count);
+    }
+
    // ==================== queryFirst(Map) ====================

    @Test
@@ -385,7 +460,7 @@ class QueryTest extends BaseH2Test {
        SimpleJdbcTemplate template = createTemplate();

        assertThrows(SQLException.class, () ->
-                template.queryList("SELECT * FROM non_existent_table",
+                template.queryValues("SELECT * FROM non_existent_table",
                        new Object[0], String.class));
    }

@@ -395,7 +470,7 @@ class QueryTest extends BaseH2Test {
        SimpleJdbcTemplate template = createTemplate();

        assertThrows(SQLException.class, () ->
-                template.queryList("SELEC * FROM users",
+                template.queryValues("SELEC * FROM users",
                        new Object[0], String.class));
    }

--- a/src/test/java/xyz/zhouxy/jdbc/test/RowMapperTest.java
+++ b/src/test/java/xyz/zhouxy/jdbc/test/RowMapperTest.java
@@ -137,9 +137,9 @@ class RowMapperTest extends BaseH2Test {
    }

    @Test
-    @DisplayName("DefaultBeanRowMapper：无无参构造器的 Bean 抛出 SQLException")
+    @DisplayName("DefaultBeanRowMapper：无无参构造器的 Bean 抛出 IllegalStateException")
    void testDefaultBeanRowMapperNoNoArgConstructor() {
-        assertThrows(SQLException.class, () ->
+        assertThrows(IllegalStateException.class, () ->
                DefaultBeanRowMapper.of(BeanWithoutNoArgConstructor.class));
    }

@@ -157,6 +157,63 @@ class RowMapperTest extends BaseH2Test {
        assertEquals("alice", user.get().getUsername());
    }

+    // ==================== DefaultBeanRowMapper 连续大写缩写映射 ====================
+
+    @Test
+    @DisplayName("DefaultBeanRowMapper：连续大写缩写属性正确映射为 snake_case")
+    void testDefaultBeanRowMapperAcronymMapping() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        // 创建测试表，列名使用 snake_case
+        template.update("CREATE TABLE acronym_test ("
+                + "id BIGINT AUTO_INCREMENT PRIMARY KEY,"
+                + "home_url VARCHAR(100),"
+                + "xml_parser VARCHAR(100),"
+                + "parse_url VARCHAR(100),"
+                + "user_id VARCHAR(100),"
+                + "parse_html VARCHAR(100),"
+                + "multi_http_client VARCHAR(100))");
+        template.update(
+                "INSERT INTO acronym_test (home_url, xml_parser, parse_url, user_id, parse_html, multi_http_client)"
+                        + " VALUES (?, ?, ?, ?, ?, ?)",
+                new Object[]{"https://example.com", "SAXParser", "/api/v1",
+                        "user-001", "<div>test</div>", "ApacheHttpClient"});
+
+        RowMapper<AcronymBean> rowMapper = RowMapper.beanRowMapper(AcronymBean.class);
+        Optional<AcronymBean> result = template.queryFirst(
+                "SELECT * FROM acronym_test WHERE id = ?",
+                new Object[]{1L}, rowMapper);
+
+        assertTrue(result.isPresent());
+        AcronymBean bean = result.get();
+        assertEquals("https://example.com", bean.getHomeURL());
+        assertEquals("SAXParser", bean.getXmlParser());
+        assertEquals("/api/v1", bean.getParseURL());
+        assertEquals("user-001", bean.getUserID());
+        assertEquals("<div>test</div>", bean.getParseHTML());
+        assertEquals("ApacheHttpClient", bean.getMultiHttpClient());
+
+        logger.info("缩写映射: homeURL={}, xmlParser={}, parseURL={}, userID={}, parseHTML={}, multiHttpClient={}",
+                bean.getHomeURL(), bean.getXmlParser(), bean.getParseURL(),
+                bean.getUserID(), bean.getParseHTML(), bean.getMultiHttpClient());
+    }
+
+    @Test
+    @DisplayName("DefaultBeanRowMapper：纯小写属性名映射为同名列")
+    void testDefaultBeanRowMapperAllLowercaseMapping() throws SQLException {
+        // 通过 User Bean 验证纯小写属性映射（username → username, email → email）
+        SimpleJdbcTemplate template = createTemplate();
+        RowMapper<User> rowMapper = RowMapper.beanRowMapper(User.class);
+
+        Optional<User> user = template.queryFirst(
+                "SELECT username, email FROM users WHERE username = ?",
+                new Object[]{"alice"}, rowMapper);
+
+        assertTrue(user.isPresent());
+        assertEquals("alice", user.get().getUsername());
+        assertEquals("alice@example.com", user.get().getEmail());
+    }
+
    // ==================== HASH_MAP_MAPPER ====================

    @Test
@@ -253,4 +310,74 @@ class RowMapperTest extends BaseH2Test {
            this.name = name;
        }
    }
+
+    /**
+     * 包含连续大写缩写属性的 Bean，用于验证 camelToSnake 的缩写处理。
+     *
+     * <p>覆盖场景：
+     * <ul>
+     * <li>homeURL — 缩写在末尾（三字母 URL）</li>
+     * <li>xmlParser — 缩写在前（三字母 XML）</li>
+     * <li>parseURL — 缩写在末尾</li>
+     * <li>userID — 两字母缩写在末尾（ID）</li>
+     * <li>parseHTML — 四字母缩写在末尾（HTML）</li>
+     * <li>multiHttpClient — 缩写夹在词中（HTTP）</li>
+     * </ul>
+     */
+    public static class AcronymBean {
+        private String homeURL;
+        private String xmlParser;
+        private String parseURL;
+        private String userID;
+        private String parseHTML;
+        private String multiHttpClient;
+
+        public String getHomeURL() {
+            return homeURL;
+        }
+
+        public void setHomeURL(String homeURL) {
+            this.homeURL = homeURL;
+        }
+
+        public String getXmlParser() {
+            return xmlParser;
+        }
+
+        public void setXmlParser(String xmlParser) {
+            this.xmlParser = xmlParser;
+        }
+
+        public String getParseURL() {
+            return parseURL;
+        }
+
+        public void setParseURL(String parseURL) {
+            this.parseURL = parseURL;
+        }
+
+        public String getUserID() {
+            return userID;
+        }
+
+        public void setUserID(String userID) {
+            this.userID = userID;
+        }
+
+        public String getParseHTML() {
+            return parseHTML;
+        }
+
+        public void setParseHTML(String parseHTML) {
+            this.parseHTML = parseHTML;
+        }
+
+        public String getMultiHttpClient() {
+            return multiHttpClient;
+        }
+
+        public void setMultiHttpClient(String multiHttpClient) {
+            this.multiHttpClient = multiHttpClient;
+        }
+    }
 }
--- a/src/test/java/xyz/zhouxy/jdbc/test/TransactionTest.java
+++ b/src/test/java/xyz/zhouxy/jdbc/test/TransactionTest.java
@@ -16,9 +16,10 @@ import xyz.zhouxy.jdbc.SimpleJdbcTemplate;
 import xyz.zhouxy.jdbc.TransactionException;

 /**
- * 事务 API 测试：executeTransaction、commitIfTrue。
+ * 事务 API 测试：通过 {@link xyz.zhouxy.jdbc.TransactionTemplate#execute} 和
+ * {@link xyz.zhouxy.jdbc.TransactionTemplate#commitIfTrue} 测试事务提交与回滚。
 */
-@DisplayName("SimpleJdbcTemplate 事务操作")
+@DisplayName("TransactionTemplate 事务操作")
 class TransactionTest extends BaseH2Test {

    private static final Logger logger = LoggerFactory.getLogger(TransactionTest.class);
@@ -28,14 +29,14 @@ class TransactionTest extends BaseH2Test {
        resetDatabase();
    }

-    // ==================== executeTransaction 正常提交 ====================
+    // ==================== execute 正常提交 ====================

    @Test
-    @DisplayName("executeTransaction：正常提交，数据持久化")
+    @DisplayName("execute：正常提交，数据持久化")
    void testExecuteTransactionCommit() throws Exception {
        SimpleJdbcTemplate template = createTemplate();

-        template.executeTransaction((JdbcOperations ops) -> {
+        template.transaction().execute((JdbcOperations ops) -> {
            ops.update("INSERT INTO users (username, email, age, balance, active) VALUES (?, ?, ?, ?, ?)",
                    buildParams("txUser1", "tx1@test.com", 25, 1000L, true));
            ops.update("UPDATE users SET balance = ? WHERE username = ?",
@@ -43,12 +44,12 @@ class TransactionTest extends BaseH2Test {
        });

        // 验证事务已提交
-        Optional<String> newUser = template.queryFirst(
+        Optional<String> newUser = template.queryValue(
                "SELECT username FROM users WHERE username = ?",
                buildParams("txUser1"), String.class);
        assertTrue(newUser.isPresent());

-        Optional<Long> balance = template.queryFirst(
+        Optional<Long> balance = template.queryValue(
                "SELECT balance FROM users WHERE username = ?",
                buildParams("alice"), Long.class);
        assertEquals(Long.valueOf(99999L), balance.orElse(null));
@@ -56,20 +57,20 @@ class TransactionTest extends BaseH2Test {
        logger.info("事务提交验证通过");
    }

-    // ==================== executeTransaction 异常回滚 ====================
+    // ==================== execute 异常回滚 ====================

    @Test
-    @DisplayName("executeTransaction：异常回滚，数据恢复原状")
+    @DisplayName("execute：异常回滚，数据恢复原状")
    void testExecuteTransactionRollback() throws Exception {
        SimpleJdbcTemplate template = createTemplate();

        // 记录原始 balance
-        Optional<Long> originalBalance = template.queryFirst(
+        Optional<Long> originalBalance = template.queryValue(
                "SELECT balance FROM users WHERE username = ?",
                buildParams("alice"), Long.class);

        TransactionException ex = assertThrows(TransactionException.class, () ->
-                template.executeTransaction((JdbcOperations ops) -> {
+                template.transaction().execute((JdbcOperations ops) -> {
                    ops.update("UPDATE users SET balance = ? WHERE username = ?",
                            buildParams(0L, "alice"));
                    ops.update("INSERT INTO users (username, email) VALUES (?, ?)",
@@ -84,13 +85,13 @@ class TransactionTest extends BaseH2Test {
        assertEquals("模拟业务异常", ex.getCause().getMessage());

        // 验证更新已回滚
-        Optional<Long> currentBalance = template.queryFirst(
+        Optional<Long> currentBalance = template.queryValue(
                "SELECT balance FROM users WHERE username = ?",
                buildParams("alice"), Long.class);
        assertEquals(originalBalance.orElse(null), currentBalance.orElse(null));

        // 验证插入已回滚
-        Optional<String> rolledBackUser = template.queryFirst(
+        Optional<String> rolledBackUser = template.queryValue(
                "SELECT username FROM users WHERE username = ?",
                buildParams("txUser2"), String.class);
        assertFalse(rolledBackUser.isPresent());
@@ -99,12 +100,12 @@ class TransactionTest extends BaseH2Test {
    }

    @Test
-    @DisplayName("executeTransaction：SQL 异常触发回滚")
+    @DisplayName("execute：SQL 异常触发回滚")
    void testExecuteTransactionSqlExceptionRollback() {
        SimpleJdbcTemplate template = createTemplate();

        assertThrows(TransactionException.class, () ->
-                template.executeTransaction((JdbcOperations ops) -> {
+                template.transaction().execute((JdbcOperations ops) -> {
                    ops.update("INSERT INTO users (username) VALUES (?)",
                            buildParams("validUser"));
                    // 错误的 SQL
@@ -113,28 +114,28 @@ class TransactionTest extends BaseH2Test {

        // 验证插入已回滚
        assertDoesNotThrow(() -> {
-            Optional<String> user = template.queryFirst(
+            Optional<String> user = template.queryValue(
                    "SELECT username FROM users WHERE username = ?",
                    buildParams("validUser"), String.class);
            assertFalse(user.isPresent());
        });
    }

-    // ==================== commitIfTrue 返回 true 提交 ====================
+    // ==================== commitIfTrue：返回 true 提交 ====================

    @Test
    @DisplayName("commitIfTrue：返回 true 提交事务")
    void testCommitIfTrueCommit() throws Exception {
        SimpleJdbcTemplate template = createTemplate();

-        template.commitIfTrue((JdbcOperations ops) -> {
+        template.transaction().commitIfTrue((JdbcOperations ops) -> {
            ops.update("INSERT INTO users (username, email) VALUES (?, ?)",
                    buildParams("cftUser", "cft@test.com"));
            return true;
        });

        // 验证数据已持久化
-        Optional<String> user = template.queryFirst(
+        Optional<String> user = template.queryValue(
                "SELECT username FROM users WHERE username = ?",
                buildParams("cftUser"), String.class);
        assertTrue(user.isPresent());
@@ -147,14 +148,14 @@ class TransactionTest extends BaseH2Test {
    void testCommitIfFalseRollback() throws Exception {
        SimpleJdbcTemplate template = createTemplate();

-        template.commitIfTrue((JdbcOperations ops) -> {
+        template.transaction().commitIfTrue((JdbcOperations ops) -> {
            ops.update("INSERT INTO users (username, email) VALUES (?, ?)",
                    buildParams("cffUser", "cff@test.com"));
            return false;
        });

        // 验证数据已回滚
-        Optional<String> user = template.queryFirst(
+        Optional<String> user = template.queryValue(
                "SELECT username FROM users WHERE username = ?",
                buildParams("cffUser"), String.class);
        assertFalse(user.isPresent());
@@ -168,7 +169,7 @@ class TransactionTest extends BaseH2Test {
        SimpleJdbcTemplate template = createTemplate();

        assertThrows(TransactionException.class, () ->
-                template.commitIfTrue((JdbcOperations ops) -> {
+                template.transaction().commitIfTrue((JdbcOperations ops) -> {
                    ops.update("INSERT INTO users (username) VALUES (?)",
                            buildParams("exUser"));
                    throw new IllegalStateException("条件不满足");
@@ -176,7 +177,7 @@ class TransactionTest extends BaseH2Test {

        // 验证回滚
        assertDoesNotThrow(() -> {
-            Optional<String> user = template.queryFirst(
+            Optional<String> user = template.queryValue(
                    "SELECT username FROM users WHERE username = ?",
                    buildParams("exUser"), String.class);
            assertFalse(user.isPresent());
@@ -186,16 +187,16 @@ class TransactionTest extends BaseH2Test {
    // ==================== 事务内查询可见性 ====================

    @Test
-    @DisplayName("executeTransaction：事务内可查询到未提交的数据")
+    @DisplayName("execute：事务内可查询到未提交的数据")
    void testTransactionVisibility() throws Exception {
        SimpleJdbcTemplate template = createTemplate();

-        template.executeTransaction((JdbcOperations ops) -> {
+        template.transaction().execute((JdbcOperations ops) -> {
            ops.update("INSERT INTO users (username, email) VALUES (?, ?)",
                    buildParams("visible", "visible@test.com"));

            // 在同一事务内可以查询到刚插入的数据
-            Optional<String> user = ops.queryFirst(
+            Optional<String> user = ops.queryValue(
                    "SELECT username FROM users WHERE username = ?",
                    buildParams("visible"), String.class);
            assertTrue(user.isPresent());
@@ -207,13 +208,13 @@ class TransactionTest extends BaseH2Test {
    // ==================== 边界情况 ====================

    @Test
-    @DisplayName("executeTransaction：空操作（无异常）正常提交")
+    @DisplayName("execute：空操作（无异常）正常提交")
    void testExecuteTransactionEmpty() throws Exception {
        SimpleJdbcTemplate template = createTemplate();

        // 空操作不应抛异常
        assertDoesNotThrow(() ->
-                template.executeTransaction(ops -> { /* no-op */ }));
+                template.transaction().execute(ops -> { /* no-op */ }));

        // 数据应保持不变
        int count = template.query("SELECT COUNT(*) FROM users",
@@ -222,12 +223,40 @@ class TransactionTest extends BaseH2Test {
    }

    @Test
-    @DisplayName("executeTransaction：null 操作抛异常")
+    @DisplayName("execute：null 操作抛异常")
    @SuppressWarnings("null")
    void testExecuteTransactionNullOps() {
        SimpleJdbcTemplate template = createTemplate();

        assertThrows(Exception.class, () ->
-                template.executeTransaction(null));
+                template.transaction().execute(null));
+    }
+
+    // ==================== TransactionException ====================
+
+    @Test
+    @DisplayName("TransactionException：单参构造器（仅 cause）")
+    void testTransactionExceptionSingleArg() {
+        RuntimeException cause = new RuntimeException("原始异常");
+        TransactionException ex = new TransactionException(cause);
+        assertEquals("Transaction failed during execution", ex.getMessage());
+        assertSame(cause, ex.getCause());
+    }
+
+    @Test
+    @DisplayName("TransactionException：双参构造器")
+    void testTransactionExceptionWithMessage() {
+        RuntimeException cause = new RuntimeException("原始异常");
+        TransactionException ex = new TransactionException("自定义消息", cause);
+        assertEquals("自定义消息", ex.getMessage());
+        assertSame(cause, ex.getCause());
+    }
+
+    @Test
+    @DisplayName("TransactionException：null cause")
+    void testTransactionExceptionNullCause() {
+        TransactionException ex = new TransactionException(null);
+        assertEquals("Transaction failed during execution", ex.getMessage());
+        assertNull(ex.getCause());
    }
 }
--- a/src/test/java/xyz/zhouxy/jdbc/test/UpdateTest.java
+++ b/src/test/java/xyz/zhouxy/jdbc/test/UpdateTest.java
@@ -4,6 +4,7 @@ import static org.junit.jupiter.api.Assertions.*;
 import static xyz.zhouxy.jdbc.ParamBuilder.buildParams;

 import java.sql.SQLException;
+import java.time.Instant;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.time.LocalTime;
@@ -20,6 +21,8 @@ import xyz.zhouxy.jdbc.SimpleJdbcTemplate;

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

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

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

    @Test
-    @DisplayName("update：DELETE 全表")
+    @DisplayName("update：参数中包含 null 元素")
+    void testUpdateWithNullElement() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        int rows = template.update(
+                "DELETE FROM users WHERE username = ?",
+                new Object[]{ null });
+
+        // 参数 null 不匹配任何行
+        assertEquals(0, rows);
+    }
+
+    @Test
+    @DisplayName("update：使用 Instant 类型参数填充 TIMESTAMP 列")
+    void testUpdateWithInstantParam() throws SQLException {
+        SimpleJdbcTemplate template = createTemplate();
+
+        Instant now = Instant.now().truncatedTo(java.time.temporal.ChronoUnit.SECONDS);
+
+        String sql = "INSERT INTO users (username, email, created_at) VALUES (?, ?, ?)";
+        int rows = template.update(sql,
+                buildParams("instant_user", "instant@example.com", now));
+
+        assertEquals(1, rows);
+
+        // 验证存储的值与原始 Instant 一致
+        java.sql.Timestamp stored = template.query(
+                "SELECT created_at FROM users WHERE username = ?",
+                buildParams("instant_user"),
+                rs -> {
+                    rs.next();
+                    return rs.getTimestamp(1);
+                });
+
+        assertNotNull(stored);
+        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();

@@ -136,27 +192,13 @@ class UpdateTest extends BaseH2Test {
    }

    @Test
-    @DisplayName("update：null 参数数组")
-    void testUpdateWithNullParams() throws SQLException {
+    @DisplayName("update：params 为 null，走 Statement 路径")
+    void testUpdateWithParamsNull() throws SQLException {
        SimpleJdbcTemplate template = createTemplate();

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

-        // 因为 DELETE ? 中参数 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);
+        assertEquals(5, rows);
    }

    @Test
@@ -169,6 +211,7 @@ class UpdateTest extends BaseH2Test {
    }

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

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

+    // --- updateAndReturnKeys / Statement 路径（无参数） ---
+
    @Test
    @DisplayName("updateAndReturnKeys：无参数重载")
    void testUpdateAndReturnKeysNoParams() throws SQLException {
@@ -216,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);
+    }
 }
--- a/src/test/java/xyz/zhouxy/jdbc/test/util/AssertToolsTests.java
+++ b/src/test/java/xyz/zhouxy/jdbc/test/util/AssertToolsTests.java
@@ -0,0 +1,522 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package xyz.zhouxy.jdbc.test.util;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static xyz.zhouxy.jdbc.util.AssertTools.*;
+
+import java.lang.reflect.Constructor;
+import java.time.LocalDate;
+import java.util.Arrays;
+import java.util.function.Supplier;
+
+import org.junit.jupiter.api.Test;
+
+import xyz.zhouxy.jdbc.util.AssertTools;
+
+class AssertToolsTests {
+
+    // #region - Argument
+
+    @Test
+    void testCheckArgument_true() {
+        checkArgument(true);
+    }
+
+    @Test
+    void testCheckArgument_true_withMessage() {
+        final String IGNORE_ME = "IGNORE_ME"; // NOSONAR
+        checkArgument(true, IGNORE_ME);
+    }
+
+    @Test
+    void testCheckArgument_true_withNullMessage() {
+        final String IGNORE_ME = null; // NOSONAR
+        checkArgument(true, IGNORE_ME);
+    }
+
+    @Test
+    void testCheckArgument_true_withMessageSupplier() {
+        checkArgument(true, () -> "Error message: " + LocalDate.now());
+    }
+
+    @Test
+    void testCheckArgument_true_withNullMessageSupplier() {
+        final Supplier<String> IGNORE_ME = null; // NOSONAR
+        checkArgument(true, IGNORE_ME);
+    }
+
+    @Test
+    void testCheckArgument_true_withMessageFormat() {
+        LocalDate today = LocalDate.now();
+        checkArgument(true, "String format: %s", today);
+    }
+
+    @Test
+    void testCheckArgument_true_withNullMessageFormat() {
+        checkArgument(true, null, LocalDate.now());
+    }
+
+    @Test
+    void testCheckArgument_false() {
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgument(false));
+
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckArgument_false_withMessage() {
+        final String message = "testCheckArgument_false_withMessage";
+
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgument(false, message));
+
+        assertEquals(message, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckArgument_false_withNullMessage() {
+        final String message = null;
+
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgument(false, message));
+
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckArgument_false_withMessageSupplier() {
+        final LocalDate today = LocalDate.now();
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgument(false, () -> "Error message: " + today));
+
+        assertEquals("Error message: " + today, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckArgument_false_withNullMessageSupplier() {
+        Supplier<String> messageSupplier = null;
+        assertThrows(NullPointerException.class,
+                () -> checkArgument(false, messageSupplier));
+    }
+
+    @Test
+    void testCheckArgument_false_withMessageFormat() {
+        LocalDate today = LocalDate.now();
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgument(false, "String format: %s", today));
+        assertEquals(String.format("String format: %s", today), e.getMessage());
+    }
+
+    @Test
+    void testCheckArgument_false_withNullMessageFormat() {
+        LocalDate today = LocalDate.now();
+        assertThrows(NullPointerException.class,
+                () -> checkArgument(false, null, today));
+    }
+
+    // #endregion - Argument
+
+    // #region - ArgumentNotNull
+
+    @Test
+    void testCheckArgumentNotNull_notNull() {
+        final Object object = new Object();
+        assertEquals(object, checkArgumentNotNull(object));
+    }
+
+    @Test
+    void testCheckArgumentNotNull_notNull_withMessage() {
+        final Object object = new Object();
+        final String IGNORE_ME = "IGNORE_ME"; // NOSONAR
+        assertEquals(object, checkArgumentNotNull(object, IGNORE_ME));
+    }
+
+    @Test
+    void testCheckArgumentNotNull_notNull_withNullMessage() {
+        final Object object = new Object();
+        final String IGNORE_ME = null; // NOSONAR
+        assertEquals(object, checkArgumentNotNull(object, IGNORE_ME));
+    }
+
+    @Test
+    void testCheckArgumentNotNull_notNull_withMessageSupplier() {
+        final Object object = new Object();
+        assertEquals(object, checkArgumentNotNull(object, () -> "Error message: " + LocalDate.now()));
+    }
+
+    @Test
+    void testCheckArgumentNotNull_notNull_withNullMessageSupplier() {
+        final Object object = new Object();
+        final Supplier<String> IGNORE_ME = null; // NOSONAR
+        assertEquals(object, checkArgumentNotNull(object, IGNORE_ME));
+    }
+
+    @Test
+    void testCheckArgumentNotNull_notNull_withMessageFormat() {
+        final Object object = new Object();
+        LocalDate today = LocalDate.now();
+        assertEquals(object, checkArgumentNotNull(object, "String format: %s", today));
+    }
+
+    @Test
+    void testCheckArgumentNotNull_notNull_withNullMessageFormat() {
+        final Object object = new Object();
+        assertEquals(object, checkArgumentNotNull(object, null, LocalDate.now()));
+    }
+
+    @Test
+    void testCheckArgumentNotNull_null() {
+        final Object object = null;
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgumentNotNull(object));
+
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckArgumentNotNull_null_withMessage() {
+        final Object object = null;
+        final String message = "testCheckArgumentNotNull_null_withMessage";
+
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgumentNotNull(object, message));
+
+        assertEquals(message, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckArgumentNotNull_null_withNullMessage() {
+        final Object object = null;
+        final String message = null;
+
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgumentNotNull(object, message));
+
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckArgumentNotNull_null_withMessageSupplier() {
+        final Object object = null;
+        final LocalDate today = LocalDate.now();
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgumentNotNull(object, () -> "Error message: " + today));
+
+        assertEquals("Error message: " + today, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckArgumentNotNull_null_withNullMessageSupplier() {
+        final Object object = null;
+        Supplier<String> messageSupplier = null;
+        assertThrows(NullPointerException.class,
+                () -> checkArgumentNotNull(object, messageSupplier));
+    }
+
+    @Test
+    void testCheckArgumentNotNull_null_withMessageFormat() {
+        final Object object = null;
+        LocalDate today = LocalDate.now();
+        final IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> checkArgumentNotNull(object, "String format: %s", today));
+        assertEquals(String.format("String format: %s", today), e.getMessage());
+    }
+
+    @Test
+    void testCheckArgumentNotNull_null_withNullMessageFormat() {
+        final Object object = null;
+        LocalDate today = LocalDate.now();
+        assertThrows(NullPointerException.class,
+                () -> checkArgumentNotNull(object, null, today));
+    }
+
+    // #endregion - ArgumentNotNull
+
+    // #region - State
+
+    @Test
+    void testCheckState_true() {
+        checkState(true);
+    }
+
+    @Test
+    void testCheckState_true_withMessage() {
+        final String IGNORE_ME = "IGNORE_ME"; // NOSONAR
+        checkState(true, IGNORE_ME);
+    }
+
+    @Test
+    void testCheckState_true_withNullMessage() {
+        final String IGNORE_ME = null; // NOSONAR
+        checkState(true, IGNORE_ME);
+    }
+
+    @Test
+    void testCheckState_true_withMessageSupplier() {
+        checkState(true, () -> "Error message: " + LocalDate.now());
+    }
+
+    @Test
+    void testCheckState_true_withNullMessageSupplier() {
+        final Supplier<String> IGNORE_ME = null; // NOSONAR
+        checkState(true, IGNORE_ME);
+    }
+
+    @Test
+    void testCheckState_true_withMessageFormat() {
+        LocalDate today = LocalDate.now();
+        checkState(true, "String format: %s", today);
+    }
+
+    @Test
+    void testCheckState_true_withNullMessageFormat() {
+        checkState(true, null, LocalDate.now());
+    }
+
+    @Test
+    void testCheckState_false() {
+        final IllegalStateException e = assertThrows(IllegalStateException.class,
+                () -> checkState(false));
+
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckState_false_withMessage() {
+        final String message = "testCheckState_false_withMessage";
+
+        final IllegalStateException e = assertThrows(IllegalStateException.class,
+                () -> checkState(false, message));
+
+        assertEquals(message, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckState_false_withNullMessage() {
+        final String message = null;
+
+        final IllegalStateException e = assertThrows(IllegalStateException.class,
+                () -> checkState(false, message));
+
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckState_false_withMessageSupplier() {
+        final LocalDate today = LocalDate.now();
+        final IllegalStateException e = assertThrows(IllegalStateException.class,
+                () -> checkState(false, () -> "Error message: " + today));
+
+        assertEquals("Error message: " + today, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckState_false_withNullMessageSupplier() {
+        Supplier<String> messageSupplier = null;
+        assertThrows(NullPointerException.class,
+                () -> checkState(false, messageSupplier));
+    }
+
+    @Test
+    void testCheckState_false_withMessageFormat() {
+        LocalDate today = LocalDate.now();
+        final IllegalStateException e = assertThrows(IllegalStateException.class,
+                () -> checkState(false, "String format: %s", today));
+        assertEquals(String.format("String format: %s", today), e.getMessage());
+    }
+
+    @Test
+    void testCheckState_false_withNullMessageFormat() {
+        LocalDate today = LocalDate.now();
+        assertThrows(NullPointerException.class,
+                () -> checkState(false, null, today));
+    }
+
+    // #endregion - State
+
+    // #region - NotNull
+
+    @Test
+    void testCheckNotNull_notNull() {
+        final Object object = new Object();
+        checkNotNull(object);
+    }
+
+    @Test
+    void testCheckNotNull_notNull_withMessage() {
+        final Object object = new Object();
+        final String IGNORE_ME = "IGNORE_ME"; // NOSONAR
+        checkNotNull(object, IGNORE_ME);
+    }
+
+    @Test
+    void testCheckNotNull_notNull_withNullMessage() {
+        final Object object = new Object();
+        final String IGNORE_ME = null; // NOSONAR
+        checkNotNull(object, IGNORE_ME);
+    }
+
+    @Test
+    void testCheckNotNull_notNull_withMessageSupplier() {
+        final Object object = new Object();
+        checkNotNull(object, () -> "Error message: " + LocalDate.now());
+    }
+
+    @Test
+    void testCheckNotNull_notNull_withNullMessageSupplier() {
+        final Object object = new Object();
+        final Supplier<String> IGNORE_ME = null; // NOSONAR
+        checkNotNull(object, IGNORE_ME);
+    }
+
+    @Test
+    void testCheckNotNull_notNull_withMessageFormat() {
+        final Object object = new Object();
+        LocalDate today = LocalDate.now();
+        checkNotNull(object, "String format: %s", today);
+    }
+
+    @Test
+    void testCheckNotNull_notNull_withNullMessageFormat() {
+        final Object object = new Object();
+        checkNotNull(object, null, LocalDate.now());
+    }
+
+    @Test
+    void testCheckNotNull_null() {
+        final Object object = null;
+        final NullPointerException e = assertThrows(NullPointerException.class,
+                () -> checkNotNull(object));
+
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckNotNull_null_withMessage() {
+        final Object object = null;
+        final String message = "testCheckNotNull_null_withMessage";
+
+        final NullPointerException e = assertThrows(NullPointerException.class,
+                () -> checkNotNull(object, message));
+
+        assertEquals(message, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckNotNull_null_withNullMessage() {
+        final Object object = null;
+        final String message = null;
+
+        final NullPointerException e = assertThrows(NullPointerException.class,
+                () -> checkNotNull(object, message));
+
+        assertNull(e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckNotNull_null_withMessageSupplier() {
+        final Object object = null;
+        final LocalDate today = LocalDate.now();
+        final NullPointerException e = assertThrows(NullPointerException.class,
+                () -> checkNotNull(object, () -> "Error message: " + today));
+
+        assertEquals("Error message: " + today, e.getMessage());
+        assertNull(e.getCause());
+    }
+
+    @Test
+    void testCheckNotNull_null_withNullMessageSupplier() {
+        final Object object = null;
+        Supplier<String> messageSupplier = null;
+        assertThrows(NullPointerException.class,
+                () -> checkNotNull(object, messageSupplier));
+    }
+
+    @Test
+    void testCheckNotNull_null_withMessageFormat() {
+        final Object object = null;
+        LocalDate today = LocalDate.now();
+        final NullPointerException e = assertThrows(NullPointerException.class,
+                () -> checkNotNull(object, "String format: %s", today));
+        assertEquals(String.format("String format: %s", today), e.getMessage());
+    }
+
+    @Test
+    void testCheckNotNull_null_withNullMessageFormat() {
+        final Object object = null;
+        LocalDate today = LocalDate.now();
+        assertThrows(NullPointerException.class,
+                () -> checkNotNull(object, null, today));
+    }
+
+    // #endregion - NotNull
+
+    // #region - Condition
+
+    static final class MyException extends RuntimeException {}
+
+    @Test
+    void testCheckCondition() {
+
+        checkCondition(true, MyException::new);
+
+        final MyException me = new MyException();
+        MyException e = assertThrows(MyException.class, () -> checkCondition(false, () -> me));
+        assertEquals(me, e);
+    }
+
+    // #endregion - Condition
+
+    // ================================
+    // #region - invoke constructor
+    // ================================
+
+    @Test
+    void test_constructor_isNotAccessible_ThrowsIllegalStateException() {
+        Constructor<?>[] constructors = AssertTools.class.getDeclaredConstructors();
+        Arrays.stream(constructors)
+                .forEach(constructor -> {
+                    assertFalse(constructor.isAccessible());
+                    constructor.setAccessible(true);
+                    Throwable cause = assertThrows(Exception.class, constructor::newInstance)
+                            .getCause();
+                    assertInstanceOf(IllegalStateException.class, cause);
+                    assertEquals("Utility class", cause.getMessage());
+                });
+    }
+
+    // ================================
+    // #endregion - invoke constructor
+    // ================================
+}
--- a/src/test/resources/init_tables.sql
+++ b/src/test/resources/init_tables.sql
@@ -1,3 +1,4 @@
+-- 测试用户表，覆盖全部列类型（数值/字符串/布尔/时间），用于验证 RowMapper 和查询功能
 DROP TABLE IF EXISTS users;

 CREATE TABLE users (
@@ -12,19 +13,25 @@ CREATE TABLE users (
    work_start_time TIME
 );

+-- 唯一约束用于测试 batchUpdate 的重复键错误场景
 ALTER TABLE users ADD CONSTRAINT uk_username UNIQUE (username);

+-- 完整数据行（全部字段非空）
 INSERT INTO users (username, email, age, balance, active, created_at, birth_date, work_start_time)
 VALUES ('alice', 'alice@example.com', 28, 15000, TRUE, '2024-01-15 09:30:00', '1996-05-20', '08:00:00');

+-- 完整数据行
 INSERT INTO users (username, email, age, balance, active, created_at, birth_date, work_start_time)
 VALUES ('bob', 'bob@example.com', 35, 25000, TRUE, '2023-11-01 14:00:00', '1989-03-12', '09:30:00');

+-- null 数据行：email、age、birth_date、work_start_time 均为 null，用于测试空字段映射
 INSERT INTO users (username, email, age, balance, active, created_at, birth_date, work_start_time)
 VALUES ('charlie', NULL, NULL, 5000, FALSE, '2025-03-10 11:15:00', NULL, NULL);

+-- 部分 null 数据行：balance 为 null，created_at 为 null，用于测试字段级 null 映射
 INSERT INTO users (username, email, age, balance, active, created_at, birth_date, work_start_time)
 VALUES ('diana', 'diana@example.com', 42, NULL, TRUE, NULL, '1982-11-08', '07:45:00');

+-- 完整数据行
 INSERT INTO users (username, email, age, balance, active, created_at, birth_date, work_start_time)
 VALUES ('eve', 'eve@example.com', 31, 8000, TRUE, '2024-07-22 16:45:00', '1993-01-30', '10:00:00');
Author	SHA1	Message	Date
ZhouXY108	7de2a7eec1	refactor: 将单列查询 Class 重载标记为过时，新增语义明确的方法 - 新增 queryValues(sql, args, Class) 替代 queryList(sql, args, Class) - 新增 queryValue(sql, args, Class) 替代 queryFirst(sql, args, Class) - 新增 queryValueOrDefault(sql, args, Class, defaultVal) 聚合查询便捷方法 - 旧方法标记 @Deprecated，委托至新方法，后续版本移除 - 更新 README 方法列表和示例代码 - 补充 queryValueOrDefault 单元测试 6 个	2026-06-18 02:58:43 +08:00
ZhouXY108	76bfff2d90	docs: 更新设计考量章节标题并补充内容	2026-06-18 02:52:37 +08:00
ZhouXY108	6f2882cd08	refactor!: 将工厂方法异常类型从 SQLException 改为 IllegalStateException DefaultBeanRowMapper.of() 及 RowMapper.beanRowMapper() 在反射异常时不再抛出受检异常 SQLException，改为抛出非受检异常 IllegalStateException。同时优化相关 Javadoc 文档并同步更新测试断言。 BREAKING CHANGE: beanRowMapper() 和 of() 方法不再抛出 SQLException。调用方 catch (SQLException e) 将静默失效，建议移除相关 catch 块或改为 catch (IllegalStateException)。	2026-06-18 02:41:10 +08:00
ZhouXY108	5100fa5f1d	docs: 添加示例代码	2026-06-17 23:27:43 +08:00
ZhouXY108	9abbef8b86	prepare 1.1.0	2026-06-17 21:24:03 +08:00
ZhouXY108	1f566ca488	release/1.0.0 [plusone/simple-jdbc#10 (Gitea)]	2026-06-17 21:16:38 +08:00
ZhouXY108	bb79777f0c	docs: 修复文档错误	2026-06-17 21:06:40 +08:00
ZhouXY108	cf911c3756	release 1.0.0	2026-06-17 20:57:43 +08:00
ZhouXY108	f471c1a489	docs: 调整文档描述	2026-06-17 20:41:09 +08:00
ZhouXY108	f35cfac913	docs: 更新 DefaultBeanRowMapper 类文档注释，强调使用场景	2026-06-17 20:27:26 +08:00
ZhouXY108	76255bf3eb	docs: 修改 README.md - 移除标题中的emoji - 新增“设计考量与边界”章节	2026-06-17 18:47:34 +08:00
ZhouXY108	aeb57dcdba	refactor: 将中断控制逻辑内化到 BatchUpdateResult 中 - BatchUpdateResult 新增 quietly 字段，由 recordErrorBatch() 自行判断状态设置为 INTERRUPTED 或 COMPLETED_WITH_ERRORS - 移除 interrupt() 方法，消除 recordErrorBatch → interrupt 的时序耦合 - 外部调用方仅需 break 控制循环，不再干预结果对象的状态流转	2026-06-17 17:27:13 +08:00
ZhouXY108	a0df4136f4	refactor!: 移除 plusone-commons 及 Guava 依赖，内化工具方法完全移除对外部工具库 plusone-commons 和 Guava 的编译期依赖，将所需功能内化实现，使项目成为真正的零依赖轻量级 JDBC 封装库。 - 新增 AssertTools: 断言工具（checkArgument / checkNotNull / checkState / checkCondition） - 新增 NamingTools: 命名转换（camelToSnake） - 新增 ThrowingConsumer / ThrowingPredicate: 可抛受检异常的函数式接口 - 新增 AssertToolsTests: 完整覆盖断言工具所有方法及边界场景 - pom.xml 移除 plusone-dependencies BOM，直接声明 jsr305 / test 依赖版本 - DefaultBeanRowMapper 使用 NamingTools.camelToSnake 替代 Guava CaseFormat - ParamBuilder 内联 Optional 展开逻辑，去除 OptionalTools / CollectionTools - JdbcOperationSupport 用 null/长度判断替代 ArrayTools.isEmpty/isNotEmpty - NOTICE 移除第三方依赖声明；README 移除无依赖分支说明 - 测试：新增缩写映射（URL/XML/ID/HTML/HTTP）覆盖、TransactionException 构造器测试 BREAKING CHANGE: BatchUpdateStatus 不再实现 IWithIntCode 接口； plusone-commons 和 Guava 不再作为传递依赖提供。	2026-06-17 17:21:31 +08:00
ZhouXY108	ad0fbb788e	docs: 添加对无依赖分支（feature/no-dependencies）的特性和适用情况的说明	2026-06-06 00:59:40 +08:00
ZhouXY108	d740ad8467	docs: 优化 README 文档结构与内容 - 调整章节顺序 - 为所有二级及以下标题添加序号 - 移除示例代码注释中的序号，避免与标题序号冲突 - 新增「连接池集成」章节（HikariCP/Druid/DBCP 2），快速开始中添加引导提示 - 快速开始各小节末尾添加跳转指引，关联至对应详细章节 - 补充事务管理章节的内容	2026-06-06 00:43:06 +08:00
ZhouXY108	e577f72d4f	docs: 新增 CHANGELOG.md 文件记录各版本更新内容	2026-06-05 22:31:27 +08:00
ZhouXY108	ef39c4323c	test: 补充测试数据库初始化脚本的注释	2026-06-05 22:31:27 +08:00
ZhouXY108	d70e12e254	docs: 补充 `ParamBuilder` 和 `SimpleJdbcTemplate` 的文档注释	2026-06-05 22:31:27 +08:00
ZhouXY108	721d0bbd5e	test: 添加事务异常测试用例	2026-06-05 22:31:27 +08:00
ZhouXY108	0b3675d3a4	test: 添加 buildParamsTemporal 测试方法验证时间类型参数构建	2026-06-05 22:31:27 +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
ZhouXY108	492be49322	docs: 完善 SimpleJdbcTemplate 类文档注释	2026-05-31 05:56:32 +08:00
ZhouXY108	1a308ed30e	refactor: 提取 TransactionTemplate，分离事务管理职责将 executeTransaction / commitIfTrue 及 TransactionJdbcExecutor 从 SimpleJdbcTemplate 移至独立的 TransactionTemplate 类： - 新增 TransactionTemplate，封装事务生命周期（开启/提交/回滚） - SimpleJdbcTemplate 新增 transaction() 入口 - 更新 TransactionTest 适配新 API：template.transaction().execute() - 更新 README.md 事务章节，说明 TransactionTemplate 使用方式	2026-05-31 05:48:51 +08:00
ZhouXY108	b639daca30	chore: 将版权年份从固定范围更新为包含当前时间的表述	2026-05-31 05:21:18 +08:00
ZhouXY108	20d10b84ee	test: 添加Instant类型参数测试用例	2026-05-31 04:54:33 +08:00
ZhouXY108	8e543b40a6	test: 添加 ParamBuilder 参数构建工具类单元测试 - 验证 buildParams 方法对各种 Optional 类型的拆箱处理 - 测试普通参数、Optional<?>、OptionalInt、OptionalLong、OptionalDouble 的处理逻辑 - 验证 buildBatchParams 方法对集合的批量映射功能 - 测试空参数、边界情况和私有构造器的异常处理	2026-05-31 04:52:49 +08:00
ZhouXY108	3aff7509eb	refactor: 简化 ParamBuilder 中的参数构建逻辑	2026-05-31 04:51:15 +08:00
ZhouXY108	3ad5718f8c	feat: 优化为批量更新结果类的 toString 方法实现 - 为BatchUpdateErrorInfo类实现toString方法 - 重构BatchUpdateResult类的toString方法，调整字段顺序	2026-05-31 04:21:33 +08:00
ZhouXY108	8de546b7a6	docs: 更新批量更新相关类的JavaDoc文档 - 优化 BatchUpdateErrorInfo、BatchUpdateResult 类和成员的注释 - 为 BatchUpdateStatus 枚举添加详细的类注释和枚举值注释	2026-05-31 04:19:10 +08:00
ZhouXY108	9bf44c5494	refactor: 优化批量更新批次内索引计算逻辑 - 将 indexInBatch 改为 1-based 计算方式：批次触发条件改为 indexInBatch==batchSize，增强可读性 - 重命名 getUpdateCountsInternal 为 getUpdateCountsOnError，语义更清晰 - 精简方法参数，移除新方案下多余的入参 paramsSize/batchSize/itemIndex - 补充关键变量注释	2026-05-31 03:21:12 +08:00
ZhouXY108	a51fcef845	docs: 更新文档完善使用说明和示例	2026-05-31 01:36:58 +08:00
ZhouXY108	cb9fd4ca75	build: 保持开发分支的版本后缀标识为 SNAPSHOT	2026-05-29 01:02:30 +08:00
ZhouXY108	ddddea0519	1.0.0-RC1 [plusone/simple-jdbc#9 (Gitea)]	2026-05-29 00:59:56 +08:00