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

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

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

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

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

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

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

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にしています。

3. ConstraintValidatorを実装する

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に適用して使ってみる

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

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

public class UserForm {

    @AlphabetOnly
    private String username;

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

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

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>

6. カスタムバリデータの実用例

6. カスタムバリデータの実用例

実務でよくあるユースケースをいくつか紹介します。

• ・パスワード強度チェック（英数字記号混在など）
• ・郵便番号や電話番号の形式
• ・日付の範囲チェック（開始日＜終了日）
• ・重複チェック（既存データとの照合）※DBアクセスには注意

Springのカスタムバリデータを使えば、複雑な業務ロジックも明確で再利用性の高い形に落とし込むことができます。

7. バリデータに依存注入（DI）したい場合

7. バリデータに依存注入（DI）したい場合

バリデータクラスにSpringの@Componentを付けておけば、DIも可能になります。ただしその場合はSpringConstraintValidatorFactoryを使うように設定しておくと安全です。

また、@AutowiredでServiceなどを注入し、外部APIやデータベースとの連携を行うことも可能ですが、パフォーマンスや依存性には注意が必要です。

まとめ

まとめ

Springカスタムバリデータの総復習

本記事ではSpring BootやSpring MVCにおけるカスタムバリデータの作成方法について詳しく解説してきました。標準のバリデーションアノテーションであるNotNullやSizeだけでは対応できない業務要件に対して独自のバリデーションルールを実装できる点がカスタムバリデータの最大の魅力です。特に業務システムやWebアプリケーション開発では入力チェックの精度が品質を大きく左右するためこの仕組みを理解しておくことは非常に重要です。

カスタムバリデータの基本構成はConstraintアノテーションを付与した独自アノテーションの作成とConstraintValidatorインタフェースを実装したバリデータクラスの作成そしてDTOやEntityへの適用という三つのステップで成り立っています。この流れをしっかり理解することでどのようなバリデーション要件にも柔軟に対応できるようになります。

実務で役立つ重要ポイント

実務でカスタムバリデータを扱う際にはいくつか重要なポイントがあります。まずnullチェックの扱いについてはNotNullなどの標準アノテーションと役割を分担することが基本です。バリデータクラスではnullの場合はtrueを返す設計にしておくことで責務を明確に分離できます。

またバリデーション処理の中でデータベースアクセスや外部API呼び出しを行う場合はパフォーマンスに十分注意する必要があります。バリデーションはリクエストごとに実行されるため重い処理を入れてしまうとアプリケーション全体のレスポンスに影響を与えます。そのためServiceクラスとの連携やキャッシュ戦略などを適切に設計することが重要になります。

さらにエラーメッセージの設計も重要な要素です。ユーザーにとって分かりやすいメッセージを表示することでユーザビリティを向上させることができます。message属性を活用して具体的な入力ルールを示すことで入力ミスを減らすことが可能です。

サンプルコードで理解を深める

ここではカスタムバリデータの流れを復習するために簡単なサンプルコードを確認してみましょう。アルファベットのみを許可するバリデーション処理の例です。

@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 {};
}

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;
        }

        return value.matches("^[A-Za-z]+$");
    }
}

実行イメージ

入力値 abcdef → 正常
入力値 abc123 → エラー
入力値 null → 正常

このようにカスタムバリデータを活用することで入力値の制御を細かく行うことができます。Spring BootやSpring MVCの開発ではDTOやFormクラスに対してバリデーションを適用することで安全で信頼性の高いシステムを構築することが可能になります。

カスタムバリデータの活用シーン

カスタムバリデータはさまざまなシーンで活用されます。例えばパスワードの強度チェックやメールアドレスの独自ルール郵便番号の形式チェック日付の範囲チェック複数項目の整合性チェックなどがあります。これらを個別に実装するのではなくアノテーションとして再利用可能な形にすることでコードの可読性と保守性が大きく向上します。

またチーム開発においても共通のバリデーションルールを統一することでバグの発生を防ぎ品質の高いコードを維持することができます。Springのバリデーション機能を正しく理解し適切に設計することがプロフェッショナルな開発者への第一歩となります。