zhouxy108/simple-jdbc
1
0
Fork 0
forked from plusone/simple-jdbc
Code Pull Requests Activity

docs: 完善文档注释

Browse Source
This commit is contained in:
ZhouXY108
2026-05-29 00:30:34 +08:00
parent 7052a621dd
commit ca3d9c67a4
5 changed files with 103 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/main/java/xyz/zhouxy/jdbc/DefaultBeanRowMapper.java
View File

@@ -54,7 +54,7 @@ import xyz.zhouxy.plusone.commons.annotation.StaticFactoryMethod;
* <li>JavaBean 属性仅支持引用类型，不支持基本数据类型。</li>
* <li>实际使用中还是建议针对目标类型自定义 {@link RowMapper}。</li>
* </ul>
* </p>
* @author ZhouXY
* @since 1.0.0
*/

2
src/main/java/xyz/zhouxy/jdbc/JdbcOperationSupport.java
View File

@@ -177,7 +177,7 @@ class JdbcOperationSupport {
* @param rowMapper 行数据映射逻辑
*
* @return generated keys
* @throws SQLException 执行 SQL 遇到异常情况将抛出
* @throws SQLException 数据库执行异常
*/
static <T> List<T> updateAndReturnKeys(Connection conn, String sql, Object[] params, RowMapper<T> rowMapper)
throws SQLException {

87
src/main/java/xyz/zhouxy/jdbc/JdbcOperations.java
View File

@@ -42,9 +42,13 @@ public interface JdbcOperations {
/**
* 执行查询，并按照自定义处理逻辑对结果进行处理，将结果转换为指定类型并返回
*
* @param <T> 返回结果类型
* @param sql SQL
* @param params 参数
* @param resultHandler 结果处理器，用于处理 {@link ResultSet}
*
* @return 查询结果
* @throws SQLException SQL异常
*/
<T> T query(String sql, Object[] params, ResultHandler<T> resultHandler)
throws SQLException;
@@ -52,8 +56,12 @@ public interface JdbcOperations {
/**
* 执行查询，并按照自定义处理逻辑对结果进行处理，将结果转换为指定类型并返回
*
* @param <T> 返回结果类型
* @param sql SQL
* @param resultHandler 结果处理器，用于处理 {@link ResultSet}
*
* @return 查询结果
* @throws SQLException SQL异常
*/
default <T> T query(String sql, ResultHandler<T> resultHandler)
throws SQLException {
@@ -67,9 +75,13 @@ public interface JdbcOperations {
/**
* 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表
*
* @param <T> 返回结果列表中每一行数据的类型
* @param sql SQL
* @param params 参数
* @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
*
* @return 查询结果列表
* @throws SQLException SQL 异常
*/
<T> List<T> queryList(String sql, Object[] params, RowMapper<T> rowMapper)
throws SQLException;
@@ -77,9 +89,13 @@ public interface JdbcOperations {
/**
* 执行查询，返回结果映射为指定的类型。当结果为单列时使用
*
* @param <T> 目标类型
* @param sql SQL
* @param params 参数
* @param clazz 将结果映射为指定的类型
* @param clazz 目标类型
*
* @return 映射结果。如果查询结果为空，则返回空列表
* @throws SQLException SQL异常
*/
<T> List<T> queryList(String sql, Object[] params, Class<T> clazz)
throws SQLException;
@@ -89,6 +105,9 @@ public interface JdbcOperations {
*
* @param sql SQL
* @param params 参数列表
*
* @return 结果列表
* @throws SQLException SQL 异常
*/
List<Map<String, Object>> queryList(String sql, Object[] params)
throws SQLException;
@@ -96,8 +115,12 @@ public interface JdbcOperations {
/**
* 执行查询，将查询结果的每一行数据按照指定逻辑进行处理，返回结果列表
*
* @param <T> 目标类型
* @param sql SQL
* @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
*
* @return 结果列表
* @throws SQLException SQL 异常
*/
default <T> List<T> queryList(String sql, RowMapper<T> rowMapper)
throws SQLException {
@@ -107,8 +130,12 @@ public interface JdbcOperations {
/**
* 执行查询，返回结果映射为指定的类型。当结果为单列时使用
*
* @param <T> 目标类型
* @param sql SQL
* @param clazz 将结果映射为指定的类型
*
* @return 查询结果
* @throws SQLException SQL 异常
*/
default <T> List<T> queryList(String sql, Class<T> clazz)
throws SQLException {
@@ -119,6 +146,9 @@ public interface JdbcOperations {
* 执行查询，每一行数据映射为 {@code Map<String, Object>}，返回结果列表
*
* @param sql SQL
*
* @return 结果列表
* @throws SQLException SQL 异常
*/
default List<Map<String, Object>> queryList(String sql)
throws SQLException {
@@ -132,9 +162,13 @@ public interface JdbcOperations {
/**
* 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional}
*
* @param <T> 目标类型
* @param sql SQL
* @param params 参数
* @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
*
* @return 查询结果
* @throws SQLException SQL 异常
*/
<T> Optional<T> queryFirst(String sql, Object[] params, RowMapper<T> rowMapper)
throws SQLException;
@@ -146,15 +180,21 @@ public interface JdbcOperations {
* @param sql SQL
* @param params 参数
* @param clazz 目标类型
*
* @return 查询结果
* @throws SQLException SQL 异常
*/
<T> Optional<T> queryFirst(String sql, Object[] params, Class<T> clazz)
throws SQLException;
/**
* 执行查询，将第一行数据转为 Map<String, Object>
* 执行查询，将第一行数据转为 Map&lt;String, Object&gt;
*
* @param sql SQL
* @param params 参数
*
* @return 查询结果
* @throws SQLException SQL 异常
*/
Optional<Map<String, Object>> queryFirst(String sql, Object[] params)
throws SQLException;
@@ -162,8 +202,12 @@ public interface JdbcOperations {
/**
* 执行查询，将查询结果的第一行数据按照指定逻辑进行处理，返回 {@link Optional}
*
* @param <T> 目标类型
* @param sql SQL
* @param rowMapper {@link ResultSet} 中每一行的数据的处理逻辑
*
* @return 查询结果
* @throws SQLException SQL 异常
*/
default <T> Optional<T> queryFirst(String sql, RowMapper<T> rowMapper)
throws SQLException {
@@ -176,6 +220,9 @@ public interface JdbcOperations {
* @param <T> 目标类型
* @param sql SQL
* @param clazz 目标类型
*
* @return 第一行第一列的值，如果查询结果为空，则返回 {@code Optional#empty()}
* @throws SQLException SQL 异常
*/
default <T> Optional<T> queryFirst(String sql, Class<T> clazz)
throws SQLException {
@@ -183,9 +230,12 @@ public interface JdbcOperations {
}
/**
* 执行查询，将第一行数据转为 Map<String, Object>
* 执行查询，将第一行数据转为 Map&lt;String, Object&gt;
*
* @param sql SQL
*
* @return 查询结果
* @throws SQLException SQL 异常
*/
default Optional<Map<String, Object>> queryFirst(String sql)
throws SQLException {
@@ -195,10 +245,10 @@ public interface JdbcOperations {
/**
* 查询第一行第一列并转换为 boolean
*
* <p>
* <b>注：如果查询结果为空，则返回 {@code false}。</b>
*
* @param sql SQL
*
* @return 查询结果。如果查询结果为空，则返回 {@code false}。
* @throws SQLException SQL 异常
*/
default boolean queryBoolean(String sql)
throws SQLException {
@@ -208,10 +258,12 @@ public interface JdbcOperations {
/**
* 查询第一行第一列并转换为 boolean
*
* <p>
* <b>注：如果查询结果为空，则返回 {@code false}。</b>
*
* @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 <T> 映射结果类型
*
* @return generated keys
* @throws SQLException 执行 SQL 遇到异常情况将抛出
* @throws SQLException 数据库执行异常
*/
<T> List<T> updateAndReturnKeys(String sql, Object[] params, RowMapper<T> rowMapper)
throws SQLException;
@@ -260,8 +317,10 @@ public interface JdbcOperations {
* @param sql 要执行的 SQL
* @param rowMapper 行数据映射逻辑
*
* @param <T> 映射结果类型
*
* @return generated keys
* @throws SQLException 执行 SQL 遇到异常情况将抛出
* @throws SQLException 数据库执行异常
*/
default <T> List<T> updateAndReturnKeys(String sql, RowMapper<T> 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<Object[]> 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<Object[]> params,
int batchSize, boolean quietly)

5
src/main/java/xyz/zhouxy/jdbc/ResultHandler.java
View File

@@ -34,6 +34,11 @@ public interface ResultHandler<T> {
/**
* 将 {@link ResultSet} 转换为指定类型的对象
*
* @param resultSet {@link ResultSet}
* @return 转换后的对象
*
* @throws SQLException 数据库执行异常
*/
T handle(ResultSet resultSet) throws SQLException;
}

21
src/main/java/xyz/zhouxy/jdbc/RowMapper.java
View File

@@ -53,12 +53,29 @@ public interface RowMapper<T> {
return result;
};
/** 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。 */
/**
* 默认实现的将 {@link ResultSet} 转换为 Java Bean 的 {@link RowMapper}。
*
* @param beanType Java Bean 的类型
* @param <T> Java Bean 的类型
*
* @return {@link DefaultBeanRowMapper}
* @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败
*/
static <T> RowMapper<T> beanRowMapper(Class<T> 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 <T> Java Bean 的类型
*
* @return {@link DefaultBeanRowMapper}
* @throws SQLException 如果创建 {@link DefaultBeanRowMapper} 失败
*/
static <T> RowMapper<T> beanRowMapper(Class<T> beanType, Map<String, String> propertyColMap)
throws SQLException {
return DefaultBeanRowMapper.of(beanType, propertyColMap);