1.1.4

src/main/java/com/igeeksky/xtool/core/AsyncCloseable.java

@@ -1,21 +1,32 @@
 package com.igeeksky.xtool.core;
 
 import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutionException;
 
 /**
  * 异步关闭接口
- * <p>
- * IO 操作类对象建议实现此接口。
  *
  * @author Patrick.Lau
  * @since 1.1.3
  */
-public interface AsyncCloseable {
+public interface AsyncCloseable extends AutoCloseable {
+
+    @Override
+    default void close() {
+        try {
+            closeAsync().get();
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new RuntimeException(e);
+        } catch (ExecutionException e) {
+            throw new RuntimeException(e);
+        }
+    }
 
     /**
      * 异步关闭
      *
-     * @return 异步关闭
+     * @return {@code CompletableFuture<Void>} – 关闭结果（可能的异常信息）
      */
     CompletableFuture<Void> closeAsync();
 

src/main/java/com/igeeksky/xtool/core/GracefulShutdown.java

@@ -0,0 +1,47 @@
+package com.igeeksky.xtool.core;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * 优雅停机接口
+ * <p>
+ * 池化类对象及工厂类对象建议实现此接口。
+ *
+ * @author Patrick.Lau
+ * @since 1.1.2
+ */
+public interface GracefulShutdown {
+
+    /**
+     * 根据预设参数执行优雅停机
+     */
+    void shutdown();
+
+    /**
+     * 根据传入参数执行优雅停机
+     *
+     * @param quietPeriod 静默时长
+     * @param timeout     最大超时
+     * @param unit        时间单位
+     */
+    void shutdown(long quietPeriod, long timeout, TimeUnit unit);
+
+    /**
+     * 根据预设参数执行优雅停机（异步）
+     *
+     * @return {@code CompletableFuture<Void>} – 关闭结果（可能的异常信息）
+     */
+    CompletableFuture<Void> shutdownAsync();
+
+    /**
+     * 根据传入参数执行优雅停机（异步）
+     *
+     * @param quietPeriod 静默时长
+     * @param timeout     最大超时
+     * @param unit        时间单位
+     * @return {@code CompletableFuture<Void>} – 关闭结果（可能的异常信息）
+     */
+    CompletableFuture<Void> shutdownAsync(long quietPeriod, long timeout, TimeUnit unit);
+
+}

src/main/java/com/igeeksky/xtool/core/KeyValue.java

@@ -36,13 +36,19 @@ public class KeyValue<K, V> implements Serializable {
 
     private final V value;
 
+    /**
+     * 使用给定的键和值创建 {@link KeyValue} 对象
+     *
+     * @param key   键（可以为空）
+     * @param value 值（可以为空）
+     */
     public KeyValue(K key, V value) {
         this.key = key;
         this.value = value;
     }
 
     /**
-     * 获取 key
+     * 获取键
      *
      * @return 键
      */
@@ -51,7 +57,7 @@ public K getKey() {
     }
 
     /**
-     * 获取 value
+     * 获取值
      *
      * @return 值
      */
@@ -60,35 +66,35 @@ public V getValue() {
     }
 
     /**
-     * 转换 key，并返回新的 Pair
+     * 将当前 KeyValue 对象中的原键转换为新键，并返回新的 {@link KeyValue} 对象
      *
      * @param mapper 转换函数
-     * @param <R>    转换类型
-     * @return 包含转换后的对象的新的 Pair
+     * @param <R>    新键类型
+     * @return {@link KeyValue} – 新的 KeyValue 对象（新键 + 原值）
      */
     public <R> KeyValue<R, V> mapKey(Function<K, R> mapper) {
         return new KeyValue<>(mapper.apply(key), value);
     }
 
     /**
-     * 转换 value，并返回新的 Pair
+     * 将当前 {@link KeyValue} 对象中的原值转换为新值，并返回新的 {@link KeyValue} 对象
      *
      * @param mapper 转换函数
-     * @param <R>    转换类型
-     * @return 包含转换后的对象的新的 Pair
+     * @param <R>    新值类型
+     * @return {@link KeyValue} – 新的 KeyValue 对象（原键 + 新值）
      */
     public <R> KeyValue<K, R> mapValue(Function<V, R> mapper) {
         return new KeyValue<>(key, mapper.apply(value));
     }
 
     /**
-     * 将当前 KeyValue 对象中的键和值映射为新的键和值
+     * 将当前 KeyValue 对象中的原键和原值转换为新键和新值，并返回新的 {@link KeyValue} 对象
      *
-     * @param keyMapper   转换函数：用于将当前 KeyValue 对象的键转换为新键
-     * @param valueMapper 转换函数：用于将当前 KeyValue 对象的值转换为新值
-     * @param <K1>        新键的类型
-     * @param <V1>        新值的类型
-     * @return 包含映射后键值对的新的KeyValue对象
+     * @param keyMapper   转换函数：用于将当前 KeyValue 对象的原键转换为新键
+     * @param valueMapper 转换函数：用于将当前 KeyValue 对象的原值转换为新值
+     * @param <K1>        新键类型
+     * @param <V1>        新值类型
+     * @return {@link KeyValue} – 新的 KeyValue 对象（新键 + 新值）
      */
     public <K1, V1> KeyValue<K1, V1> map(Function<K, K1> keyMapper, Function<V, V1> valueMapper) {
         return new KeyValue<>(keyMapper.apply(key), valueMapper.apply(value));
@@ -97,7 +103,7 @@ public <K1, V1> KeyValue<K1, V1> map(Function<K, K1> keyMapper, Function<V, V1>
     /**
      * 是否包含键
      *
-     * @return boolean
+     * @return {@code boolean} - 如果键不为空，返回 {@code true}; 否则返回 {@code false}。
      */
     public boolean hasKey() {
         return null != key;
@@ -106,17 +112,33 @@ public boolean hasKey() {
     /**
      * 是否包含值
      *
-     * @return boolean
+     * @return {@code boolean} - 如果值不为空，返回 {@code true}; 否则返回 {@code false}。
      */
     public boolean hasValue() {
         return null != value;
     }
 
+    /**
+     * 获取空的 {@link KeyValue} 对象
+     *
+     * @param <K> 键类型
+     * @param <V> 值类型
+     * @return {@link KeyValue} – 空的 KeyValue 对象
+     */
     @SuppressWarnings("unchecked")
     public static <K, V> KeyValue<K, V> empty() {
         return (KeyValue<K, V>) EMPTY;
     }
 
+    /**
+     * 创建 {@link KeyValue} 对象
+     *
+     * @param key   键（可以为空）
+     * @param value 值（可以为空）
+     * @param <K>   键类型
+     * @param <V>   值类型
+     * @return {@link KeyValue} – 键值对
+     */
     public static <K, V> KeyValue<K, V> create(K key, V value) {
         return new KeyValue<>(key, value);
     }