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

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

news 2025/8/10 21:43:40

需求

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

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

目标

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

校验逻辑

有效格式

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

不校验非空

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

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

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

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

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

核心代码

注解：@Phone

package com.example.core.validation.phone;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;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;@Overridepublic void initialize(Phone constraintAnnotation) {ConstraintValidator.super.initialize(constraintAnnotation);description = constraintAnnotation.description();}@Overridepublic 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.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.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;}