手机号码，格式校验：@Phone（自定义注解）

超、凢脫俗 2023-10-16 16:56 61阅读 0赞

## 需求 ##

`新增接口` 和 `修改接口` 中，`手机号码`的格式校验是普遍需要的。

在每个`手机号码`字段上添加`正则表达式校验注解`来实现校验，重复书写，容易出错；在不同的手机号码字段上，可能使用了不同的校验规则，无法有效统一校验规则。

## 目标 ##

自定义一个用于校验`手机号码格式`的注解`@Phone`，能够和现有的 `Validation` 兼容，使用方式和其他校验注解保持一致。

## 校验逻辑 ##

### 有效格式 ###

1.  不能包含空格；
2.  应为11位数字；

### 不校验非空 ###

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

这样设计是为了，将手机号码`是否允许为空`，交给接口（业务逻辑）来决定；因为在不同的业务逻辑中，有时手机号码字段可以为空，有时不能为空。

但是，无论手机号码字段是否可以为空，只要客户端传递了手机号码，就应该保证格式是正确的。

Validation本身提供的@Email注解，也是这样的处理逻辑。

注：手机号码，使用字符串类型（Integer类型装不下11位的数值）。

## 核心代码 ##

需要定义的内容包含两个部分：注解`@Phone`和 校验器`PhoneValidator`。

### 注解：@Phone ###

package com.example.core.validation.phone.strict;
    
    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;
    
    /**
     * 字符串必须是格式正确的手机号码。正确格式为：11位数字。
     * <p>
     * {@code null} 或 空字符串，是有效的（能够通过校验）。
     * <p>
     * 支持的类型：字符串
     *
     * @author songguanxun
     * @since 1.0
     */
    @Target({
        FIELD})
    @Retention(RUNTIME)
    @Documented
    @Constraint(validatedBy = PhoneValidator.class)
    public @interface Phone {
        
    
        /**
         * @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 {
        };
    
        /**
         * 手机号码的详细描述。
         * <p>
         * 用于用户提示中，当页面中存在多个手机号码时，帮助用户更好的区分是哪个手机号码填错了。
         */
        String description() default "手机号码";
    }

### 校验器：PhoneValidator ###

package com.example.core.validation.phone.strict;
    
    import org.springframework.util.ObjectUtils;
    
    import javax.validation.ConstraintValidator;
    import javax.validation.ConstraintValidatorContext;
    import java.util.regex.Pattern;
    
    /**
     * 手机号码格式校验器
     */
    public class PhoneValidator implements ConstraintValidator<Phone, String> {
        
    
        // 手机号码的详细描述。
        private String description;
    
    
        @Override
        public void initialize(Phone constraintAnnotation) {
        
            ConstraintValidator.super.initialize(constraintAnnotation);
            description = constraintAnnotation.description();
        }
    
    
        @Override
        public boolean isValid(String value, ConstraintValidatorContext context) {
        
            if (ObjectUtils.isEmpty(value)) {
        
                return true;
            }
    
            if (value.contains(" ")) {
        
                String message = String.format("%s，格式错误：不能包含空格", description);
                resetMessage(context, message);
                return false;
            }
    
            if (!isPhone(value)) {
        
                String message = String.format("%s，格式错误", description);
                resetMessage(context, message);
                return false;
            }
    
            return true;
        }
    
    
        // 格式为：11位数字
        private static final Pattern PATTERN = Pattern.compile("^\\d{11}$");
    
    
        /**
         * 是手机号码
         */
        private boolean isPhone(CharSequence input) {
        
            return PATTERN.matcher(input).matches();
        }
    
    
        /**
         * 重置提示信息
         */
        private void resetMessage(ConstraintValidatorContext context, String messageTemplate) {
        
            context.disableDefaultConstraintViolation();
            context.buildConstraintViolationWithTemplate(messageTemplate).addConstraintViolation();
        }
    
    }

## 使用 ##

`@Phone` 放在需要校验格式的 `手机号码` 字段上。

### 新增用户Param ###

package com.example.web.response.model.param;
    
    import com.example.core.validation.phone.strict.Phone;
    import io.swagger.v3.oas.annotations.media.Schema;
    import lombok.Data;
    
    import javax.validation.constraints.Email;
    import javax.validation.constraints.NotBlank;
    import javax.validation.constraints.NotEmpty;
    
    @Data
    @Schema(name = "新增用户Param")
    public class UserAddParam {
        
    
        @NotBlank(message = "姓名，不能为空")
        @Schema(description = "姓名", example = "张三")
        private String name;
    
        @Phone
        @NotEmpty(message = "手机号码，不能为空")
        @Schema(description = "手机号码", example = "18612345678")
        private String phone;
    
        @Email
        @Schema(description = "电子邮箱", example = "zhangsan@example.com")
        private String email;
    
    }

### 编辑用户Param ###

package com.example.web.response.model.param;
    
    import com.example.core.validation.phone.strict.Phone;
    import io.swagger.v3.oas.annotations.media.Schema;
    import lombok.Data;
    
    import javax.validation.constraints.Email;
    import javax.validation.constraints.NotBlank;
    import javax.validation.constraints.NotEmpty;
    
    @Data
    @Schema(name = "编辑用户Param")
    public class UserEditParam {
        
    
        @NotBlank(message = "姓名，不能为空")
        @Schema(description = "姓名", example = "张三")
        private String name;
    
        @Phone(description = "编辑用户-手机号码")
        @NotEmpty(message = "手机号码，不能为空")
        @Schema(description = "手机号码", example = "18612345678")
        private String phone;
    
        @Email
        @Schema(description = "电子邮箱", example = "zhangsan@example.com")
        private String email;
    
    }

## 校验效果 ##

### 输入包含空格 ###

![在这里插入图片描述][0501aba9ed314de393f660e1cdcfc777.png]

### 输入非数字 ###

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

### 输入超过11位 ###

![在这里插入图片描述][7df0cbbc617048a6a2422fa25965c200.png]

### 指定 `手机号码的详细描述` ###

![在这里插入图片描述][322e8e2f69654134be0a917f0b9ab608.png]

[0501aba9ed314de393f660e1cdcfc777.png]: https://img-blog.csdnimg.cn/0501aba9ed314de393f660e1cdcfc777.png
[8dd151794e02493db940878072bd5aa6.png]: https://img-blog.csdnimg.cn/8dd151794e02493db940878072bd5aa6.png
[7df0cbbc617048a6a2422fa25965c200.png]: https://img-blog.csdnimg.cn/7df0cbbc617048a6a2422fa25965c200.png
[322e8e2f69654134be0a917f0b9ab608.png]: https://img-blog.csdnimg.cn/322e8e2f69654134be0a917f0b9ab608.png