修改身份证号的实现

修改 ParsingFailureException 的注释
新增中国二代居民身份证正则常量
2024-12-02 18:30:38 +08:00 · 2024-12-02 18:29:34 +08:00 · 2024-12-02 18:29:00 +08:00 · 2024-12-02 18:28:23 +08:00 · 2024-12-02 18:26:39 +08:00
13 changed files with 330 additions and 105 deletions
--- a/src/main/java/xyz/zhouxy/plusone/commons/constant/PatternConsts.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/constant/PatternConsts.java
@@ -22,27 +22,39 @@ import java.util.regex.Pattern;
 * 正则表达式常量
 *
 * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @see RegexConsts
+ * @see xyz.zhouxy.plusone.commons.util.RegexTools
 */
 public final class PatternConsts {

-    // TODO 【添加】 新增身份证等正则常量
-
+    /** yyyyMMdd */
    public static final Pattern BASIC_ISO_DATE = Pattern.compile(RegexConsts.BASIC_ISO_DATE);

+    /** yyyy-MM-dd */
    public static final Pattern ISO_LOCAL_DATE = Pattern.compile(RegexConsts.ISO_LOCAL_DATE);

+    /** 密码 */
    public static final Pattern PASSWORD = Pattern.compile(RegexConsts.PASSWORD);

+    /** 验证码 */
    public static final Pattern CAPTCHA = Pattern.compile(RegexConsts.CAPTCHA);

+    /** 邮箱地址 */
    public static final Pattern EMAIL = Pattern.compile(RegexConsts.EMAIL);

+    /** 中国大陆手机号 */
    public static final Pattern MOBILE_PHONE = Pattern.compile(RegexConsts.MOBILE_PHONE);

+    /** 用户名 */
    public static final Pattern USERNAME = Pattern.compile(RegexConsts.USERNAME);

+    /** 昵称 */
    public static final Pattern NICKNAME = Pattern.compile(RegexConsts.NICKNAME);

+    /** 中国第二代居民身份证 */
+    public static final Pattern CHINESE_2ND_ID_CARD_NUMBER
+            = Pattern.compile(RegexConsts.CHINESE_2ND_ID_CARD_NUMBER);
+
    private PatternConsts() {
        throw new IllegalStateException("Utility class");
    }
--- a/src/main/java/xyz/zhouxy/plusone/commons/constant/RegexConsts.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/constant/RegexConsts.java
@@ -20,28 +20,30 @@ package xyz.zhouxy.plusone.commons.constant;
 * 正则表达式常量
 *
 * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @see PatternConsts
 */
 public final class RegexConsts {

-    // TODO 【优化】 根据需要添加 group
-
-    // TODO 【添加】 新增身份证等正则常量
-
    public static final String BASIC_ISO_DATE = "^(?<y>\\d{4})(?<M>\\d{2})(?<d>\\d{2})";

    public static final String ISO_LOCAL_DATE = "^(?<y>\\d{4})-(?<M>\\d{2})-(?<d>\\d{2})";

    public static final String PASSWORD = "^(?=.*\\d)(?=.*[a-z])(?=.*[A-Z])[\\w\\\\!#$%&'*\\+\\-/=?^`{|}~@\\(\\)\\[\\]\",\\.;':><]{8,32}$";

-    public static final String CAPTCHA = "^[0-9A-Za-z]{4,6}$";
+    public static final String CAPTCHA = "^\\w{4,6}$";

-    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])+)\\])";
+    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])+)\\])";

    public static final String MOBILE_PHONE = "^(13[0-9]|14[01456879]|15[0-35-9]|16[2567]|17[0-8]|18[0-9]|19[0-35-9])\\d{8}$";

-    public static final String USERNAME = "^[\\da-zA-Z_.@\\\\]{4,36}$";
+    public static final String USERNAME = "^[\\w_.@\\\\]{4,36}$";

-    public static final String NICKNAME = "^[\\da-zA-Z_.@\\\\]{4,36}$";
+    public static final String NICKNAME = "^[\\w_.@\\\\]{4,36}$";
+
+    public static final String CHINESE_2ND_ID_CARD_NUMBER
+            = "^(?<county>(?<city>(?<province>\\d{2})\\d{2})\\d{2})(?<birthDate>\\d{8})\\d{2}(?<gender>\\d)([\\dXx])$";

    private RegexConsts() {
        throw new IllegalStateException("Utility class");
--- a/src/main/java/xyz/zhouxy/plusone/commons/exception/DataNotExistsException.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/DataNotExistsException.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2024 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package xyz.zhouxy.plusone.commons.exception;
+
+/**
+ * 数据不存在异常
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 0.1.0
+ */
+public final class DataNotExistsException extends Exception {
+
+    private static final long serialVersionUID = 6536955800679703111L;
+
+    public DataNotExistsException() {
+        super("数据不存在");
+    }
+
+    public DataNotExistsException(String message) {
+        super(message);
+    }
+}
--- a/src/main/java/xyz/zhouxy/plusone/commons/exception/ParsingFailureException.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/exception/ParsingFailureException.java
@@ -18,12 +18,14 @@ package xyz.zhouxy.plusone.commons.exception;

 import java.time.format.DateTimeParseException;

+import xyz.zhouxy.plusone.commons.exception.business.RequestParamsException;
+
 /**
 * 解析失败异常
 *
 * <p>
- * 解析失败的不一定是客户传的参数，也可能是其它来源的数据解析失败
- * 如果表示用户传参造成的解析失败，可使用 RequestParamsException(Throwable cause)，
+ * 解析失败的不一定是客户传的参数，也可能是其它来源的数据解析失败。
+ * 如果表示用户传参造成的解析失败，可使用 {@link RequestParamsException#RequestParamsException(Throwable)}，
 * 将 ParsingFailureException 包装成 {@link RequestParamsException} 再抛出
 * </p>
 *
--- a/src/main/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumber.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumber.java
@@ -16,26 +16,39 @@

 package xyz.zhouxy.plusone.commons.model;

+import java.io.Serializable;
 import java.time.LocalDate;
 import java.time.format.DateTimeFormatter;
 import java.util.Map;
+import java.util.Objects;
 import java.util.regex.Matcher;
-import java.util.regex.Pattern;

 import com.google.common.base.Strings;
 import com.google.common.collect.ImmutableMap;
 import com.google.errorprone.annotations.Immutable;

+import xyz.zhouxy.plusone.commons.annotation.ReaderMethod;
 import xyz.zhouxy.plusone.commons.annotation.ValueObject;
+import xyz.zhouxy.plusone.commons.constant.PatternConsts;
 import xyz.zhouxy.plusone.commons.util.AssertTools;
 import xyz.zhouxy.plusone.commons.util.StringTools;

 /**
+ * Chinese2ndGenIDCardNumber
+ *
+ * <p>
 * 中国第二代居民身份证号
+ * </p>
+ *
+ * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
+ * @since 1.0
+ * @see xyz.zhouxy.plusone.commons.constant.PatternConsts#CHINESE_2ND_ID_CARD_NUMBER
 */
@ValueObject
@Immutable
-public class Chinese2ndGenIDCardNumber extends IDCardNumber {
+public class Chinese2ndGenIDCardNumber implements IDCardNumber, Serializable {
+
+    private final String value;

    /** 省份编码 */
    private final String provinceCode;
@@ -52,7 +65,7 @@ public class Chinese2ndGenIDCardNumber extends IDCardNumber {

    private Chinese2ndGenIDCardNumber(String value, String provinceCode, String cityCode, String countyCode,
            Gender gender, LocalDate birthDate) {
-        super(value);
+        this.value = value;
        this.provinceCode = provinceCode;
        this.cityCode = cityCode;
        this.countyCode = countyCode;
@@ -60,13 +73,11 @@ public class Chinese2ndGenIDCardNumber extends IDCardNumber {
        this.birthDate = birthDate;
    }

-    public static final Pattern PATTERN = Pattern.compile("^(?<county>(?<city>(?<province>\\d{2})\\d{2})\\d{2})(?<birthDate>\\d{8})\\d{2}(?<gender>\\d)([\\dXx])$");
-
    public static Chinese2ndGenIDCardNumber of(final String value) {
        AssertTools.checkArgument(StringTools.isNotBlank(value), "二代居民身份证校验失败：号码为空");
        final String idNumber = value.toUpperCase();

-        final Matcher matcher = Chinese2ndGenIDCardNumber.PATTERN.matcher(idNumber);
+        final Matcher matcher = PatternConsts.CHINESE_2ND_ID_CARD_NUMBER.matcher(idNumber);
        AssertTools.checkArgument(matcher.matches(), () -> "二代居民身份证校验失败：" + value);

        final String provinceCode = matcher.group("province");
@@ -98,39 +109,53 @@ public class Chinese2ndGenIDCardNumber extends IDCardNumber {
    // #region - reader methods
    // ================================

+    @ReaderMethod
+    public String value() {
+        return value;
+    }
+
+    @ReaderMethod
    public String getProvinceCode() {
        return provinceCode;
    }

+    @ReaderMethod
    public String getProvinceName() {
        return PROVINCE_CODES.get(this.provinceCode);
    }

+    @ReaderMethod
    public String getFullProvinceCode() {
        return Strings.padEnd(this.provinceCode, 12, '0');
    }

+    @ReaderMethod
    public String getCityCode() {
        return cityCode;
    }

+    @ReaderMethod
    public String getFullCityCode() {
        return Strings.padEnd(this.cityCode, 12, '0');
    }

+    @ReaderMethod
    public String getCountyCode() {
        return countyCode;
    }

+    @ReaderMethod
    public String getFullCountyCode() {
        return Strings.padEnd(this.countyCode, 12, '0');
    }

+    @ReaderMethod
    @Override
    public Gender getGender() {
        return gender;
    }

+    @ReaderMethod
    @Override
    public LocalDate getBirthDate() {
        return birthDate;
@@ -188,11 +213,18 @@ public class Chinese2ndGenIDCardNumber extends IDCardNumber {

    @Override
    public int hashCode() {
-        return super.hashCode();
+        return Objects.hashCode(value);
    }

    @Override
    public boolean equals(Object obj) {
-        return super.equals(obj);
+        if (this == obj)
+            return true;
+        if (!(obj instanceof Chinese2ndGenIDCardNumber))
+            return false;
+        Chinese2ndGenIDCardNumber other = (Chinese2ndGenIDCardNumber) obj;
+        return Objects.equals(value, other.value);
    }
+
+    private static final long serialVersionUID = 20241202095400L;
 }
--- a/src/main/java/xyz/zhouxy/plusone/commons/model/IDCardNumber.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/model/IDCardNumber.java
@@ -19,42 +19,31 @@ package xyz.zhouxy.plusone.commons.model;
 import java.time.LocalDate;
 import java.time.Period;

-import javax.annotation.Nonnull;
-
 import xyz.zhouxy.plusone.commons.util.AssertTools;

 /**
 * 身份证号
 */
-public abstract class IDCardNumber {
+public interface IDCardNumber {

-    @Nonnull
-    private final String value;
+    static final char DEFAULT_REPLACED_CHAR = '*';
+    static final int DEFAULT_DISPLAY_FRONT = 1;
+    static final int DEFAULT_DISPLAY_END = 2;

-    private static final char DEFAULT_REPLACED_CHAR = '*';
-    private static final int DEFAULT_DISPLAY_FRONT = 1;
-    private static final int DEFAULT_DISPLAY_END = 2;
-
-    protected IDCardNumber(String value) {
-        this.value = value;
-    }
-
-    public final String getValue() {
-        return this.value;
-    }
+    String value();

    /**
     * 根据身份证号判断性别
     */
-    public abstract Gender getGender();
+    Gender getGender();

    /**
     * 获取出生日期
     */
-    public abstract LocalDate getBirthDate();
+    LocalDate getBirthDate();

    /** 计算年龄 */
-    public final int calculateAge() {
+    default int calculateAge() {
        LocalDate now = LocalDate.now();
        return Period.between(getBirthDate(), now).getYears();
    }
@@ -63,23 +52,19 @@ public abstract class IDCardNumber {
    // #region - toString
    // ================================

-    @Override
-    public String toString() {
-        return toDesensitizedString();
-    }
-
-    public String toDesensitizedString() {
+    default String toDesensitizedString() {
        return toDesensitizedString(DEFAULT_REPLACED_CHAR, DEFAULT_DISPLAY_FRONT, DEFAULT_DISPLAY_END);
    }

-    public String toDesensitizedString(int front, int end) {
+    default String toDesensitizedString(int front, int end) {
        return toDesensitizedString(DEFAULT_REPLACED_CHAR, front, end);
    }

-    public String toDesensitizedString(char replacedChar, int front, int end) {
+    default String toDesensitizedString(char replacedChar, int front, int end) {
+        final String value = value();
        AssertTools.checkArgument(front >= 0 && end >= 0);
-        AssertTools.checkArgument((front + end) <= this.value.length(), "需要截取的长度不能大于身份证号长度");
-        final char[] charArray = getValue().toCharArray();
+        AssertTools.checkArgument((front + end) <= value.length(), "需要截取的长度不能大于身份证号长度");
+        final char[] charArray = value.toCharArray();
        for (int i = front; i < charArray.length - end; i++) {
            charArray[i] = replacedChar;
        }
--- a/src/main/java/xyz/zhouxy/plusone/commons/model/ValidatableStringRecord.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/model/ValidatableStringRecord.java
@@ -50,8 +50,8 @@ public abstract class ValidatableStringRecord

    protected ValidatableStringRecord(@Nonnull String value, @Nonnull Pattern pattern,
            @Nonnull String errorMessage) {
-        AssertTools.checkArgumentNotNull(value, "The value cannot be null.");
-        AssertTools.checkArgumentNotNull(pattern, "The pattern cannot be null.");
+        AssertTools.checkArgument(Objects.nonNull(value), "The value cannot be null.");
+        AssertTools.checkArgument(Objects.nonNull(pattern), "The pattern cannot be null.");
        this.matcher = pattern.matcher(value);
        AssertTools.checkArgument(this.matcher.matches(), errorMessage);
        this.value = value;
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/ArrayTools.java
@@ -437,7 +437,7 @@ public class ArrayTools {
    }

    public static char[] repeat(char[] arr, int times, int maxLength) {
-        AssertTools.checkArgumentNotNull(arr);
+        AssertTools.checkArgument(Objects.nonNull(arr));
        AssertTools.checkArgument(times >= 0,
                "The number of times must be greater than or equal to zero");
        AssertTools.checkArgument(maxLength >= 0,
@@ -458,7 +458,7 @@ public class ArrayTools {
    }

    public static byte[] repeat(byte[] arr, int times, int maxLength) {
-        AssertTools.checkArgumentNotNull(arr);
+        AssertTools.checkArgument(Objects.nonNull(arr));
        AssertTools.checkArgument(times >= 0,
                "The number of times must be greater than or equal to zero");
        AssertTools.checkArgument(maxLength >= 0,
@@ -479,7 +479,7 @@ public class ArrayTools {
    }

    public static short[] repeat(short[] arr, int times, int maxLength) {
-        AssertTools.checkArgumentNotNull(arr);
+        AssertTools.checkArgument(Objects.nonNull(arr));
        AssertTools.checkArgument(times >= 0,
                "The number of times must be greater than or equal to zero");
        AssertTools.checkArgument(maxLength >= 0,
@@ -500,7 +500,7 @@ public class ArrayTools {
    }

    public static int[] repeat(int[] arr, int times, int maxLength) {
-        AssertTools.checkArgumentNotNull(arr);
+        AssertTools.checkArgument(Objects.nonNull(arr));
        AssertTools.checkArgument(times >= 0,
                "The number of times must be greater than or equal to zero");
        AssertTools.checkArgument(maxLength >= 0,
@@ -521,7 +521,7 @@ public class ArrayTools {
    }

    public static long[] repeat(long[] arr, int times, int maxLength) {
-        AssertTools.checkArgumentNotNull(arr);
+        AssertTools.checkArgument(Objects.nonNull(arr));
        AssertTools.checkArgument(times >= 0,
                "The number of times must be greater than or equal to zero");
        AssertTools.checkArgument(maxLength >= 0,
@@ -542,7 +542,7 @@ public class ArrayTools {
    }

    public static float[] repeat(float[] arr, int times, int maxLength) {
-        AssertTools.checkArgumentNotNull(arr);
+        AssertTools.checkArgument(Objects.nonNull(arr));
        AssertTools.checkArgument(times >= 0,
                "The number of times must be greater than or equal to zero");
        AssertTools.checkArgument(maxLength >= 0,
@@ -563,7 +563,7 @@ public class ArrayTools {
    }

    public static double[] repeat(double[] arr, int times, int maxLength) {
-        AssertTools.checkArgumentNotNull(arr);
+        AssertTools.checkArgument(Objects.nonNull(arr));
        AssertTools.checkArgument(times >= 0,
                "The number of times must be greater than or equal to zero");
        AssertTools.checkArgument(maxLength >= 0,
@@ -592,7 +592,7 @@ public class ArrayTools {
    }

    public static void fill(char[] a, int fromIndex, int toIndex, char... values) {
-        AssertTools.checkArgumentNotNull(a);
+        AssertTools.checkArgument(Objects.nonNull(a));
        if (values.length == 0) {
            return;
        }
@@ -621,7 +621,7 @@ public class ArrayTools {
    }

    public static void fill(byte[] a, int fromIndex, int toIndex, byte... values) {
-        AssertTools.checkArgumentNotNull(a);
+        AssertTools.checkArgument(Objects.nonNull(a));
        if (values.length == 0) {
            return;
        }
@@ -650,7 +650,7 @@ public class ArrayTools {
    }

    public static void fill(short[] a, int fromIndex, int toIndex, short... values) {
-        AssertTools.checkArgumentNotNull(a);
+        AssertTools.checkArgument(Objects.nonNull(a));
        if (values.length == 0) {
            return;
        }
@@ -679,7 +679,7 @@ public class ArrayTools {
    }

    public static void fill(int[] a, int fromIndex, int toIndex, int... values) {
-        AssertTools.checkArgumentNotNull(a);
+        AssertTools.checkArgument(Objects.nonNull(a));
        if (values.length == 0) {
            return;
        }
@@ -708,7 +708,7 @@ public class ArrayTools {
    }

    public static void fill(long[] a, int fromIndex, int toIndex, long... values) {
-        AssertTools.checkArgumentNotNull(a);
+        AssertTools.checkArgument(Objects.nonNull(a));
        if (values.length == 0) {
            return;
        }
@@ -737,7 +737,7 @@ public class ArrayTools {
    }

    public static void fill(float[] a, int fromIndex, int toIndex, float... values) {
-        AssertTools.checkArgumentNotNull(a);
+        AssertTools.checkArgument(Objects.nonNull(a));
        if (values.length == 0) {
            return;
        }
@@ -766,7 +766,7 @@ public class ArrayTools {
    }

    public static void fill(double[] a, int fromIndex, int toIndex, double... values) {
-        AssertTools.checkArgumentNotNull(a);
+        AssertTools.checkArgument(Objects.nonNull(a));
        if (values.length == 0) {
            return;
        }
@@ -799,7 +799,7 @@ public class ArrayTools {
    }

    private static <T> void fillInternal(@Nonnull T[] a, int fromIndex, int toIndex, @Nullable T[] values) {
-        AssertTools.checkArgumentNotNull(a);
+        AssertTools.checkArgument(Objects.nonNull(a));
        if (values == null || values.length == 0) {
            return;
        }
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/AssertTools.java
@@ -16,10 +16,15 @@

 package xyz.zhouxy.plusone.commons.util;

+import java.util.Objects;
+import java.util.Optional;
 import java.util.function.Supplier;

 import javax.annotation.Nonnull;

+import xyz.zhouxy.plusone.commons.exception.DataNotExistsException;
+import xyz.zhouxy.plusone.commons.exception.system.DataOperationResultException;
+
 /**
 * 断言工具
 *
@@ -30,91 +35,231 @@ import javax.annotation.Nonnull;
 * <pre>
 * AssertTools.checkArgument(StringUtils.hasText(str), "The argument cannot be blank.");
 * AssertTools.checkState(ArrayUtils.isNotEmpty(result), "The result cannot be empty.");
- * AssertTools.checkCondition(!CollectionUtils.isEmpty(roles), () -> new InvalidInputException("The roles cannot be empty."));
- * AssertTools.checkCondition(RegexTools.matches(email, PatternConsts.EMAIL), "must be a well-formed email address");
+ * AssertTools.checkCondition(!CollectionUtils.isEmpty(roles),
+ *     () -> new InvalidInputException("The roles cannot be empty."));
+ * AssertTools.checkCondition(RegexTools.matches(email, PatternConsts.EMAIL),
+ *     "must be a well-formed email address");
 * </pre>
 *
 * @author <a href="http://zhouxy.xyz:3000/ZhouXY108">ZhouXY</a>
 */
 public class AssertTools {

-    // #region - checkArgument
-
-    public static <T> void checkArgumentNotNull(T argument) {
-        checkCondition(argument != null, () -> new IllegalArgumentException("The argument cannot be null."));
-    }
-
-    public static <T> void checkArgumentNotNull(T argument, String errMsg) {
-        checkCondition(argument != null, () -> new IllegalArgumentException(errMsg));
-    }
-
-    public static <T> void checkArgumentNotNull(T argument, Supplier<String> messageSupplier) {
-        checkCondition(argument != null, () -> new IllegalArgumentException(messageSupplier.get()));
-    }
-
-    public static <T> void checkArgumentNotNull(T argument, String format, Object... args) {
-        checkCondition(argument != null, () -> new IllegalArgumentException(String.format(format, args)));
-    }
+    // ================================
+    // #region - Argument
+    // ================================

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

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

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

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

-    // #endregion
+    // ================================
+    // #endregion - Argument
+    // ================================

-    // #region - checkState
+    // ================================
+    // #region - State
+    // ================================

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

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

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

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

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

-    // #region - checkNotNull
+    // ================================
+    // #region - NotNull
+    // ================================

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

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

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

-    // #region - checkCondition
+    // ================================
+    // #region - Exists
+    // ================================
+
+    /** Throw {@link DataNotExistsException} if the {@code obj} is null. */
+    public static <T> T checkExists(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)
+            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)
+            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)
+            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)
+            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)
+            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)
+            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)
+            throws DataNotExistsException {
+        checkCondition(optional.isPresent(), () -> new DataNotExistsException(String.format(format, args)));
+        return optional.get();
+    }
+
+    // ================================
+    // #endregion - Exists
+    // ================================
+
+    // ================================
+    // #region - AffectedRows
+    // ================================
+
+    public static void checkAffectedRows(int expectedValue, int result) {
+        checkAffectedRows(expectedValue, result,
+                "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) {
+        checkCondition(expectedValue == result, () -> new DataOperationResultException(message));
+    }
+
+    public static void checkAffectedRows(int expectedValue, int result,
+            @Nonnull Supplier<String> messageSupplier) {
+        checkCondition(expectedValue == result,
+                () -> new DataOperationResultException(messageSupplier.get()));
+    }
+
+    public static void checkAffectedRows(int expectedValue, int result, String format, Object... args) {
+        checkCondition(expectedValue == result,
+                () -> new DataOperationResultException(String.format(format, args)));
+    }
+
+    public static void checkAffectedRows(long result, long expectedValue) {
+        checkCondition(expectedValue == result, DataOperationResultException::new);
+    }
+
+    public static void checkAffectedRows(long result, long expectedValue, String message) {
+        checkCondition(expectedValue == result, () -> new DataOperationResultException(message));
+    }
+
+    public static void checkAffectedRows(long result, long expectedValue,
+            @Nonnull Supplier<String> messageSupplier) {
+        checkCondition(expectedValue == result,
+                () -> new DataOperationResultException(messageSupplier.get()));
+    }
+
+    public static void checkAffectedRows(long result, long expectedValue, String format, Object... args) {
+        checkCondition(expectedValue == result,
+                () -> new DataOperationResultException(String.format(format, args)));
+    }
+
+    public static void checkAffectedOneRow(int result) {
+        checkAffectedRows(1, result,
+                () -> "The number of rows affected is expected to be 1, but is: " + result);
+    }
+
+    public static void checkAffectedOneRow(int result, String message) {
+        checkAffectedRows(1, result, message);
+    }
+
+    public static void checkAffectedOneRow(int result, @Nonnull Supplier<String> messageSupplier) {
+        checkAffectedRows(1, result, messageSupplier);
+    }
+
+    public static void checkAffectedOneRow(int result, String format, Object... args) {
+        checkAffectedRows(1, result, format, args);
+    }
+
+    // ================================
+    // #endregion - AffectedRows
+    // ================================
+
+    // ================================
+    // #region - Condition
+    // ================================

    public static <T extends Exception> void checkCondition(boolean condition, @Nonnull Supplier<T> e)
            throws T {
@@ -123,13 +268,19 @@ public class AssertTools {
        }
    }

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

-    // #region - private constructor
+    // ================================
+    // #region - constructor
+    // ================================

    private AssertTools() {
        throw new IllegalStateException("Utility class");
    }

+    // ================================
    // #endregion
+    // ================================
 }
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/IdGenerator.java
@@ -17,6 +17,7 @@
 package xyz.zhouxy.plusone.commons.util;

 import java.util.Map;
+import java.util.Objects;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;

@@ -40,7 +41,7 @@ public class IdGenerator {
    }

    public static String toSimpleString(UUID uuid) {
-        AssertTools.checkArgumentNotNull(uuid);
+        AssertTools.checkArgument(Objects.nonNull(uuid));
        return (uuidDigits(uuid.getMostSignificantBits() >> 32, 8) +
                uuidDigits(uuid.getMostSignificantBits() >> 16, 4) +
                uuidDigits(uuid.getMostSignificantBits(), 4) +
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/RandomTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/RandomTools.java
@@ -17,6 +17,7 @@
 package xyz.zhouxy.plusone.commons.util;

 import java.security.SecureRandom;
+import java.util.Objects;
 import java.util.Random;
 import java.util.concurrent.ThreadLocalRandom;

@@ -41,20 +42,20 @@ public final class RandomTools {
     * @return 随机字符串
     */
    public static String randomStr(@Nonnull Random random, @Nonnull char[] sourceCharacters, int length) {
-        AssertTools.checkArgumentNotNull(random, "Random cannot be null.");
-        AssertTools.checkArgumentNotNull(sourceCharacters, "Source characters cannot be null.");
+        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) {
-        AssertTools.checkArgumentNotNull(sourceCharacters, "Source characters 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(ThreadLocalRandom.current(), sourceCharacters, length);
    }

    public static String secureRandomStr(@Nonnull char[] sourceCharacters, int length) {
-        AssertTools.checkArgumentNotNull(sourceCharacters, "Source characters 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(DEFAULT_SECURE_RANDOM, sourceCharacters, length);
    }
@@ -70,20 +71,20 @@ public final class RandomTools {
     * @return 随机字符串
     */
    public static String randomStr(@Nonnull Random random, @Nonnull String sourceCharacters, int length) {
-        AssertTools.checkArgumentNotNull(random, "Random cannot be null.");
-        AssertTools.checkArgumentNotNull(sourceCharacters, "Source characters cannot be null.");
+        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) {
-        AssertTools.checkArgumentNotNull(sourceCharacters, "Source characters 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(ThreadLocalRandom.current(), sourceCharacters, length);
    }

    public static String secureRandomStr(@Nonnull String sourceCharacters, int length) {
-        AssertTools.checkArgumentNotNull(sourceCharacters, "Source characters 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(DEFAULT_SECURE_RANDOM, sourceCharacters, length);
    }
--- a/src/main/java/xyz/zhouxy/plusone/commons/util/StringTools.java
+++ b/src/main/java/xyz/zhouxy/plusone/commons/util/StringTools.java
@@ -16,6 +16,8 @@

 package xyz.zhouxy.plusone.commons.util;

+import java.util.Objects;
+
 import com.google.common.annotations.Beta;

@Beta
@@ -40,7 +42,7 @@ public class StringTools {
    }

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

--- a/src/test/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumberTests.java
+++ b/src/test/java/xyz/zhouxy/plusone/commons/model/Chinese2ndGenIDCardNumberTests.java
@@ -26,13 +26,14 @@ import java.util.regex.Matcher;
 import org.junit.jupiter.api.Test;

 import lombok.extern.slf4j.Slf4j;
+import xyz.zhouxy.plusone.commons.constant.PatternConsts;

@Slf4j
 public class Chinese2ndGenIDCardNumberTests {

    @Test
    void testPattern() {
-        Matcher matcher = Chinese2ndGenIDCardNumber.PATTERN.matcher("11010520000101111X");
+        Matcher matcher = PatternConsts.CHINESE_2ND_ID_CARD_NUMBER.matcher("11010520000101111X");
        assertTrue(matcher.matches());
        for (int i = 0; i < matcher.groupCount(); i++) {
            log.info("{}: {}", i, matcher.group(i));
@@ -42,7 +43,7 @@ public class Chinese2ndGenIDCardNumberTests {
    @Test
    void test() {
        Chinese2ndGenIDCardNumber idCardNumber = Chinese2ndGenIDCardNumber.of("11010520000101111X");
-        assertEquals("11010520000101111X", idCardNumber.getValue());
+        assertEquals("11010520000101111X", idCardNumber.value());
        assertEquals(LocalDate.of(2000, 1, 1), idCardNumber.getBirthDate());
        assertEquals(Gender.MALE, idCardNumber.getGender());
        assertEquals("110105", idCardNumber.getCountyCode());
Author	SHA1	Message	Date
ZhouXY108	cca3c8b1ee	修改身份证号的实现	2024-12-02 18:30:38 +08:00
ZhouXY108	274f2d9874	修改 ParsingFailureException 的注释	2024-12-02 18:29:34 +08:00
ZhouXY108	2e4e32af45	新增中国二代居民身份证正则常量	2024-12-02 18:29:00 +08:00
ZhouXY108	c06c486ab9	AssertTools 删除 checkArgumentNotNull 方法，新增 checkExists、checkAffectedRows、checkAffectedOneRow 方法。	2024-12-02 18:28:23 +08:00
ZhouXY108	d499433a34	新增 DataNotExistsException	2024-12-02 18:26:39 +08:00