身份证号码，格式校验：@IdCard（Validation + Hutool）

ゞ浴缸里的玫瑰 2024-02-20 08:47 52阅读 0赞

## 目标 ##

自定义一个用于校验 `身份证号码` 格式的注解`@IdCard`，能够和现有的 `Validation` 参数校验机制兼容，使用方式和其他校验注解保持一致（使用 `@Valid` 注解接口参数）。

![在这里插入图片描述][8d5529ec4a964576ab78c9738b5dcfe4.png]

## 校验逻辑 ##

### 有效格式 ###

符合国家标准。

公民身份号码按照GB11643－1999《公民身份号码》国家标准编制，由18位数字组成：前6位为行政区划代码，第7至14位为出生日期码，第15至17位为顺序码，第18位为校验码。

### 不校验非空 ###

身份证号码注解，校验的是`格式`；不校验是否为空（null 或 空字符串）。如果身份证号码为空，此注解校验是可以通过的；

`是否校验非空`，要根据`业务逻辑`来确定；如果业务逻辑需要校验非空，则使用注解 `@NotEmpty` 。

## 校验格式的工具：Hutool ##

使用`Hutool`提供的身份证格式校验方法。

注意，Hutool 校验身份证格式，忽略`X的大小写`；也就是，大小写的X，都认为表达的是`罗马数字十`。

## 依赖 ##

1.  Validation
2.  Hutool

Validation：

<dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-validation</artifactId>
            </dependency>

Hutool：

<dependency>
                <groupId>cn.hutool</groupId>
                <artifactId>hutool-all</artifactId>
                <version>5.8.22</version>
            </dependency>

## 核心代码 ##

需要自定义的内容，包含两个部分：

1.  注解`@IdCard`
2.  校验器`IdCardValidator`

### 注解：@IdCard ###

package com.example.core.validation.idcard;
    
    import javax.validation.Constraint;
    import javax.validation.Payload;
    import java.lang.annotation.Documented;
    import java.lang.annotation.Retention;
    import java.lang.annotation.Target;
    
    import static java.lang.annotation.ElementType.FIELD;
    import static java.lang.annotation.RetentionPolicy.RUNTIME;
    
    /**
     * 身份证号码。字符串必须是格式正确的身份证号码。
     * <p>
     * {@code null} 或 空字符串，是有效的（能够通过校验）。
     * <p>
     * 支持的类型：字符串
     *
     * @author songguanxun
     * @since 1.0
     */
    @Target({
        FIELD})
    @Retention(RUNTIME)
    @Documented
    @Constraint(validatedBy = IdCardValidator.class)
    public @interface IdCard {
        
    
        /**
         * @return the error message template
         */
        String message() default "身份证号码，格式错误";
    
        /**
         * @return the groups the constraint belongs to
         */
        Class<?>[] groups() default {
        };
    
        /**
         * @return the payload associated to the constraint
         */
        Class<? extends Payload>[] payload() default {
        };
    
    }

### 校验器：IdCardValidator ###

package com.example.core.validation.idcard;
    
    import cn.hutool.core.util.IdcardUtil;
    import com.example.core.validation.ResetMessageUtil;
    import org.springframework.util.ObjectUtils;
    
    import javax.validation.ConstraintValidator;
    import javax.validation.ConstraintValidatorContext;
    
    /**
     * 身份证号码，格式校验器
     */
    public class IdCardValidator implements ConstraintValidator<IdCard, String> {
        
    
        @Override
        public void initialize(IdCard constraintAnnotation) {
        
            ConstraintValidator.super.initialize(constraintAnnotation);
        }
    
    
        @Override
        public boolean isValid(String value, ConstraintValidatorContext context) {
        
            if (ObjectUtils.isEmpty(value)) {
        
                return true;
            }
    
            if (value.contains(" ")) {
        
                ResetMessageUtil.reset(context, "身份证号码，格式错误：不能包含空格");
                return false;
            }
    
            return IdcardUtil.isValidCard(value);
        }
    
    }

## 使用 ##

`@IdCard` 放在需要校验格式的 `身份证号码` 字段上。

package com.example.web.response.model.param;
    
    import com.example.core.validation.idcard.IdCard;
    import io.swagger.v3.oas.annotations.media.Schema;
    import lombok.Data;
    
    @Data
    @Schema(name = "新增用户Param")
    public class UserAddParam {
        
        
        // 其他字段
    
        @IdCard
        @Schema(description = "身份证号码", example = "110101202301024130")
        private String idCard;
    
    }

## 补充代码 ##

### ResetMessageUtil：重置提示信息工具类 ###

package com.example.core.validation;
    
    import javax.validation.ConstraintValidatorContext;
    
    /**
     * 参数校验 - 重置提示信息工具类
     */
    public class ResetMessageUtil {
        
    
        /**
         * 重置提示信息
         */
        public static void reset(ConstraintValidatorContext context, String message) {
        
            context.disableDefaultConstraintViolation();
            context.buildConstraintViolationWithTemplate(message).addConstraintViolation();
        }
    
    }

## 校验效果 ##

### 校验工具类（Hutool），测试 ###

对Hutool提供的身份证校验方法，进行测试。

package com.example;
    
    import cn.hutool.core.util.IdcardUtil;
    import lombok.extern.slf4j.Slf4j;
    import org.junit.jupiter.api.Test;
    
    /**
     * 身份证号码校验测试（使用Hutool）
     */
    @Slf4j
    public class IdCardHutoolTest {
        
    
        @Test
        void test() {
        
            test("110101202301024130");
            test("11010120230102857X");
            test("11010120230102857x");
            test("110101202301024130啊啊啊啊");
        }
    
    
        private void test(String idCard) {
        
            boolean validCard = IdcardUtil.isValidCard(idCard);
            log.info("是否为身份证号码格式：{} = {}", idCard, validCard);
        }
    
    }

能够正确校验身份证格式。  
![在这里插入图片描述][da1871834f0a4219b5657802baba582d.png]

### 接口测试 ###

#### 校验结果为 成功 ####

![在这里插入图片描述][d48b7a60d285492ea49df08cc1a6e3b3.png]  
![在这里插入图片描述][52c7cdf9a2c24c87953911f4cf68d97a.png]

![在这里插入图片描述][770a412d59e54f6897a1b42e4f2e4d6f.png]

#### 校验结果为 失败 ####

![在这里插入图片描述][4020b945886443459bf7a52fdfda3878.png]

![在这里插入图片描述][513229b4fb0d4e8aafbeb27d963ee55e.png]

[8d5529ec4a964576ab78c9738b5dcfe4.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/20/8af0ede34920424d97421ff96df393f2.png
[da1871834f0a4219b5657802baba582d.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/20/dab78835db8c4c61b63426b4e7447088.png
[d48b7a60d285492ea49df08cc1a6e3b3.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/20/81606d7166c14b4c98511460551716aa.png
[52c7cdf9a2c24c87953911f4cf68d97a.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/20/6060a74450a642f1810435b525786e14.png
[770a412d59e54f6897a1b42e4f2e4d6f.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/20/421e768e02a54db9be277d336df5d836.png
[4020b945886443459bf7a52fdfda3878.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/20/15518702b506466e921dced8da730428.png
[513229b4fb0d4e8aafbeb27d963ee55e.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/20/b1b3a8b96e3e450fba52e2826fcaa86a.png