From d70e12e2545a66ebfdd1996bcf6fddb42a1fc858 Mon Sep 17 00:00:00 2001
From: ZhouXY108 <luquanlion@outlook.com>
Date: Fri, 5 Jun 2026 22:27:51 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20`ParamBuilder`=20?=
 =?UTF-8?q?=E5=92=8C=20`SimpleJdbcTemplate`=20=E7=9A=84=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../java/xyz/zhouxy/jdbc/ParamBuilder.java    | 31 +++++++++++++++++++
 .../xyz/zhouxy/jdbc/SimpleJdbcTemplate.java   | 13 ++++++++
 2 files changed, 44 insertions(+)

diff --git a/src/main/java/xyz/zhouxy/jdbc/ParamBuilder.java b/src/main/java/xyz/zhouxy/jdbc/ParamBuilder.java
index b335e9c..0075e65 100644
--- a/src/main/java/xyz/zhouxy/jdbc/ParamBuilder.java
+++ b/src/main/java/xyz/zhouxy/jdbc/ParamBuilder.java
@@ -45,8 +45,26 @@ 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)) {
             return EMPTY_OBJECT_ARRAY;
@@ -87,6 +105,19 @@ public class ParamBuilder {
         return param;
     }
 
+    /**
+     * 批量构建参数列表
+     *
+     * <p>
+     * 将集合中的每个元素通过 {@code func} 映射为 {@code Object[]}，
+     * 最终返回 {@code List<Object[]>}，用于 {@link #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.");
diff --git a/src/main/java/xyz/zhouxy/jdbc/SimpleJdbcTemplate.java b/src/main/java/xyz/zhouxy/jdbc/SimpleJdbcTemplate.java
index cfc2aa0..d03c6f4 100644
--- a/src/main/java/xyz/zhouxy/jdbc/SimpleJdbcTemplate.java
+++ b/src/main/java/xyz/zhouxy/jdbc/SimpleJdbcTemplate.java
@@ -59,6 +59,11 @@ public class SimpleJdbcTemplate implements JdbcOperations {
     @Nonnull
     private final TransactionTemplate transactionTemplate;
 
+    /**
+     * 构造一个 {@code SimpleJdbcTemplate} 实例
+     *
+     * @param dataSource 数据源，用于获取数据库连接；不可为 {@code null}
+     */
     public SimpleJdbcTemplate(@Nonnull DataSource dataSource) {
         AssertTools.checkNotNull(dataSource);
         this.dataSource = dataSource;
@@ -199,6 +204,14 @@ public class SimpleJdbcTemplate implements JdbcOperations {
 
     // #region - transaction
 
+    /**
+     * 获取事务模板
+     *
+     * <p>
+     * 返回的 {@link TransactionTemplate} 与当前模板共享同一个 {@link DataSource}。
+     *
+     * @return 事务模板
+     */
     public TransactionTemplate transaction() {
         return this.transactionTemplate;
     }