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

新人

「Spring MVCで画面を表示するときって、成功か失敗かは画面だけで判断しているんですか？」

先輩

「実は画面だけじゃなくて、HTTPステータスコードという番号も一緒に返しています。ブラウザはそれを見て処理結果を判断しています。」

新人

「番号ですか？Controllerでは特に書いたことがないです。」

先輩

「Spring MVCでは、Controller側でその番号を明示的に指定できます。まずはHTTPステータスコードの基本から整理していきましょう。」

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

HTTPステータスコードとは、Webブラウザやクライアントがサーバーへリクエストを送った結果として、サーバー側が返す処理結果を表す番号です。 Webアプリでは、画面やデータと一緒に、この番号が必ず返されています。

例えば、正常に処理が完了した場合は200番台のステータスコードが返されます。一方で、存在しないページにアクセスした場合は404のような番号が返されます。これらの番号は、人が読むためというよりも、通信の状態を正しく伝えるための仕組みです。

Spring MVCやSpring BootでControllerを書く場合も、最終的にはHTTPレスポンスとして結果が返されます。そのため、HTTPステータスコードの意味を理解することは、 Web開発の基本としてとても重要です。

2. Webアプリにおけるレスポンスとステータスコードの関係

Webアプリでは、ユーザーがURLにアクセスすると、サーバーはレスポンスを返します。このレスポンスには、HTMLやJSONといったデータだけでなく、 HTTPステータスコードも必ず含まれています。

画面が表示されている場合でも、内部では必ずステータスコードが返されています。ブラウザはこのコードを見て、正常表示なのか、エラーなのかを判断しています。

Spring MVCのControllerで特に指定をしない場合、正常終了を示すステータスコードが自動的に返されます。しかし、状況によっては意図的に別のステータスコードを返したい場面も出てきます。

3. Spring MVCでステータスコードを扱う理由

Spring MVCでHTTPステータスコードを扱う理由は、 Webアプリの状態を正確に伝えるためです。画面だけを見ると正常に見えても、実際には処理が失敗しているケースもあります。

そのような場合に、HTTPステータスコードを使って、「この処理は成功ではない」という情報を明確に伝えることができます。 Spring MVCでは、その指定を簡単に行える仕組みが用意されています。

まずは、特別な指定をしない場合のControllerの例を見てみましょう。この場合、正常終了を示すステータスコードが返されます。


package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class NormalController {

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

このControllerでは、画面名を返しているだけです。 Spring MVCは、この処理が正常に完了したと判断し、自動的に成功を示すHTTPステータスコードを返します。開発者が特に意識しなくても動作する点が特徴です。

次に、@ResponseStatusを使って、明示的にステータスコードを指定する例を見てみましょう。ここでは、意図的にエラー状態を表すケースを想定します。


package com.example.demo.controller;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseStatus;

@Controller
public class ErrorSampleController {

    @GetMapping("/notfound")
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public String notFound() {
        return "error";
    }
}

この例では、@ResponseStatusを使って、処理結果として「見つからない」状態を示すステータスコードを返しています。画面は表示されていても、ブラウザやシステム側ではエラーとして扱われます。

このように、Spring MVCのControllerでHTTPステータスコードを指定できるようになると、 Webアプリの状態をより正確に表現できるようになります。次の構成では、@ResponseStatusの具体的な使い方をさらに詳しく見ていきます。

4. @ResponseStatus の役割と基本的な使い方

Spring MVCでHTTPステータスコードを明示的に指定したい場合に使われるのが@ResponseStatusです。 @ResponseStatusは、Controllerのメソッドや例外クラスに付与することで、「この処理結果はどのステータスコードとして返すか」を指定するためのアノテーションです。

初心者が混乱しやすい点として、「画面を返しているのに、なぜステータスコードを指定する必要があるのか」という疑問があります。これは、画面表示とHTTP通信の結果が別の概念であることが原因です。画面が表示されていても、通信としてはエラーを表したい場面が存在します。

@ResponseStatusを付けない場合、 Spring MVCはControllerの処理が正常に終わったと判断し、自動的に成功を表すステータスコードを返します。一方で、@ResponseStatusを付けると、開発者が指定したステータスコードが返されるようになります。

まずは、@ResponseStatusを使わない場合の基本的な動きを整理してみましょう。


package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class DefaultStatusController {

    @GetMapping("/default-status")
    public String defaultStatus() {
        return "default";
    }
}

このControllerでは、画面名を返しているだけです。 Spring MVCは処理が問題なく完了したと判断し、成功を示すHTTPステータスコードを自動的に返します。多くの初心者は、この動きを意識せずに開発を進めています。

次に、@ResponseStatusを使ってステータスコードを指定する例を見てみましょう。


package com.example.demo.controller;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseStatus;

@Controller
public class ResponseStatusController {

    @GetMapping("/forbidden")
    @ResponseStatus(HttpStatus.FORBIDDEN)
    public String forbidden() {
        return "forbidden";
    }
}

この例では、画面を返しつつも、処理結果としては「アクセスできない状態」を示すステータスコードが返されます。見た目は画面表示でも、通信上はエラーとして扱われる点が重要なポイントです。

5. 正常系とエラー時でステータスコードを返す考え方

Spring MVCでステータスコードを考えるときは、「この処理は正常なのか、それともエラーなのか」を明確に分けて考えることが大切です。初心者のうちは、画面が表示されていれば正常だと考えがちですが、実際のWeb開発ではそれだけでは不十分な場合があります。

例えば、入力値が不正な場合や、必要なデータが存在しない場合でも、画面自体は表示できてしまうことがあります。そのような場合に、HTTPステータスコードを使って、「この結果はエラーである」と明示的に伝えることが重要になります。

正常系では、特別な指定をせずにSpring MVCに任せるケースが一般的です。一方で、エラーを表現したい場合には、 @ResponseStatusを使って意図したステータスコードを返します。

次の例では、条件によって処理結果の意味が変わるケースを想定します。


package com.example.demo.controller;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;

@Controller
public class ConditionController {

    @GetMapping("/check")
    @ResponseStatus(HttpStatus.OK)
    public String check(@RequestParam("value") int value) {
        if (value < 0) {
            return "error";
        }
        return "success";
    }
}

このコードでは、表面的には同じ画面遷移を行っていますが、本来はエラーと正常を分けて扱う必要があります。初心者の段階では、「どの状態をエラーとしたいのか」を意識することが重要です。

実務では、条件に応じて異なるステータスコードを返す設計が求められます。その考え方の第一歩として、正常系とエラー系を分けて考える習慣を身に付けましょう。

6. @Controller でステータスコードを指定する実装例

ここでは、Spring MVCの@Controllerを使って、ステータスコードを明示的に指定する具体的な実装例を整理します。ポイントは、画面を返す処理とステータスコードの指定が、別の役割であることを理解することです。

次の例では、データが存在しない場合を想定し、ステータスコードでその状態を表現します。


package com.example.demo.controller;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseStatus;

@Controller
public class DataController {

    @GetMapping("/data")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public String data() {
        return "data";
    }
}

このControllerでは、画面は返していますが、ステータスコードとしては「内容が存在しない」状態を示しています。このように、画面表示と通信結果を切り分けて設計できる点が、 Spring MVCにおける@ResponseStatusの大きな特徴です。

初心者のうちは、まずは「画面を返す処理」と「ステータスコードを返す意味」を別々に考えることを意識すると理解しやすくなります。その上で、どの場面でどのステータスコードを返すべきかを少しずつ整理していくと、Controller設計の精度が上がっていきます。

7. よく使われるHTTPステータスコードの例

Spring MVCで@ResponseStatusを使い始めた初心者が、まず覚えておきたいのは、実務で頻繁に登場するHTTPステータスコードの代表例です。すべての番号を暗記する必要はありませんが、「この番号はどんな意味を持つのか」という感覚を持つことが大切です。

最もよく使われるのは、正常終了を表す200番台のステータスコードです。画面が問題なく表示された場合や、処理が期待通りに完了した場合に使われます。 Spring MVCでは、Controllerで特に指定をしなければ、この成功を表すステータスコードが自動的に返されます。

次によく使われるのが、400番台のステータスコードです。これは、リクエストに問題がある場合や、データが存在しない場合などに使われます。代表的なものとしては、見つからない状態を示す404があります。

実際のControllerでの指定例を見てみましょう。ここでは、存在しない画面を意図的に表現するケースを想定します。


package com.example.demo.controller;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseStatus;

@Controller
public class NotFoundController {

    @GetMapping("/sample/notfound")
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public String notFound() {
        return "notfound";
    }
}

このように、Spring MVCの@Controllerと@ResponseStatusを組み合わせることで、画面表示と同時にステータスコードの意味を明確に伝えることができます。初心者のうちは、まず200番台と400番台の違いを理解することから始めましょう。

8. 初心者が @ResponseStatus でつまずきやすいポイント

@ResponseStatusを学び始めた初心者がつまずきやすいポイントの一つは、「画面が表示されているのに、なぜエラー扱いになるのか」という点です。これは、画面表示とHTTP通信の結果が別の概念であることを、まだ十分に理解できていないことが原因です。

Spring MVCでは、Controllerが返す画面と、 HTTPステータスコードは別々に制御できます。そのため、見た目上は通常の画面が表示されていても、通信上はエラーとして扱われるケースが存在します。

次の例では、画面を表示しつつ、ステータスコードだけをエラーとして返すケースを示します。


package com.example.demo.controller;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseStatus;

@Controller
public class ForbiddenController {

    @GetMapping("/sample/forbidden")
    @ResponseStatus(HttpStatus.FORBIDDEN)
    public String forbidden() {
        return "forbidden";
    }
}

このControllerでは、画面自体は表示されますが、 HTTPステータスコードとしては403が返されます。初心者のうちは、「画面が表示されているから成功」「画面が表示されないから失敗」と単純に考えてしまいがちですが、 Spring MVCではそうとは限らない点に注意が必要です。

9. 画面表示とステータスコード制御の考え方

Spring MVCでの画面表示とHTTPステータスコード制御は、それぞれ異なる役割を持っています。画面表示はユーザーに見せるためのものであり、ステータスコードは通信相手に処理結果を伝えるためのものです。

例えば、入力内容に問題があった場合でも、エラーメッセージ付きの画面を表示することはよくあります。その場合、画面は表示されますが、処理結果としてはエラーであることを示すために、 400番台のステータスコードを返す設計が考えられます。

この考え方を理解すると、 Spring MVCで@ResponseStatusを使う目的が明確になります。単に画面を切り替えるだけでなく、 Webアプリ全体の状態を正確に表現するための仕組みなのです。

10. 初心者はまず何を理解すべきか

Spring MVCでHTTPステータスコードと@ResponseStatusを学ぶ初心者は、まず「画面表示」と「通信結果」は別物であるという点を理解することが重要です。この違いを意識できるようになるだけで、 Controller設計の考え方が大きく変わります。

次に、200番台は正常、400番台はエラーという大まかな分類を理解しましょう。細かい番号の意味は、実際に使う場面で少しずつ覚えていけば問題ありません。重要なのは、「なぜこのステータスコードを返すのか」を説明できることです。

今回学んだ@ResponseStatusの基本を土台として、次のステップでは例外処理やエラーハンドリングの仕組みを学ぶと、 Spring MVCでのController設計がより実践的になります。焦らず、一つずつ理解を積み重ねていきましょう。

Spring MVCでHTTPステータスコードを返す方法を完全解説｜@ResponseStatusの基本を初心者向けに理解しよう