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

新人

「Spring MVCで画面を作っていると、エラーが起きたときに画面は表示されるんですが、通信としては成功なのか失敗なのか分からなくて困ることがあるんです。」

先輩

「それはHTTPステータスコードを意識していないことが原因かもしれないね。」

新人

「画面はエラーっぽいのに、ステータスコードってそんなに重要なんですか？」

先輩

「Spring MVCでは、画面表示と同時にHTTPステータスも返しているから、そこを理解するとエラーハンドリングが一気に分かりやすくなるよ。」

1. HTTPステータスコードとは何か

HTTPステータスコードとは、ブラウザとサーバの通信結果を数値で表したものです。画面に何が表示されているかとは別に、「このリクエストは成功したのか、それとも失敗したのか」を機械的に伝える役割を持っています。

例えば、正常に画面が表示された場合は成功を示す数値が返り、ページが見つからない場合やエラーが発生した場合は、失敗を示す別の数値が返されます。ブラウザはこの数値を見て、通信の結果を判断しています。

初心者のうちは、画面が表示されていれば成功、表示されなければ失敗と考えがちです。しかし、Spring MVC HTTPステータスの考え方では、画面表示と通信結果は必ずしも一致しません。エラー画面が表示されていても、通信としては失敗であることを明確に伝える必要があります。

例えば、入力値が不正な場合にエラーメッセージを表示する処理でも、通信としては「リクエストは受け取ったが内容に問題がある」という意味を持たせることができます。これをステータスコードで表現することで、クライアント側は状況を正確に把握できます。


@Controller
public class StatusSampleController {

    @GetMapping("/statusSample")
    public String statusSample() {
        return "sample";
    }
}

このような通常のコントローラでも、実際にはHTTPステータスコードが返されています。何も指定しなければ、Spring MVCは「正常終了」を表すステータスを自動的に設定します。この裏側の動きを知ることが、 Spring MVC エラーハンドリング基礎の第一歩になります。

2. Spring MVCでステータスコードを意識する理由

Spring MVCでステータスコードを意識すべき理由は、エラー処理を正しく設計するためです。画面だけを見て処理結果を判断していると、後から仕様変更や機能追加を行う際に混乱が生じます。

特に、エラー時の挙動は重要です。エラー画面を表示するだけでは、「なぜ失敗したのか」「どの種類の失敗なのか」を通信として正確に伝えることができません。ここでHTTPステータスコードが役立ちます。

Spring MVCでは、エラーが発生した場合も通常のリクエスト処理の一部として扱われます。そのため、画面遷移とは別に、ステータスコードをどう返すかを設計する必要があります。これを意識しないと、エラーなのに成功と同じ扱いになってしまうことがあります。

@ResponseStatus 基本の考え方は、「この処理はどのような結果なのか」を開発者が明示的に示すことです。画面表示に頼らず、通信結果として意味を持たせることで、アプリケーション全体の品質が向上します。


@Controller
public class ErrorControllerSample {

    @GetMapping("/errorSample")
    public String errorSample() {
        throw new IllegalArgumentException();
    }
}

このような処理では例外が発生しますが、画面がどう表示されるかと同時に、ステータスコードがどのように返されているかが重要になります。 Spring MVC HTTPステータスを理解していないと、この部分はブラックボックスに見えてしまいます。

エラー時にステータスコードを正しく返せるようになると、画面遷移中心の開発から一歩進み、意味のあるエラーハンドリング設計ができるようになります。次のステップでは、そのための具体的な仕組みである @ResponseStatus の役割を詳しく見ていくことになります。

3. @ResponseStatusとは何か

Spring MVC エラーハンドリングを学ぶ中で、次に理解しておきたい仕組みが @ResponseStatus です。 @ResponseStatus は、「この処理結果はどのHTTPステータスとして返すのか」をSpring MVCに教えるためのアノテーションです。

これまで見てきたように、 Spring MVCでは何も指定しなければ、処理が正常に終わったと判断され、成功を示すステータスが自動的に返されます。しかし、エラーが発生した場合や、意図的に失敗として扱いたい場合には、そのままでは不十分なことがあります。

@ResponseStatus を使うと、「このメソッドが呼ばれた場合は、このステータスコードを返す」というルールを明示的に定義できます。これにより、画面遷移とは別に、通信結果としての意味を正しく伝えられるようになります。

初心者が混乱しやすい点として、 @ResponseStatus は画面を切り替えるための仕組みではありません。あくまで、レスポンスとして返す HTTPステータスコードを制御するためのものです。画面に何が表示されるかとは、直接的には関係しない点を押さえておくことが大切です。

Spring MVC エラーハンドリングの基礎として、 @ResponseStatus は「通信の結果をどう表現するか」を整理するための重要な道具だと言えます。

4. @ResponseStatusを使った基本的な使い方

@ResponseStatus 使い方を理解するために、まずは最も基本的なパターンを見ていきます。 @ResponseStatus は、コントローラのメソッドに直接付けて使用できます。

メソッドに付けた場合、そのメソッドが正常に終了したときでも、指定したステータスコードが返されます。これは、「処理自体は問題なく終わったが、結果としてはエラー扱いにしたい」といったケースで役立ちます。


@Controller
public class ResponseStatusController {

    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @GetMapping("/statusError")
    public String statusError() {
        return "errorPage";
    }
}

この例では、 errorPage という画面を返していますが、通信としては入力内容に問題があることを示すステータスが返されます。画面遷移とステータス制御が別々に考えられている点が重要です。

@ResponseStatus は、例外クラスに付けて使うこともできます。この場合、その例外が発生したタイミングで、自動的に指定したステータスが返されます。


@ResponseStatus(HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
}

このように例外クラスに付けておくと、コントローラ内でこの例外を投げるだけで、ステータスコードが制御されます。メソッドごとに設定しなくてよいため、共通的なエラー表現に向いています。

コントローラメソッドに付ける場合と、例外クラスに付ける場合の違いは、「どの単位でルールを決めたいか」にあります。処理単位で決めたい場合はメソッド、エラーの種類で決めたい場合は例外、という考え方をすると整理しやすくなります。

5. エラー時にステータスだけを制御する設計の考え方

Spring MVC エラーハンドリングを考える際、「エラー時は必ず特別な画面を用意する」と考えてしまう初心者の方は多いです。しかし、必ずしも画面を切り替える必要はありません。

エラーの種類によっては、画面はそのままで、ステータスコードだけを変えた方が分かりやすい場合もあります。例えば、入力チェックエラーのように、画面自体は同じで、メッセージだけを表示したいケースです。

このような場合、 @ResponseStatus を使ってステータスだけを制御する設計が有効です。画面遷移の責務と、通信結果の表現を分離することで、コントローラの役割が明確になります。

初心者が混乱しやすいポイントとして、「ステータスがエラーなら画面もエラーになる」という思い込みがあります。実際には、どの画面を返すかと、どのステータスを返すかは別の話です。 Spring MVCでは、この二つを独立して設計できます。

@ResponseStatus を使った設計は、エラー処理を段階的に整理するための第一歩です。まずは、ステータスコードを正しく返せるようにすること。そのうえで、どの画面を表示するかを考える。この順番を意識すると、 Spring MVC エラーハンドリングの全体像が見えやすくなります。

次のステップでは、例外処理と組み合わせたより実践的なエラーハンドリング設計について学んでいくことになります。

6. @ResponseStatusを使うメリットと注意点

Spring MVC @ResponseStatus は、 HTTPステータスを簡潔に制御できる点が大きなメリットです。コントローラや例外クラスに付けるだけで、「この処理結果はどの状態なのか」を Spring MVCに明確に伝えることができます。

特に初心者にとっては、ステータスコードを意識した設計を最小限の記述で実現できる点が魅力です。画面遷移のロジックを大きく変えずに、通信結果としての意味だけを調整できるため、既存のMVC構成とも自然に組み合わせられます。

一方で、@ResponseStatus には限界もあります。制御できるのは基本的にステータスコードのみであり、「なぜそのエラーが起きたのか」「どの項目に問題があるのか」といった詳細な情報までは表現できません。

初心者のうちは、ステータスコードさえ返せば十分だと感じるかもしれません。しかし、アプリケーションが成長すると、エラー内容をより細かく伝える必要が出てきます。そのとき、 @ResponseStatus だけでは情報が足りなくなる場面が増えてきます。

また、@ResponseStatus を多用しすぎると、どの処理がどのステータスを返すのかが分かりにくくなることもあります。特にメソッドごとに異なるステータスを指定していると、コード全体の見通しが悪くなる点には注意が必要です。

Spring MVC エラーハンドリングの第一段階としては、 @ResponseStatus は非常に有効ですが、すべてをこれだけで解決しようとしない姿勢が大切です。

7. @ResponseStatusと他の例外処理手法の使い分け

Spring MVCのエラーハンドリングには、 @ResponseStatus 以外にも複数の手法があります。代表的なものが、コントローラ内での例外処理や、専用の例外処理メソッドを使う方法です。

@ResponseStatus は、「この例外はこのステータス」「この処理結果はこの状態」といった単純なルールを表現するのに向いています。そのため、画面構成を大きく変えずに、状態だけを伝えたいケースでは最適です。

しかし、エラーの種類が増えてくると、ステータスコードだけでは足りなくなります。例えば、同じ失敗でも理由が複数ある場合や、画面に表示するメッセージを切り替えたい場合です。こうした場面では、例外ごとに処理を分ける仕組みが必要になります。


@Controller
public class ExceptionSampleController {

    @GetMapping("/sampleError")
    public String sampleError() {
        throw new IllegalStateException();
    }
}

このように例外が発生した場合、 @ResponseStatus だけでは「どの画面を表示するか」「どのメッセージを使うか」といった細かな制御が難しくなります。

そこで登場するのが、例外をまとめて扱うための仕組みです。 @ExceptionHandler や、それを発展させた共通処理の考え方は、 @ResponseStatus の次に学ぶべき重要なテーマになります。

実務では、軽微なエラーや単純な状態表現には @ResponseStatus、複雑なエラー処理や共通化したい部分には別の例外処理手法を使う、という使い分けがよく行われます。

Spring MVC @ResponseStatus は、エラーハンドリング設計の入口として捉えると、全体の位置づけが理解しやすくなります。

8. 次に学ぶべきSpring MVCのエラーハンドリング設計

ここまでで、 HTTPステータスコードの役割と、 @ResponseStatus を使った基本的な制御方法を学びました。これにより、 Spring MVC エラーハンドリングの基礎はしっかりと身に付いています。

次に意識したいのは、エラー処理をどの単位で設計するかです。コントローラごとに書くのか、例外クラスごとにまとめるのか、あるいはアプリケーション全体で共通化するのか、といった設計判断が重要になります。

ステータスコードだけでは足りなくなったとき、エラー内容や画面表示を一元的に管理したくなる場面が必ず訪れます。そのためには、例外クラスの設計や、共通エラーハンドリングの考え方を学ぶ必要があります。


@ResponseStatus(HttpStatus.BAD_REQUEST)
public class ValidationException extends RuntimeException {
}

このような例外クラス設計を起点に、エラーの種類を整理していくことで、コードの見通しは大きく改善します。さらに進むと、アプリケーション全体で同じルールでエラーを扱えるようになります。

Spring MVC エラーハンドリングの学習は、一気にすべてを理解する必要はありません。まずは @ResponseStatus でステータスコードを正しく返す。次に、例外をどう整理するかを考える。そして、共通エラーハンドリングへと発展させていく。この段階的な理解が大切です。

今回学んだ内容を土台として、次は「例外クラス設計」「共通エラーハンドリング」といったテーマに進むことで、より実践的なSpring MVC設計ができるようになるでしょう。

@ResponseStatusを使ったHTTPステータスの制御をやさしく解説！Spring MVCエラーハンドリング基礎