For AI agents: the complete documentation index is available at /Practical-Introduction-to-Spring-Boot/llms.txt, the full documentation bundle is available at /Practical-Introduction-to-Spring-Boot/llms-full.txt, and this page is available as Markdown at /Practical-Introduction-to-Spring-Boot/SpringBoot入門/バリデーション入門.md.

Spring Boot バリデーション実践入門

講義の区切り

基本編の目安は 90 分です。終了条件は「不正入力を400で拒否」です。 発展内容・次回の目安: 独自制約と多言語対応。基本の確認後に取り組んでください。 準備と前後の章は 学習ガイド で確認できます。

この教材について

対象者と到達目標

  • 基本的な Spring Boot アプリを作ったことはあるが、バリデーションを体系的に学んでいない人
  • Spring Boot プロジェクトの基礎設計をする人

入力値に制約を定義し、妥当な入力では処理を続け、不正な入力には HTTP 400 を返せるようになることを目指します。

事前準備と読み方

プロジェクト作成 と同じ方法で、新しい Maven / Java 21 プロジェクトを作ります。 Spring Boot は 4.0 系、パッケージ名は dev.mikoto2000.springboot.validation.workshop.firststep にします。 依存関係に Spring Web、Validation、Lombok を選んでください。 Validation は、制約アノテーションを実際に検証するために必要です。

まず「基本のバリデーション」でリクエストの成功・失敗を確認します。 次に「バリデーションエラーの返却」で応答を統一します。 独自制約と多言語対応は発展内容なので、基本の確認後に進めても構いません。

なぜバリデーションが必要か

  • バリデーションは、入力が API の仕様(必須、文字数、形式など)を満たすか確認する処理
  • バリデーションを行い、不正な状態を Service に渡さないことで、Controller 以降がビジネスロジックに集中できる

Spring Boot では、制約アノテーションを使ってリクエストの入力値を検証できます。

基本のバリデーション

まず、入力項目ごとに値を検証します。項目を受け取る引数やフィールドに制約アノテーションを付け、検証する条件を定義します。

  • @RequestParam に直接定義
  • @RequestBody のバリデーション定義(Bean のフィールドにバリデーション定義)
  • デフォルトアノテーションの一例

代表的な制約は次のとおりです。

制約確認すること
@NotNullnull ではない
@NotBlank文字列が null・空文字・空白だけではない
@SizeString の長さやコレクションの要素数が指定範囲内
@Min / @Max数値が指定範囲内
@Pattern文字列が正規表現に一致する

String の @Size は String.length() と同じ UTF-16 コードユニット単位です。見た目の文字数や UTF-8 のバイト数とは異なります。例えば "😀" は1コードポイントですが、長さは2です。入力仕様で必要な単位を決め、表示上の文字数を検証する独自制約は発展内容として扱います。

@Size や @Pattern は null を許可します。必須にしたい場合は @NotNull などを組み合わせます。

@Length は Hibernate Validator 固有のアノテーションで、文字列長を @Size と同様に検証します。標準の Bean Validation の範囲で書きたい場合は @Size を使ってください。以下の例は Hibernate Validator の @Length を使っています。 ここでの DTO は値を受け渡す Java オブジェクトであり、Spring が管理する Bean として登録する必要はありません。

@RequestParam に直接定義

次のように、引数にアノテーションをつけることでバリデーションを定義する。

package dev.mikoto2000.springboot.validation.workshop.firststep.controller;

import org.hibernate.validator.constraints.Length;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import jakarta.validation.constraints.Pattern;

/**
 * EchoController
 */
@RestController
public class EchoController {

  /**
   * 引数を直接バリデーション。
   *
   * @param message 文字列
   *              - 必須ではない
   *              - デフォルト値は "0"
   *              - 1文字以上10文字以下
   *              - 数字のみ
   * @return 引数に改行文字を付与して返す
   */
  @GetMapping("/number-echo")
  public String numberEcho(
      @RequestParam(defaultValue = "0")
      // 文字列の長さは 1 から 10 とする
      @Length(min = 1, max = 10)
      // 文字は、正規表現 `[0-9]*` にマッチする
      @Pattern(regexp = "[0-9]*")
      String message) {
    return message + "\n";
  }
}

動作確認

アプリを ./mvnw spring-boot:run で起動し、別のターミナルから確認します。

curl -i "http://localhost:8080/number-echo?message=123"
curl -i "http://localhost:8080/number-echo?message=123a"
curl -i "http://localhost:8080/number-echo?message=12345678901"
curl -i "http://localhost:8080/number-echo"
入力期待する結果理由
123200、本文は 123 と改行数字のみ、1〜10 文字
123a400数字以外を含む
11 桁の数字400上限の 10 文字を超える
パラメータ省略200、本文は 0 と改行デフォルト値が使われる

defaultValue があるため、空の値も 0 に置き換わります。 正規表現 [0-9]* 自体は空文字にも一致します。@Length(min = 1) は1文字以上という制約を表しますが、この API の空値は検証前に 0 へ置き換わるため、空値を送っても長さ違反にはなりません。 defaultValue を指定すると、required = false の指定を省いてもクエリパラメータを省略できます。 まず HTTP ステータスを確認してください。エラー本文は設定によって異なり、スタックトレースが必ず含まれるわけではありません。 この例は Spring MVC のメソッド検証を使うため、Controller のクラスに @Validated は付けません。 公式資料の検証方式 も参照できます。

@RequestBody のバリデーション定義

次のように、 @RequestBody に @Valid を付与することで、その Bean のバリデーション定義を検証する。

そして、Bean のフィールドに、バリデーション定義を付与する。

BeanEchoController.java:

package dev.mikoto2000.springboot.validation.workshop.firststep.controller;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import dev.mikoto2000.springboot.validation.workshop.firststep.bean.ValidationExampleBean;
import jakarta.validation.Valid;

/**
 * BeanEchoController
 */
@RestController
public class BeanEchoController {

  /**
   * Bean 定義でバリデーション。
   *
   * @param bean リクエストボディの JSON をマッピングした Bean
   *            - 各フィールドは null 不可(ValidationExampleBean の定義を参照)
   * @return 引数を Lombok の toString() で文字列化して改行文字を付与して返す
   */
  @PostMapping("/bean-echo")
  public String beanEcho(
      @Valid @RequestBody ValidationExampleBean bean) {
    return bean.toString() + "\n";
  }
}

ValidationExampleBean.java:

package dev.mikoto2000.springboot.validation.workshop.firststep.bean;

import jakarta.validation.constraints.NotNull;
import lombok.Data;

/**
 * ValidationExampleBean
 */
@Data
public class ValidationExampleBean {
  @NotNull
  private String stringValue;
  @NotNull
  private Integer integerValue;
  @NotNull
  private Double doubleValue;
}

リクエストボディの動作確認

curl -i -X POST -H 'Content-Type: application/json' http://localhost:8080/bean-echo -d '{"stringValue":"hello","integerValue":1,"doubleValue":1.5}'
curl -i -X POST -H 'Content-Type: application/json' http://localhost:8080/bean-echo -d '{"stringValue":null,"integerValue":1,"doubleValue":1.5}'

最初は 200、次は stringValue の必須違反で 400 になります。 @Valid を外すとフィールドの制約は検証されません。 @NotNull では空文字は許可されるため、空文字も拒否したい項目は @NotBlank を使います。

バリデーションエラーの返却

バリデーションエラーは、一元管理するのが楽なので、その方法を紹介する。

  • advice によるバリデーションエラー返却の一元化

advice によるバリデーションエラー返却の一元化

  • エラー本文は環境設定に依存するため、API として返す項目を明示的に決める
  • また、バリデーションエラーの構造は全エンドポイントで統一されていることがほとんど
  • ⇒ @RestControllerAdvice を用いてバリデーションエラー返却の一元化が可能

@RestControllerAdvice の定義

@RestControllerAdvice は、複数の Controller で発生する例外を共通処理にまとめる仕組みです。 今回は次の 3 種類を扱います。JSON の読み取り失敗と、読み取った値の制約違反は異なる段階です。

例外この教材で発生する場面
HandlerMethodValidationException/number-echo の引数制約違反
MethodArgumentNotValidException/bean-echo の DTO の制約違反
HttpMessageNotReadableExceptionJSON が壊れている、型に変換できない

まず応答用 DTO を作成してください。 ここでは Java の record を使います。宣言した項目を持ち、コンストラクタと値の取得メソッドが生成されるため、Lombok は不要です。

bean/ValidationError.java
package dev.mikoto2000.springboot.validation.workshop.firststep.bean;

public record ValidationError(String field, String message) {}
bean/ValidationErrors.java
package dev.mikoto2000.springboot.validation.workshop.firststep.bean;

import java.util.List;

public record ValidationErrors(List<ValidationError> errors) {}

この章では制約違反の項目名と説明に絞り、独自 DTO の errors 配列を返します。標準メンバーを使う形式は RFC 9457 エラー返却入門 で扱います。

続いて controller/advice/ValidationExceptionHandler.java を作成します。 HandlerMethodValidationException は入力の制約違反と戻り値の制約違反の両方で発生します。入力の違反は 400、戻り値の違反は 500 にし、500 の本文には制約の詳細を出しません。詳細は「例外処理・エラー応答入門」を参照してください。

package dev.mikoto2000.springboot.validation.workshop.firststep.controller.advice;

import java.util.ArrayList;
import java.util.List;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.method.annotation.HandlerMethodValidationException;

import dev.mikoto2000.springboot.validation.workshop.firststep.bean.ValidationError;
import dev.mikoto2000.springboot.validation.workshop.firststep.bean.ValidationErrors;
import lombok.extern.slf4j.Slf4j;

/**
 * ValidationExceptionHandler
 */
@Slf4j
@RestControllerAdvice
public class ValidationExceptionHandler {

  /**
   * メソッド引数と戻り値のバリデーションエラーを処理するハンドラ。
   * @return ValidationErrors
   */
  @ExceptionHandler(HandlerMethodValidationException.class)
  public ResponseEntity<ValidationErrors> handleMethodValidationException(HandlerMethodValidationException e) {
    if (e.isForReturnValue()) {
      log.error("戻り値が制約に違反しました", e);
      var error = new ValidationError(null, "サーバー内部でエラーが発生しました");
      return ResponseEntity.internalServerError().body(new ValidationErrors(List.of(error)));
    }

    log.info("handleMethodValidationException: {}", e);

    List<ValidationError> errors = new ArrayList<>();

    for (var error : e.getParameterValidationResults()) {
      String field = error.getMethodParameter().getParameterName();

      List<ValidationError> fieldErrors = error.getResolvableErrors().stream()
          .map(ve -> new ValidationError(field, ve.getDefaultMessage()))
          .toList();

      errors.addAll(fieldErrors);
    }

    for (var error : e.getCrossParameterValidationResults()) {
      errors.add(new ValidationError(null, error.getDefaultMessage()));
    }
    return ResponseEntity.badRequest().body(new ValidationErrors(errors));
  }

  /**
   * メソッド引数の bean のバリデーションエラーを処理するハンドラ。
   * @return ValidationErrors
   */
  @ExceptionHandler(MethodArgumentNotValidException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  public ValidationErrors handleMethodArgumentNotValidException(MethodArgumentNotValidException e) {

    log.info("handleMethodArgumentNotValidException: {}", e);

    List<ValidationError> errors = e.getFieldErrors().stream()
        .map((error) -> new ValidationError(error.getField(), error.getDefaultMessage()))
        .toList();

    return new ValidationErrors(errors);
  }

  /**
   * シンタックスエラーなど、そもそも正しくないリクエストだった場合に処理するハンドラ。
   * @return ValidationErrors
   */
  @ExceptionHandler(HttpMessageNotReadableException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  public ValidationErrors handleHttpMessageNotReadableException(HttpMessageNotReadableException e) {
    log.info("handleHttpMessageNotReadableException: {}", e);

    List<ValidationError> errors = List.of(new ValidationError(null, "JSON の形式または値の型が不正です"));

    return new ValidationErrors(errors);
  }
}

共通エラー応答の確認

再起動後、/bean-echo に stringValue=null のリクエストを送ると、400 と次のような本文が返ります。

{"errors":[{"field":"stringValue","message":"値を入力してください。"}]}

メッセージは設定した言語とメッセージ定義で変わります。確認するのは、errors の中に項目名と説明が入ることです。

/number-echo に message=123a を送ると、引数制約違反も同じ形式の 400 になります。field には引数名 message が入ります。

curl -i "http://localhost:8080/number-echo?message=123a"

壊れた JSON も 400 になり、内部の例外メッセージを本文へ直接出さないことを確認してください。field: null は、エラーがリクエスト本文全体に関係し、特定の項目に結び付かないことを示します。

基本編はここで一区切りです。独自制約と多言語対応も試す方は、次の発展内容へ進んでください。

カスタムバリデーション(発展)

基本のバリデーションで足りない場合、ロジックを自分で書くことになる。 相関チェックや、単項目チェックでもデフォルトで足りないものなど。

  • 相関チェック(複数項目の組み合わせ)
  • カスタムバリデーターの作成

相関チェック(複数項目の組み合わせ)

@AssertTrue を付けた getter で、複数項目の組み合わせを確認できます。 これは getter のプロパティ制約です。クラス自体に独自アノテーションを付けるクラスレベル制約とは区別します。

isXxx メソッドに、 @AssertTrue を付与し、バリデーション結果を true/false で返却する。

package dev.mikoto2000.springboot.validation.workshop.firststep.bean;

import jakarta.validation.constraints.AssertTrue;
import jakarta.validation.constraints.NotNull;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * CalcInfo
 */
@AllArgsConstructor
@NoArgsConstructor
@Data
public class CalcInfo {

  @NotNull
  private Double left;
  @NotNull
  private Double right;
  @NotNull
  private Operation operation;

  public enum Operation {
    ADD,
    SUBTRACT,
    MULTIPLY,
    DIVIDE
  }

  /**
   * 割り算はゼロ除算してはいけない。
   */
  @AssertTrue(message = "Division by zero is not allowed.")
  public boolean isValid() {
    // 必須項目の null は @NotNull に任せる
    if (operation == null || right == null) {
      return true;
    }
    // 割り算、かつ、右辺がゼロの場合は不正とする
    if (operation == Operation.DIVIDE && right == 0) {
      return false;
    }
    return true;
  }
}

この制約は、@Valid @RequestBody CalcInfo を引数に持つ Controller で検証できます。 DIVIDE と right=0 の組み合わせは違反、それ以外の演算はこの相関チェックを通ります。 isValid() は JavaBeans の valid プロパティの getter なので、違反のプロパティ名は valid になります。 基本編で追加した Advice を使うと、400応答の errors[].field にも valid が入ります。 入力項目の right ではなく相関チェックの結果を指すため、原因はメッセージの Division by zero is not allowed. と合わせて確認してください。 入力項目に違反を関連付けたい場合は、独自のクラスレベル制約で ConstraintValidatorContext の addPropertyNode("right") を使う方法があります。クラスレベル制約にするだけでは入力項目への関連付けは行われません。

カスタムバリデーター

デフォルトで提供されているアノテーションでは不十分な場合、自分でアノテーションを作ることもできる。

次の例は、整数の「0〜100、または 255」を許可する独自制約です。 標準の範囲制約と組み合わせると 255 が拒否されるため、範囲と例外値の判断をひとつのバリデーターにまとめます。

package dev.mikoto2000.springboot.validation.workshop.firststep.bean;

import dev.mikoto2000.springboot.validation.workshop.firststep.validation.constraints.RangeEx;
import jakarta.validation.constraints.NotNull;
import lombok.Data;

/**
 * BatteryStatus
 */
@Data
public class BatteryStatus {
  // バッテリー残量(0〜100の範囲, ただし、255 は不明とする)
  // 無理矢理感あるが、 IoT 機器とかの API でたまにこういうのがある
  @NotNull
  @RangeEx(min = 0, max = 100, others = {255})
  private Integer batteryLevel;
  // 充電中かどうか
  @NotNull
  private Boolean charging;
  // バッテリーの健康状態
  @NotNull
  private Health health;

  public static enum Health {
    GOOD,
    FAIR,
    POOR
  }
}

カスタムバリデーターの作成

「Bean に付ける制約を表すクラス」と「実際にバリデーションの処理を行うクラス」を作成することで、先ほどのような独自バリデーションを行える。

Bean に付ける制約を表すクラスを作成

RangeEx.java:

package dev.mikoto2000.springboot.validation.workshop.firststep.validation.constraints;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import jakarta.validation.Constraint;
import jakarta.validation.Payload;

import dev.mikoto2000.springboot.validation.workshop.firststep.validation.validator.RangeExValidator;


/**
 * RangeEx。
 */
@Target({
    ElementType.FIELD,
    ElementType.METHOD,
    ElementType.PARAMETER,
    ElementType.ANNOTATION_TYPE,
    ElementType.TYPE_USE })
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = RangeExValidator.class)
@Documented
public @interface RangeEx {

  /**
   * 最小値。
   */
  long min() default 0;

  /**
   * 最大値。
   */
  long max() default Integer.MAX_VALUE;

  String message() default "{dev.mikoto2000.springboot.validation.workshop.firststep.validation.constraints.RangeEx.message}";

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

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

  /**
   * 最大値と最小値範囲以外で許可する値のリスト。
   */
  long[] others();

}
実際にバリデーションの処理を行うクラス作成

RangeExValidator.java:

package dev.mikoto2000.springboot.validation.workshop.firststep.validation.validator;


import java.util.Arrays;

import dev.mikoto2000.springboot.validation.workshop.firststep.validation.constraints.RangeEx;
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

/**
 * RangeExValidator
 */
public class RangeExValidator implements ConstraintValidator<RangeEx, Integer> {

  private long min;
  private long max;
  private long[] others;

  @Override
  public void initialize(RangeEx rangeEx) {
    this.min = rangeEx.min();
    this.max = rangeEx.max();
    this.others = rangeEx.others();
  }

  @Override
  public boolean isValid(Integer value, ConstraintValidatorContext context) {

    // null の拒否は @NotNull に任せる
    if (value == null) {
      return true;
    }

    // others に存在しているか確認
    if (Arrays.stream(others).anyMatch(e -> e == value.longValue())) {
      // others に存在しているものは OK
      return true;
    } else {
      // others に存在していない場合、 min, max の範囲チェックを行う
      if (min <= value.longValue() && value.longValue() <= max) {
        // 範囲内であれば OK
        return true;
      } else {
        // 範囲外であれば NG
        return false;
      }
    }
  }
}

完成後は BatteryStatus を @Valid @RequestBody で受け取る Controller を用意して確認します。

package dev.mikoto2000.springboot.validation.workshop.firststep.controller;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import dev.mikoto2000.springboot.validation.workshop.firststep.bean.BatteryStatus;
import jakarta.validation.Valid;

/**
 * BatteryController
 */
@RestController
public class BatteryController {

  @PostMapping("/battery")
  public String battery(@Valid @RequestBody BatteryStatus status) {
    return status.toString() + "\n";
  }
}

charging と health に妥当な値を設定し、batteryLevel の 0 / 100 / 255 が成功、-1 / 101 が違反となることを確認します。

curl -i -X POST -H 'Content-Type: application/json' http://localhost:8080/battery -d '{"batteryLevel":255,"charging":false,"health":"GOOD"}'
curl -i -X POST -H 'Content-Type: application/json' http://localhost:8080/battery -d '{"batteryLevel":101,"charging":false,"health":"GOOD"}'

1 件目は 200、2 件目は 400 になります。400 の本文は、基本編で追加した Advice により共通の形式になります。 この例は Integer 用です。小数を扱う制約にそのまま流用しないでください。

エラーメッセージと i18n(多言語対応)

エラーメッセージの設定方法は、大きく分けて次の 3 つです。

  • 個別指定(アノテーションで指定)
  • デフォルト指定(ValidationMessages.properties)
  • 言語別デフォルト指定

個別指定(アノテーションで指定)

先に作成した EchoController を次の内容で置き換えます。制約アノテーションの message に、個別のエラーメッセージを指定できます。

controller/EchoController.java
package dev.mikoto2000.springboot.validation.workshop.firststep.controller;

import org.hibernate.validator.constraints.Length;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import jakarta.validation.constraints.Pattern;

/**
 * EchoController
 */
@RestController
public class EchoController {

  /**
   * 引数を直接バリデーション。
   *
   * @param message 文字列
   *              - 必須ではない
   *              - デフォルト値は "0"
   *              - 1文字以上10文字以下
   *              - 数字のみ
   * @return 引数に改行文字を付与して返す
   */
  @GetMapping("/number-echo")
  public String numberEcho(
      @RequestParam(defaultValue = "0")
      // 文字列の長さは 1 から 10 とする
      @Length(min = 1, max = 10, message = "1文字以上10文字以下で指定してください")
      // 文字は、正規表現 `[0-9]*` にマッチする
      @Pattern(regexp = "[0-9]*", message = "数字のみで指定してください")
      String message) {
    return message + "\n";
  }
}

デフォルト指定

src/main/resources/ValidationMessages.properties にデフォルトメッセージ定義を記述できる。

jakarta.validation.constraints.AssertFalse.message=不正な値が入力されました。
jakarta.validation.constraints.AssertTrue.message=不正な値が入力されました。
jakarta.validation.constraints.DecimalMax.message={value}以下の値を入力してください。
jakarta.validation.constraints.DecimalMin.message={value}以上の値を入力してください。
jakarta.validation.constraints.Digits.message=整数{integer}桁以内、小数{fraction}桁以内で入力してください。
jakarta.validation.constraints.Future.message=未来の日付を入力してください。
jakarta.validation.constraints.Max.message={value}以下の値を入力してください。
jakarta.validation.constraints.Min.message={value}以上の値を入力してください。
jakarta.validation.constraints.NotNull.message=値を入力してください。
jakarta.validation.constraints.NotBlank.message=値を入力してください。
jakarta.validation.constraints.Null.message=未入力でなければいけません。
jakarta.validation.constraints.Past.message=過去の日付を入力してください。
jakarta.validation.constraints.Pattern.message="{regexp}"にマッチしていません。
jakarta.validation.constraints.Size.message={min}から{max}の間の値を入力してください。

org.hibernate.validator.constraints.Length.message={min}文字から{max}文字の間で入力してください。
jakarta.validation.constraints.NotEmpty.message=値を入力してください。
org.hibernate.validator.constraints.Range.message={min}から{max}の間の値を入力してください。
org.hibernate.validator.constraints.URL.message=不正なURLです。

dev.mikoto2000.springboot.validation.workshop.firststep.validation.constraints.RangeEx.message={min}から{max}の間の値、または{others}を入力してください。

使う制約のキーが一覧にない場合は追加してください。キーを追加しない場合は、選択された言語に応じた Hibernate Validator の既定メッセージが使われます。

言語別デフォルト指定

src/main/resources/ValidationMessages_en.properties や src/main/resources/ValidationMessages_ja.properties 等を作成することで、言語別のデフォルトメッセージ定義が可能。

ValidationMessages.properties はすでに日本語で作成しているため、切り替えを確認するには英語用の ValidationMessages_en.properties を追加します。切り替えたいキーだけを書けば十分です。

jakarta.validation.constraints.NotNull.message=Please enter a value.
org.hibernate.validator.constraints.Length.message=Please enter between {min} and {max} characters.
jakarta.validation.constraints.Pattern.message=Please enter digits only.

Spring MVC の標準設定では、リクエストの Accept-Language ヘッダーを基に言語が選ばれます。ヘッダーがない場合は、サーバーの既定ロケールが使われます。 該当する言語別ファイルが見つからないときは、実行環境の既定ロケールのファイルが候補になる場合があります。基本ファイルの ValidationMessages.properties にフォールバックした場合、この教材では日本語のメッセージが使われます。 アノテーションに日本語の message を直接指定した場合、その文字列は言語別ファイルでは切り替わりません。 個別指定と言語別ファイルの動作は、次の「発展内容の動作確認」で確認します。

発展内容の動作確認

基本編の Advice を使い、独自制約やメッセージ設定を適用した結果を確認します。

個別指定を適用した場合は、errors に「数字のみで指定してください」が含まれることを確認します。

ValidationMessages.properties と ValidationMessages_en.properties を作成した場合は、同じリクエストを言語違いで送ります。

curl -i -H "Accept-Language: en" -X POST -H 'Content-Type: application/json' http://localhost:8080/bean-echo -d '{"stringValue":null,"integerValue":1,"doubleValue":1.5}'
curl -i -H "Accept-Language: ja" -X POST -H 'Content-Type: application/json' http://localhost:8080/bean-echo -d '{"stringValue":null,"integerValue":1,"doubleValue":1.5}'

stringValue のメッセージは、en では「Please enter a value.」、ja では「値を入力してください。」になります。 切り替わらない場合は、両ファイルを src/main/resources に置いたことと、アプリを再起動したことを確認してください。

言語別ファイルに追加した @Pattern と @Length も確認します。EchoController で個別に設定した 2 つの message 属性を外し、アプリを再起動します。

curl -i -H "Accept-Language: en" "http://localhost:8080/number-echo?message=123a"
curl -i -H "Accept-Language: en" "http://localhost:8080/number-echo?message=12345678901"

1 件目は「Please enter digits only.」、2 件目は「Please enter between 1 and 10 characters.」になります。本文が異なる場合は、属性の指定とプロパティーファイルのキーを確認してください。

独自制約を実装した場合は、不正な値で /battery にリクエストを送り直します。

curl -i -X POST -H 'Accept-Language: ja' -H 'Content-Type: application/json' http://localhost:8080/battery -d '{"batteryLevel":101,"charging":false,"health":"GOOD"}'

Accept-Language: ja を付けて確認すると、batteryLevel のメッセージは「0から100の間の値、または[255]を入力してください。」になります。

まとめ

基本編で確認する項目は、次のとおりです。

  • 単項目バリデーション
  • 既定の制約とエラー応答の確認
  • バリデーションエラーの効率の良いハンドリング方法

発展内容として、次も扱いました。基本の確認後に取り組んでください。

  • 相関チェックのバリデーション(発展)
  • 独自制約(カスタムバリデーター)(発展)
  • 言語別のデフォルトメッセージの設定方法(発展)

Spring Boot は、効率よく望んだとおりのバリデーションを行うための仕組みを用意してくれています。 これら機能を活用してどんどん楽をしていきましょう。