当前位置：首页 > news >正文

身份证号码，格式校验：@IdCard（自定义注解）

news 2025/7/26 10:05:40

目标

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

校验逻辑

有效格式

符合国家标准。

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

严格校验

本文采用的校验方式，采用严格校验，第18位校验码，只能为数字或大写X，小写x无法通过校验。

不校验非空

身份证号码，校验的是格式；不校验是否为空（null 或空字符串）。如果身份证号码为空，直接通过校验；

核心代码

需要定义的内容包含三个部分：

注解@ZipCode
校验器ZipCodeValidator
校验工具类 IdCardUtil

注解：@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 com.example.core.util.IdCardUtil;
import org.springframework.util.ObjectUtils;import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;/*** 身份证号码，格式校验器*/
public class IdCardValidator implements ConstraintValidator<IdCard, String> {@Overridepublic void initialize(IdCard constraintAnnotation) {ConstraintValidator.super.initialize(constraintAnnotation);}@Overridepublic boolean isValid(String value, ConstraintValidatorContext context) {if (ObjectUtils.isEmpty(value)) {return true;}return IdCardUtil.isValid(value);}}

校验工具类

package com.example.core.util;/*** 身份证号码，校验工具类*/
public class IdCardUtil {// 每位加权因子private static final int[] power = {7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2};/*** 是格式正确的身份证号码*/public static boolean isValid(String idCard) {// null ，为假if (idCard == null) {return false;}// 非18位，为假if (idCard.length() != 18) {return false;}// 获取前17位String idCard17 = idCard.substring(0, 17);// 获取第18位String idCard18Code = idCard.substring(17, 18);// 前17位，不全部为数字，为假if (!isDigital(idCard17)) {return false;}char[] c = idCard17.toCharArray();int[] bit = convertCharToInt(c);int sum17 = getPowerSum(bit);// 将和值与11取模得到余数进行校验码判断String checkCode = getCheckCodeBySum(sum17);if (null == checkCode) {return false;}// 将身份证的第18位，与算出来的校码进行匹配，不相等就为假return idCard18Code.equals(checkCode);}/*** 数字验证*/private static boolean isDigital(String str) {return str != null && !str.isEmpty() && str.matches("^[0-9]*$");}/*** 将字符数组转为整型数组*/private static int[] convertCharToInt(char[] c) throws NumberFormatException {int[] a = new int[c.length];int k = 0;for (char temp : c) {a[k++] = Integer.parseInt(String.valueOf(temp));}return a;}/*** 将身份证的每位和对应位的加权因子相乘之后，再得到和值*/private static int getPowerSum(int[] bit) {if (power.length != bit.length) {return 0;}int sum = 0;for (int i = 0; i < bit.length; i++) {for (int j = 0; j < power.length; j++) {if (i == j) {sum = sum + bit[i] * power[j];}}}return sum;}/*** 将和值与11取模得到余数进行校验码判断** @return 校验位*/private static String getCheckCodeBySum(int sum17) {String checkCode = null;switch (sum17 % 11) {case 10:checkCode = "2";break;case 9:checkCode = "3";break;case 8:checkCode = "4";break;case 7:checkCode = "5";break;case 6:checkCode = "6";break;case 5:checkCode = "7";break;case 4:checkCode = "8";break;case 3:checkCode = "9";break;case 2:checkCode = "X";break;case 1:checkCode = "0";break;case 0:checkCode = "1";break;}return checkCode;}}

使用

@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;}

校验效果

校验工具类，单元测试

package com.example;import com.example.core.util.IdCardUtil;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;@Slf4j
public class IdCardTest {@Testvoid test() {test("110101202301024130");test("11010120230102857X");test("11010120230102857x");test("110101202301024130啊啊啊啊");}private void test(String idCard) {log.info("是否为身份证号码格式：{} = {}", idCard, IdCardUtil.isValid(idCard));}}