はじめに
Web API を作っていると必ず必要になるのが
入力チェック（バリデーション） です。
「名前は必須にしたい」
「メールアドレスの形式をチェックしたい」
「数値は 0 以上にしたい」
こういったルールを簡単に実現できるのが
Validation（@Valid） です。
この記事では、@Valid の使い方を
やさしく・実務で役立つ形 で整理していきます。
まずはコードを見て、そこから少しずつ理解していきましょう。
まずはコードを確認
public class UserRequest {
@NotBlank
private String name;
@Min(0)
private int age;
// getter / setter
}@PostMapping("/users")
public ResponseEntity<String> createUser(@Valid @RequestBody UserRequest request) {
return ResponseEntity.ok("created");
}このように、DTO にアノテーションを付けて、
Controller で @Valid を付けるだけで入力チェックが動きます。
コードのしくみを解説
@Valid とは
一言でいうと、
「このオブジェクトのバリデーションを実行してください」
という指示です。
Spring が
- DTO のフィールドに付いたアノテーションを読み取り
- 自動でチェックを実行し
- エラーがあれば例外を投げてくれます
よく使うバリデーションアノテーション
代表的なものを整理します。
| アノテーション | 意味 |
|---|---|
| @NotBlank | 空文字禁止（null も不可） |
| @NotNull | null 禁止 |
| @Size(min, max) | 文字数や配列のサイズ |
| メールアドレス形式 | |
| @Min / @Max | 数値の最小・最大 |
| @Positive / @PositiveOrZero | 正の数 |
| @Pattern | 正規表現 |
これだけで多くの入力チェックが書けます。
エラー時のレスポンスを整える
@Valid でエラーが起きると、 MethodArgumentNotValidException が発生します。
これを ControllerAdvice でキャッチすると、
きれいなエラーレスポンスを返せます。
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<Map<String, String>> handleValidation(MethodArgumentNotValidException e) {
Map<String, String> errors = new HashMap<>();
e.getBindingResult().getFieldErrors().forEach(error ->
errors.put(error.getField(), error.getDefaultMessage())
);
return ResponseEntity.badRequest().body(errors);
}
}実務ではこの形がとてもよく使われます。
あわせて知っておきたいポイント
@RequestBody とセットで使うことが多い
JSON を DTO に変換するときに
@Valid が一緒に動きます。
@Validated との違い
- @Valid → 基本的なバリデーション
- @Validated → グループ分けなど高度なバリデーションが可能
まずは @Valid で十分です。
メッセージをカスタマイズできる
@NotBlank(message = "名前は必須です")
private String name;
application.properties でメッセージを外出しできる
spring.messages.basename=messages
messages.properties に書くと管理しやすくなります。
使うときに気をつけたいこと
DTO にロジックを書かない
バリデーションは「ルール」だけを書く場所です。
Controller に if 文を書かない
@Valid と ControllerAdvice を使えば
try-catch や if 文は不要になります。
エラーメッセージは利用者目線で
API の利用者が理解しやすいメッセージにするのが実務的です。
まとめ
Validation（@Valid）は、
「DTO に付けたルールに従って入力チェックを自動で行う仕組み」
です。
- DTO にアノテーションを付けるだけ
- Controller で @Valid を付けるだけ
- エラーは自動で例外に
- ControllerAdvice と組み合わせると美しい API に
難しく聞こえますが、
「入力チェックを自動化するための仕組み」
と理解できれば十分です。
Validation を使いこなすと、API の品質が一気に上がります。
入力チェックをコードに散らばらせず、
DTO にまとめるだけで設計がとてもきれいになります。
あなたの開発が、今日より少しだけ楽になりますように。
入力をそっと見守ってくれるなんて…@Valid さん、やさしいね。
コメント