カスタムエラーメッセージの表示方法（messages.properties）｜初心者でもわかるSpring MVCのメッセージ管理

新人と先輩の会話形式で理解しよう

新人

「Spring MVCでバリデーションのエラーメッセージを自分でカスタマイズしたいんですが、どうすればいいですか？」

先輩

「それなら、messages.propertiesというファイルを使ってエラーメッセージを管理すると便利です。Spring MVCの標準機能で、簡単にカスタムメッセージを表示できますよ。」

新人

「messages.propertiesって何ですか？どういう役割があるんでしょう？」

先輩

「messages.propertiesは、エラーメッセージやラベルなどの文言をキーと値のペアで管理するテキストファイルです。これを使うことで、コードに直接メッセージを書かずに済み、管理が楽になるんです。」

新人

「なるほど。Spring MVCではどのようにしてこのファイルを使うんですか？」

先輩

「Spring MVCのバリデーションと連携させて、エラーが発生した時にmessages.propertiesの中身を参照して、ユーザーにわかりやすいメッセージを表示します。これで多言語対応も簡単にできますよ。」

新人

「具体的な設定や例も知りたいです！」

先輩

「それは次のセクションで詳しく解説しますね。開発環境はPleiadesでGradleを使い、@Controllerでの実装を前提に説明します。」

1. カスタムエラーメッセージとは何か？基本的な概要

カスタムエラーメッセージとは、Spring MVCのバリデーションで発生したエラーに対して、開発者が自由に設定したわかりやすいメッセージのことです。デフォルトのエラーメッセージはシステム的でわかりづらい場合がありますが、カスタムメッセージを使うことでユーザーに伝わりやすくなります。

たとえば、「メールアドレスが正しくありません」といった具体的で親切なメッセージを表示することで、ユーザーの入力ミスを迅速に修正してもらうことが可能になります。

このカスタムメッセージは、messages.propertiesファイルに記述することで一元管理でき、メンテナンス性も高まります。また、多言語対応にも対応しやすい仕組みとなっています。

2. Spring MVCでmessages.propertiesを使ったエラーメッセージ管理の基本

Spring MVCでは、バリデーション時のエラーメッセージをmessages.propertiesというファイルで管理します。このファイルは、プロジェクトのresourcesディレクトリ配下に配置され、キーとメッセージのペアを記述します。

バリデーションアノテーションのmessage属性に、messages.propertiesのキーを指定すると、そのキーに対応したメッセージが画面に表示される仕組みです。

例えば、ユーザー名の必須入力エラーに対して以下のようにmessages.propertiesに記述します。


user.name.notblank=ユーザー名は必須項目です。

そして、モデルのフィールドに設定したバリデーションアノテーションでこのキーを使います。


@NotBlank(message = "{user.name.notblank}")
private String userName;

このようにすることで、バリデーションに失敗したときに「ユーザー名は必須項目です。」というメッセージが表示されます。これがSpring MVCでのmessages.propertiesを使った基本的なカスタムエラーメッセージの管理方法です。

3. messages.propertiesファイルの作成と記述方法

messages.propertiesファイルは、Spring MVCプロジェクトのリソースフォルダ（src/main/resources）に配置します。このファイルには、エラーメッセージやラベルの文言を「キー=値」の形式で記述します。こうすることで、コードの中で直接メッセージを記述せずに済み、メッセージの一元管理が可能になります。

例えば、以下のように記述します。


user.name.notblank=ユーザー名は必須入力です。
user.email.invalid=メールアドレスの形式が正しくありません。
user.password.size=パスワードは8文字以上で入力してください。

上記のように、わかりやすいキー名を付け、対応するメッセージを記載します。これにより、複数のバリデーションルールや画面で共通したメッセージ管理がしやすくなります。

また、多言語対応をする場合は、messages_ja.propertiesやmessages_en.propertiesのようにファイルを分けることで、言語ごとに異なるメッセージを設定することもできます。

4. Spring MVCでmessages.propertiesを設定する具体的な方法

Spring MVCでmessages.propertiesを利用するためには、MessageSourceを設定する必要があります。PleiadesでGradleを使う環境では、通常application.propertiesにメッセージファイルのパスを設定します。

以下は、application.propertiesにメッセージファイルの場所を指定する例です。


spring.messages.basename=messages
spring.messages.encoding=UTF-8

これにより、Springが自動的にsrc/main/resources/messages.propertiesを読み込み、バリデーションのエラーメッセージとして利用できるようになります。

もしJava Configで設定したい場合は、以下のようにMessageSourceのBeanを定義します。


@Configuration
public class MessageConfig {

    @Bean
    public MessageSource messageSource() {
        ReloadableResourceBundleMessageSource messageSource = new ReloadableResourceBundleMessageSource();
        messageSource.setBasename("classpath:messages");
        messageSource.setDefaultEncoding("UTF-8");
        return messageSource;
    }
}

この設定を行うことで、Spring MVCのバリデーション時にmessages.propertiesのカスタムメッセージが正しく参照されるようになります。

5. コントローラやモデルでのエラーメッセージの適用例

モデルクラスのフィールドにバリデーションアノテーションを付ける際、message属性にmessages.propertiesのキーを指定することでカスタムメッセージを表示できます。たとえば以下のようなUserFormクラスの例です。


public class UserForm {

    @NotBlank(message = "{user.name.notblank}")
    private String userName;

    @Email(message = "{user.email.invalid}")
    private String email;

    @Size(min = 8, message = "{user.password.size}")
    private String password;

    // ゲッター・セッター省略
}

このUserFormを使うコントローラは以下のようになります。


@Controller
public class UserController {

    @GetMapping("/register")
    public String showForm(Model model) {
        model.addAttribute("userForm", new UserForm());
        return "registerForm";
    }

    @PostMapping("/register")
    public String submitForm(@Validated UserForm userForm, BindingResult bindingResult) {
        if (bindingResult.hasErrors()) {
            return "registerForm";
        }
        // 正常処理
        return "registerSuccess";
    }
}

エラーがある場合、messages.propertiesに定義したキーに対応したカスタムメッセージが画面に表示されます。これにより、ユーザーにとってわかりやすい入力チェックのフィードバックが実現できます。

6. よくあるカスタムエラーメッセージのトラブルと解決方法

Spring MVCでmessages.propertiesを使ったカスタムエラーメッセージの設定時によく起こるトラブルにはいくつかのパターンがあります。代表的なものとその対処法を紹介します。

キーが見つからないエラー
messages.propertiesに記述したキーが間違っている、もしくはファイルの場所が正しくないと、エラーメッセージが表示されず、デフォルトのメッセージやキー名そのものが表示されることがあります。
解決策としては、ファイルがsrc/main/resourcesに配置されているか、application.propertiesでbasenameが正しく設定されているかを確認しましょう。また、キーの綴りミスがないか注意してください。

文字化けが発生する
messages.propertiesの文字コードがUTF-8でない場合、メッセージが文字化けすることがあります。
これを防ぐために、application.propertiesにて「spring.messages.encoding=UTF-8」を設定し、MessageSourceのBean定義でもUTF-8を指定することが重要です。

バリデーションアノテーションのmessage属性が無視される
まれにmessage属性で指定したキーが反映されず、デフォルトメッセージが表示されることがあります。
この場合は、アノテーションに正しいキー名を指定しているか、MessageSourceが正しく設定されているかを見直しましょう。また、キーの前後に{}を忘れずに付けることも重要です。