补充部分JavaDoc

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

@@ -9,20 +9,79 @@ 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 <R> R execute(@NotNull Function<T, R> function, @Nullable BiConsumer<SQLException, SQLAction<T>> exceptionHandler) {
 		T value = execute(exceptionHandler);
@@ -30,6 +89,12 @@ public interface SQLAction<T> {
 		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();
@@ -42,16 +107,33 @@ public interface SQLAction<T> {
 		return value;
 	}
 
+	/**
+	 * 异步执行SQL语句，采用默认异常处理，无需返回值。
+	 */
 	default void executeAsync() {
 		executeAsync(null);
 	}
 
+	/**
+	 * 异步执行SQL语句
+	 *
+	 * @param success 成功时的操作
+	 */
 	default void executeAsync(@Nullable Consumer<T> success) {
 		executeAsync(success, null);
 	}
 
+	/**
+	 * 异步执行SQL语句
+	 *
+	 * @param success 成功时的操作
+	 * @param failure 异常处理器 默认为 {@link SQLAction#defaultExceptionHandler()}
+	 */
 	void executeAsync(@Nullable Consumer<T> success, @Nullable BiConsumer<SQLException, SQLAction<T>> failure);
 
+	/**
+	 * @return 默认的异常处理器
+	 */
 	default BiConsumer<SQLException, SQLAction<T>> defaultExceptionHandler() {
 		return (exception, action) -> {
 			getManager().getLogger().severe("Error when execute [" + action.getSQLContent() + "]");

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;
@@ -76,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/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-demo/src/main/java/EasySQLDemo.java

@@ -1,5 +1,5 @@
 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.util.TimeDateUtils;
 import cc.carm.lib.easysql.api.util.UUIDUtil;
 

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

@@ -10,6 +10,7 @@ import java.sql.Connection;
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.SQLException;
+import java.util.ArrayList;
 import java.util.List;
 
 public class PreparedSQLUpdateActionImpl extends SQLUpdateActionImpl implements PreparedSQLUpdateAction {
@@ -37,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;

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

@@ -1,7 +1,5 @@
 package cc.carm.lib.easysql.action.query;
 
-import cc.carm.lib.easysql.api.SQLAction;
-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;
@@ -15,7 +13,6 @@ import java.sql.ResultSet;
 import java.sql.SQLException;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 public class PreparedQueryActionImpl extends QueryActionImpl implements PreparedQueryAction {
@@ -39,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());
 		}
 	}

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

@@ -2,7 +2,7 @@ package cc.carm.lib.easysql.action.query;
 
 import cc.carm.lib.easysql.action.AbstractSQLAction;
 import cc.carm.lib.easysql.api.SQLAction;
-import cc.carm.lib.easysql.api.SQLQuery;
+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;

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;

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;