docs: 改正 OptionalTools 的 javadoc

Reviewed-on: http://zhouxy.xyz:3000/plusone/plusone-commons/pulls/34
docs: fix javadoc
2025-03-28 09:02:28 +08:00 · 2025-03-28 08:55:35 +08:00 · 2025-03-25 14:28:22 +08:00 · 2025-03-23 13:50:03 +08:00 · 2025-03-23 13:49:23 +08:00 · 2025-03-23 13:27:37 +08:00
30 changed files with 659 additions and 158 deletions
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
 Java 非 final 的实例方法，对应 C++/C# 中的虚方法，允许被子类覆写。 Virtual 注解旨在设计父类时，强调该方法父类虽然有默认实现，但子类可以根据自己的需要覆写。

 ### 5. ValueObject
-标记一个类，表示其作为值对象，区别与 Entity。
+标记一个类，表示其作为值对象，区别于 Entity。

 ## 二、base - 基础组件
 ### 1. Ref
--- a/src/main/java/xyz/zhouxy/plusone/commons/annotation/package-info.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/annotation/package-info.java
@@ -56,7 +56,7 @@
 * 5. {@link ValueObject}
 * </h3>
 * <p>
- * 标记一个类，表示其作为值对象，区别与 Entity。
+ * 标记一个类，表示其作为值对象，区别于 Entity。
 * </p>
 *
 * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
--- a/src/main/java/xyz/zhouxy/plusone/commons/collection/package-info.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/collection/package-info.java
@@ -24,4 +24,7 @@
 *
 * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
 */
+@ParametersAreNonnullByDefault
 package xyz.zhouxy.plusone.commons.collection;
+
+import javax.annotation.ParametersAreNonnullByDefault;
--- a/src/main/java/xyz/zhouxy/plusone/commons/constant/PatternConsts.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/constant/PatternConsts.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -61,7 +61,7 @@ public final class PatternConsts {
     *
     * @see RegexConsts#EMAIL
     */
-    public static final Pattern EMAIL = Pattern.compile(RegexConsts.EMAIL);
+    public static final Pattern EMAIL = Pattern.compile(RegexConsts.EMAIL, Pattern.CASE_INSENSITIVE);

    /**
     * 中国大陆手机号
--- a/src/main/java/xyz/zhouxy/plusone/commons/constant/RegexConsts.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/constant/RegexConsts.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2022-2024 the original author or authors.
+ * Copyright 2022-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -32,6 +32,9 @@ public final class RegexConsts {

    public static final String CAPTCHA = "^\\w{4,6}$";

+    /**
+     * from https://emailregex.com/
+     */
    public static final String EMAIL
            = "(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*|\"(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21\\x23-\\x5b\\x5d-\\x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])*\")"
            + "@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21-\\x5a\\x53-\\x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])+)\\])";
--- a/src/main/java/xyz/zhouxy/plusone/commons/time/Quarter.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/time/Quarter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 the original author or authors.
+ * Copyright 2024-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
--- a/src/main/java/xyz/zhouxy/plusone/commons/time/YearQuarter.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/time/YearQuarter.java
@@ -27,7 +27,7 @@ import java.util.Calendar;
 import java.util.Date;
 import java.util.Objects;

-import javax.annotation.Nonnull;
+import javax.annotation.Nullable;

 import com.google.errorprone.annotations.Immutable;

@@ -52,7 +52,7 @@ public final class YearQuarter implements Comparable<YearQuarter>, Serializable
    /** 季度结束日期 */
    private final LocalDate lastDate;

-    private YearQuarter(int year, @Nonnull Quarter quarter) {
+    private YearQuarter(int year, Quarter quarter) {
        this.year = year;
        this.quarter = quarter;
        this.firstDate = quarter.firstMonthDay().atYear(year);
@@ -249,7 +249,7 @@ public final class YearQuarter implements Comparable<YearQuarter>, Serializable
    }

    @Override
-    public boolean equals(Object obj) {
+    public boolean equals(@Nullable Object obj) {
        if (this == obj)
            return true;
        if (obj == null)
@@ -264,6 +264,7 @@ public final class YearQuarter implements Comparable<YearQuarter>, Serializable

    // #region - compare

+    @SuppressWarnings("null")
    @Override
    public int compareTo(YearQuarter other) {
        int cmp = (this.year - other.year);
--- a/src/main/java/xyz/zhouxy/plusone/commons/time/package-info.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/time/package-info.java
@@ -24,4 +24,7 @@
 *
 * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
 */
+@ParametersAreNonnullByDefault
 package xyz.zhouxy.plusone.commons.time;
+
+import javax.annotation.ParametersAreNonnullByDefault;
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 the original author or authors.
+ * Copyright 2024-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -26,7 +26,6 @@ import java.util.Objects;
 import java.util.function.Predicate;
 import java.util.stream.Collectors;

-import javax.annotation.Nonnull;
 import javax.annotation.Nullable;

 /**
@@ -259,7 +258,7 @@ public class ArrayTools {
     *
     * @throws IllegalArgumentException 当参数为空时抛出
     */
-    public static <T> boolean isAllElementsNotNull(@Nonnull final T[] arr) {
+    public static <T> boolean isAllElementsNotNull(final T[] arr) {
        AssertTools.checkArgument(arr != null, "The array cannot be null.");
        return Arrays.stream(arr).allMatch(Objects::nonNull);
    }
@@ -622,15 +621,15 @@ public class ArrayTools {

    // fill - char

-    public static void fill(char[] a, char[] values) {
+    public static void fill(char[] a, @Nullable char[] values) {
        fill(a, 0, a.length, values);
    }

-    public static void fill(char[] a, String values) {
+    public static void fill(char[] a, @Nullable String values) {
        fill(a, 0, a.length, values != null ? values.toCharArray() : EMPTY_CHAR_ARRAY);
    }

-    public static void fill(char[] a, int fromIndex, int toIndex, char[] values) {
+    public static void fill(char[] a, int fromIndex, int toIndex, @Nullable char[] values) {
        AssertTools.checkArgument(Objects.nonNull(a));
        if (values == null || values.length == 0) {
            return;
@@ -655,11 +654,11 @@ public class ArrayTools {

    // fill - byte

-    public static void fill(byte[] a, byte[] values) {
+    public static void fill(byte[] a, @Nullable byte[] values) {
        fill(a, 0, a.length, values);
    }

-    public static void fill(byte[] a, int fromIndex, int toIndex, byte[] values) {
+    public static void fill(byte[] a, int fromIndex, int toIndex, @Nullable byte[] values) {
        AssertTools.checkArgument(Objects.nonNull(a));
        if (values == null || values.length == 0) {
            return;
@@ -684,11 +683,11 @@ public class ArrayTools {

    // fill - short

-    public static void fill(short[] a, short[] values) {
+    public static void fill(short[] a, @Nullable short[] values) {
        fill(a, 0, a.length, values);
    }

-    public static void fill(short[] a, int fromIndex, int toIndex, short[] values) {
+    public static void fill(short[] a, int fromIndex, int toIndex, @Nullable short[] values) {
        AssertTools.checkArgument(Objects.nonNull(a));
        if (values == null || values.length == 0) {
            return;
@@ -713,11 +712,11 @@ public class ArrayTools {

    // fill - int

-    public static void fill(int[] a, int[] values) {
+    public static void fill(int[] a, @Nullable int[] values) {
        fill(a, 0, a.length, values);
    }

-    public static void fill(int[] a, int fromIndex, int toIndex, int[] values) {
+    public static void fill(int[] a, int fromIndex, int toIndex, @Nullable int[] values) {
        AssertTools.checkArgument(Objects.nonNull(a));
        if (values == null || values.length == 0) {
            return;
@@ -742,11 +741,11 @@ public class ArrayTools {

    // fill - long

-    public static void fill(long[] a, long[] values) {
+    public static void fill(long[] a, @Nullable long[] values) {
        fill(a, 0, a.length, values);
    }

-    public static void fill(long[] a, int fromIndex, int toIndex, long[] values) {
+    public static void fill(long[] a, int fromIndex, int toIndex, @Nullable long[] values) {
        AssertTools.checkArgument(Objects.nonNull(a));
        if (values == null || values.length == 0) {
            return;
@@ -771,11 +770,11 @@ public class ArrayTools {

    // fill - float

-    public static void fill(float[] a, float[] values) {
+    public static void fill(float[] a, @Nullable float[] values) {
        fill(a, 0, a.length, values);
    }

-    public static void fill(float[] a, int fromIndex, int toIndex, float[] values) {
+    public static void fill(float[] a, int fromIndex, int toIndex, @Nullable float[] values) {
        AssertTools.checkArgument(Objects.nonNull(a));
        if (values == null || values.length == 0) {
            return;
@@ -800,11 +799,11 @@ public class ArrayTools {

    // fill - double

-    public static void fill(double[] a, double[] values) {
+    public static void fill(double[] a, @Nullable double[] values) {
        fill(a, 0, a.length, values);
    }

-    public static void fill(double[] a, int fromIndex, int toIndex, double[] values) {
+    public static void fill(double[] a, int fromIndex, int toIndex, @Nullable double[] values) {
        AssertTools.checkArgument(Objects.nonNull(a));
        if (values == null || values.length == 0) {
            return;
@@ -829,15 +828,15 @@ public class ArrayTools {

    // fill - T

-    public static <T> void fill(@Nonnull T[] a, T[] values) {
+    public static <T> void fill(T[] a, @Nullable T[] values) {
        fillInternal(a, 0, a.length, values);
    }

-    public static <T> void fill(@Nonnull T[] a, int fromIndex, int toIndex, T[] values) {
+    public static <T> void fill(T[] a, int fromIndex, int toIndex, @Nullable T[] values) {
        fillInternal(a, fromIndex, toIndex, values);
    }

-    private static <T> void fillInternal(@Nonnull T[] a, int fromIndex, int toIndex, @Nullable T[] values) {
+    private static <T> void fillInternal(T[] a, int fromIndex, int toIndex, @Nullable T[] values) {
        AssertTools.checkArgument(Objects.nonNull(a));
        if (values == null || values.length == 0) {
            return;
@@ -864,9 +863,9 @@ public class ArrayTools {

    // #region - indexOf

-    public static <T> int indexOfWithPredicate(T[] arr, Predicate<? super T> predicate) {
+    public static <T> int indexOfWithPredicate(@Nullable T[] arr, Predicate<? super T> predicate) {
        AssertTools.checkNotNull(predicate);
-        if (isNullOrEmpty(arr)) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = 0; i < arr.length; i++) {
@@ -877,12 +876,12 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static <T> int indexOf(T[] arr, T obj) {
+    public static <T> int indexOf(@Nullable T[] arr, @Nullable T obj) {
        return indexOfWithPredicate(arr, item -> Objects.equals(item, obj));
    }

-    public static int indexOf(char[] arr, char value) {
-        if (isNullOrEmpty(arr)) {
+    public static int indexOf(@Nullable char[] arr, char value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = 0; i < arr.length; i++) {
@@ -893,8 +892,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int indexOf(byte[] arr, byte value) {
-        if (isNullOrEmpty(arr)) {
+    public static int indexOf(@Nullable byte[] arr, byte value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = 0; i < arr.length; i++) {
@@ -905,8 +904,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int indexOf(short[] arr, short value) {
-        if (isNullOrEmpty(arr)) {
+    public static int indexOf(@Nullable short[] arr, short value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = 0; i < arr.length; i++) {
@@ -917,8 +916,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int indexOf(int[] arr, int value) {
-        if (isNullOrEmpty(arr)) {
+    public static int indexOf(@Nullable int[] arr, int value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = 0; i < arr.length; i++) {
@@ -929,8 +928,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int indexOf(long[] arr, long value) {
-        if (isNullOrEmpty(arr)) {
+    public static int indexOf(@Nullable long[] arr, long value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = 0; i < arr.length; i++) {
@@ -941,8 +940,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int indexOf(float[] arr, float value) {
-        if (isNullOrEmpty(arr)) {
+    public static int indexOf(@Nullable float[] arr, float value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = 0; i < arr.length; i++) {
@@ -953,8 +952,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int indexOf(double[] arr, double value) {
-        if (isNullOrEmpty(arr)) {
+    public static int indexOf(@Nullable double[] arr, double value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = 0; i < arr.length; i++) {
@@ -969,9 +968,9 @@ public class ArrayTools {

    // #region - lastIndexOf

-    public static <T> int lastIndexOfWithPredicate(T[] arr, @Nonnull Predicate<? super T> predicate) {
+    public static <T> int lastIndexOfWithPredicate(@Nullable T[] arr, Predicate<? super T> predicate) {
        AssertTools.checkNotNull(predicate);
-        if (isNullOrEmpty(arr)) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = arr.length - 1; i >= 0; i--) {
@@ -986,8 +985,8 @@ public class ArrayTools {
        return lastIndexOfWithPredicate(arr, item -> Objects.equals(item, obj));
    }

-    public static int lastIndexOf(char[] arr, char value) {
-        if (isNullOrEmpty(arr)) {
+    public static int lastIndexOf(@Nullable char[] arr, char value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = arr.length - 1; i >= 0; i--) {
@@ -998,8 +997,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int lastIndexOf(byte[] arr, byte value) {
-        if (isNullOrEmpty(arr)) {
+    public static int lastIndexOf(@Nullable byte[] arr, byte value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = arr.length - 1; i >= 0; i--) {
@@ -1010,8 +1009,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int lastIndexOf(short[] arr, short value) {
-        if (isNullOrEmpty(arr)) {
+    public static int lastIndexOf(@Nullable short[] arr, short value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = arr.length - 1; i >= 0; i--) {
@@ -1022,8 +1021,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int lastIndexOf(int[] arr, int value) {
-        if (isNullOrEmpty(arr)) {
+    public static int lastIndexOf(@Nullable int[] arr, int value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = arr.length - 1; i >= 0; i--) {
@@ -1034,8 +1033,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int lastIndexOf(long[] arr, long value) {
-        if (isNullOrEmpty(arr)) {
+    public static int lastIndexOf(@Nullable long[] arr, long value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = arr.length - 1; i >= 0; i--) {
@@ -1046,8 +1045,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int lastIndexOf(float[] arr, float value) {
-        if (isNullOrEmpty(arr)) {
+    public static int lastIndexOf(@Nullable float[] arr, float value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = arr.length - 1; i >= 0; i--) {
@@ -1058,8 +1057,8 @@ public class ArrayTools {
        return NOT_FOUND_INDEX;
    }

-    public static int lastIndexOf(double[] arr, double value) {
-        if (isNullOrEmpty(arr)) {
+    public static int lastIndexOf(@Nullable double[] arr, double value) {
+        if (arr == null || arr.length == 0) {
            return NOT_FOUND_INDEX;
        }
        for (int i = arr.length - 1; i >= 0; i--) {
@@ -1074,39 +1073,39 @@ public class ArrayTools {

    // #region - contains

-    public static <T> boolean contains(T[] arr, T obj) {
+    public static <T> boolean contains(@Nullable T[] arr, @Nullable T obj) {
        return indexOf(arr, obj) > NOT_FOUND_INDEX;
    }

-    public static boolean contains(char[] arr, char obj) {
+    public static boolean contains(@Nullable char[] arr, char obj) {
        return indexOf(arr, obj) > NOT_FOUND_INDEX;
    }

-    public static boolean contains(byte[] arr, byte obj) {
+    public static boolean contains(@Nullable byte[] arr, byte obj) {
        return indexOf(arr, obj) > NOT_FOUND_INDEX;
    }

-    public static boolean contains(short[] arr, short obj) {
+    public static boolean contains(@Nullable short[] arr, short obj) {
        return indexOf(arr, obj) > NOT_FOUND_INDEX;
    }

-    public static boolean contains(int[] arr, int obj) {
+    public static boolean contains(@Nullable int[] arr, int obj) {
        return indexOf(arr, obj) > NOT_FOUND_INDEX;
    }

-    public static boolean contains(long[] arr, long obj) {
+    public static boolean contains(@Nullable long[] arr, long obj) {
        return indexOf(arr, obj) > NOT_FOUND_INDEX;
    }

-    public static boolean contains(float[] arr, float obj) {
+    public static boolean contains(@Nullable float[] arr, float obj) {
        return indexOf(arr, obj) > NOT_FOUND_INDEX;
    }

-    public static boolean contains(double[] arr, double obj) {
+    public static boolean contains(@Nullable double[] arr, double obj) {
        return indexOf(arr, obj) > NOT_FOUND_INDEX;
    }

-    public static boolean containsValue(BigDecimal[] arr, BigDecimal obj) {
+    public static boolean containsValue(@Nullable BigDecimal[] arr, @Nullable BigDecimal obj) {
        return indexOfWithPredicate(arr, item -> BigDecimals.equalsValue(item, obj)) > NOT_FOUND_INDEX;
    }

--- a/src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 the original author or authors.
+ * Copyright 2024-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -20,7 +20,7 @@ import java.util.Objects;
 import java.util.Optional;
 import java.util.function.Supplier;

-import javax.annotation.Nonnull;
+import javax.annotation.Nullable;

 import xyz.zhouxy.plusone.commons.exception.DataNotExistsException;
 import xyz.zhouxy.plusone.commons.exception.system.DataOperationResultException;
@@ -55,12 +55,12 @@ public class AssertTools {
    }

    /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */
-    public static void checkArgument(boolean condition, String errMsg) {
+    public static void checkArgument(boolean condition, @Nullable String errMsg) {
        checkCondition(condition, () -> new IllegalArgumentException(errMsg));
    }

    /** Throw {@link IllegalArgumentException} if the {@code condition} is false. */
-    public static void checkArgument(boolean condition, @Nonnull Supplier<String> messageSupplier) {
+    public static void checkArgument(boolean condition, Supplier<String> messageSupplier) {
        checkCondition(condition, () -> new IllegalArgumentException(messageSupplier.get()));
    }

@@ -83,12 +83,12 @@ public class AssertTools {
    }

    /** Throw {@link IllegalStateException} if the {@code condition} is false. */
-    public static void checkState(boolean condition, String errMsg) {
+    public static void checkState(boolean condition, @Nullable String errMsg) {
        checkCondition(condition, () -> new IllegalStateException(errMsg));
    }

    /** Throw {@link IllegalStateException} if the {@code condition} is false. */
-    public static void checkState(boolean condition, @Nonnull Supplier<String> messageSupplier) {
+    public static void checkState(boolean condition, Supplier<String> messageSupplier) {
        checkCondition(condition, () -> new IllegalStateException(messageSupplier.get()));
    }

@@ -106,22 +106,22 @@ public class AssertTools {
    // ================================

    /** Throw {@link NullPointerException} if the {@code obj} is null. */
-    public static <T> void checkNotNull(T obj) {
+    public static <T> void checkNotNull(@Nullable T obj) {
        checkCondition(obj != null, NullPointerException::new);
    }

    /** Throw {@link NullPointerException} if the {@code obj} is null. */
-    public static <T> void checkNotNull(T obj, String errMsg) {
+    public static <T> void checkNotNull(@Nullable T obj, String errMsg) {
        checkCondition(obj != null, () -> new NullPointerException(errMsg));
    }

    /** Throw {@link NullPointerException} if the {@code obj} is null. */
-    public static <T> void checkNotNull(T obj, @Nonnull Supplier<String> messageSupplier) {
+    public static <T> void checkNotNull(@Nullable T obj, Supplier<String> messageSupplier) {
        checkCondition(obj != null, () -> new NullPointerException(messageSupplier.get()));
    }

    /** Throw {@link NullPointerException} if the {@code obj} is null. */
-    public static <T> void checkNotNull(T obj, String format, Object... args) {
+    public static <T> void checkNotNull(@Nullable T obj, String format, Object... args) {
        checkCondition(obj != null, () -> new NullPointerException(String.format(format, args)));
    }

@@ -134,56 +134,56 @@ public class AssertTools {
    // ================================

    /** Throw {@link DataNotExistsException} if the {@code obj} is null. */
-    public static <T> T checkExists(T obj)
+    public static <T> T checkExists(@Nullable T obj)
            throws DataNotExistsException {
        checkCondition(Objects.nonNull(obj), DataNotExistsException::new);
        return obj;
    }

    /** Throw {@link DataNotExistsException} if the {@code obj} is null. */
-    public static <T> T checkExists(T obj, String message)
+    public static <T> T checkExists(@Nullable T obj, String message)
            throws DataNotExistsException {
        checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(message));
        return obj;
    }

    /** Throw {@link DataNotExistsException} if the {@code obj} is null. */
-    public static <T> T checkExists(T obj, @Nonnull Supplier<String> messageSupplier)
+    public static <T> T checkExists(@Nullable T obj, Supplier<String> messageSupplier)
            throws DataNotExistsException {
        checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(messageSupplier.get()));
        return obj;
    }

    /** Throw {@link DataNotExistsException} if the {@code obj} is null. */
-    public static <T> T checkExists(T obj, String format, Object... args)
+    public static <T> T checkExists(@Nullable T obj, String format, Object... args)
            throws DataNotExistsException {
        checkCondition(Objects.nonNull(obj), () -> new DataNotExistsException(String.format(format, args)));
        return obj;
    }

    /** Throw {@link DataNotExistsException} if the {@code optional} is present. */
-    public static <T> T checkExists(@Nonnull Optional<T> optional)
+    public static <T> T checkExists(Optional<T> optional)
            throws DataNotExistsException {
        checkCondition(optional.isPresent(), DataNotExistsException::new);
        return optional.get();
    }

    /** Throw {@link DataNotExistsException} if the {@code optional} is present. */
-    public static <T> T checkExists(@Nonnull Optional<T> optional, String message)
+    public static <T> T checkExists(Optional<T> optional, String message)
            throws DataNotExistsException {
        checkCondition(optional.isPresent(), () -> new DataNotExistsException(message));
        return optional.get();
    }

    /** Throw {@link DataNotExistsException} if the {@code optional} is present. */
-    public static <T> T checkExists(@Nonnull Optional<T> optional, @Nonnull Supplier<String> messageSupplier)
+    public static <T> T checkExists(Optional<T> optional, Supplier<String> messageSupplier)
            throws DataNotExistsException {
        checkCondition(optional.isPresent(), () -> new DataNotExistsException(messageSupplier.get()));
        return optional.get();
    }

    /** Throw {@link DataNotExistsException} if the {@code optional} is present. */
-    public static <T> T checkExists(@Nonnull Optional<T> optional, String format, Object... args)
+    public static <T> T checkExists(Optional<T> optional, String format, Object... args)
            throws DataNotExistsException {
        checkCondition(optional.isPresent(), () -> new DataNotExistsException(String.format(format, args)));
        return optional.get();
@@ -202,17 +202,18 @@ public class AssertTools {
                "The number of rows affected is expected to be %d, but is: %d", expectedValue, result);
    }

-    public static void checkAffectedRows(int expectedValue, int result, String message) {
+    public static void checkAffectedRows(int expectedValue, int result, @Nullable String message) {
        checkCondition(expectedValue == result, () -> new DataOperationResultException(message));
    }

    public static void checkAffectedRows(int expectedValue, int result,
-            @Nonnull Supplier<String> messageSupplier) {
+            Supplier<String> messageSupplier) {
        checkCondition(expectedValue == result,
                () -> new DataOperationResultException(messageSupplier.get()));
    }

-    public static void checkAffectedRows(int expectedValue, int result, String format, Object... args) {
+    public static void checkAffectedRows(int expectedValue, int result,
+            String format, Object... args) {
        checkCondition(expectedValue == result,
                () -> new DataOperationResultException(String.format(format, args)));
    }
@@ -222,17 +223,18 @@ public class AssertTools {
                "The number of rows affected is expected to be %d, but is: %d", expectedValue, result);
    }

-    public static void checkAffectedRows(long expectedValue, long result, String message) {
+    public static void checkAffectedRows(long expectedValue, long result, @Nullable String message) {
        checkCondition(expectedValue == result, () -> new DataOperationResultException(message));
    }

    public static void checkAffectedRows(long expectedValue, long result,
-            @Nonnull Supplier<String> messageSupplier) {
+            Supplier<String> messageSupplier) {
        checkCondition(expectedValue == result,
                () -> new DataOperationResultException(messageSupplier.get()));
    }

-    public static void checkAffectedRows(long expectedValue, long result, String format, Object... args) {
+    public static void checkAffectedRows(long expectedValue, long result,
+            String format, Object... args) {
        checkCondition(expectedValue == result,
                () -> new DataOperationResultException(String.format(format, args)));
    }
@@ -246,7 +248,7 @@ public class AssertTools {
        checkAffectedRows(1, result, message);
    }

-    public static void checkAffectedOneRow(int result, @Nonnull Supplier<String> messageSupplier) {
+    public static void checkAffectedOneRow(int result, Supplier<String> messageSupplier) {
        checkAffectedRows(1, result, messageSupplier);
    }

@@ -263,11 +265,12 @@ public class AssertTools {
        checkAffectedRows(1L, result, message);
    }

-    public static void checkAffectedOneRow(long result, @Nonnull Supplier<String> messageSupplier) {
+    public static void checkAffectedOneRow(long result, Supplier<String> messageSupplier) {
        checkAffectedRows(1L, result, messageSupplier);
    }

-    public static void checkAffectedOneRow(long result, String format, Object... args) {
+    public static void checkAffectedOneRow(long result,
+            String format, Object... args) {
        checkAffectedRows(1L, result, format, args);
    }

@@ -279,7 +282,7 @@ public class AssertTools {
    // #region - Condition
    // ================================

-    public static <T extends Exception> void checkCondition(boolean condition, @Nonnull Supplier<T> e)
+    public static <T extends Exception> void checkCondition(boolean condition, Supplier<T> e)
            throws T {
        if (!condition) {
            throw e.get();
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/BigDecimals.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/BigDecimals.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -46,7 +46,9 @@ public class BigDecimals {
    }

    public static boolean ge(BigDecimal a, BigDecimal b) {
-        return gt(a, b) || equalsValue(a, b);
+        AssertTools.checkNotNull(a, "Parameter could not be null.");
+        AssertTools.checkNotNull(b, "Parameter could not be null.");
+        return (a == b) || (a.compareTo(b) >= 0);
    }

    public static boolean lt(BigDecimal a, BigDecimal b) {
@@ -56,7 +58,9 @@ public class BigDecimals {
    }

    public static boolean le(BigDecimal a, BigDecimal b) {
-        return lt(a, b) || equalsValue(a, b);
+        AssertTools.checkNotNull(a, "Parameter could not be null.");
+        AssertTools.checkNotNull(b, "Parameter could not be null.");
+        return (a == b) || (a.compareTo(b) <= 0);
    }

    public static BigDecimal sum(final BigDecimal... numbers) {
@@ -79,7 +83,7 @@ public class BigDecimals {
    }

    @StaticFactoryMethod(BigDecimal.class)
-    public static BigDecimal of(final String val) {
+    public static BigDecimal of(@Nullable final String val) {
        return (StringTools.isNotBlank(val)) ? new BigDecimal(val) : BigDecimal.ZERO;
    }

--- a/src/main/java/xyz/zhouxy/plusone/commons/util/DateTimeTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/DateTimeTools.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -44,7 +44,9 @@ import xyz.zhouxy.plusone.commons.time.YearQuarter;
 */
 public class DateTimeTools {

+    // ================================
    // #region - toString
+    // ================================

    public static String toYearString(int year) {
        return Integer.toString(YEAR.checkValidIntValue(year));
@@ -70,9 +72,13 @@ public class DateTimeTools {
        return String.format("%02d", month.getValue());
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - toDate
+    // ================================

    /**
     * 将时间戳转换为 {@link Date} 对象
@@ -137,9 +143,13 @@ public class DateTimeTools {
        return Date.from(ZonedDateTime.of(localDate, localTime, zone).toInstant());
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - toInstant
+    // ================================

    /**
     * 将时间戳转换为 {@link Instant} 对象
@@ -192,9 +202,13 @@ public class DateTimeTools {
        return ZonedDateTime.of(localDateTime, zone).toInstant();
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - toZonedDateTime
+    // ================================

    /**
     * 获取时间戳在指定时区的地区时间。
@@ -285,9 +299,13 @@ public class DateTimeTools {
        return ZonedDateTime.of(localDateTime, zone);
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - toLocalDateTime
+    // ================================

    /**
     * 获取时间戳在指定时区的地区时间。
@@ -355,11 +373,13 @@ public class DateTimeTools {
        return LocalDateTime.ofInstant(zonedDateTime.toInstant(), zone);
    }

+    // ================================
    // #endregion
+    // ================================

-    // ====================
-
+    // ================================
    // #region - toJodaInstant
+    // ================================

    /**
     * 将 {@link java.time.Instant} 转换为 {@link org.joda.time.Instant}
@@ -392,9 +412,13 @@ public class DateTimeTools {
        return toJodaInstant(java.time.ZonedDateTime.of(localDateTime, zone));
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - toJavaInstant
+    // ================================

    /**
     * 将 {@link org.joda.time.Instant} 对象转换为 {@link java.time.Instant} 对象
@@ -432,9 +456,13 @@ public class DateTimeTools {
        return toJavaInstant(localDateTime.toDateTime(zone));
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - toJodaDateTime
+    // ================================

    /**
     * 将 Java 中表示日期时间的 {@link java.time.ZonedDateTime} 对象
@@ -479,9 +507,13 @@ public class DateTimeTools {
        return toJodaInstant(instant).toDateTime(dateTimeZone);
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - toZonedDateTime
+    // ================================

    /**
     * 将 joda-time 中带时区的日期时间，转换为 java.time 中带时区的日期时间
@@ -511,7 +543,7 @@ public class DateTimeTools {
    }

    /**
-     * 获取 joda-time 中的 {@link org.joda.time.Instant} 在指定时区的时间，用 Java 8
+     * 获取 joda-time 中的 {@link org.joda.time.Instant} 在指定时区的时间，用 Java 8+ 的
     * {@link java.time.ZonedDateTime} 表示
     *
     * @param instant      joda-time 中的时间戳
@@ -525,9 +557,13 @@ public class DateTimeTools {
        return toJavaInstant(instant).atZone(zone);
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - toJodaLocalDateTime
+    // ================================

    /**
     * 将 {@link java.time.LocalDateTime} 转换为 {@link org.joda.time.LocalDateTime}
@@ -541,9 +577,13 @@ public class DateTimeTools {
        return toJodaInstant(localDateTime, javaZone).toDateTime(jodaZone).toLocalDateTime();
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - toJavaLocalDateTime
+    // ================================

    /**
     * 将 {@link org.joda.time.LocalDateTime} 转换为 {@link java.time.LocalDateTime}
@@ -557,9 +597,13 @@ public class DateTimeTools {
        return toJavaInstant(localDateTime, jodaZone).atZone(javaZone).toLocalDateTime();
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - ZoneId <--> DateTimeZone
+    // ================================

    /**
     * 转换 Java API 和 joda-time API 表示时区的对象
@@ -581,9 +625,13 @@ public class DateTimeTools {
        return org.joda.time.DateTimeZone.forID(zone.getId());
    }

+    // ================================
    // #endregion
+    // ================================

+    // ================================
    // #region - YearQuarter & Quarter
+    // ================================

    /**
     * 获取指定日期所在季度
@@ -646,10 +694,12 @@ public class DateTimeTools {
        return YearQuarter.of(date);
    }

+    // ================================
    // #endregion
+    // ================================

    // ================================
-    // #region - others
+    // #region - start & end
    // ================================

    public static LocalDate startDateOfYear(int year) {
@@ -668,6 +718,86 @@ public class DateTimeTools {
        return date.plusDays(1L).atStartOfDay(zone);
    }

+    // ================================
+    // #endregion - start & end
+    // ================================
+
+    // ================================
+    // #region - isFuture
+    // ================================
+
+    public static boolean isFuture(Date date) {
+        return date.after(new Date());
+    }
+
+    public static boolean isFuture(Calendar date) {
+        return date.after(Calendar.getInstance());
+    }
+
+    public static boolean isFuture(Instant instant) {
+        return instant.isAfter(Instant.now());
+    }
+
+    public static boolean isFuture(long timeMillis) {
+        return timeMillis > System.currentTimeMillis();
+    }
+
+    public static boolean isFuture(LocalDate date) {
+        return date.isAfter(LocalDate.now());
+    }
+
+    public static boolean isFuture(LocalDateTime dateTime) {
+        return dateTime.isAfter(LocalDateTime.now());
+    }
+
+    public static boolean isFuture(ZonedDateTime dateTime) {
+        return dateTime.isAfter(ZonedDateTime.now());
+    }
+
+    // ================================
+    // #endregion - isFuture
+    // ================================
+
+    // ================================
+    // #region - isPast
+    // ================================
+
+    public static boolean isPast(Date date) {
+        return date.before(new Date());
+    }
+
+    public static boolean isPast(Calendar date) {
+        return date.before(Calendar.getInstance());
+    }
+
+    public static boolean isPast(Instant instant) {
+        return instant.isBefore(Instant.now());
+    }
+
+    public static boolean isPast(long timeMillis) {
+        return timeMillis < System.currentTimeMillis();
+    }
+
+    public static boolean isPast(LocalDate date) {
+        return date.isBefore(LocalDate.now());
+    }
+
+    public static boolean isPast(LocalDateTime dateTime) {
+        return dateTime.isBefore(LocalDateTime.now());
+    }
+
+    public static boolean isPast(ZonedDateTime dateTime) {
+        return dateTime.isBefore(ZonedDateTime.now());
+    }
+
+    // ================================
+    // #endregion - isPast
+    // ================================
+
+    // ================================
+    // #region - others
+    // ================================
+
    public static Range<LocalDateTime> toDateTimeRange(LocalDate date) {
        return Range.closedOpen(date.atStartOfDay(), startOfNextDate(date));
    }
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/EnumTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/EnumTools.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2022-2024 the original author or authors.
+ * Copyright 2022-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -18,7 +18,6 @@ package xyz.zhouxy.plusone.commons.util;

 import java.util.function.Supplier;

-import javax.annotation.Nonnull;
 import javax.annotation.Nullable;

 /**
@@ -42,7 +41,7 @@ public final class EnumTools {
     * @deprecated 不推荐使用枚举的 ordinal。
     */
    @Deprecated
-    private static <E extends Enum<?>> E valueOfInternal(@Nonnull Class<E> enumType, int ordinal) { // NOSONAR 该方法弃用，但不删掉
+    private static <E extends Enum<?>> E valueOfInternal(Class<E> enumType, int ordinal) { // NOSONAR 该方法弃用，但不删掉
        E[] values = enumType.getEnumConstants();
        AssertTools.checkCondition((ordinal >= 0 && ordinal < values.length),
                () -> new EnumConstantNotPresentException(enumType, Integer.toString(ordinal)));
@@ -76,7 +75,7 @@ public final class EnumTools {
     */
    @Deprecated
    public static <E extends Enum<?>> E valueOf(Class<E> enumType, // NOSONAR 该方法弃用，但不删掉
-            @Nullable Integer ordinal, E defaultValue) {
+            @Nullable Integer ordinal, @Nullable E defaultValue) {
        AssertTools.checkNotNull(enumType);
        return null == ordinal ? defaultValue : valueOfInternal(enumType, ordinal);
    }
@@ -190,7 +189,7 @@ public final class EnumTools {
     */
    @Nullable
    private static <E extends Enum<?>> Integer checkOrdinalOrDefaultInternal(
-            @Nonnull Class<E> enumType,
+            Class<E> enumType,
            @Nullable Integer ordinal,
            @Nullable Integer defaultValue) {
        return ordinal != null
@@ -200,9 +199,9 @@ public final class EnumTools {

    @Nullable
    private static <E extends Enum<?>> Integer checkOrdinalOrGetInternal(
-            @Nonnull Class<E> enumType,
+            Class<E> enumType,
            @Nullable Integer ordinal,
-            @Nonnull Supplier<Integer> defaultValueSupplier) {
+            Supplier<Integer> defaultValueSupplier) {
        return ordinal != null
                ? checkOrdinal(enumType, ordinal)
                : defaultValueSupplier.get();
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/Enumeration.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/Enumeration.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2022-2024 the original author or authors.
+ * Copyright 2022-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -24,6 +24,8 @@ import java.util.Objects;
 import java.util.function.Function;
 import java.util.stream.Collectors;

+import javax.annotation.Nullable;
+
 import xyz.zhouxy.plusone.commons.annotation.StaticFactoryMethod;

 /**
@@ -54,6 +56,7 @@ public abstract class Enumeration<T extends Enumeration<T>> // NOSONAR 暂不移
        return name;
    }

+    @SuppressWarnings("null")
    @Override
    public final int compareTo(final T o) {
        return Integer.compare(this.id, o.id);
@@ -65,7 +68,7 @@ public abstract class Enumeration<T extends Enumeration<T>> // NOSONAR 暂不移
    }

    @Override
-    public final boolean equals(final Object obj) {
+    public final boolean equals(@Nullable final Object obj) {
        if (this == obj)
            return true;
        if (obj == null)
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java
@@ -21,8 +21,6 @@ import java.util.Objects;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;

-import javax.annotation.Nonnull;
-
 /**
 * ID 生成器
 *
@@ -50,7 +48,7 @@ public class IdGenerator {
        return toSimpleString(UUID.randomUUID());
    }

-    public static String toSimpleString(@Nonnull UUID uuid) {
+    public static String toSimpleString(UUID uuid) {
        AssertTools.checkArgument(Objects.nonNull(uuid));
        return (uuidDigits(uuid.getMostSignificantBits() >> 32, 8) +
                uuidDigits(uuid.getMostSignificantBits() >> 16, 4) +
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/IdWorker.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/IdWorker.java
@@ -22,6 +22,8 @@ import java.util.Enumeration;
 import java.util.concurrent.ThreadLocalRandom;
 import java.util.concurrent.atomic.AtomicLong;

+import javax.annotation.Nullable;
+
 import xyz.zhouxy.plusone.commons.exception.system.NoAvailableMacFoundException;

 /**
@@ -115,7 +117,7 @@ public class IdWorker {
     * init workerId
     * @param workerId if null, then auto generate one
     */
-    private void initWorkerId(Long workerId) {
+    private void initWorkerId(@Nullable Long workerId) {
        if (workerId == null) {
            workerId = generateWorkerId();
        }
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/OptionalTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/OptionalTools.java
@@ -26,7 +26,7 @@ import javax.annotation.Nullable;
 import com.google.common.annotations.Beta;

 /**
- * OptionalUtil
+ * OptionalTools
 *
 * <p>
 * 提供一些 Optional 相关的方法
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/RandomTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/RandomTools.java
@@ -22,8 +22,6 @@ import java.util.Objects;
 import java.util.Random;
 import java.util.concurrent.ThreadLocalRandom;

-import javax.annotation.Nonnull;
-
 /**
 * 随机工具类
 * <p>
@@ -68,20 +66,20 @@ public final class RandomTools {
     * @param length           字符串长度
     * @return 随机字符串
     */
-    public static String randomStr(@Nonnull Random random, @Nonnull char[] sourceCharacters, int length) {
+    public static String randomStr(Random random, char[] sourceCharacters, int length) {
        AssertTools.checkArgument(Objects.nonNull(random), "Random cannot be null.");
        AssertTools.checkArgument(Objects.nonNull(sourceCharacters), "Source characters cannot be null.");
        AssertTools.checkArgument(length >= 0, "The length should be greater than or equal to zero.");
        return randomStrInternal(random, sourceCharacters, length);
    }

-    public static String randomStr(@Nonnull char[] sourceCharacters, int length) {
+    public static String randomStr(char[] sourceCharacters, int length) {
        AssertTools.checkArgument(Objects.nonNull(sourceCharacters), "Source characters cannot be null.");
        AssertTools.checkArgument(length >= 0, "The length should be greater than or equal to zero.");
        return randomStrInternal(ThreadLocalRandom.current(), sourceCharacters, length);
    }

-    public static String secureRandomStr(@Nonnull char[] sourceCharacters, int length) {
+    public static String secureRandomStr(char[] sourceCharacters, int length) {
        AssertTools.checkArgument(Objects.nonNull(sourceCharacters), "Source characters cannot be null.");
        AssertTools.checkArgument(length >= 0, "The length should be greater than or equal to zero.");
        return randomStrInternal(DEFAULT_SECURE_RANDOM, sourceCharacters, length);
@@ -97,20 +95,20 @@ public final class RandomTools {
     * @param length           字符串长度
     * @return 随机字符串
     */
-    public static String randomStr(@Nonnull Random random, @Nonnull String sourceCharacters, int length) {
+    public static String randomStr(Random random, String sourceCharacters, int length) {
        AssertTools.checkArgument(Objects.nonNull(random), "Random cannot be null.");
        AssertTools.checkArgument(Objects.nonNull(sourceCharacters), "Source characters cannot be null.");
        AssertTools.checkArgument(length >= 0, "The length should be greater than or equal to zero.");
        return randomStrInternal(random, sourceCharacters, length);
    }

-    public static String randomStr(@Nonnull String sourceCharacters, int length) {
+    public static String randomStr(String sourceCharacters, int length) {
        AssertTools.checkArgument(Objects.nonNull(sourceCharacters), "Source characters cannot be null.");
        AssertTools.checkArgument(length >= 0, "The length should be greater than or equal to zero.");
        return randomStrInternal(ThreadLocalRandom.current(), sourceCharacters, length);
    }

-    public static String secureRandomStr(@Nonnull String sourceCharacters, int length) {
+    public static String secureRandomStr(String sourceCharacters, int length) {
        AssertTools.checkArgument(Objects.nonNull(sourceCharacters), "Source characters cannot be null.");
        AssertTools.checkArgument(length >= 0, "The length should be greater than or equal to zero.");
        return randomStrInternal(DEFAULT_SECURE_RANDOM, sourceCharacters, length);
@@ -126,7 +124,7 @@ public final class RandomTools {
     * @param length           字符串长度
     * @return 随机字符串
     */
-    private static String randomStrInternal(@Nonnull Random random, @Nonnull char[] sourceCharacters, int length) {
+    private static String randomStrInternal(Random random, char[] sourceCharacters, int length) {
        if (length == 0) {
            return StringTools.EMPTY_STRING;
        }
@@ -147,7 +145,7 @@ public final class RandomTools {
     * @param length           字符串长度
     * @return 随机字符串
     */
-    private static String randomStrInternal(@Nonnull Random random, @Nonnull String sourceCharacters, int length) {
+    private static String randomStrInternal(Random random, String sourceCharacters, int length) {
        if (length == 0) {
            return StringTools.EMPTY_STRING;
        }
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/RegexTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/RegexTools.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 the original author or authors.
+ * Copyright 2023-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -272,7 +272,7 @@ public final class RegexTools {
     * @return {@link Pattern} 实例
     */
    @Nonnull
-    private static Pattern cacheAndGetPatternInternal(@Nonnull final String pattern) {
+    private static Pattern cacheAndGetPatternInternal(final String pattern) {
        if (PATTERN_CACHE.size() < MAX_CACHE_SIZE) {
            return PATTERN_CACHE.computeIfAbsent(pattern, Pattern::compile);
        }
@@ -290,7 +290,7 @@ public final class RegexTools {
     * @return {@link Pattern} 实例
     */
    @Nonnull
-    private static Pattern getPatternInternal(@Nonnull final String pattern) {
+    private static Pattern getPatternInternal(final String pattern) {
        Pattern result = PATTERN_CACHE.get(pattern);
        if (result == null) {
            result = Pattern.compile(pattern);
@@ -305,7 +305,7 @@ public final class RegexTools {
     * @return {@link Pattern} 实例数组
     */
    @Nonnull
-    private static Pattern[] cacheAndGetPatternsInternal(@Nonnull final String[] patterns) {
+    private static Pattern[] cacheAndGetPatternsInternal(final String[] patterns) {
        return Arrays.stream(patterns)
                .map(RegexTools::cacheAndGetPatternInternal)
                .toArray(Pattern[]::new);
@@ -318,7 +318,7 @@ public final class RegexTools {
     * @return {@link Pattern} 实例数组
     */
    @Nonnull
-    private static Pattern[] getPatternsInternal(@Nonnull final String[] patterns) {
+    private static Pattern[] getPatternsInternal(final String[] patterns) {
        return Arrays.stream(patterns)
                .map(RegexTools::getPatternInternal)
                .toArray(Pattern[]::new);
@@ -331,17 +331,17 @@ public final class RegexTools {
     * @param pattern 正则
     * @return 判断结果
     */
-    private static boolean matchesInternal(@Nullable final CharSequence input, @Nonnull final Pattern pattern) {
+    private static boolean matchesInternal(@Nullable final CharSequence input, final Pattern pattern) {
        return input != null && pattern.matcher(input).matches();
    }

-    private static boolean matchesOneInternal(@Nullable final CharSequence input, @Nonnull final Pattern[] patterns) {
+    private static boolean matchesOneInternal(@Nullable final CharSequence input, final Pattern[] patterns) {
        return input != null
                && Arrays.stream(patterns)
                        .anyMatch(pattern -> pattern.matcher(input).matches());
    }

-    private static boolean matchesAllInternal(@Nullable final CharSequence input, @Nonnull final Pattern[] patterns) {
+    private static boolean matchesAllInternal(@Nullable final CharSequence input, final Pattern[] patterns) {
        return input != null
                && Arrays.stream(patterns)
                        .allMatch(pattern -> pattern.matcher(input).matches());
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/StringTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/StringTools.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 the original author or authors.
+ * Copyright 2024-2025 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -16,16 +16,30 @@

 package xyz.zhouxy.plusone.commons.util;

+import java.net.MalformedURLException;
+import java.net.URL;
 import java.util.Objects;

+import javax.annotation.Nullable;
+
 import com.google.common.annotations.Beta;

-@Beta
+import xyz.zhouxy.plusone.commons.constant.PatternConsts;
+
+/**
+ * StringTools
+ *
+ * <p>
+ * 字符串工具类。
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ */
 public class StringTools {

    public static final String EMPTY_STRING = "";

-    public static boolean isNotBlank(final String cs) {
+    public static boolean isNotBlank(@Nullable final String cs) {
        if (cs == null || cs.isEmpty()) {
            return false;
        }
@@ -37,15 +51,50 @@ public class StringTools {
        return false;
    }

+    public static boolean isBlank(@Nullable String cs) {
+        if (cs == null || cs.isEmpty()) {
+            return true;
+        }
+        for (int i = 0; i < cs.length(); i++) {
+            if (!Character.isWhitespace(cs.charAt(i))) {
+                return false;
+            }
+        }
+        return true;
+    }
+
    public static String repeat(String str, int times) {
        return repeat(str, times, Integer.MAX_VALUE);
    }

-    public static String repeat(String str, int times, int maxLength) {
+    public static String repeat(final String str, int times, int maxLength) {
        AssertTools.checkArgument(Objects.nonNull(str));
        return String.valueOf(ArrayTools.repeat(str.toCharArray(), times, maxLength));
    }

+    public static boolean isNotEmpty(@Nullable final String cs) {
+        return cs != null && !cs.isEmpty();
+    }
+
+    public static boolean isEmpty(@Nullable final String cs) {
+        return cs == null || cs.isEmpty();
+    }
+
+    @Beta
+    public static boolean isEmail(@Nullable final String cs) {
+        return RegexTools.matches(cs, PatternConsts.EMAIL);
+    }
+
+    @Beta
+    public static boolean isURL(@Nullable final String cs) {
+        try {
+            new URL(cs);
+        } catch (MalformedURLException e) {
+            return false;
+        }
+        return true;
+    }
+
    private StringTools() {
        throw new IllegalStateException("Utility class");
    }
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/TreeBuilder.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/TreeBuilder.java
@@ -45,7 +45,7 @@ public class TreeBuilder<T, TSubTree extends T, TIdentity> {
    }

    public TreeBuilder(Function<T, TIdentity> identityGetter, Function<T, Optional<TIdentity>> parentIdentityGetter,
-            BiConsumer<TSubTree, T> addChild, Comparator<? super T> defaultComparator) {
+            BiConsumer<TSubTree, T> addChild, @Nullable Comparator<? super T> defaultComparator) {
        this.identityGetter = identityGetter;
        this.parentIdentityGetter = parentIdentityGetter;
        this.addChildMethod = addChild;
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/package-info.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/package-info.java
@@ -22,4 +22,7 @@
 *
 * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
 */
+@ParametersAreNonnullByDefault
 package xyz.zhouxy.plusone.commons.util;
+
+import javax.annotation.ParametersAreNonnullByDefault;
--- a/src/test/java/xyz/zhouxy/plusone/commons/time/YearQuarterTests.java
+++ b/src/test/java/xyz/zhouxy/plusone/commons/time/YearQuarterTests.java
@@ -36,6 +36,7 @@ import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;

@Slf4j
+@SuppressWarnings("null")
 public class YearQuarterTests {

    // ================================
@@ -588,7 +589,7 @@ public class YearQuarterTests {
            Year.MIN_VALUE,
            Year.MAX_VALUE,
    })
-    void of_ValidYearMonth_CreatesYearMnoth_Q1(int year) {
+    void of_ValidYearMonth_CreatesYearMonth_Q1(int year) {
        {
            YearMonth yearMonth = YearMonth.of(year, 1);
            YearQuarter yearQuarter = YearQuarter.of(yearMonth);
@@ -619,7 +620,7 @@ public class YearQuarterTests {
            Year.MIN_VALUE,
            Year.MAX_VALUE,
    })
-    void of_ValidYearMonth_CreatesYearMnoth_Q2(int year) {
+    void of_ValidYearMonth_CreatesYearMonth_Q2(int year) {
        {
            YearMonth yearMonth = YearMonth.of(year, 4);
            YearQuarter yearQuarter = YearQuarter.of(yearMonth);
@@ -650,7 +651,7 @@ public class YearQuarterTests {
            Year.MIN_VALUE,
            Year.MAX_VALUE,
    })
-    void of_ValidYearMonth_CreatesYearMnoth_Q3(int year) {
+    void of_ValidYearMonth_CreatesYearMonth_Q3(int year) {
        {
            YearMonth yearMonth = YearMonth.of(year, 7);
            YearQuarter yearQuarter = YearQuarter.of(yearMonth);
@@ -681,7 +682,7 @@ public class YearQuarterTests {
            Year.MIN_VALUE,
            Year.MAX_VALUE,
    })
-    void of_ValidYearMonth_CreatesYearMnoth_Q4(int year) {
+    void of_ValidYearMonth_CreatesYearMonth_Q4(int year) {
        {
            YearMonth yearMonth = YearMonth.of(year, 10);
            YearQuarter yearQuarter = YearQuarter.of(yearMonth);
@@ -712,7 +713,7 @@ public class YearQuarterTests {
            Year.MIN_VALUE,
            Year.MAX_VALUE,
    })
-    void of_NullYearMonth_CreatesYearMnoth_Q4(int year) {
+    void of_NullYearMonth_CreatesYearMonth_Q4(int year) {
        YearMonth yearMonth = null;
        assertThrows(NullPointerException.class,
                () -> YearQuarter.of(yearMonth));
--- a/src/test/java/xyz/zhouxy/plusone/commons/util/BigDecimalsTests.java
+++ b/src/test/java/xyz/zhouxy/plusone/commons/util/BigDecimalsTests.java
@@ -27,6 +27,7 @@ import org.junit.jupiter.api.Test;
 import lombok.extern.slf4j.Slf4j;

@Slf4j
+@SuppressWarnings("null")
 public class BigDecimalsTests {

    @Test
--- a/src/test/java/xyz/zhouxy/plusone/commons/util/DateTimeToolsTests.java
+++ b/src/test/java/xyz/zhouxy/plusone/commons/util/DateTimeToolsTests.java
@@ -435,32 +435,117 @@ class DateTimeToolsTests {
    // ================================

    // ================================
-    // #region - others
+    // #region - start & end
    // ================================

    @Test
-    void startDateOfYear() {
+    void testStartAndEndDateOfYear() {
        assertEquals(LocalDate.of(2008, 1, 1), DateTimeTools.startDateOfYear(2008));
        assertEquals(LocalDate.of(2008, 12, 31), DateTimeTools.endDateOfYear(2008));
+    }
+
+    @Test
+    void testStartOfNextDate() {
        assertEquals(LocalDateTime.of(2024, 12, 30, 0, 0, 0),
                DateTimeTools.startOfNextDate(LOCAL_DATE));
        assertEquals(LocalDateTime.of(2024, 12, 30, 0, 0, 0).atZone(SYS_ZONE_ID),
                DateTimeTools.startOfNextDate(LOCAL_DATE, SYS_ZONE_ID));
        assertEquals(LocalDateTime.of(2024, 12, 30, 0, 0, 0).atZone(ZONE_ID),
                DateTimeTools.startOfNextDate(LOCAL_DATE, ZONE_ID));
+    }

+    // ================================
+    // #endregion - start & end
+    // ================================
+
+    // ================================
+    // #region - isFuture & isPast
+    // ================================
+
+    @Test
+    void test_isFuture_And_isPast_WhenFuture() {
+        Date date = new Date(Instant.now().plusSeconds(10).toEpochMilli());
+        assertTrue(DateTimeTools.isFuture(date));
+        assertFalse(DateTimeTools.isPast(date));
+
+        Calendar calendar = Calendar.getInstance(TimeZone.getTimeZone("+01:00"));
+        calendar.add(Calendar.SECOND, 10);
+        assertTrue(DateTimeTools.isFuture(calendar));
+        assertFalse(DateTimeTools.isPast(calendar));
+
+        Instant instant = Instant.now().plusSeconds(10);
+        assertTrue(DateTimeTools.isFuture(instant));
+        assertFalse(DateTimeTools.isPast(instant));
+
+        long timeMillis = Instant.now().plusSeconds(10).toEpochMilli();
+        assertTrue(DateTimeTools.isFuture(timeMillis));
+        assertFalse(DateTimeTools.isPast(timeMillis));
+
+        LocalDate localDate = LocalDate.now().plusDays(1);
+        assertTrue(DateTimeTools.isFuture(localDate));
+        assertFalse(DateTimeTools.isPast(localDate));
+
+        LocalDateTime localDateTime = LocalDateTime.now().plusSeconds(10);
+        assertTrue(DateTimeTools.isFuture(localDateTime));
+        assertFalse(DateTimeTools.isPast(localDateTime));
+
+        ZonedDateTime zonedDateTime = Instant.now().plusSeconds(10).atZone(ZoneId.of("+01:00"));
+        assertTrue(DateTimeTools.isFuture(zonedDateTime));
+        assertFalse(DateTimeTools.isPast(zonedDateTime));
+    }
+
+    @Test
+    void test_isFuture_And_isPast_WhenPast() {
+        Date date = new Date(Instant.now().minusSeconds(10).toEpochMilli());
+        assertFalse(DateTimeTools.isFuture(date));
+        assertTrue(DateTimeTools.isPast(date));
+
+        Calendar calendar = Calendar.getInstance(TimeZone.getTimeZone("+01:00"));
+        calendar.add(Calendar.SECOND, -10);
+        assertFalse(DateTimeTools.isFuture(calendar));
+        assertTrue(DateTimeTools.isPast(calendar));
+
+        Instant instant = Instant.now().minusSeconds(10);
+        assertFalse(DateTimeTools.isFuture(instant));
+        assertTrue(DateTimeTools.isPast(instant));
+
+        long timeMillis = Instant.now().minusSeconds(10).toEpochMilli();
+        assertFalse(DateTimeTools.isFuture(timeMillis));
+        assertTrue(DateTimeTools.isPast(timeMillis));
+
+        LocalDate localDate = LocalDate.now().minusDays(1);
+        assertFalse(DateTimeTools.isFuture(localDate));
+        assertTrue(DateTimeTools.isPast(localDate));
+
+        LocalDateTime localDateTime = LocalDateTime.now().minusSeconds(10);
+        assertFalse(DateTimeTools.isFuture(localDateTime));
+        assertTrue(DateTimeTools.isPast(localDateTime));
+
+        ZonedDateTime zonedDateTime = Instant.now().minusSeconds(10).atZone(ZoneId.of("+01:00"));
+        assertFalse(DateTimeTools.isFuture(zonedDateTime));
+        assertTrue(DateTimeTools.isPast(zonedDateTime));
+    }
+
+    // ================================
+    // #endregion - isFuture & isPast
+    // ================================
+
+    // ================================
+    // #region - others
+    // ================================
+
+    @Test
+    void startDateTimeRange() {
        Range<LocalDateTime> localDateTimeRange = DateTimeTools.toDateTimeRange(LOCAL_DATE);
        assertEquals(LOCAL_DATE.atStartOfDay(), localDateTimeRange.lowerEndpoint());
+        assertEquals(LocalDate.of(2024, 12, 30).atStartOfDay(), localDateTimeRange.upperEndpoint());
        assertTrue(localDateTimeRange.contains(LOCAL_DATE.atStartOfDay()));
-        assertEquals(LocalDate.of(2024, 12, 30).atStartOfDay(), localDateTimeRange.upperEndpoint());
-        assertEquals(LocalDate.of(2024, 12, 30).atStartOfDay(), localDateTimeRange.upperEndpoint());
        assertFalse(localDateTimeRange.contains(LocalDate.of(2024, 12, 30).atStartOfDay()));

        Range<ZonedDateTime> zonedDateTimeRange = DateTimeTools.toDateTimeRange(LOCAL_DATE, SYS_ZONE_ID);
        assertEquals(LOCAL_DATE.atStartOfDay().atZone(SYS_ZONE_ID), zonedDateTimeRange.lowerEndpoint());
+        assertEquals(LocalDate.of(2024, 12, 30).atStartOfDay().atZone(SYS_ZONE_ID), zonedDateTimeRange.upperEndpoint());
        assertTrue(zonedDateTimeRange.contains(LOCAL_DATE.atStartOfDay().atZone(SYS_ZONE_ID)));
-        assertEquals(ZonedDateTime.of(LocalDate.of(2024, 12, 30).atStartOfDay(), SYS_ZONE_ID), zonedDateTimeRange.upperEndpoint());
-        assertEquals(ZonedDateTime.of(LocalDate.of(2024, 12, 30).atStartOfDay(), SYS_ZONE_ID), zonedDateTimeRange.upperEndpoint());
        assertFalse(zonedDateTimeRange.contains(LocalDate.of(2024, 12, 30).atStartOfDay().atZone(SYS_ZONE_ID)));
    }

@@ -480,6 +565,10 @@ class DateTimeToolsTests {
        assertThrows(DateTimeException.class, () -> DateTimeTools.toYearString(Year.MIN_VALUE - 1));
        assertThrows(DateTimeException.class, () -> DateTimeTools.toYearString(Year.MAX_VALUE + 1));

+        assertEquals("2024", DateTimeTools.toYearString(Year.of(2024)));
+        assertEquals("999999999", DateTimeTools.toYearString(Year.of(Year.MAX_VALUE)));
+        assertEquals("-999999999", DateTimeTools.toYearString(Year.of(Year.MIN_VALUE)));
+
        assertEquals("01", DateTimeTools.toMonthStringMM(1));
        assertEquals("02", DateTimeTools.toMonthStringMM(2));
        assertEquals("3", DateTimeTools.toMonthStringM(3));
--- a/src/test/java/xyz/zhouxy/plusone/commons/util/EnumToolsTests.java
+++ b/src/test/java/xyz/zhouxy/plusone/commons/util/EnumToolsTests.java
@@ -30,7 +30,7 @@ import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;

-@SuppressWarnings("deprecation")
+@SuppressWarnings({"deprecation", "null"})
 public
 class EnumToolsTests {

--- a/src/test/java/xyz/zhouxy/plusone/commons/util/OptionalToolsTests.java
+++ b/src/test/java/xyz/zhouxy/plusone/commons/util/OptionalToolsTests.java
@@ -35,6 +35,7 @@ import org.junit.jupiter.api.Test;
 /**
 * {@link OptionalTools} 单元测试
 */
+@SuppressWarnings("null")
 public
 class OptionalToolsTests {

--- a/src/test/java/xyz/zhouxy/plusone/commons/util/RegexToolsTests.java
+++ b/src/test/java/xyz/zhouxy/plusone/commons/util/RegexToolsTests.java
@@ -28,6 +28,7 @@ import org.junit.jupiter.api.Test;
 import lombok.extern.slf4j.Slf4j;

@Slf4j
+@SuppressWarnings("null")
 public
 class RegexToolsTests {

--- a/src/test/java/xyz/zhouxy/plusone/commons/util/StringToolsTests.java
+++ b/src/test/java/xyz/zhouxy/plusone/commons/util/StringToolsTests.java
@@ -28,9 +28,14 @@ import java.util.Arrays;

 import org.junit.jupiter.api.Test;

+@SuppressWarnings("null")
 public
 class StringToolsTests {

+    // ================================
+    // #region - isNotBlank
+    // ================================
+
    @Test
    void isNotBlank_NullString_ReturnsFalse() {
        assertFalse(StringTools.isNotBlank(null));
@@ -51,6 +56,206 @@ class StringToolsTests {
        assertTrue(StringTools.isNotBlank("Hello"));
    }

+    // ================================
+    // #endregion - isNotBlank
+    // ================================
+
+    // ================================
+    // #region - isBlank
+    // ================================
+
+    @Test
+    void isBlank_NullString_ReturnsTrue() {
+        assertTrue(StringTools.isBlank(null));
+    }
+
+    @Test
+    void isBlank_EmptyString_ReturnsTrue() {
+        assertTrue(StringTools.isBlank(""));
+    }
+
+    @Test
+    void isBlank_WhitespaceString_ReturnsTrue() {
+        assertTrue(StringTools.isBlank("   "));
+    }
+
+    @Test
+    void isBlank_NonWhitespaceString_ReturnsFalse() {
+        assertFalse(StringTools.isBlank("Hello"));
+    }
+
+    // ================================
+    // #endregion - isBlank
+    // ================================
+
+    // ================================
+    // #region - isNotEmpty
+    // ================================
+
+    @Test
+    void isNotEmpty_NullString_ReturnsFalse() {
+        assertFalse(StringTools.isNotEmpty(null));
+    }
+
+    @Test
+    void isNotEmpty_EmptyString_ReturnsFalse() {
+        assertFalse(StringTools.isNotEmpty(""));
+    }
+
+    @Test
+    void isNotEmpty_WhitespaceString_ReturnsTrue() {
+        assertTrue(StringTools.isNotEmpty("   "));
+    }
+
+    @Test
+    void isNotEmpty_NonWhitespaceString_ReturnsTrue() {
+        assertTrue(StringTools.isNotEmpty("Hello"));
+    }
+
+    // ================================
+    // #endregion - isNotEmpty
+    // ================================
+
+    // ================================
+    // #region - isEmpty
+    // ================================
+
+    @Test
+    void isEmpty_NullString_ReturnsTrue() {
+        assertTrue(StringTools.isEmpty(null));
+    }
+
+    @Test
+    void isEmpty_EmptyString_ReturnsTrue() {
+        assertTrue(StringTools.isEmpty(""));
+    }
+
+    @Test
+    void isEmpty_WhitespaceString_ReturnsFalse() {
+        assertFalse(StringTools.isEmpty("   "));
+    }
+
+    @Test
+    void isEmpty_NonWhitespaceString_ReturnsFalse() {
+        assertFalse(StringTools.isEmpty("Hello"));
+    }
+
+    // ================================
+    // #endregion - isEmpty
+    // ================================
+
+    // ================================
+    // #region - EMAIL
+    // ================================
+
+    @Test
+    public void testValidEmails() {
+        assertTrue(StringTools.isEmail("test@example.com"));
+        assertTrue(StringTools.isEmail("user.name+tag+sorting@example.com"));
+        assertTrue(StringTools.isEmail("user@sub.example.com"));
+        assertTrue(StringTools.isEmail("user@123.123.123.123"));
+    }
+
+    @Test
+    public void testInvalidEmails() {
+        assertFalse(StringTools.isEmail(".username@example.com"));
+        assertFalse(StringTools.isEmail("@missingusername.com"));
+        assertFalse(StringTools.isEmail("plainaddress"));
+        assertFalse(StringTools.isEmail("username..username@example.com"));
+        assertFalse(StringTools.isEmail("username.@example.com"));
+        assertFalse(StringTools.isEmail("username@-example.com"));
+        assertFalse(StringTools.isEmail("username@-example.com"));
+        assertFalse(StringTools.isEmail("username@.com.com"));
+        assertFalse(StringTools.isEmail("username@.com.my"));
+        assertFalse(StringTools.isEmail("username@.com"));
+        assertFalse(StringTools.isEmail("username@com."));
+        assertFalse(StringTools.isEmail("username@com"));
+        assertFalse(StringTools.isEmail("username@example..com"));
+        assertFalse(StringTools.isEmail("username@example.com-"));
+        assertFalse(StringTools.isEmail("username@example.com."));
+        assertFalse(StringTools.isEmail("username@example"));
+    }
+
+    // ================================
+    // #endregion - EMAIL
+    // ================================
+
+    // ================================
+    // #region - isURL
+    // ================================
+
+        /**
+     * TC1: 验证标准HTTP协议URL
+     */
+    @Test
+    void isURL_ValidHttpURL_ReturnsTrue() {
+        assertTrue(StringTools.isURL("http://example.com"));
+    }
+
+    /**
+     * TC2: 验证带路径参数的HTTPS复杂URL
+     */
+    @Test
+    void isURL_ValidHttpsComplexURL_ReturnsTrue() {
+        assertTrue(StringTools.isURL("https://test.com:8080/api/v1?param=value#anchor"));
+    }
+
+    /**
+     * TC3: 验证FTP协议URL
+     */
+    @Test
+    void isURL_ValidFtpURL_ReturnsTrue() {
+        assertTrue(StringTools.isURL("ftp://files.example.com/directory/"));
+    }
+
+    /**
+     * TC4: 验证非法协议处理
+     */
+    @Test
+    void isURL_InvalidProtocol_ReturnsFalse() {
+        assertFalse(StringTools.isURL("httpx://invalid.com"));
+    }
+
+    /**
+     * TC5: 验证null输入处理
+     */
+    @Test
+    void isURL_NullInput_ReturnsFalse() {
+        assertFalse(StringTools.isURL(null));
+    }
+
+    /**
+     * TC6: 验证空字符串处理
+     */
+    @Test
+    void isURL_EmptyString_ReturnsFalse() {
+        assertFalse(StringTools.isURL(StringTools.EMPTY_STRING));
+    }
+
+    /**
+     * TC7: 验证缺失协议头处理
+     */
+    @Test
+    void isURL_MissingProtocol_ReturnsFalse() {
+        assertFalse(StringTools.isURL("www.example.com/path"));
+    }
+
+    /**
+     * TC8: 验证未编码特殊字符处理
+     */
+    @Test
+    void isURL_UnencodedSpecialChars_ReturnsTrue() {
+        assertTrue(StringTools.isURL("http://example.com/测试"));
+    }
+
+    // ================================
+    // #endregion - isURL
+    // ================================
+
+    // ================================
+    // #region - repeat
+    // ================================
+
    @Test
    void repeat_NullString_ThrowsException() {
        IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, () -> {
@@ -89,6 +294,10 @@ class StringToolsTests {
        assertEquals("", StringTools.repeat("Hello", 0));
    }

+    // ================================
+    // #endregion - repeat
+    // ================================
+
    @Test
    void test_constructor_isNotAccessible_ThrowsIllegalStateException() {
        Constructor<?>[] constructors = StringTools.class.getDeclaredConstructors();
--- a/src/test/java/xyz/zhouxy/plusone/commons/util/TreeBuilderTests.java
+++ b/src/test/java/xyz/zhouxy/plusone/commons/util/TreeBuilderTests.java
@@ -39,6 +39,7 @@ import cn.hutool.core.util.ObjectUtil;
 import lombok.EqualsAndHashCode;
 import lombok.ToString;

+@SuppressWarnings("null")
 class TreeBuilderTests {

    private static final Logger log = LoggerFactory.getLogger(TreeBuilderTests.class);
Author	SHA1	Message	Date
ZhouXY108	88ca20cd6a	docs: 改正 OptionalTools 的 javadoc Reviewed-on: http://zhouxy.xyz:3000/plusone/plusone-commons/pulls/34	2025-03-28 09:02:28 +08:00
ZhouXY108	e98fe66b65	docs: fix javadoc fix issue plusone/plusone-commons#29	2025-03-28 08:55:35 +08:00
ZhouXY108	872d42aef0	docs: fix typos	2025-03-25 14:28:22 +08:00
ZhouXY108	3f08b08910	docs: 修改 copyright	2025-03-23 13:50:03 +08:00
ZhouXY108	4c1ee87b4d	feat: StringTools 新增工具方法新增 StringTools#isBlank、StringTools#isEmpty、StringTools#isNotEmpty、StringTools#isURL、StringTools#isEmail	2025-03-23 13:49:23 +08:00
ZhouXY108	a9c8fec81a	feat: DateTimeTools 新增 isFuture 和 isPast。	2025-03-23 13:27:37 +08:00
ZhouXY108	29519f3489	修改 email 的正则常量 1. fix: Email 的 Pattern 不区分大小写 2. docs: 标注正则表达式的出处	2025-03-22 17:45:02 +08:00
ZhouXY108	26efd1125e	docs: 修改注释和文档	2025-03-22 15:36:17 +08:00
ZhouXY108	b912f4b063	perf: 优化 JSR305 注解的使用	2025-03-22 15:30:29 +08:00