JavaのSpringで使う@NotNullアノテーションを完全解説！初心者でも理解できる入力チェックの基本

1. @NotNullアノテーションとは何か

1. @NotNullアノテーションとは何か

@NotNullアノテーションは、JavaのBean Validation仕様に含まれる基本的な制約アノテーションです。Spring BootやSpring MVCでフォーム入力やREST APIのパラメータを受け取る際に使うことで、その値が必ず存在することを保証できます。

もし値がnullだった場合は自動的にバリデーションエラーとなり、開発者が明示的にチェックを記述しなくてもエラー処理が行えるため、コードを簡潔に保ちながら安全性を高められます。

2. 基本的な使い方

2. 基本的な使い方

Spring Bootで@NotNullを使うには、対象のフィールドに付与するだけです。例えば以下のように書きます。

import jakarta.validation.constraints.NotNull;

public class UserRequest {

    @NotNull
    private String name;

    private Integer age;

    // getterとsetter
}

この場合、nameフィールドには必ず値が設定されていなければなりません。nullが送られてきた場合はバリデーションエラーになります。

3. 実行例とエラーメッセージ

3. 実行例とエラーメッセージ

Spring MVCのコントローラで@Validを組み合わせると、自動的に@NotNullのチェックが行われます。

@PostMapping("/users")
public ResponseEntity<String> createUser(@Valid @RequestBody UserRequest request) {
    return ResponseEntity.ok("ユーザー登録成功");
}

{
  "name": null,
  "age": 20
}

{
  "errors": [
    {
      "field": "name",
      "message": "must not be null"
    }
  ]
}

このように、nullが送られると自動的に「must not be null」というエラーメッセージが返されます。

4. @NotNullと@NotEmpty、@NotBlankの違い

4. @NotNullと@NotEmpty、@NotBlankの違い

初心者が混乱しやすいのが@NotNull、@NotEmpty、@NotBlankの違いです。

• @NotNull … 値がnullではいけない（空文字や空リストは許容される）
• @NotEmpty … nullも空も許されない（空文字や空コレクションは禁止）
• @NotBlank … nullや空白文字のみは禁止（文字列専用でスペースだけも不可）

例えばユーザー名の入力を必須にしたい場合は@NotBlankを使うほうが適切ですが、年齢のような数値であれば@NotNullで十分です。

5. 実務での活用例

5. 実務での活用例

@NotNullアノテーションは多くの場面で利用できます。特に次のようなシーンで役立ちます。

• ユーザー登録で名前やメールアドレスを必須入力にしたい場合
• 商品の注文リクエストで数量を必ず指定させたい場合
• システム設定で必須のパラメータが欠けていないかを確認する場合

こうした必須項目を自動的に検証できることで、入力ミスを減らしシステムの信頼性を高めることができます。

6. エラーメッセージのカスタマイズ

6. エラーメッセージのカスタマイズ

@NotNullで返されるメッセージはデフォルトでは「must not be null」ですが、Spring Bootでは簡単にカスタマイズ可能です。例えばValidationMessages.propertiesを用意して以下のように書きます。

name.notnull=名前は必ず入力してください

そしてフィールドに以下のように指定します。

@NotNull(message = "{name.notnull}")
private String name;

こうすることで、ユーザーにとって分かりやすいエラーメッセージを返すことができます。

7. グループバリデーションとの併用

7. グループバリデーションとの併用

実務では新規登録と更新でルールを変えたい場合があります。そのようなときはバリデーショングループを使います。

public class ValidationGroups {
    public interface Create {}
    public interface Update {}
}

public class UserRequest {

    @NotNull(groups = ValidationGroups.Update.class)
    private Long id;

    @NotNull(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class})
    private String name;
}

これにより、更新処理ではidが必須、新規作成では不要といった柔軟なルールを適用できます。

8. Spring BootとHibernate Validatorの連携

8. Spring BootとHibernate Validatorの連携

@NotNullはHibernate Validatorの実装を通じて実際に検証されます。Spring Bootではこのライブラリが自動で組み込まれているため、特別な設定をしなくても使えます。

また、複雑な条件を組み合わせたい場合は、@NotNullと他のアノテーションを同時に使ったり、独自のバリデーションアノテーションを定義することも可能です。

9. API設計における@NotNullの役割

9. API設計における@NotNullの役割

REST APIの入力チェックでは@NotNullが特に重要です。フロントエンドや外部システムからのリクエストに必須項目が抜け落ちていないかを自動でチェックできるため、セキュリティ面やデータ整合性の観点でも有効です。

また、OpenAPI仕様書やSwaggerを利用する場合も@NotNullの情報は必須項目として自動反映されるため、ドキュメントの品質も向上します。

まとめ

まとめ

この記事全体の振り返り

ここまで、JavaのSpringでよく使われる@NotNullアノテーションについて、基礎から実務での使い方までを順番に確認してきました。@NotNullは、入力値が必ず存在していなければならないことを保証するための非常に基本的で重要なバリデーションアノテーションです。Spring BootやSpring MVCを使ったWebアプリケーション開発では、フォーム入力やREST APIのリクエストを安全に受け取るために欠かせない存在と言えます。

@NotNullを使うことで、値がnullかどうかを毎回if文で確認する必要がなくなり、コードは読みやすく、保守しやすくなります。また、バリデーションエラーが発生した場合も、SpringとHibernate Validatorが自動的にエラー情報を生成してくれるため、入力チェックの実装にかかる手間を大きく減らせます。これは、初心者にとっても理解しやすく、実務でもすぐに役立つポイントです。

記事の中では、@NotNullの基本的な使い方だけでなく、@NotEmptyや@NotBlankとの違いについても解説しました。どれも似たように見えますが、対象となる値の種類やチェック内容が異なります。その違いを理解して使い分けることで、より正確な入力チェックができるようになります。特に文字列入力では、単にnullを防ぐだけでなく、空文字や空白のみの入力も防ぎたいケースが多いため、用途に応じた選択が重要です。

さらに、エラーメッセージのカスタマイズや、バリデーショングループを使った柔軟なルール設定についても触れました。これらは一見すると少し難しそうに感じるかもしれませんが、実務では非常によく使われる考え方です。ユーザーに分かりやすいエラーメッセージを返したり、新規登録と更新で異なるチェックを行ったりすることで、アプリケーションの使いやすさと信頼性が大きく向上します。

まとめとしてのシンプルなサンプル

最後に、この記事の内容をぎゅっとまとめたシンプルな@NotNullの使用例をもう一度確認しておきましょう。基本形を何度も見返すことで、自然と書けるようになります。

import jakarta.validation.constraints.NotNull;

public class SampleRequest {

    @NotNull(message = "必須項目です")
    private String value;

    // getterとsetter
}

このように@NotNullを付けるだけで、「値が必ず存在する」というルールをクラスに明確に表現できます。Springのコントローラで@Validと組み合わせれば、リクエストを受け取った時点で自動的にチェックが行われます。これがSpringのバリデーションの基本的な流れです。