SpringBoot Validation 自定義郵箱校驗

一、背景

1.1 為啥自定義郵箱校驗

validation 原生的 @Email 註解適合快速校驗郵箱格式，但由於其侷限性比如”123@123可以透過校驗“，不適用於所有場景，如果專案需要高可靠性的郵箱驗證，建議自定義郵箱格式校驗

1.2 如何自定義郵箱校驗

1. 首先自定義校驗註解

2. 然後自定義校驗邏輯

3. 最後測試正反例狀態

二、Action

2.1 自定義校驗註解

可以透過實現 javax.validation.Constraint 自定義一個校驗註解。

package com.pilot.meterage.web.utils.validation.annotation;


import com.pilot.meterage.web.utils.validation.constraint.EmailValidator;

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 自定義郵箱校驗註解
 *
 * @author yangp
 * @version 1.0
 * @date 2024/11/16 10:00
 */
@Constraint(validatedBy = EmailValidator.class) // 指定校驗器
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER}) // 適用範圍
@Retention(RetentionPolicy.RUNTIME) // 註解保留時間
public @interface ValidEmail {
    String message() default "郵箱格式不正確";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

2.2 自定義郵箱校驗器

實現 jakarta.validation.ConstraintValidator 介面，自定義校驗邏輯：

package com.pilot.meterage.web.utils.validation.constraint;

import com.pilot.meterage.web.utils.validation.annotation.ValidEmail;

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import java.util.regex.Pattern;

/**
 * 自定義郵箱校驗器
 *
 * @author yangp
 * @version 1.0
 * @date 2024/11/16 10:00
 */
public class EmailValidator implements ConstraintValidator<ValidEmail, String> {

    /**
     * 定義郵箱格式的正規表示式
     */
    private static final String EMAIL_REGEX = "^[a-zA-Z0-9_.-]+@[a-zA-Z0-9-]+(\.[a-zA-Z]{2,6})+$";

    private static final Pattern EMAIL_PATTERN = Pattern.compile(EMAIL_REGEX);

    @Override
    public boolean isValid(String email, ConstraintValidatorContext context) {
        // 空值時的校驗邏輯（可按需求調整） 空值視為無效
        if (email == null || email.trim().isEmpty()) {
            return false;
        }

        // 匹配正規表示式
        return EMAIL_PATTERN.matcher(email).matches();
    }
}

2.3 在實體類中使用註解

使用自定義註解 @ValidEmail 校驗郵箱欄位：

public class Tenant {

    @ValidEmail(message = "請輸入有效的郵箱地址")
    private String email;

    // Getter 和 Setter
    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

2.4 測試驗證

透過 Validator 工具執行驗證，返回校驗結果：

import jakarta.validation.ConstraintViolation;
import jakarta.validation.Validation;
import jakarta.validation.Validator;
import jakarta.validation.ValidatorFactory;

import java.util.Set;

public class Main {
    public static void main(String[] args) {
        // 建立 Validator 工廠
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        Validator validator = factory.getValidator();

        // 建立待校驗物件
        Tenant tenant = new Tenant();
        tenant.setEmail("invalid_email.com"); // 測試用的無效郵箱

        // 執行校驗
        Set<ConstraintViolation<Tenant>> violations = validator.validate(tenant);

        // 輸出校驗結果
        if (!violations.isEmpty()) {
            for (ConstraintViolation<Tenant> violation : violations) {
                System.out.println(violation.getMessage());
            }
        } else {
            System.out.println("郵箱驗證透過！");
        }
    }
}

2.5 執行結果

測試用例1

• 輸入：tenant.setEmail("example@test.com");

• 結果：郵箱驗證透過！

測試用例2

• 輸入：tenant.setEmail("invalid_email.com");

• 結果：請輸入有效的郵箱地址

測試用例3

• 輸入：tenant.setEmail("123@123");

• 結果：請輸入有效的郵箱地址