From ca3d9c67a4379d7c03e4f23f623a79e8ec89eef1 Mon Sep 17 00:00:00 2001 From: ZhouXY108 Date: Fri, 29 May 2026 00:30:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=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 --- .../xyz/zhouxy/jdbc/DefaultBeanRowMapper.java | 4 +- .../xyz/zhouxy/jdbc/JdbcOperationSupport.java | 2 +- .../java/xyz/zhouxy/jdbc/JdbcOperations.java | 87 ++++++++++++++++--- .../java/xyz/zhouxy/jdbc/ResultHandler.java | 5 ++ src/main/java/xyz/zhouxy/jdbc/RowMapper.java | 21 ++++- 5 files changed, 103 insertions(+), 16 deletions(-) diff --git a/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java b/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java index 2179386..7d13026 100644 --- a/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java +++ b/src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java @@ -54,8 +54,8 @@ import xyz.zhouxy.plusone.commons.annotation.StaticFactoryMethod; *
  • JavaBean 属性仅支持引用类型，不支持基本数据类型。
    • *
  • 实际使用中还是建议针对目标类型自定义 {@link RowMapper}。
    • * - *

    - * @author ZhouXY + +* @author ZhouXY * @since 1.0.0 */ public class DefaultBeanRowMapper implements RowMapper { diff --git a/src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java b/src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java index ac1dded..986c705 100644 --- a/src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java +++ b/src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java @@ -177,7 +177,7 @@ class JdbcOperationSupport { * @param rowMapper 行数据映射逻辑 * * @return generated keys - * @throws SQLException 执行 SQL 遇到异常情况将抛出 + * @throws SQLException 数据库执行异常 */ static List updateAndReturnKeys(Connection conn, String sql, Object[] params, RowMapper rowMapper) throws SQLException { diff --git a/src/main/java/xyz/zhouxy/jdbc/JdbcOperations.java b/src/main/java/xyz/zhouxy/jdbc/JdbcOperations.java index 891ba12..3aadfe3 100644 --- a/src/main/java/xyz/zhouxy/jdbc/JdbcOperations.java +++ b/src/main/java/xyz/zhouxy/jdbc/JdbcOperations.java @@ -42,9 +42,13 @@ public interface JdbcOperations { /** * 执行查询，并按照自定义处理逻辑对结果进行处理，将结果转换为指定类型并返回 * + * @param 返回结果类型 * @param sql SQL * @param params 参数 * @param resultHandler 结果处理器，用于处理 {@link ResultSet} + * + * @return 查询结果 + * @throws SQLException SQL异常 */ T query(String sql, Object[] params, ResultHandler resultHandler) throws SQLException; @@ -52,8 +56,12 @@ public interface JdbcOperations { /** * 执行查询，并按照自定义处理逻辑对结果进行处理，将结果转换为指定类型并返回 * + * @param 返回结果类型 * @param sql SQL * @param resultHandler 结果处理器，用于处理 {@link ResultSet} + * + * @return 查询结果 + * @throws SQLException SQL异常 */ default T query(String sql, ResultHandler resultHandler) throws SQLException { @@ -67,9 +75,13 @@ public interface JdbcOperations { /** * 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表 * + * @param 返回结果列表中每一行数据的类型 * @param sql SQL * @param params 参数 * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑 + * + * @return 查询结果列表 + * @throws SQLException SQL 异常 */ List queryList(String sql, Object[] params, RowMapper rowMapper) throws SQLException; @@ -77,9 +89,13 @@ public interface JdbcOperations { /** * 执行查询，返回结果映射为指定的类型。当结果为单列时使用 * + * @param 目标类型 * @param sql SQL * @param params 参数 - * @param clazz 将结果映射为指定的类型 + * @param clazz 目标类型 + * + * @return 映射结果。如果查询结果为空，则返回空列表 + * @throws SQLException SQL异常 */ List queryList(String sql, Object[] params, Class clazz) throws SQLException; @@ -89,6 +105,9 @@ public interface JdbcOperations { * * @param sql SQL * @param params 参数列表 + * + * @return 结果列表 + * @throws SQLException SQL 异常 */ List> queryList(String sql, Object[] params) throws SQLException; @@ -96,8 +115,12 @@ public interface JdbcOperations { /** * 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表 * + * @param 目标类型 * @param sql SQL * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑 + * + * @return 结果列表 + * @throws SQLException SQL 异常 */ default List queryList(String sql, RowMapper rowMapper) throws SQLException { @@ -107,8 +130,12 @@ public interface JdbcOperations { /** * 执行查询，返回结果映射为指定的类型。当结果为单列时使用 * + * @param 目标类型 * @param sql SQL * @param clazz 将结果映射为指定的类型 + * + * @return 查询结果 + * @throws SQLException SQL 异常 */ default List queryList(String sql, Class clazz) throws SQLException { @@ -119,6 +146,9 @@ public interface JdbcOperations { * 执行查询，每一行数据映射为 {@code Map}，返回结果列表 * * @param sql SQL + * + * @return 结果列表 + * @throws SQLException SQL 异常 */ default List> queryList(String sql) throws SQLException { @@ -132,9 +162,13 @@ public interface JdbcOperations { /** * 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional} * + * @param 目标类型 * @param sql SQL * @param params 参数 * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑 + * + * @return 查询结果 + * @throws SQLException SQL 异常 */ Optional queryFirst(String sql, Object[] params, RowMapper rowMapper) throws SQLException; @@ -146,15 +180,21 @@ public interface JdbcOperations { * @param sql SQL * @param params 参数 * @param clazz 目标类型 + * + * @return 查询结果 + * @throws SQLException SQL 异常 */ Optional queryFirst(String sql, Object[] params, Class clazz) throws SQLException; /** - * 执行查询，将第一行数据转为 Map + * 执行查询，将第一行数据转为 Map<String, Object> * * @param sql SQL * @param params 参数 + * + * @return 查询结果 + * @throws SQLException SQL 异常 */ Optional> queryFirst(String sql, Object[] params) throws SQLException; @@ -162,8 +202,12 @@ public interface JdbcOperations { /** * 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional} * + * @param 目标类型 * @param sql SQL * @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑 + * + * @return 查询结果 + * @throws SQLException SQL 异常 */ default Optional queryFirst(String sql, RowMapper rowMapper) throws SQLException { @@ -176,6 +220,9 @@ public interface JdbcOperations { * @param 目标类型 * @param sql SQL * @param clazz 目标类型 + * + * @return 第一行第一列的值，如果查询结果为空，则返回 {@code Optional#empty()} + * @throws SQLException SQL 异常 */ default Optional queryFirst(String sql, Class clazz) throws SQLException { @@ -183,9 +230,12 @@ public interface JdbcOperations { } /** - * 执行查询，将第一行数据转为 Map + * 执行查询，将第一行数据转为 Map<String, Object> * * @param sql SQL + * + * @return 查询结果 + * @throws SQLException SQL 异常 */ default Optional> queryFirst(String sql) throws SQLException { @@ -195,10 +245,10 @@ public interface JdbcOperations { /** * 查询第一行第一列并转换为 boolean * - *

    - * 注：如果查询结果为空，则返回 {@code false}。 - * * @param sql SQL + * + * @return 查询结果。如果查询结果为空，则返回 {@code false}。 + * @throws SQLException SQL 异常 */ default boolean queryBoolean(String sql) throws SQLException { @@ -208,10 +258,12 @@ public interface JdbcOperations { /** * 查询第一行第一列并转换为 boolean * - *

    - * 注：如果查询结果为空，则返回 {@code false}。 - * * @param sql SQL + * @param params 参数 + * + * @return 查询结果。如果查询结果为空，则返回 {@code false} + * + * @throws SQLException SQL 异常 */ boolean queryBoolean(String sql, Object[] params) throws SQLException; @@ -226,6 +278,7 @@ public interface JdbcOperations { * @param sql 要执行的 SQL * @param params 参数 * @return 更新记录数 + * @throws SQLException SQL 异常 */ int update(String sql, Object[] params) throws SQLException; @@ -235,6 +288,8 @@ public interface JdbcOperations { * * @param sql 要执行的 SQL * @return 更新记录数 + * + * @throws SQLException 数据库执行异常 */ default int update(String sql) throws SQLException { @@ -248,8 +303,10 @@ public interface JdbcOperations { * @param params 参数 * @param rowMapper 行数据映射逻辑 * + * @param 映射结果类型 + * * @return generated keys - * @throws SQLException 执行 SQL 遇到异常情况将抛出 + * @throws SQLException 数据库执行异常 */ List updateAndReturnKeys(String sql, Object[] params, RowMapper rowMapper) throws SQLException; @@ -260,8 +317,10 @@ public interface JdbcOperations { * @param sql 要执行的 SQL * @param rowMapper 行数据映射逻辑 * + * @param 映射结果类型 + * * @return generated keys - * @throws SQLException 执行 SQL 遇到异常情况将抛出 + * @throws SQLException 数据库执行异常 */ default List updateAndReturnKeys(String sql, RowMapper rowMapper) throws SQLException { @@ -280,6 +339,9 @@ public interface JdbcOperations { * @param sql SQL 语句 * @param params 参数列表 * @param batchSize 每次批量更新的数据量 + * + * @return 批量更新的结果 + * @throws SQLException SQL 异常 */ BatchUpdateResult batchUpdate(String sql, @Nullable Collection params, int batchSize) throws SQLException; @@ -296,6 +358,9 @@ public interface JdbcOperations { * @param quietly 静默分批更新。 * 如果 {@code quietly} 为 {@code true}，分批更新过程中发生异常不中断操作； * 如果 {@code quietly} 为 {@code false}，分批更新过程中发生异常即中断操作，并返回结果。 + * + * @return 批次更新结果 + * @throws SQLException 数据库执行异常 */ BatchUpdateResult batchUpdate(String sql, @Nullable Collection params, int batchSize, boolean quietly) diff --git a/src/main/java/xyz/zhouxy/jdbc/ResultHandler.java b/src/main/java/xyz/zhouxy/jdbc/ResultHandler.java index 2c1f6e7..51d8d8e 100644 --- a/src/main/java/xyz/zhouxy/jdbc/ResultHandler.java +++ b/src/main/java/xyz/zhouxy/jdbc/ResultHandler.java @@ -34,6 +34,11 @@ public interface ResultHandler { /** * 将 {@link ResultSet} 转换为指定类型的对象 + * + * @param resultSet {@link ResultSet} + * @return 转换后的对象 + * + * @throws SQLException 数据库执行异常 */ T handle(ResultSet resultSet) throws SQLException; } diff --git a/src/main/java/xyz/zhouxy/jdbc/RowMapper.java b/src/main/java/xyz/zhouxy/jdbc/RowMapper.java index fea5af8..d195bce 100644 --- a/src/main/java/xyz/zhouxy/jdbc/RowMapper.java +++ b/src/main/java/xyz/zhouxy/jdbc/RowMapper.java @@ -53,12 +53,29 @@ public interface RowMapper { return result; }; - /** 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。 */ + /** + * 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。 + * + * @param beanType Java Bean 的类型 + * @param Java Bean 的类型 + * + * @return {@link DefaultBeanRowMapper} + * @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败 + */ static RowMapper beanRowMapper(Class beanType) throws SQLException { return DefaultBeanRowMapper.of(beanType); } - /** 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。 */ + /** + * 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。 + * + * @param beanType Java Bean 的类型 + * @param propertyColMap Java Bean 属性名与数据库列名的映射关系 + * @param Java Bean 的类型 + * + * @return {@link DefaultBeanRowMapper} + * @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败 + */ static RowMapper beanRowMapper(Class beanType, Map propertyColMap) throws SQLException { return DefaultBeanRowMapper.of(beanType, propertyColMap);