[v0.2.1] 版本更新

1. 补充演示代码与部分关键内容的Javadoc
2. 自动部署包含连接池的版本，方便打包使用。
3. 修改了部分代码的逻辑。

.documentation/JAVADOC-README.md

@@ -0,0 +1,9 @@
+# EasySQL Javadoc
+
+基于 [Github Pages](https://pages.github.com/) 搭建，请访问 [JavaDoc](https://carmjos.github.io/EasySQL) 。
+
+## 如何实现？
+
+若您也想通过 [Github Actions](https://docs.github.com/en/actions/learn-github-actions) 
+自动部署项目的Javadoc到 [Github Pages](https://pages.github.com/) ，
+可以参考我的文章 [《自动部署Javadoc到Github Pages》](https://pages.carm.cc/doc/javadoc-in-github.html) 。

.github/ISSUE_TEMPLATE/bugs_report.md

@@ -12,8 +12,8 @@ assignees: ''
 
 **问题来源**
 描述一下通过哪些操作才发现的问题，如：
-1. 打开 '...'
+1. 使用了 '...'
-2. 点击了 '....'
+2. 输入了 '....'
 3. 出现了报错 '....'
 
 **预期结果**(可选)
@@ -23,8 +23,8 @@ assignees: ''
 如果有报错或输出，请提供截图。
 
 **操作环境**
-请在后台输入 `version` 并复制相关输出。
+- 系统环境: `Windows 10` / `Ubuntu` / `...`
-
+- Java版本: `JDK11` / `OPENJDK8` / `JRE8` / `...`
 
 **其他补充**
 如有其他补充，可以在这里描述。

.github/workflows/javadoc.yml

@@ -24,20 +24,20 @@ jobs:
           distribution: 'adopt'
 
       - name: Generate docs
-        run: mvn javadoc:javadoc
+        run: mvn clean package
 
       - name: Copy to Location
         run: |
           rm -rf docs
           mkdir -vp docs
-          cp -vrf easysql-api/target/site/apidocs/* docs/
+          cp -vrf easysql-api/target/apidocs/* docs/
-          cp -vrf JAVADOC-README.md docs/README.md
+          cp -vrf .documentation/JAVADOC-README.md docs/README.md
 
       - name: Generate the sitemap
         id: sitemap
         uses: cicirello/generate-sitemap@v1
         with:
-          base-url-path: https://carmjos.github.io/userprefix
+          base-url-path: https://carmjos.github.io/EasySQL
           path-to-root: docs
 
       - name: Output stats
@@ -62,7 +62,7 @@ jobs:
         run: |
           cd docs
           git init
-          git remote add origin git@github.com:CarmJos/UserPrefix.git
+          git remote add origin git@github.com:CarmJos/EasySQL.git
           git checkout -b gh-pages
           git add -A
           git commit -m "API Document generated."

README.md

@@ -9,13 +9,13 @@
 
 # EasySQL
 
-[![CodeFactor](https://www.codefactor.io/repository/github/carmjos/easysql/badge)](https://www.codefactor.io/repository/github/carmjos/easysql)
+[![version](https://img.shields.io/github/v/release/CarmJos/EasySQL)](https://github.com/CarmJos/EasySQL/releases)
-![CodeSize](https://img.shields.io/github/languages/code-size/CarmJos/EasySQL)
 [![License](https://img.shields.io/github/license/CarmJos/EasySQL)](https://opensource.org/licenses/GPL-3.0)
 [![workflow](https://github.com/CarmJos/EasySQL/actions/workflows/maven.yml/badge.svg?branch=master)](https://github.com/CarmJos/EasySQL/actions/workflows/maven.yml)
+[![CodeFactor](https://www.codefactor.io/repository/github/carmjos/easysql/badge)](https://www.codefactor.io/repository/github/carmjos/easysql)
+![CodeSize](https://img.shields.io/github/languages/code-size/CarmJos/EasySQL)
 ![](https://visitor-badge.glitch.me/badge?page_id=EasySQL.readme)
 
-
 简单便捷的数据库操作工具，可自定义连接池来源。
 
 随项目分别提供 [BeeCP](https://github.com/Chris2018998/BeeCP) 与 [Hikari](https://github.com/brettwooldridge/HikariCP~~~~)
@@ -30,76 +30,16 @@
     - 创建表
     - 修改表
     - ...
+- 自动关闭数据流
 - 支持同步操作与异步操作
 
 ## 开发
 
-详细开发介绍请 [点击这里](.documentation/INDEX.md) 。
+详细开发介绍请 [点击这里](.documentation/README.md) , JavaDoc(最新Release) 请 [点击这里](https://carmjos.github.io/EasySQL) 。
 
 ### 示例代码
 
-```java
+您可以 [点击这里](easysql-demo/src/main/java/EasySQLDemo.java) 查看部分代码演示，更多演示详见 [开发介绍](.documentation/README.md) 。
-public class EasySQLDemo {
-
-	public void createTable(SQLManager sqlManager) {
-		//异步创建表
-		sqlManager.createTable("users")
-				.addColumn("id", "INT(11) AUTO_INCREMENT NOT NULL PRIMARY KEY")
-				.addColumn("username", "VARCHAR(16) NOT NULL UNIQUE KEY")
-				.addColumn("email", "VARCHAR(32)")
-				.addColumn("phone", "VARCHAR(16)")
-				.addColumn("registerTime", "DATETIME NOT NULL")
-				.build().execute(null /* 不处理错误 */);
-	}
-
-	public void sqlQuery(SQLManager sqlManager) {
-		// 同步SQL查询
-		try (SQLQuery query = sqlManager.createQuery()
-				.inTable("users") // 在users表中查询
-				.addCondition("id", ">", 5) // 限定 id 要大于5
-				.addCondition("email", null) // 限定查询email字段为空
-				.addNotNullCondition("phone") // 限定 phone字段不为空
-				.addTimeCondition(
-						"registerTime", // 时间字段
-						System.currentTimeMillis() - 100000, //限制开始时间
-						-1) //不限制结束时间
-				.build().execute()) {
-			ResultSet resultSet = query.getResultSet();
-			//do something
-
-		} catch (SQLException exception) {
-			exception.printStackTrace();
-		}
-	}
-
-	public void sqlQueryAsync(SQLManager sqlManager) {
-		// 异步SQL查询
-		sqlManager.createQuery()
-				.inTable("users") // 在users表中查询
-				.addCondition("id", 5) // 限定 id 为 5
-				.setLimit(1).build().executeAsync(success -> {
-					ResultSet resultSet = success.getResultSet();
-					//do something
-				}, exception -> {
-					//do something
-				});
-	}
-
-	public void sqlInsert(SQLManager sqlManager) {
-		// 同步SQL插入 （不使用try-catch的情况下，返回的数值可能为空。）
-		Integer id = sqlManager.createInsert("users")
-				.setColumnNames("username", "phone", "email", "registerTime")
-				.setParams("CarmJos", "18888888888", "carm@carm.cc", TimeDateUtils.getCurrentTime())
-				.setKeyIndex(1) // 设定自增主键的index，将会在后续返回自增主键
-				.execute(exception -> {
-					// 处理异常
-				});
-	}
-
-}
-```
-
-更多演示详见开发介绍。
 
 ### 依赖方式 (Maven)
 

easysql-api/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>cc.carm.lib</groupId>
         <artifactId>easysql-parent</artifactId>
-        <version>v0.0.1</version>
+        <version>0.2.1</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLAction.java

@@ -5,54 +5,139 @@ import org.jetbrains.annotations.Nullable;
 
 import java.sql.SQLException;
 import java.util.UUID;
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
+import java.util.function.Function;
 
+/**
+ * SQLAction 是用于承载SQL语句并进行处理、返回的基本类。
+ *
+ * <ul>
+ *     <li>同步执行 {@link #execute()}, {@link #execute(Function, BiConsumer)}</li>
+ *     <br> 同步执行方法中有会抛出异常的方法与不抛出异常的方法，
+ *     <br> 若选择不抛出异常，则返回值可能为空，需要特殊处理。
+ *
+ *     <li>异步执行 {@link #executeAsync(Consumer, BiConsumer)}</li>
+ *     <br> 异步执行时将提供成功与异常两种处理方式
+ *     <br> 可自行选择是否对数据或异常进行处理
+ *     <br> 默认的异常处理器为 {@link #defaultExceptionHandler()}
+ * </ul>
+ *
+ * <b>注意：</b> 无论是否异步，都不需要自行关闭ResultSet，本API已自动关闭
+ *
+ * @param <T> 需要返回的类型
+ * @author CarmJos
+ * @since 0.0.1
+ */
 public interface SQLAction<T> {
 
+	/**
+	 * 得到该Action的UUID
+	 *
+	 * @return UUID
+	 */
 	@NotNull UUID getActionUUID();
 
+	/**
+	 * 得到短八位格式的UUID
+	 *
+	 * @return UUID(8)
+	 */
 	@NotNull String getShortID();
 
+	/**
+	 * 得到该Action的创建时间
+	 *
+	 * @return 创建时间
+	 */
 	long getCreateTime();
 
+	/**
+	 * 得到该Action所要执行的源SQL语句
+	 *
+	 * @return 源SQL语句
+	 */
 	@NotNull String getSQLContent();
 
+	/**
+	 * 得到承载该Action的对应{@link SQLManager}
+	 *
+	 * @return {@link SQLManager}
+	 */
 	@NotNull SQLManager getManager();
 
+	/**
+	 * 执行该Action对应的SQL语句
+	 *
+	 * @return 指定数据类型
+	 * @throws SQLException 当SQL操作出现问题时抛出
+	 */
 	@NotNull T execute() throws SQLException;
 
+	/**
+	 * 执行语句并处理返回值
+	 *
+	 * @param function         处理方法
+	 * @param exceptionHandler 异常处理器 默认为 {@link #defaultExceptionHandler()}
+	 * @param <R>              需要返回的内容
+	 * @return 指定类型数据
+	 */
 	@Nullable
-	default T execute(@Nullable Consumer<SQLException> exceptionHandler) {
+	default <R> R execute(@NotNull Function<T, R> function, @Nullable BiConsumer<SQLException, SQLAction<T>> exceptionHandler) {
+		T value = execute(exceptionHandler);
+		if (value == null) return null;
+		else return function.apply(value);
+	}
+
+	/**
+	 * 执行语句并返回值
+	 *
+	 * @param exceptionHandler 异常处理器 默认为 {@link #defaultExceptionHandler()}
+	 * @return 指定类型数据
+	 */
+	@Nullable
+	default T execute(@Nullable BiConsumer<SQLException, SQLAction<T>> exceptionHandler) {
 		if (exceptionHandler == null) exceptionHandler = defaultExceptionHandler();
 		T value = null;
 		try {
 			value = execute();
 		} catch (SQLException exception) {
-			exceptionHandler.accept(exception);
+			exceptionHandler.accept(exception, this);
 		}
 		return value;
 	}
 
+	/**
+	 * 异步执行SQL语句，采用默认异常处理，无需返回值。
+	 */
 	default void executeAsync() {
 		executeAsync(null);
 	}
 
-	default void executeAsync(Consumer<T> success) {
+	/**
+	 * 异步执行SQL语句
+	 *
+	 * @param success 成功时的操作
+	 */
+	default void executeAsync(@Nullable Consumer<T> success) {
 		executeAsync(success, null);
 	}
 
-	void executeAsync(Consumer<T> success, Consumer<SQLException> failure);
+	/**
+	 * 异步执行SQL语句
+	 *
+	 * @param success 成功时的操作
+	 * @param failure 异常处理器 默认为 {@link SQLAction#defaultExceptionHandler()}
+	 */
+	void executeAsync(@Nullable Consumer<T> success, @Nullable BiConsumer<SQLException, SQLAction<T>> failure);
 
-	SQLAction<T> handleException(Consumer<SQLException> failure);
+	/**
-
+	 * @return 默认的异常处理器
-	@NotNull Consumer<SQLException> getExceptionHandler();
+	 */
-
+	default BiConsumer<SQLException, SQLAction<T>> defaultExceptionHandler() {
-	default Consumer<SQLException> defaultExceptionHandler() {
+		return (exception, action) -> {
-		return Throwable::printStackTrace;
+			getManager().getLogger().severe("Error when execute [" + action.getSQLContent() + "]");
-	}
+			getManager().getLogger().severe(exception.getLocalizedMessage());
-
-	default Consumer<T> defaultResultHandler() {
-		return t -> {
 		};
 	}
 

easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLBuilder.java

@@ -2,8 +2,20 @@ package cc.carm.lib.easysql.api;
 
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * SQLBuilder 是用于构建SQL语句以生成SQLAction执行操作的中间类。
+ * <br> 其连接了{@link SQLManager} 与 {@link SQLAction} ,避免大量的代码堆积
+ * <br> 也是本接口的核心功能所在
+ *
+ * @author CarmJos
+ */
 public interface SQLBuilder {
 
+	/**
+	 * 得到承载该Builder的对应{@link SQLManager}
+	 *
+	 * @return {@link SQLManager}
+	 */
 	@NotNull SQLManager getManager();
 
 }

easysql-api/src/main/java/cc/carm/lib/easysql/api/SQLManager.java

@@ -2,6 +2,7 @@ package cc.carm.lib.easysql.api;
 
 import cc.carm.lib.easysql.api.action.PreparedSQLUpdateAction;
 import cc.carm.lib.easysql.api.action.PreparedSQLUpdateBatchAction;
+import cc.carm.lib.easysql.api.action.query.SQLQuery;
 import cc.carm.lib.easysql.api.builder.*;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -12,9 +13,12 @@ import java.sql.SQLException;
 import java.util.List;
 import java.util.Map;
 import java.util.UUID;
+import java.util.logging.Logger;
 
 public interface SQLManager {
 
+	Logger getLogger();
+
 	boolean isDebugMode();
 
 	void setDebugMode(boolean enable);
@@ -73,6 +77,12 @@ public interface SQLManager {
 	 */
 	@Nullable List<Integer> executeSQLBatch(@NotNull String sql, String... moreSQL);
 
+	/**
+	 * 执行多条不需要返回结果的SQL。
+	 *
+	 * @param sqlBatch SQL语句内容
+	 * @return 对应参数返回的行数
+	 */
 	@Nullable List<Integer> executeSQLBatch(@NotNull Iterable<String> sqlBatch);
 
 	TableCreateBuilder createTable(@NotNull String tableName);

easysql-api/src/main/java/cc/carm/lib/easysql/api/action/PreparedSQLUpdateAction.java

@@ -1,7 +1,23 @@
 package cc.carm.lib.easysql.api.action;
 
+import org.jetbrains.annotations.Nullable;
+
 public interface PreparedSQLUpdateAction extends SQLUpdateAction {
 
+	/**
+	 * 设定SQL语句中所有 ? 对应的参数
+	 *
+	 * @param params 参数内容
+	 * @return {@link PreparedSQLUpdateAction}
+	 */
 	PreparedSQLUpdateAction setParams(Object... params);
 
+	/**
+	 * 设定SQL语句中所有 ? 对应的参数
+	 *
+	 * @param params 参数内容
+	 * @return {@link PreparedSQLUpdateAction}
+	 */
+	PreparedSQLUpdateAction setParams(@Nullable Iterable<Object> params);
+
 }

easysql-api/src/main/java/cc/carm/lib/easysql/api/action/PreparedSQLUpdateBatchAction.java

@@ -6,12 +6,37 @@ import java.util.List;
 
 public interface PreparedSQLUpdateBatchAction extends SQLAction<List<Integer>> {
 
+	/**
+	 * 设定多组SQL语句中所有 ? 对应的参数
+	 *
+	 * @param allParams 所有参数内容
+	 * @return {@link PreparedSQLUpdateBatchAction}
+	 */
 	PreparedSQLUpdateBatchAction setAllParams(Iterable<Object[]> allParams);
 
+	/**
+	 * 添加一组SQL语句中所有 ? 对应的参数
+	 *
+	 * @param params 参数内容
+	 * @return {@link PreparedSQLUpdateBatchAction}
+	 */
 	PreparedSQLUpdateBatchAction addParamsBatch(Object... params);
 
+	/**
+	 * 设定自增主键的序列
+	 *
+	 * @param keyColumnIndex 自增主键的序列
+	 *                       若该值 > 0，则 {@link #execute()} 返回自增主键数值
+	 *                       若该值 ≤ 0，则 {@link #execute()} 返回变更的行数
+	 * @return {@link PreparedSQLUpdateBatchAction}
+	 */
 	PreparedSQLUpdateBatchAction setKeyIndex(int keyColumnIndex);
 
+	/**
+	 * 默认主键序列的数值为 -1 (≤0) ，即默认返回发生变更的行数。
+	 *
+	 * @return 默认主键序列
+	 */
 	default PreparedSQLUpdateBatchAction defaultKeyIndex() {
 		return setKeyIndex(-1); // will return changed lines number
 	}

easysql-api/src/main/java/cc/carm/lib/easysql/api/action/SQLUpdateAction.java

@@ -4,8 +4,21 @@ import cc.carm.lib.easysql.api.SQLAction;
 
 public interface SQLUpdateAction extends SQLAction<Integer> {
 
+	/**
+	 * 设定自增主键的序列
+	 *
+	 * @param keyColumnIndex 自增主键的序列
+	 *                       若该值 > 0，则 {@link #execute()} 返回自增主键数值
+	 *                       若该值 ≤ 0，则 {@link #execute()} 返回变更的行数
+	 * @return {@link SQLUpdateAction}
+	 */
 	SQLUpdateAction setKeyIndex(int keyColumnIndex);
 
+	/**
+	 * 默认主键序列的数值为 -1 (≤0) ，即默认返回发生变更的行数。
+	 *
+	 * @return 默认主键序列
+	 */
 	default SQLUpdateAction defaultKeyIndex() {
 		return setKeyIndex(-1); // will return changed lines number
 	}

easysql-api/src/main/java/cc/carm/lib/easysql/api/action/SQLUpdateBatchAction.java

@@ -7,6 +7,12 @@ import java.util.List;
 
 public interface SQLUpdateBatchAction extends SQLAction<List<Integer>> {
 
+	/**
+	 * 添加一条批量执行的SQL语句
+	 *
+	 * @param sql SQL语句
+	 * @return {@link SQLUpdateBatchAction}
+	 */
 	SQLUpdateBatchAction addBatch(@NotNull String sql);
 
 }

easysql-api/src/main/java/cc/carm/lib/easysql/api/action/query/PreparedQueryAction.java

@@ -7,10 +7,29 @@ import java.util.function.Consumer;
 
 public interface PreparedQueryAction extends QueryAction {
 
+	/**
+	 * 设定SQL语句中所有 ? 对应的参数
+	 *
+	 * @param params 参数内容
+	 * @return {@link PreparedQueryAction}
+	 */
 	PreparedQueryAction setParams(@Nullable Object... params);
 
+	/**
+	 * 设定SQL语句中所有 ? 对应的参数
+	 *
+	 * @param params 参数内容
+	 * @return {@link PreparedQueryAction}
+	 */
 	PreparedQueryAction setParams(@Nullable Iterable<Object> params);
 
+	/**
+	 * 直接对 {@link PreparedStatement} 进行处理
+	 *
+	 * @param statement {@link Consumer} 处理操作
+	 *                  若为空则不进行处理
+	 * @return {@link PreparedQueryAction}
+	 */
 	PreparedQueryAction handleStatement(@Nullable Consumer<PreparedStatement> statement);
 
 }

easysql-api/src/main/java/cc/carm/lib/easysql/api/action/query/QueryAction.java

@@ -1,7 +1,6 @@
 package cc.carm.lib.easysql.api.action.query;
 
 import cc.carm.lib.easysql.api.SQLAction;
-import cc.carm.lib.easysql.api.SQLQuery;
 
 public interface QueryAction extends SQLAction<SQLQuery> {
 

easysql-api/src/main/java/cc/carm/lib/easysql/api/action/query/SQLQuery.java

@@ -1,6 +1,6 @@
-package cc.carm.lib.easysql.api;
+package cc.carm.lib.easysql.api.action.query;
 
-import cc.carm.lib.easysql.api.action.query.QueryAction;
+import cc.carm.lib.easysql.api.SQLManager;
 
 import java.sql.Connection;
 import java.sql.ResultSet;
@@ -15,8 +15,18 @@ public interface SQLQuery extends AutoCloseable {
 	 */
 	long getExecuteTime();
 
+	/**
+	 * 得到承载该SQLQuery的对应{@link SQLManager}
+	 *
+	 * @return {@link SQLManager}
+	 */
 	SQLManager getManager();
 
+	/**
+	 * 得到承载该SQLQuery的对应{@link QueryAction}
+	 *
+	 * @return {@link QueryAction} 或 {@link PreparedQueryAction}
+	 */
 	QueryAction getAction();
 
 	ResultSet getResultSet();

easysql-api/src/main/java/cc/carm/lib/easysql/api/builder/QueryBuilder.java

@@ -7,10 +7,30 @@ import org.jetbrains.annotations.NotNull;
 
 public interface QueryBuilder extends SQLBuilder {
 
+	/**
+	 * 通过一条 SQL语句创建查询
+	 *
+	 * @param sql SQL语句
+	 * @return {@link QueryAction}
+	 * @deprecated 存在SQL注入风险，请使用 {@link QueryBuilder#withPreparedSQL(String)}
+	 */
+	@Deprecated
 	QueryAction withSQL(@NotNull String sql);
 
+	/**
+	 * 通过一条 SQL语句创建预查询
+	 *
+	 * @param sql SQL语句
+	 * @return {@link PreparedQueryAction}
+	 */
 	PreparedQueryAction withPreparedSQL(@NotNull String sql);
 
+	/**
+	 * 创建表查询
+	 *
+	 * @param tableName 表名
+	 * @return {@link TableQueryBuilder}
+	 */
 	TableQueryBuilder inTable(@NotNull String tableName);
 
 }

easysql-api/src/main/java/cc/carm/lib/easysql/api/builder/UpsertBuilder.java

@@ -0,0 +1,4 @@
+package cc.carm.lib.easysql.api.builder;
+
+public interface UpsertBuilder {
+}

easysql-api/src/main/java/cc/carm/lib/easysql/api/enums/ReturnedType.java

@@ -1,9 +0,0 @@
-package cc.carm.lib.easysql.api.enums;
-
-public enum ReturnedType {
-
-	AUTO_INCREASE_KEY,
-
-	CHANGED_LINES
-
-}

easysql-api/src/main/java/cc/carm/lib/easysql/api/util/TimeDateUtils.java

@@ -11,19 +11,42 @@ public class TimeDateUtils {
 	public TimeDateUtils() {
 	}
 
+	/**
+	 * 得到当前时间文本。
+	 *
+	 * @return 时间文本 格式{@link TimeDateUtils#getFormat()}
+	 */
 	public static String getCurrentTime() {
-		return getFormat().format(new Date());
+		return getTimeString(System.currentTimeMillis());
 	}
 
+	/**
+	 * 得到一个时间戳的文本
+	 *
+	 * @param timeMillis 时间戳
+	 * @return 时间文本 格式{@link TimeDateUtils#getFormat()}
+	 */
 	public static String getTimeString(long timeMillis) {
 		return getFormat().format(new Date(timeMillis));
 	}
 
+	/**
+	 * 得到一个日期时间的文本
+	 *
+	 * @param time 日期时间
+	 * @return 时间文本 格式{@link TimeDateUtils#getFormat()}
+	 */
 	public static String getTimeString(Date time) {
 		return getFormat().format(time);
 	}
 
-	public static long getTimeMillis(String timeString) {
+	/**
+	 * 得到一个时间文本的时间戳
+	 *
+	 * @param timeString 时间文本
+	 * @return 时间戳 格式{@link TimeDateUtils#getFormat()}
+	 */
+	public static long parseTimeMillis(String timeString) {
 		if (timeString == null) {
 			return -1L;
 		} else {
@@ -35,6 +58,13 @@ public class TimeDateUtils {
 		}
 	}
 
+
+	/**
+	 * 得到一个时间文本的对应日期实例
+	 *
+	 * @param timeString 时间文本
+	 * @return 日期实例 格式{@link TimeDateUtils#getFormat()}
+	 */
 	public static Date getTimeDate(String timeString) {
 		if (timeString == null) {
 			return null;
@@ -47,6 +77,12 @@ public class TimeDateUtils {
 		}
 	}
 
+	/**
+	 * 将秒数转化为 DD:hh:mm:ss 格式
+	 *
+	 * @param allSeconds 秒数
+	 * @return DD:hh:mm:ss格式文本
+	 */
 	public static String toDHMSStyle(long allSeconds) {
 		long days = allSeconds / 86400L;
 		long hours = allSeconds % 86400L / 3600L;

easysql-beecp/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easysql-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>v0.0.1</version>
+        <version>0.2.1</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 
@@ -50,6 +50,7 @@
         <maven.compiler.target>8</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
+        <maven.javadoc.skip>true</maven.javadoc.skip>
     </properties>
 
     <dependencies>

easysql-demo/pom.xml

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>easysql-parent</artifactId>
+        <groupId>cc.carm.lib</groupId>
+        <version>0.2.1</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>easysql-demo</artifactId>
+    <packaging>jar</packaging>
+
+    <name>99-EasySQL-Demo</name>
+    <description>EasySQL的演示部分</description>
+    <url>https://github.com/CarmJos/EasySQL</url>
+
+    <developers>
+        <developer>
+            <id>CarmJos</id>
+            <name>Carm Jos</name>
+            <email>carm@carm.cc</email>
+            <url>https://www.carm.cc</url>
+            <roles>
+                <role>Main Developer</role>
+            </roles>
+        </developer>
+    </developers>
+
+    <licenses>
+        <license>
+            <name>GNU General Public License v3.0</name>
+            <url>https://opensource.org/licenses/GPL-3.0</url>
+        </license>
+    </licenses>
+
+    <issueManagement>
+        <system>GitHub Issues</system>
+        <url>${project.url}/issues</url>
+    </issueManagement>
+
+    <ciManagement>
+        <system>GitHub Actions</system>
+        <url>${project.url}/actions/workflows/maven.yml</url>
+    </ciManagement>
+
+    <properties>
+        <maven.compiler.source>8</maven.compiler.source>
+        <maven.compiler.target>8</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
+        <maven.javadoc.skip>true</maven.javadoc.skip>
+        <maven.deploy.skip>true</maven.deploy.skip>
+    </properties>
+
+    <dependencies>
+
+        <dependency>
+            <groupId>${project.parent.groupId}</groupId>
+            <artifactId>easysql-impl</artifactId>
+            <version>${project.parent.version}</version>
+            <scope>compile</scope>
+        </dependency>
+
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>

easysql-demo/src/main/java/EasySQLDemo.java

@@ -0,0 +1,113 @@
+import cc.carm.lib.easysql.api.SQLManager;
+import cc.carm.lib.easysql.api.action.query.SQLQuery;
+import cc.carm.lib.easysql.api.util.TimeDateUtils;
+import cc.carm.lib.easysql.api.util.UUIDUtil;
+
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.util.UUID;
+
+public class EasySQLDemo {
+
+	public void createTable(SQLManager sqlManager) {
+		// 同步创建表
+		sqlManager.createTable("users")
+				.addColumn("id", "INT(11) AUTO_INCREMENT NOT NULL PRIMARY KEY")
+				.addColumn("uuid", "VARCHAR(32) NOT NULL UNIQUE KEY")
+				.addColumn("username", "VARCHAR(16) NOT NULL UNIQUE KEY")
+				.addColumn("age", "INT(3) NOT NULL DEFAULT 1")
+				.addColumn("email", "VARCHAR(32)")
+				.addColumn("phone", "VARCHAR(16)")
+				.addColumn("registerTime", "DATETIME NOT NULL")
+				.build().execute(null /* 不处理错误 */);
+	}
+
+	public void sqlQuery(SQLManager sqlManager) {
+		// 同步SQL查询
+		try (SQLQuery query = sqlManager.createQuery()
+				.inTable("users") // 在users表中查询
+				.selectColumns("id", "name") // 选中 id 与 name列
+				.addCondition("age", ">", 18) // 限定 age 要大于5
+				.addCondition("email", null) // 限定查询 email 字段为空
+				.addNotNullCondition("phone") // 限定 phone 字段不为空
+				.addTimeCondition("registerTime", // 时间字段
+						System.currentTimeMillis() - 100000, //限制开始时间
+						-1//不限制结束时间
+				).build().execute()) {
+			ResultSet resultSet = query.getResultSet();
+			//do something
+
+		} catch (SQLException exception) {
+			exception.printStackTrace();
+		}
+
+		UUID userUUID = sqlManager.createQuery()
+				.inTable("users") // 在users表中查询
+				.selectColumns("uuid")
+				.addCondition("id", 5) // 限定 id 为 5
+				.setLimit(1) // 只取出一个数据
+				.build().execute(query -> {
+					//可以直接进行数据处理
+					ResultSet result = query.getResultSet();
+					try {
+						if (result != null && result.next()) {
+							return UUIDUtil.toUUID(result.getString("uuid"));
+						}
+					} catch (SQLException ignored) {
+					}
+					return null;
+				}, (exception, action) -> {
+					// 处理异常，不想处理直接填null
+				});
+	}
+
+	public void sqlQueryAsync(SQLManager sqlManager) {
+		// 异步SQL查询
+		sqlManager.createQuery()
+				.inTable("users") // 在users表中查询
+				.addCondition("id", 5) // 限定 id 为 5
+				.setLimit(1) // 只取出一个数据
+				.build().executeAsync(success -> {
+					ResultSet resultSet = success.getResultSet();
+					try {
+						if (resultSet != null && resultSet.next()) {
+							String username = resultSet.getString("username");
+						}
+					} catch (SQLException e) {
+						e.printStackTrace();
+					}
+				}, (exception, action) -> {
+					//do something
+					long createTIme = action.getCreateTime();
+					String shortID = action.getShortID();
+					String sqlContent = action.getSQLContent();
+				});
+	}
+
+	public void sqlInsert(SQLManager sqlManager) {
+		// 同步SQL插入 （不使用try-catch的情况下，返回的数值可能为空。）
+		Integer id = sqlManager.createInsert("users")
+				.setColumnNames("username", "phone", "email", "registerTime")
+				.setParams("CarmJos", "18888888888", "carm@carm.cc", TimeDateUtils.getCurrentTime())
+				.setKeyIndex(1) // 设定自增主键的index，将会在后续返回自增主键
+				.execute((exception, action) -> {
+					// 处理异常
+					System.out.println("#" + action.getShortID() + " -> " + action.getSQLContent());
+					exception.printStackTrace();
+				});
+
+		try {
+			Integer userID = sqlManager.createInsert("users")
+					.setColumnNames("username", "phone", "email", "registerTime")
+					.setParams("CarmJos", "18888888888", "carm@carm.cc", TimeDateUtils.getCurrentTime())
+					.setKeyIndex(1) // 设定自增主键的index，将会在后续返回自增主键
+					.execute();
+
+			System.out.println("新用户的ID为 " + userID);
+
+		} catch (SQLException exception) {
+			exception.printStackTrace();
+		}
+	}
+
+}

easysql-hikaricp/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easysql-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>v0.0.1</version>
+        <version>0.2.1</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 
@@ -49,6 +49,7 @@
         <maven.compiler.target>8</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
+        <maven.javadoc.skip>true</maven.javadoc.skip>
     </properties>
 
     <dependencies>

easysql-impl/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>easysql-parent</artifactId>
         <groupId>cc.carm.lib</groupId>
-        <version>v0.0.1</version>
+        <version>0.2.1</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 
@@ -50,6 +50,7 @@
         <maven.compiler.target>8</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
+        <maven.javadoc.skip>true</maven.javadoc.skip>
     </properties>
 
     <dependencies>

easysql-impl/src/main/java/cc/carm/lib/easysql/action/AbstractSQLAction.java

@@ -3,9 +3,11 @@ package cc.carm.lib.easysql.action;
 import cc.carm.lib.easysql.api.SQLAction;
 import cc.carm.lib.easysql.manager.SQLManagerImpl;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.sql.SQLException;
 import java.util.UUID;
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 public abstract class AbstractSQLAction<T> implements SQLAction<T> {
@@ -17,7 +19,7 @@ public abstract class AbstractSQLAction<T> implements SQLAction<T> {
 
 	protected @NotNull String sqlContent;
 
-	protected @NotNull Consumer<SQLException> exceptionHandler = defaultExceptionHandler();
+	protected @Nullable BiConsumer<SQLException, SQLAction<T>> exceptionHandler = null;
 
 	public AbstractSQLAction(@NotNull SQLManagerImpl manager, @NotNull String sql) {
 		this(manager, sql, System.currentTimeMillis());
@@ -69,14 +71,25 @@ public abstract class AbstractSQLAction<T> implements SQLAction<T> {
 		getManager().debug("#" + getShortID() + " ->" + getSQLContent());
 	}
 
-	@Override
+	public void handleException(SQLException exception) {
-	public SQLAction<T> handleException(Consumer<SQLException> handler) {
+		if (this.exceptionHandler == null) {
-		this.exceptionHandler = handler;
+			defaultExceptionHandler().accept(exception, this);
-		return this;
+		} else {
+			this.exceptionHandler.accept(exception, this);
+		}
 	}
 
-	@NotNull
+	@Override
-	public Consumer<SQLException> getExceptionHandler() {
+	public void executeAsync(Consumer<T> success, BiConsumer<SQLException, SQLAction<T>> failure) {
-		return exceptionHandler;
+		getManager().getExecutorPool().submit(() -> {
+			try {
+				T returnedValue = execute();
+				if (success != null) success.accept(returnedValue);
+			} catch (SQLException e) {
+				(failure == null ? defaultExceptionHandler() : failure).accept(e, this);
+			}
+		});
 	}
+
+
 }

easysql-impl/src/main/java/cc/carm/lib/easysql/action/PreparedSQLBatchUpdateActionImpl.java

@@ -72,8 +72,4 @@ public class PreparedSQLBatchUpdateActionImpl extends SQLUpdateBatchActionImpl i
 		return returnedValues;
 	}
 
-	@Override
-	public void executeAsync(Consumer<List<Integer>> success, Consumer<SQLException> failure) {
-
-	}
 }

easysql-impl/src/main/java/cc/carm/lib/easysql/action/PreparedSQLUpdateActionImpl.java

@@ -10,8 +10,8 @@ import java.sql.Connection;
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.SQLException;
+import java.util.ArrayList;
 import java.util.List;
-import java.util.function.Consumer;
 
 public class PreparedSQLUpdateActionImpl extends SQLUpdateActionImpl implements PreparedSQLUpdateAction {
 
@@ -38,6 +38,17 @@ public class PreparedSQLUpdateActionImpl extends SQLUpdateActionImpl implements
 		return this;
 	}
 
+	@Override
+	public PreparedSQLUpdateAction setParams(@Nullable Iterable<Object> params) {
+		if (params == null) {
+			return setParams((Object[]) null);
+		} else {
+			List<Object> paramsList = new ArrayList<>();
+			params.forEach(paramsList::add);
+			return setParams(paramsList.toArray());
+		}
+	}
+
 	@Override
 	public @NotNull Integer execute() throws SQLException {
 		int value = -1;
@@ -63,9 +74,4 @@ public class PreparedSQLUpdateActionImpl extends SQLUpdateActionImpl implements
 		return value;
 	}
 
-	@Override
-	public void executeAsync(Consumer<Integer> success, Consumer<SQLException> failure) {
-
-	}
-
 }

easysql-impl/src/main/java/cc/carm/lib/easysql/action/SQLUpdateActionImpl.java

@@ -43,10 +43,6 @@ public class SQLUpdateActionImpl extends AbstractSQLAction<Integer> implements S
 		return returnedValue;
 	}
 
-	@Override
-	public void executeAsync(Consumer<Integer> success, Consumer<SQLException> failure) {
-
-	}
 
 	@Override
 	public SQLUpdateActionImpl setKeyIndex(int keyIndex) {

easysql-impl/src/main/java/cc/carm/lib/easysql/action/SQLUpdateBatchActionImpl.java

@@ -10,7 +10,6 @@ import java.sql.Statement;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
-import java.util.function.Consumer;
 import java.util.stream.Collectors;
 
 public class SQLUpdateBatchActionImpl extends AbstractSQLAction<List<Integer>> implements SQLUpdateBatchAction {
@@ -52,10 +51,4 @@ public class SQLUpdateBatchActionImpl extends AbstractSQLAction<List<Integer>> i
 		return returnedValues;
 	}
 
-	@Override
-	public void executeAsync(Consumer<List<Integer>> success, Consumer<SQLException> failure) {
-
-	}
-
-
 }

easysql-impl/src/main/java/cc/carm/lib/easysql/action/query/PreparedQueryActionImpl.java

@@ -1,6 +1,5 @@
 package cc.carm.lib.easysql.action.query;
 
-import cc.carm.lib.easysql.api.SQLQuery;
 import cc.carm.lib.easysql.api.action.query.PreparedQueryAction;
 import cc.carm.lib.easysql.manager.SQLManagerImpl;
 import cc.carm.lib.easysql.query.SQLQueryImpl;
@@ -37,9 +36,7 @@ public class PreparedQueryActionImpl extends QueryActionImpl implements Prepared
 			return setParams((Object[]) null);
 		} else {
 			List<Object> paramsList = new ArrayList<>();
-			for (Object param : params) {
+			params.forEach(paramsList::add);
-				paramsList.add(param);
-			}
 			return setParams(paramsList.toArray());
 		}
 	}
@@ -67,10 +64,4 @@ public class PreparedQueryActionImpl extends QueryActionImpl implements Prepared
 
 		return new SQLQueryImpl(getManager(), this, connection, preparedStatement, resultSet);
 	}
-
-	@Override
-	public void executeAsync(Consumer<SQLQuery> success, Consumer<SQLException> failure) {
-
-	}
-
 }

easysql-impl/src/main/java/cc/carm/lib/easysql/action/query/QueryActionImpl.java

@@ -1,7 +1,8 @@
 package cc.carm.lib.easysql.action.query;
 
 import cc.carm.lib.easysql.action.AbstractSQLAction;
-import cc.carm.lib.easysql.api.SQLQuery;
+import cc.carm.lib.easysql.api.SQLAction;
+import cc.carm.lib.easysql.api.action.query.SQLQuery;
 import cc.carm.lib.easysql.api.action.query.QueryAction;
 import cc.carm.lib.easysql.manager.SQLManagerImpl;
 import cc.carm.lib.easysql.query.SQLQueryImpl;
@@ -11,6 +12,7 @@ import java.sql.Connection;
 import java.sql.ResultSet;
 import java.sql.SQLException;
 import java.sql.Statement;
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 public class QueryActionImpl extends AbstractSQLAction<SQLQuery> implements QueryAction {
@@ -20,7 +22,7 @@ public class QueryActionImpl extends AbstractSQLAction<SQLQuery> implements Quer
 	}
 
 	@Override
-	public @NotNull SQLQuery execute() throws SQLException {
+	public @NotNull SQLQueryImpl execute() throws SQLException {
 		Connection connection = getManager().getConnection();
 		Statement statement = connection.createStatement();
 
@@ -33,8 +35,13 @@ public class QueryActionImpl extends AbstractSQLAction<SQLQuery> implements Quer
 		return query;
 	}
 
-	@Override
-	public void executeAsync(Consumer<SQLQuery> success, Consumer<SQLException> failure) {
 
+	@Override
+	public void executeAsync(Consumer<SQLQuery> success, BiConsumer<SQLException, SQLAction<SQLQuery>> failure) {
+		try (SQLQueryImpl query = execute()) {
+			if (success != null) success.accept(query);
+		} catch (SQLException exception) {
+			(exceptionHandler == null ? defaultExceptionHandler() : exceptionHandler).accept(exception, this);
+		}
 	}
 }

easysql-impl/src/main/java/cc/carm/lib/easysql/builder/impl/QueryBuilderImpl.java

@@ -16,6 +16,7 @@ public class QueryBuilderImpl extends AbstractSQLBuilder implements QueryBuilder
 	}
 
 	@Override
+	@Deprecated
 	public QueryAction withSQL(@NotNull String sql) {
 		return new QueryActionImpl(getManager(), sql);
 	}

easysql-impl/src/main/java/cc/carm/lib/easysql/manager/SQLManagerImpl.java

@@ -5,7 +5,7 @@ import cc.carm.lib.easysql.action.PreparedSQLUpdateActionImpl;
 import cc.carm.lib.easysql.action.SQLUpdateActionImpl;
 import cc.carm.lib.easysql.action.SQLUpdateBatchActionImpl;
 import cc.carm.lib.easysql.api.SQLManager;
-import cc.carm.lib.easysql.api.SQLQuery;
+import cc.carm.lib.easysql.api.action.query.SQLQuery;
 import cc.carm.lib.easysql.api.action.PreparedSQLUpdateAction;
 import cc.carm.lib.easysql.api.action.PreparedSQLUpdateBatchAction;
 import cc.carm.lib.easysql.api.action.SQLUpdateBatchAction;
@@ -19,6 +19,8 @@ import java.sql.Connection;
 import java.sql.SQLException;
 import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
 import java.util.logging.Logger;
 
 public class SQLManagerImpl implements SQLManager {
@@ -29,13 +31,21 @@ public class SQLManagerImpl implements SQLManager {
 
 	boolean debug = false;
 
+	protected ExecutorService executorPool;
+
 	public SQLManagerImpl(@NotNull DataSource dataSource) {
 		this(dataSource, null);
 	}
 
 	public SQLManagerImpl(@NotNull DataSource dataSource, @Nullable String name) {
-		this.LOGGER = Logger.getLogger("SQLManager" + (name != null ? "#" + name : ""));
+		String managerName = "SQLManager" + (name != null ? "#" + name : "");
+		this.LOGGER = Logger.getLogger(managerName);
 		this.dataSource = dataSource;
+		this.executorPool = Executors.newFixedThreadPool(3, r -> {
+			Thread thread = new Thread(r, managerName);
+			thread.setDaemon(true);
+			return thread;
+		});
 	}
 
 	@Override
@@ -56,6 +66,9 @@ public class SQLManagerImpl implements SQLManager {
 		return LOGGER;
 	}
 
+	public ExecutorService getExecutorPool() {
+		return executorPool;
+	}
 
 	@Override
 	public @NotNull DataSource getDataSource() {

easysql-impl/src/main/java/cc/carm/lib/easysql/query/SQLQueryImpl.java

@@ -1,7 +1,7 @@
 package cc.carm.lib.easysql.query;
 
 import cc.carm.lib.easysql.action.query.QueryActionImpl;
-import cc.carm.lib.easysql.api.SQLQuery;
+import cc.carm.lib.easysql.api.action.query.SQLQuery;
 import cc.carm.lib.easysql.manager.SQLManagerImpl;
 
 import java.sql.Connection;
@@ -70,7 +70,7 @@ public class SQLQueryImpl implements SQLQuery {
 			);
 			getManager().getActiveQuery().remove(getAction().getActionUUID());
 		} catch (SQLException e) {
-			getAction().getExceptionHandler().accept(e);
+			getAction().handleException(e);
 		}
 		this.queryAction = null;
 	}

easysql-impl/src/main/java/cc/carm/lib/easysql/util/StatementUtil.java

@@ -1,5 +1,7 @@
 package cc.carm.lib.easysql.util;
 
+import cc.carm.lib.easysql.api.SQLAction;
+
 import java.math.BigDecimal;
 import java.math.BigInteger;
 import java.sql.*;

pom.xml

@@ -7,7 +7,7 @@
     <groupId>cc.carm.lib</groupId>
     <artifactId>easysql-parent</artifactId>
     <packaging>pom</packaging>
-    <version>v0.0.1</version>
+    <version>0.2.1</version>
 
     <modules>
         <module>easysql-api</module>
@@ -15,6 +15,7 @@
 
         <module>easysql-beecp</module>
         <module>easysql-hikaricp</module>
+        <module>easysql-demo</module>
 
     </modules>
 
@@ -40,7 +41,7 @@
             <url>https://opensource.org/licenses/GPL-3.0</url>
         </license>
     </licenses>
-    
+
     <issueManagement>
         <system>GitHub Issues</system>
         <url>${project.url}/issues</url>
@@ -79,7 +80,7 @@
         <repository>
             <id>github</id>
             <name>GitHub Packages</name>
-            <url>https://maven.pkg.github.com/CarmJos/${project.name}</url>
+            <url>https://maven.pkg.github.com/CarmJos/EasySQL</url>
         </repository>
 
     </repositories>
@@ -91,7 +92,7 @@
         <repository>
             <id>github</id>
             <name>GitHub Packages</name>
-            <url>https://maven.pkg.github.com/CarmJos/${project.name}</url>
+            <url>https://maven.pkg.github.com/CarmJos/EasySQL</url>
         </repository>
 
     </distributionManagement>