将通用的对 JDBC 进行操作的静态方法封装到 JdbcOperationSupport；使用 JdbcOperations 定义 SimpleJdbcTemplate 和 JdbcExecutor 的行为。

src/main/java/xyz/zhouxy/jdbc/DbRecord.java

@@ -16,49 +16,78 @@
 
 package xyz.zhouxy.jdbc;
 
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalDouble;
+import java.util.OptionalInt;
+import java.util.OptionalLong;
+
+import javax.annotation.Nonnull;
+
 import com.google.common.annotations.Beta;
-import com.google.common.base.Preconditions;
+
 import xyz.zhouxy.plusone.commons.collection.AbstractMapWrapper;
+import xyz.zhouxy.plusone.commons.util.AssertTools;
 import xyz.zhouxy.plusone.commons.util.OptionalTools;
 import xyz.zhouxy.plusone.commons.util.StringTools;
 
-import java.util.*;
-
+/**
+ * DbRecord
+ *
+ * <p>
+ * 封装 Map<String, Object>，表示一条 DB 记录
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ */
 @Beta
 public class DbRecord extends AbstractMapWrapper<String, Object, DbRecord> {
 
     public DbRecord() {
-        super(new HashMap<>(), k -> Preconditions.checkArgument(StringTools.isNotBlank(k), "Key must has text."), null);
+        super(new HashMap<>(),
+                k -> AssertTools.checkArgument(StringTools.isNotBlank(k), "Key must has text."),
+                null);
     }
 
     public DbRecord(Map<String, Object> map) {
-        super(map, k -> Preconditions.checkArgument(StringTools.isNotBlank(k), "Key must has text."), null);
+        super(map,
+                k -> AssertTools.checkArgument(StringTools.isNotBlank(k), "Key must has text."),
+                null);
     }
 
+    /**
+     * 将值强转为 {@link String}，并放在 {@link Optional} 中。
+     * 如果 {@code key} 存在，而值不存在，则返回 {@link Optional#empty()}。
+     */
     public Optional<String> getValueAsString(String key) {
         return this.getAndConvert(key);
     }
 
-    public <T> List<T> getValueAsList(String key) {
-        return this.<Collection<T>>getAndConvert(key)
-                .map(l -> (l instanceof List) ? (List<T>) l : new ArrayList<>(l))
-                .orElse(Collections.emptyList());
-    }
-
-    public <T> Set<T> getValueAsSet(String key) {
-        return this.<Collection<T>>getAndConvert(key)
-                .map(l -> (l instanceof Set) ? (Set<T>) l : new HashSet<>(l))
-                .orElse(Collections.emptySet());
-    }
-
+    /**
+     * 将值强转为 {@code int}，并放在 {@link OptionalInt} 中。
+     * 如果 {@code key} 存在，而值不存在，则返回 {@link OptionalInt#empty()}。
+     */
+    @Nonnull
     public OptionalInt getValueAsInt(String key) {
         return OptionalTools.toOptionalInt(this.getAndConvert(key));
     }
 
+    /**
+     * 将值强转为 {@code long}，并放在 {@link OptionalLong} 中。
+     * 如果 {@code key} 存在，而值不存在，则返回 {@link OptionalLong#empty()}。
+     */
+    @Nonnull
     public OptionalLong getValueAsLong(String key) {
         return OptionalTools.toOptionalLong(this.getAndConvert(key));
     }
 
+    /**
+     * 将值强转为 {@code double}，并放在 {@link OptionalDouble} 中。
+     * 如果 {@code key} 存在，而值不存在，则返回 {@link OptionalDouble#empty()}。
+     */
+    @Nonnull
     public OptionalDouble getValueAsDouble(String key) {
         return OptionalTools.toOptionalDouble(this.getAndConvert(key));
     }

src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java

@@ -35,9 +35,28 @@ import javax.annotation.Nullable;
 
 import com.google.common.base.CaseFormat;
 
+import xyz.zhouxy.plusone.commons.annotation.StaticFactoryMethod;
+
+/**
+ * DefaultBeanRowMapper
+ *
+ * <p>
+ * 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。
+ * </p>
+ *
+ * <p>
+ * <b>NOTE: 使用反射获取类型信息，也是使用反射调用无参构造器和 {@code setter} 方法。
+ * 实际使用中还是建议针对目标类型自定义 {@link RowMapper}。</b>
+ * </p>
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ */
 public class DefaultBeanRowMapper<T> implements RowMapper<T> {
 
+    /** Bean 的无参构造器 */
     private final Constructor<T> constructor;
+
+    /** 列名到属性的映射 */
     private final Map<String, PropertyDescriptor> colPropertyMap;
 
     private DefaultBeanRowMapper(Constructor<T> constructor, Map<String, PropertyDescriptor> colPropertyMap) {
@@ -45,10 +64,29 @@ public class DefaultBeanRowMapper<T> implements RowMapper<T> {
         this.colPropertyMap = colPropertyMap;
     }
 
+    /**
+     * 创建一个 DefaultBeanRowMapper
+     *
+     * @param <T>      Bean 类型
+     * @param beanType Bean 类型
+     * @return DefaultBeanRowMapper 对象
+     * @throws SQLException 创建 DefaultBeanRowMapper 出现错误的异常时抛出
+     */
+    @StaticFactoryMethod(DefaultBeanRowMapper.class)
     public static <T> DefaultBeanRowMapper<T> of(Class<T> beanType) throws SQLException {
         return of(beanType, null);
     }
 
+    /**
+     * 创建一个 DefaultBeanRowMapper
+     *
+     * @param <T>            Bean 类型
+     * @param beanType       Bean 类型
+     * @param propertyColMap Bean 字段与列名的映射关系。key 是字段，value 是列名。
+     * @return DefaultBeanRowMapper 对象
+     * @throws SQLException 创建 DefaultBeanRowMapper 出现错误的异常时抛出
+     */
+    @StaticFactoryMethod(DefaultBeanRowMapper.class)
     public static <T> DefaultBeanRowMapper<T> of(Class<T> beanType, @Nullable Map<String, String> propertyColMap)
             throws SQLException {
         try {
@@ -60,6 +98,7 @@ public class DefaultBeanRowMapper<T> implements RowMapper<T> {
             BeanInfo beanInfo = Introspector.getBeanInfo(beanType);
             PropertyDescriptor[] propertyDescriptors = beanInfo.getPropertyDescriptors();
 
+            // Bean 的属性名为小驼峰，对应的列名为下划线
             Function<? super PropertyDescriptor, String> keyMapper;
             if (propertyColMap == null || propertyColMap.isEmpty()) {
                 keyMapper = p -> CaseFormat.LOWER_CAMEL.to(CaseFormat.LOWER_UNDERSCORE, p.getName());
@@ -84,13 +123,17 @@ public class DefaultBeanRowMapper<T> implements RowMapper<T> {
         }
     }
 
+    /** {@inheritDoc} */
     @Override
     public T mapRow(ResultSet rs, int rowNumber) throws SQLException {
         try {
+            // 调用无参构造器创建实例
             T newInstance = this.constructor.newInstance();
             ResultSetMetaData metaData = rs.getMetaData();
+            // 遍历结果的每一列
             for (int i = 1; i <= metaData.getColumnCount(); i++) {
                 String colName = metaData.getColumnName(i);
+                // 获取查询结果列名对应的属性，调用 setter
                 PropertyDescriptor propertyDescriptor = this.colPropertyMap.get(colName);
                 if (propertyDescriptor != null) {
                     Method setter = propertyDescriptor.getWriteMethod();

src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java

@@ -0,0 +1,471 @@
+/*
+ * Copyright 2024 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;
+
+import java.math.BigDecimal;
+import java.sql.Connection;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.util.ArrayList;
+import java.util.Collection;
+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 javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+import com.google.common.collect.Lists;
+
+import xyz.zhouxy.plusone.commons.collection.CollectionTools;
+import xyz.zhouxy.plusone.commons.util.AssertTools;
+import xyz.zhouxy.plusone.commons.util.OptionalTools;
+
+/**
+ * JdbcOperationSupport
+ *
+ * <p>
+ * 提供静态方法，封装 JDBC 基础操作
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ */
+class JdbcOperationSupport {
+
+    // #region - query
+
+    /**
+     * 执行查询，并按照自定义处理逻辑对结果进行处理，将结果转换为指定类型并返回
+     *
+     * @param conn          数据库连接
+     * @param sql           SQL
+     * @param params        参数
+     * @param resultHandler 结果处理器，用于处理 {@link ResultSet}
+     */
+    static <T> T query(Connection conn, String sql, Object[] params, ResultHandler<T> resultHandler)
+            throws SQLException {
+        assertConnectionNotNull(conn);
+        assertSqlNotNull(sql);
+        assertResultHandlerNotNull(resultHandler);
+        return queryInternal(conn, sql, params, resultHandler);
+    }
+
+    // #endregion
+
+    // #region - queryList
+
+    /**
+     * 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表
+     *
+     * @param conn      数据库连接
+     * @param sql       SQL
+     * @param params    参数
+     * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     */
+    static <T> List<T> queryList(Connection conn, String sql, Object[] params, RowMapper<T> rowMapper)
+            throws SQLException {
+        assertConnectionNotNull(conn);
+        assertSqlNotNull(sql);
+        assertRowMapperNotNull(rowMapper);
+        return queryListInternal(conn, sql, params, rowMapper);
+    }
+
+    /**
+     * 执行查询，返回结果映射为指定的类型。当结果为单列时使用
+     *
+     * @param conn   数据库连接
+     * @param sql    SQL
+     * @param params 参数
+     * @param clazz  将结果映射为指定的类型
+     */
+    static <T> List<T> queryList(Connection conn, String sql, Object[] params, Class<T> clazz)
+            throws SQLException {
+        assertConnectionNotNull(conn);
+        assertSqlNotNull(sql);
+        assertClazzNotNull(clazz);
+        return queryListInternal(conn, sql, params, (rs, rowNumber) -> rs.getObject(1, clazz));
+    }
+
+    // #endregion
+
+    // #region - queryFirst
+
+    /**
+     * 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional}
+     *
+     * @param conn      数据库连接
+     * @param sql       SQL
+     * @param params    参数
+     * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     */
+    static <T> Optional<T> queryFirst(Connection conn, String sql, Object[] params, RowMapper<T> rowMapper)
+            throws SQLException {
+        assertConnectionNotNull(conn);
+        assertSqlNotNull(sql);
+        assertRowMapperNotNull(rowMapper);
+        return queryFirstInternal(conn, sql, params, rowMapper);
+    }
+
+    /**
+     * 查询第一行第一列，并转换为指定类型
+     *
+     * @param <T>    目标类型
+     * @param sql    SQL
+     * @param params 参数
+     * @param clazz  目标类型
+     */
+    static <T> Optional<T> queryFirst(Connection conn, String sql, Object[] params, Class<T> clazz)
+            throws SQLException {
+        assertConnectionNotNull(conn);
+        assertSqlNotNull(sql);
+        assertClazzNotNull(clazz);
+        return queryFirstInternal(conn, sql, params, (rs, rowNumber) -> rs.getObject(1, clazz));
+    }
+
+    /**
+     * 查询第一行第一列，并转换为字符串
+     *
+     * @param conn   数据库连接
+     * @param sql    SQL
+     * @param params 参数
+     */
+    static Optional<String> queryFirstString(Connection conn, String sql, Object[] params)
+            throws SQLException {
+        return queryFirst(conn, sql, params, (rs, rowNumber) -> rs.getString(1));
+    }
+
+    /**
+     * 查询第一行第一列，并转换为整数值
+     *
+     * @param conn   数据库连接
+     * @param sql    SQL
+     * @param params 参数
+     */
+    static OptionalInt queryFirstInt(Connection conn, String sql, Object[] params)
+            throws SQLException {
+        Optional<Integer> result = queryFirst(conn, sql, params, (rs, rowNumber) -> rs.getInt(1));
+        return OptionalTools.toOptionalInt(result);
+    }
+
+    /**
+     * 查询第一行第一列，并转换为长整型
+     *
+     * @param conn   数据库连接
+     * @param sql    SQL
+     * @param params 参数
+     */
+    static OptionalLong queryFirstLong(Connection conn, String sql, Object[] params)
+            throws SQLException {
+        Optional<Long> result = queryFirst(conn, sql, params, (rs, rowNumber) -> rs.getLong(1));
+        return OptionalTools.toOptionalLong(result);
+    }
+
+    /**
+     * 查询第一行第一列，并转换为双精度浮点型
+     *
+     * @param conn   数据库连接
+     * @param sql    SQL
+     * @param params 参数
+     */
+    static OptionalDouble queryFirstDouble(Connection conn, String sql, Object[] params)
+            throws SQLException {
+        Optional<Double> result = queryFirst(conn, sql, params, (rs, rowNumber) -> rs.getDouble(1));
+        return OptionalTools.toOptionalDouble(result);
+    }
+
+    /**
+     * 查询第一行第一列，并转换为 {@link BigDecimal}
+     *
+     * @param conn   数据库连接
+     * @param sql    SQL
+     * @param params 参数
+     */
+    static Optional<BigDecimal> queryFirstBigDecimal(Connection conn, String sql, Object[] params)
+            throws SQLException {
+        return queryFirst(conn, sql, params, (rs, rowNumber) -> rs.getBigDecimal(1));
+    }
+
+    // #endregion
+
+    // #region - update & batchUpdate
+
+    /**
+     * 执行更新操作
+     *
+     * @param conn   数据库连接
+     * @param sql    要执行的 SQL
+     * @param params 参数
+     * @return 更新记录数
+     */
+    static int update(Connection conn, String sql, Object[] params)
+            throws SQLException {
+        assertConnectionNotNull(conn);
+        assertSqlNotNull(sql);
+        try (PreparedStatement stmt = conn.prepareStatement(sql)) {
+            fillStatement(stmt, params);
+            return stmt.executeUpdate();
+        }
+    }
+
+    /**
+     * 执行 SQL 并返回生成的 keys
+     *
+     * @param conn      数据库连接
+     * @param sql       要执行的 SQL
+     * @param params    参数
+     * @param rowMapper 行数据映射逻辑
+     *
+     * @return generated keys
+     * @throws SQLException 执行 SQL 遇到异常情况将抛出
+     */
+    static <T> List<T> update(Connection conn, String sql, Object[] params, RowMapper<T> rowMapper)
+            throws SQLException {
+        assertConnectionNotNull(conn);
+        assertSqlNotNull(sql);
+        assertRowMapperNotNull(rowMapper);
+        final List<T> result = new ArrayList<>();
+        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);
+                }
+            }
+            return result;
+        }
+    }
+
+    /**
+     * 执行批量更新，批量更新数据，返回每条记录更新的行数
+     *
+     * @param conn      数据库连接
+     * @param sql       SQL 语句
+     * @param params    参数列表
+     * @param batchSize 每次批量更新的数据量
+     */
+    static List<int[]> batchUpdate(Connection conn, String sql, Collection<Object[]> params, int batchSize)
+            throws SQLException {
+        assertConnectionNotNull(conn);
+        assertSqlNotNull(sql);
+
+        if (params == null || params.isEmpty()) {
+            return Collections.emptyList();
+        }
+        int executeCount = params.size() / batchSize;
+        executeCount = (params.size() % batchSize == 0) ? executeCount : (executeCount + 1);
+        List<int[]> result = Lists.newArrayListWithCapacity(executeCount);
+
+        try (PreparedStatement stmt = conn.prepareStatement(sql)) {
+            int i = 0;
+            for (Object[] ps : params) {
+                i++;
+                fillStatement(stmt, ps);
+                stmt.addBatch();
+                if (i % batchSize == 0 || i >= params.size()) {
+                    int[] n = stmt.executeBatch();
+                    result.add(n);
+                    stmt.clearBatch();
+                }
+            }
+            return result;
+        }
+    }
+
+    /**
+     * 批量更新，返回更新成功的记录行数。发生异常时不中断操作，将异常存入 {@code exceptions} 中
+     *
+     * @param conn       数据库连接
+     * @param sql        sql语句
+     * @param params     参数列表
+     * @param batchSize  每次批量更新的数据量
+     * @param exceptions 异常列表，用于记录异常信息
+     */
+    static List<int[]> batchUpdateAndIgnoreException(Connection conn,
+            String sql, @Nullable Collection<Object[]> params, int batchSize,
+            List<Exception> exceptions)
+            throws SQLException {
+        assertConnectionNotNull(conn);
+        assertSqlNotNull(sql);
+        AssertTools.checkArgument(CollectionTools.isNotEmpty(exceptions),
+                "The list used to store exceptions should be non-null and empty.");
+        if (params == null || params.isEmpty()) {
+            return Collections.emptyList();
+        }
+        int executeCount = params.size() / batchSize;
+        executeCount = (params.size() % batchSize == 0) ? executeCount : (executeCount + 1);
+        List<int[]> result = Lists.newArrayListWithCapacity(executeCount);
+
+        try (PreparedStatement stmt = conn.prepareStatement(sql)) {
+            int i = 0;
+            for (Object[] ps : params) {
+                i++;
+                fillStatement(stmt, ps);
+                stmt.addBatch();
+                final int batchIndex = i % batchSize;
+                if (batchIndex == 0 || i >= params.size()) {
+                    try {
+                        int[] n = stmt.executeBatch();
+                        result.add(n);
+                        stmt.clearBatch();
+                    }
+                    catch (Exception e) {
+                        int n = (i >= params.size() && batchIndex != 0) ? batchIndex : batchSize;
+                        result.add(new int[n]);
+                        stmt.clearBatch();
+                        // 收集异常信息
+                        exceptions.add(e);
+                    }
+                }
+            }
+            return result;
+        }
+    }
+
+    // #endregion
+
+    // #region - internal
+
+    /**
+     * 执行查询，将查询结果按照指定逻辑进行处理并返回
+     *
+     * @param conn          数据库连接
+     * @param sql           SQL
+     * @param params        参数
+     * @param resultHandler 结果处理器，用于处理 {@link ResultSet}
+     */
+    private static <T> T queryInternal(@Nonnull Connection conn,
+                                        @Nonnull String sql,
+                                        @Nullable Object[] params,
+                                        @Nonnull ResultHandler<T> resultHandler)
+            throws SQLException {
+        try (PreparedStatement stmt = conn.prepareStatement(sql)) {
+            fillStatement(stmt, params);
+            try (ResultSet rs = stmt.executeQuery()) {
+                return resultHandler.handle(rs);
+            }
+        }
+    }
+
+    /**
+     * 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表
+     *
+     * @param conn      数据库连接
+     * @param sql       SQL
+     * @param params    参数
+     * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     */
+    private static <T> List<T> queryListInternal(@Nonnull Connection conn,
+                                            @Nonnull String sql,
+                                            @Nullable Object[] params,
+                                            @Nonnull RowMapper<T> rowMapper)
+            throws SQLException {
+        return queryInternal(conn, sql, params, rs -> {
+            List<T> result = new ArrayList<>();
+            int rowNumber = 0;
+            while (rs.next()) {
+                T e = rowMapper.mapRow(rs, rowNumber++);
+                result.add(e);
+            }
+            return result;
+        });
+    }
+
+    /**
+     * 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional}
+     *
+     * @param conn      数据库连接
+     * @param sql       SQL
+     * @param params    参数
+     * @param rowMapper 行数据映射逻辑
+     */
+    private static <T> Optional<T> queryFirstInternal(@Nonnull Connection conn,
+                                            @Nonnull String sql,
+                                            @Nullable Object[] params,
+                                            @Nonnull RowMapper<T> rowMapper)
+            throws SQLException {
+        return queryInternal(conn, sql, params, rs -> {
+            if (rs.next()) {
+                return Optional.ofNullable(rowMapper.mapRow(rs, 0));
+            }
+            return Optional.empty();
+        });
+    }
+
+    // #endregion
+
+    /**
+     * 填充参数
+     */
+    private static void fillStatement(@Nonnull PreparedStatement stmt, @Nullable Object[] params)
+            throws SQLException {
+        if (params != null && params.length > 0) {
+            Object param;
+            for (int i = 0; i < params.length; i++) {
+                param = params[i];
+                if (param instanceof java.sql.Date) {
+                    stmt.setDate(i + 1, (java.sql.Date) param);
+                }
+                else if (param instanceof java.sql.Time) {
+                    stmt.setTime(i + 1, (java.sql.Time) param);
+                }
+                else if (param instanceof java.sql.Timestamp) {
+                    stmt.setTimestamp(i + 1, (java.sql.Timestamp) param);
+                }
+                else {
+                    stmt.setObject(i + 1, param);
+                }
+            }
+        }
+    }
+
+    // #region - 参数校验
+
+    private static void assertConnectionNotNull(Connection conn) {
+        AssertTools.checkArgumentNotNull(conn, "The argument \"conn\" could not be null.");
+    }
+
+    private static void assertSqlNotNull(String sql) {
+        AssertTools.checkArgumentNotNull(sql, "The argument \"sql\" could not be null.");
+    }
+
+    private static void assertRowMapperNotNull(RowMapper<?> rowMapper) {
+        AssertTools.checkArgumentNotNull(rowMapper, "The argument \"rowMapper\" could not be null.");
+    }
+
+    private static void assertResultHandlerNotNull(ResultHandler<?> resultHandler) {
+        AssertTools.checkArgumentNotNull(resultHandler, "The argument \"resultHandler\" could not be null.");
+    }
+
+    private static void assertClazzNotNull(Class<?> clazz) {
+        AssertTools.checkArgumentNotNull(clazz, "The argument \"clazz\" could not be null.");
+    }
+
+    // #endregion
+
+    private JdbcOperationSupport() {
+        throw new IllegalStateException("Utility class");
+    }
+}

src/main/java/xyz/zhouxy/jdbc/JdbcOperations.java

@@ -0,0 +1,359 @@
+package xyz.zhouxy.jdbc;
+
+import java.math.BigDecimal;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalDouble;
+import java.util.OptionalInt;
+import java.util.OptionalLong;
+
+import javax.annotation.Nullable;
+
+/**
+ * JdbcOperations
+ *
+ * <p>
+ * 定义 JdbcTemplate 的 API
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ */
+interface JdbcOperations {
+
+    // #region - query
+
+    /**
+     * 执行查询，并按照自定义处理逻辑对结果进行处理，将结果转换为指定类型并返回
+     *
+     * @param sql           SQL
+     * @param params        参数
+     * @param resultHandler 结果处理器，用于处理 {@link ResultSet}
+     */
+    <T> T query(String sql, Object[] params, ResultHandler<T> resultHandler)
+            throws SQLException;
+
+    /**
+     * 执行查询，并按照自定义处理逻辑对结果进行处理，将结果转换为指定类型并返回
+     *
+     * @param sql           SQL
+     * @param resultHandler 结果处理器，用于处理 {@link ResultSet}
+     */
+    <T> T query(String sql, ResultHandler<T> resultHandler)
+            throws SQLException;
+
+    // #endregion
+
+    // #region - queryList
+
+    /**
+     * 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表
+     *
+     * @param sql       SQL
+     * @param params    参数
+     * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     */
+    <T> List<T> queryList(String sql, Object[] params, RowMapper<T> rowMapper)
+            throws SQLException;
+
+    /**
+     * 执行查询，返回结果映射为指定的类型。当结果为单列时使用
+     *
+     * @param sql    SQL
+     * @param params 参数
+     * @param clazz  将结果映射为指定的类型
+     */
+    <T> List<T> queryList(String sql, Object[] params, Class<T> clazz)
+            throws SQLException;
+
+    /**
+     * 执行查询，每一行数据映射为 {@code Map<String, Object>}，返回结果列表
+     *
+     * @param sql    SQL
+     * @param params 参数列表
+     */
+    List<Map<String, Object>> queryList(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 执行查询，每一行数据映射为 {@link DbRecord}，返回结果列表
+     *
+     * @param sql    SQL
+     * @param params 参数列表
+     */
+    List<DbRecord> queryRecordList(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表
+     *
+     * @param sql       SQL
+     * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     */
+    <T> List<T> queryList(String sql, RowMapper<T> rowMapper)
+            throws SQLException;
+
+    /**
+     * 执行查询，返回结果映射为指定的类型。当结果为单列时使用
+     *
+     * @param sql   SQL
+     * @param clazz 将结果映射为指定的类型
+     */
+    <T> List<T> queryList(String sql, Class<T> clazz)
+            throws SQLException;
+
+    /**
+     * 执行查询，每一行数据映射为 {@code Map<String, Object>}，返回结果列表
+     *
+     * @param sql SQL
+     */
+    List<Map<String, Object>> queryList(String sql)
+            throws SQLException;
+
+    /**
+     * 执行查询，每一行数据映射为 {@link DbRecord}，返回结果列表
+     *
+     * @param sql SQL
+     */
+    List<DbRecord> queryRecordList(String sql)
+            throws SQLException;
+
+    // #endregion
+
+    // #region - queryFirst
+
+    /**
+     * 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional}
+     *
+     * @param sql       SQL
+     * @param params    参数
+     * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     */
+    <T> Optional<T> queryFirst(String sql, Object[] params, RowMapper<T> rowMapper)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为指定类型
+     *
+     * @param <T>    目标类型
+     * @param sql    SQL
+     * @param params 参数
+     * @param clazz  目标类型
+     */
+    <T> Optional<T> queryFirst(String sql, Object[] params, Class<T> clazz)
+            throws SQLException;
+
+    /**
+     * 执行查询，将第一行数据转为 Map<String, Object>
+     *
+     * @param sql    SQL
+     * @param params 参数
+     */
+    Optional<Map<String, Object>> queryFirst(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 执行查询，将第一行数据转为 DbRecord
+     *
+     * @param sql    SQL
+     * @param params 参数
+     */
+    Optional<DbRecord> queryFirstRecord(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为字符串
+     *
+     * @param sql    SQL
+     * @param params 参数
+     */
+    Optional<String> queryFirstString(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为整数值
+     *
+     * @param sql    SQL
+     * @param params 参数
+     */
+    OptionalInt queryFirstInt(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为长整型
+     *
+     * @param sql    SQL
+     * @param params 参数
+     */
+    OptionalLong queryFirstLong(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为双精度浮点型
+     *
+     * @param sql    SQL
+     * @param params 参数
+     */
+    OptionalDouble queryFirstDouble(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为 {@link BigDecimal}
+     *
+     * @param sql    SQL
+     * @param params 参数
+     */
+    Optional<BigDecimal> queryFirstBigDecimal(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional}
+     *
+     * @param sql       SQL
+     * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
+     */
+    <T> Optional<T> queryFirst(String sql, RowMapper<T> rowMapper)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为指定类型
+     *
+     * @param <T>   目标类型
+     * @param sql   SQL
+     * @param clazz 目标类型
+     */
+    <T> Optional<T> queryFirst(String sql, Class<T> clazz)
+            throws SQLException;
+
+    /**
+     * 执行查询，将第一行数据转为 Map<String, Object>
+     *
+     * @param sql SQL
+     */
+    Optional<Map<String, Object>> queryFirst(String sql)
+            throws SQLException;
+
+    /**
+     * 执行查询，将第一行数据转为 DbRecord
+     *
+     * @param sql SQL
+     */
+    Optional<DbRecord> queryFirstRecord(String sql)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为字符串
+     *
+     * @param sql SQL
+     */
+    Optional<String> queryFirstString(String sql)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为整数值
+     *
+     * @param sql SQL
+     */
+    OptionalInt queryFirstInt(String sql)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为长整型
+     *
+     * @param sql SQL
+     */
+    OptionalLong queryFirstLong(String sql)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为双精度浮点型
+     *
+     * @param sql SQL
+     */
+    OptionalDouble queryFirstDouble(String sql)
+            throws SQLException;
+
+    /**
+     * 查询第一行第一列，并转换为 {@link BigDecimal}
+     *
+     * @param sql SQL
+     */
+    Optional<BigDecimal> queryFirstBigDecimal(String sql)
+            throws SQLException;
+
+    // #endregion
+
+    // #region - update & batchUpdate
+
+    /**
+     * 执行更新操作
+     *
+     * @param sql    要执行的 SQL
+     * @param params 参数
+     * @return 更新记录数
+     */
+    int update(String sql, Object[] params)
+            throws SQLException;
+
+    /**
+     * 执行更新操作
+     *
+     * @param sql 要执行的 SQL
+     * @return 更新记录数
+     */
+    int update(String sql)
+            throws SQLException;
+
+    /**
+     * 执行 SQL 并返回生成的 keys
+     *
+     * @param sql       要执行的 SQL
+     * @param params    参数
+     * @param rowMapper 行数据映射逻辑
+     *
+     * @return generated keys
+     * @throws SQLException 执行 SQL 遇到异常情况将抛出
+     */
+    <T> List<T> update(String sql, Object[] params, RowMapper<T> rowMapper)
+            throws SQLException;
+
+    /**
+     * 执行 SQL 并返回生成的 keys
+     *
+     * @param sql       要执行的 SQL
+     * @param rowMapper 行数据映射逻辑
+     *
+     * @return generated keys
+     * @throws SQLException 执行 SQL 遇到异常情况将抛出
+     */
+    <T> List<T> update(String sql, RowMapper<T> rowMapper)
+            throws SQLException;
+
+    /**
+     * 执行批量更新，批量更新数据，返回每条记录更新的行数
+     *
+     * @param sql       SQL 语句
+     * @param params    参数列表
+     * @param batchSize 每次批量更新的数据量
+     */
+    List<int[]> batchUpdate(String sql, @Nullable Collection<Object[]> params, int batchSize)
+            throws SQLException;
+
+    /**
+     * 批量更新，返回更新成功的记录行数。发生异常时不中断操作，将异常存入 {@code exceptions} 中
+     *
+     * @param sql        sql语句
+     * @param params     参数列表
+     * @param batchSize  每次批量更新的数据量
+     * @param exceptions 异常列表，用于记录异常信息
+     */
+    List<int[]> batchUpdateAndIgnoreException(String sql, @Nullable Collection<Object[]> params,
+            int batchSize, List<Exception> exceptions)
+            throws SQLException;
+
+    // #endregion
+}

src/main/java/xyz/zhouxy/jdbc/ParamBuilder.java

@@ -27,12 +27,21 @@ import java.util.OptionalLong;
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
-import com.google.common.base.Preconditions;
-
 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;
 
+/**
+ * ParamBuilder
+ *
+ * <p>
+ * JDBC 参数构造器，将数据转换为 {@code Object[]} 类型，以传给 {@link PreparedStatement}
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ */
 public class ParamBuilder {
     public static final Object[] EMPTY_OBJECT_ARRAY = {};
 
@@ -60,8 +69,8 @@ public class ParamBuilder {
     }
 
     public static <T> List<Object[]> buildBatchParams(final Collection<T> c, final Function<T, Object[]> func) {
-        Preconditions.checkNotNull(c, "The collection can not be null.");
-        Preconditions.checkNotNull(func, "The func can not be null.");
+        AssertTools.checkNotNull(c, "The collection can not be null.");
+        AssertTools.checkNotNull(func, "The func can not be null.");
         if (CollectionTools.isEmpty(c)) {
             return Collections.emptyList();
         }

src/main/java/xyz/zhouxy/jdbc/ResultHandler.java

@@ -19,7 +19,21 @@ package xyz.zhouxy.jdbc;
 import java.sql.ResultSet;
 import java.sql.SQLException;
 
+/**
+ * ResultHandler
+ *
+ * <p>
+ * 处理 {@link ResultSet}
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ */
 @FunctionalInterface
 public interface ResultHandler<T> {
+
+    /**
+     * 将 {@link ResultSet} 转换为指定类型的对象
+     */
     T handle(ResultSet resultSet) throws SQLException;
 }

src/main/java/xyz/zhouxy/jdbc/RowMapper.java

@@ -22,10 +22,21 @@ import java.sql.SQLException;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * RowMapper
+ *
+ * <p>
+ * {@link ResultSet} 中每一行数据的处理逻辑。
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0.0
+ */
 @FunctionalInterface
 public interface RowMapper<T> {
     T mapRow(ResultSet rs, int rowNumber) throws SQLException;
 
+    /** 每一行数据转换为 {@link HashMap} */
     public static final RowMapper<Map<String, Object>> HASH_MAP_MAPPER = (rs, rowNumber) -> {
         Map<String, Object> result = new HashMap<>();
         ResultSetMetaData metaData = rs.getMetaData();
@@ -37,13 +48,16 @@ public interface RowMapper<T> {
         return result;
     };
 
+    /** 每一行数据转换为 {@link DbRecord} */
     public static final RowMapper<DbRecord> RECORD_MAPPER =
             (rs, rowNumber) -> new DbRecord(HASH_MAP_MAPPER.mapRow(rs, rowNumber));
 
+    /** 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。 */
     public static <T> RowMapper<T> beanRowMapper(Class<T> beanType) throws SQLException {
         return DefaultBeanRowMapper.of(beanType);
     }
 
+    /** 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。 */
     public static <T> RowMapper<T> beanRowMapper(Class<T> beanType, Map<String, String> propertyColMap)
             throws SQLException {
         return DefaultBeanRowMapper.of(beanType, propertyColMap);