在 spring boot 中校验身份证号,最标准且可维护的做法是引入 hibernate-validator 依赖,并在实体类字段上添加自定义的 @valididcard 注解。该注解底层通过正则表达式匹配 18 位或 15 位身份证格式,并增加了对校验码(最后一位)的合法性验证,从而确保输入的数据既符合格式规范又具备逻辑有效性。

如何定义支持校验码验证的自定义注解
要实现精确的身份证号校验,不能仅依赖简单的正则,必须处理校验码。我们需要创建一个名为 ValidIdCard 的注解,并将其关联到一个实现了 ConstraintValidator 接口的校验器类中。这个校验器会接收用户输入的字符串,先判断是否为空,再使用正则进行格式初筛,最后通过加权求和算法验证第 18 位的校验码是否正确。

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.*;
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Constraint(validatedBy = IdCardValidator.class)
public @interface ValidIdCard {
String message() default "身份证号格式不正确";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}
import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import java.util.regex.Pattern;
public class IdCardValidator implements ConstraintValidator<ValidIdCard, String> {
private static final Pattern PATTERN = Pattern.compile("^(\d{6})(19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$");
@Override
public boolean isValid(String value, ConstraintValidatorContext context) {
if (value == null || value.isEmpty()) return true; // 由 @NotBlank 处理空值
if (!PATTERN.matcher(value).matches()) return false;
int[] w = {7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2};
char[] checkCode = {'1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'};
int sum = 0;
for (int i = 0; i < 17; i++) {
sum += (value.charAt(i) - '0') * w[i];
}
return checkCode[sum % 11] == Character.toUpperCase(value.charAt(17));
}
}
上述代码定义了校验的核心逻辑。当 Spring MVC 接收到请求时,如果字段未通过此校验,将自动抛出 MethodArgumentNotValidException,你可以通过全局异常处理器将其转换为统一的 JSON 错误响应。这种解耦方式使得业务代码无需手动编写复杂的判断语句。
如何在 Controller 层启用参数绑定与校验
定义好注解后,需要在 Controller 的方法参数中使用 @Valid 或 @Validated 来触发校验机制。通常我们会创建一个 DTO(数据传输对象)来接收前端传来的数据,并在该 DTO 的 idCard 字段上应用我们刚才定义的 @ValidIdCard 注解。这样,Spring 会在方法执行前自动完成校验工作。

import lombok.Data;
import javax.validation.constraints.NotBlank;
@Data
public class UserRegisterDTO {
@NotBlank(message = "姓名不能为空")
private String name;
@ValidIdCard(message = "身份证号无效")
private String idCard;
}
<pre class="brush:php;toolbar:false;">import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;
@RestController
@RequestMapping("/api/users")
public class UserController {
@PostMapping("/register")
public String register(@Valid @RequestBody UserRegisterDTO dto) {
return "注册成功:" + dto.getName();
}
}
在这个示例中,@Valid 注解告诉 Spring 对 UserRegisterDTO 对象进行校验。如果传入的身份证号不符合规则,Spring 会拦截请求并返回 400 Bad Request 状态码及具体的错误信息。这种方式确保了进入业务逻辑层的数据都是经过严格验证的,提高了系统的安全性和健壮性。
当身份证号包含 X 时校验器如何处理大小写
在实际应用中,身份证号的最后一位校验码如果是 10,通常会用罗马数字 'X' 表示。用户在输入时可能会使用小写 'x' 或大写 'X'。我们的 IdCardValidator 需要能够兼容这两种情况。在之前的校验逻辑中,我们通过 Character.toUpperCase() 将输入的第 18 位字符统一转换为大写,再与预定义的校验码数组进行比对。这意味着无论用户输入的是 'x' 还是 'X',只要前面的 17 位数字计算出的校验结果正确,校验就会通过。


















