Springのカスタムバリデータ作成を完全ガイド！@ConstraintとConstraintValidatorの使い方

カスタムバリデータ作成：@Constraint／ConstraintValidator 実装手順

先生と生徒の会話形式で理解しよう

生徒

「@NotNullとか@Sizeみたいなアノテーション以外に、オリジナルのバリデーションって作れますか？」

先生

「Springでは自分でバリデーションアノテーションを定義して、独自のルールを実装できますよ。」

生徒

「自作できるんですね！どんな時に使うんですか？」

先生

「たとえば『特定の値だけOK』『2つの値が一致している』みたいな、標準のアノテーションでは足りないときに使います。今日はその作り方を一緒に見ていきましょう。」

1. カスタムバリデータを作る流れ

Springでカスタムバリデーションアノテーションを作成するには、以下の3ステップが必要です。

① アノテーションの作成（@Constraint付き）
② バリデータクラスの実装（ConstraintValidatorインタフェース）
③ DTOやEntityに適用

今回は「値がアルファベットのみかどうか」を検証する@AlphabetOnlyというカスタムバリデータを例に進めます。

2. アノテーションを定義する

まずは自作のバリデーションアノテーションを定義します。@Constraintアノテーションで、どのバリデータクラスを使うか指定します。


@Documented
@Constraint(validatedBy = AlphabetOnlyValidator.class)
@Target({ ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
public @interface AlphabetOnly {
    String message() default "アルファベットのみを入力してください";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

このアノテーションはフィールドに対して使えるようにElementType.FIELDにしています。

将来を見据えて、＋αのスキルを身につけたい方へ

JavaやLinuxを学んでいても、「このままで市場価値は上がるのか」「キャリアの選択肢を広げたい」と感じる方は少なくありません。

AIを学ぶならアイデミープレミアム

3. ConstraintValidatorを実装する

次に、実際のチェックロジックをConstraintValidatorインタフェースで実装します。第一引数にアノテーション型、第二引数に対象の型を指定します。


public class AlphabetOnlyValidator implements ConstraintValidator<AlphabetOnly, String> {

    @Override
    public void initialize(AlphabetOnly constraintAnnotation) {
        // 初期化処理が必要ならここに書く
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null) return true; // @NotNullと併用する前提
        return value.matches("^[A-Za-z]+$");
    }
}

nullチェックは別のアノテーション（例：@NotNull）で行う前提で、nullならtrueを返します。

4. DTOに適用して使ってみる

あとは通常のアノテーションと同じように、DTOやFormクラスのフィールドに付けるだけです。


public class UserForm {

    @AlphabetOnly
    private String username;

    // その他フィールド...
}

5. Controllerでの使い方とエラーメッセージの表示

Controllerでは@Validや@Validatedを使ってバリデーションを実行します。


@PostMapping("/submit")
public String submit(@Valid UserForm form, BindingResult result) {
    if (result.hasErrors()) {
        return "formPage";
    }
    return "success";
}

Thymeleafでエラー表示するHTMLコードの例は次のようになります。


<div>
    <label>ユーザー名</label>
    <input type="text" th:field="*{username}" />
    <div th:if="${#fields.hasErrors('username')}" th:errors="*{username}"></div>
</div>