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

新人

「Spring BootでWebアプリを作っていると、Controllerってよく出てきますけど、そもそも何をしているんですか？」

先輩

「Spring MVCでは、Controllerが画面表示やリクエスト処理の中心的な役割を担っています。ブラウザからのアクセスを受け取って、次に何をするかを決める場所ですね。」

新人

「なるほど。@Controllerと@RestControllerって似た名前ですが、どう違うんですか？」

先輩

「役割は近いですが、想定している使い道が違います。まずはSpring MVCのコントローラの基本から整理していきましょう。」

1. Spring MVCにおけるコントローラとは何か

Spring Bootを使ったWeb開発では、Spring MVCという仕組みを利用して画面表示やリクエスト処理を行います。その中で重要な役割を持つのがコントローラです。コントローラは、ブラウザから送られてきたリクエストを受け取り、どの画面を表示するか、どの処理を実行するかを判断します。

Pleiadesで作成したSpring Bootプロジェクトでも、コントローラクラスを用意し、そこにアノテーションを付けることで、 Webアプリとして動作するようになります。この仕組みによって、URLと処理内容を分かりやすく管理できるのがSpring MVCの特徴です。

初心者のうちは、コントローラは「リクエストの受付係」と考えると理解しやすいでしょう。画面遷移を行う場合も、入力内容を受け取る場合も、まずコントローラが登場します。

2. @Controller と @RestController の役割の違い

Spring MVCには、@Controllerと@RestControllerという二つの似たアノテーションがあります。名前が似ているため混乱しやすいですが、役割には明確な違いがあります。

@Controllerは、主に画面を表示するためのコントローラです。 HTMLを表示したい場合、コントローラは「どの画面を返すか」を決めて返します。つまり、ブラウザに画面を見せるWebアプリ開発では@Controllerが基本になります。

一方で@RestControllerは、画面ではなくデータを返すことを前提にしたコントローラです。 API開発でよく使われ、JSONなどのデータを返す用途が中心になります。ただし本記事の前提では@RestControllerは使わないため、「@Controllerでもデータを返せる」というポイントを押さえて使い分けの考え方を理解します。

ポイント

画面を返したいなら@Controllerで画面名を返す。データを返したいなら@Controllerに加えて、データとして返す指定をする。これを知っているだけで、Spring BootとSpring MVCのController設計が迷いにくくなります。

画面を返す例

次は、Spring BootのSpring MVCで画面を返す典型例です。 URLにアクセスされたら、画面名を返して画面表示につなげます。ここでは@Controllerを使い、画面遷移の考え方を優先します。


package com.example.demo.controller;

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

@Controller
public class PageController {

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

この場合、ブラウザでアクセスすると「hello」という画面が表示されます。 Spring BootとSpring MVCでは、Controllerが「どの画面を見せるか」を決める役割になります。そのため、Webアプリ開発ではController設計が分かりやすく整理できます。

データを返す例

では、画面ではなくデータを返したい場合はどうするのかという疑問が出ます。ここで大事なのは、@Controllerでもデータを返せるという点です。 APIのように文字列やJSONに近い情報を返したいときは、返す対象が「画面」ではなく「データ」だと分かる指定を行います。


package com.example.demo.controller;

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

@Controller
public class ApiLikeController {

    @GetMapping("/api/message")
    @ResponseBody
    public String message() {
        return "Hello from Controller";
    }
}

この例では@Controllerのままですが、データとして返したいことを明確にしています。その結果、ブラウザには画面ではなく文字として結果が表示されます。 Spring BootでController設計を考えるときは、返したいものが画面なのかデータなのかを意識すると、 @Controllerと@RestControllerの使い分けの考え方が自然に理解できます。

ブラウザ表示のイメージ

画面を返すControllerと、データを返すControllerでは、ブラウザの見え方が変わります。初心者が混乱しやすいのは、画面を返すつもりでデータが表示されたり、データを返すつもりで画面遷移してしまったりする点です。 Spring MVCのControllerは「何を返すか」を意識して作ることが重要です。


/hello にアクセス → 画面が表示される想定
/api/message にアクセス → 文字が表示される想定

3. なぜ @RestController という仕組みが用意されているのか

Spring Bootが広く使われるようになった背景には、 Webアプリだけでなく、API開発の需要が増えたことがあります。従来の@Controllerは画面表示を前提とした設計が中心で、データを返すときは「データとして返す指定」を追加する必要がありました。

API開発ではHTMLではなく、データそのものを返す場面が多くなります。そこで、データを返す用途に最適化した考え方として@RestControllerが用意されました。ただし、画面中心のWebアプリ開発では@Controllerが自然に理解しやすく、初心者はまずSpring MVCのControllerの流れを掴むことが大切です。

Spring BootとSpring MVCでは、「Controllerで何を返すのか」を意識して作るだけで、 Webアプリ開発とAPI開発の違いが整理しやすくなります。

4. @Controller を使った基本的な画面遷移の仕組み

Spring BootとSpring MVCを使ったWeb開発では、画面遷移の中心に@Controllerがあります。ブラウザからURLにアクセスすると、そのリクエストはまずコントローラに届きます。コントローラは、そのURLに対応する処理を実行し、最終的に「どの画面を表示するか」を返します。

画面遷移の考え方はとてもシンプルで、「URL」と「表示する画面名」を結びつけているだけです。この仕組みを理解しておくと、Spring MVCでのWeb開発が一気に分かりやすくなります。

例えば、トップページと入力画面を切り替えるような場合でも、それぞれのURLに対応するメソッドを@Controllerに用意するだけで実現できます。 Pleiadesで作成したSpring Bootプロジェクトでも、この流れは同じです。


package com.example.demo.controller;

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

@Controller
public class ScreenController {

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

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

このように、@GetMappingでURLを指定し、メソッドの戻り値として画面名を返すことで画面遷移が行われます。 Spring MVCでは、コントローラが画面遷移の司令塔となるため、画面構成を考えるときは@Controllerの役割を意識することが大切です。

5. @Controller で JSON を返す場合の考え方

Spring MVCでは、@Controllerは画面表示専用というイメージを持たれがちですが、実際にはデータを返すこともできます。この考え方を理解しておくと、@RestControllerとの違いがより明確になります。

@ControllerでJSONのようなデータを返す場合は、「これは画面ではなくデータとして返したい」という意思を明確に示す必要があります。そのために使われるのが@ResponseBodyです。

@ResponseBodyを付けることで、 Spring MVCは戻り値を画面名として扱わず、そのままレスポンスデータとしてブラウザに返します。


package com.example.demo.controller;

import java.util.HashMap;
import java.util.Map;

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

@Controller
public class JsonController {

    @GetMapping("/api/user")
    @ResponseBody
    public Map<String, String> user() {
        Map<String, String> result = new HashMap<>();
        result.put("name", "Taro");
        result.put("role", "beginner");
        return result;
    }
}

この例では、Mapを返していますが、 Spring BootとSpring MVCの仕組みによって、自動的にJSON形式のデータとして変換されます。画面を返す場合と違い、HTMLは表示されず、データそのものがブラウザに表示されます。

初心者が混乱しやすいポイントは、「@Controllerなのに画面が表示されない」という状況です。これは@ResponseBodyが付いているためであり、 Spring MVCが正しく動作している結果でもあります。

6. @RestController が想定している用途

@RestControllerは、画面表示ではなく、 API開発を主な目的として用意された仕組みです。 Webアプリ開発よりも、データ通信を中心とした設計を想定しています。

スマートフォンアプリや外部システムとの連携では、 HTML画面ではなくJSON形式のデータをやり取りするケースが一般的です。そのような場合、毎回@ResponseBodyを付けるのは手間になります。

そこで、「このコントローラは常にデータを返す」という前提で使えるのが@RestControllerです。本記事では実装例として使用していませんが、考え方として理解しておくことが重要です。

Spring Bootでは、WebアプリとAPIの両方を同じプロジェクトで扱えるため、用途に応じたコントローラ設計が求められます。その判断基準を理解するためにも、まず@Controllerでの動きをしっかり把握しておく必要があります。

7. @Controller と @RestController の使い分けのポイント

@Controllerと@RestControllerの使い分けで最も大切なのは、「最終的に何を返したいのか」を明確にすることです。画面を返したいのか、それともデータを返したいのかによって、選択すべき設計が変わります。

画面中心のWebアプリ開発では@Controllerが基本になります。画面遷移や入力フォームの表示などは、 Spring MVCと@Controllerの組み合わせが最も理解しやすい構成です。

一方で、API開発ではデータ返却が前提となるため、 @RestControllerの考え方が向いています。ただし、初心者のうちは両方を同時に学ぶと混乱しやすくなります。

まずは@Controllerを使って、 URLと画面遷移、データ返却の違いを理解することが重要です。その上でAPI開発に進むと、 @RestControllerの役割が自然に理解できるようになります。

Spring BootとSpring MVCでは、コントローラの役割を正しく理解することが、保守しやすく分かりやすいアプリケーション設計につながります。

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

Spring Bootを学び始めた初心者が@RestControllerでつまずきやすい理由は、「画面が表示されると思っていたのに、文字やJSONだけが表示される」という体験をしやすい点にあります。 Spring MVCの仕組みを十分に理解しないまま@RestControllerを使うと、 Webアプリの動きが直感と合わなくなります。

特に混乱しやすいのが、「コントローラなのだから画面遷移するはず」という思い込みです。 @RestControllerは、画面遷移ではなくデータ返却を前提にした考え方で作られています。そのため、HTMLファイルを用意しても表示されず、意図しない結果になることがあります。

初心者の段階では、画面表示とデータ返却の違いを明確に意識できていないケースが多いため、まずは@Controllerで画面遷移の流れを理解することが重要です。 Spring MVCの基本が分かっていない状態で@RestControllerを使うと、なぜそうなるのかが分からず、学習効率が下がってしまいます。


@Controller
public class ConfuseController {

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

このような@Controllerの基本的な構造を理解していれば、「この戻り値は画面名を返している」という考え方が自然に身につきます。その上で@RestControllerの考え方を学ぶと、つまずきにくくなります。

9. @Controller で書く設計が向いているケース

Spring BootとSpring MVCを使ったWebアプリ開発では、多くのケースで@Controllerを使った設計が向いています。特に、画面を中心とした業務システムや管理画面では、画面遷移の流れが分かりやすい@Controllerが適しています。

入力画面、確認画面、完了画面といった流れを持つアプリでは、 URLと画面の対応関係を整理しやすいことが大きなメリットです。 Pleiades環境でSpring Bootプロジェクトを作成した場合でも、この設計は非常に扱いやすくなります。


@Controller
public class FlowController {

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

    @PostMapping("/confirm")
    public String confirm() {
        return "confirm";
    }

    @PostMapping("/complete")
    public String complete() {
        return "complete";
    }
}

このように@Controllerを使うことで、画面の流れをコードから読み取りやすくなります。初心者にとっては、「今どの画面にいて、次にどこへ進むのか」を理解しやすい構造になります。

Webアプリ開発では、分かりやすい設計が保守性の高さにも直結します。その意味でも、@Controllerを中心とした設計は、初心者にとって非常に相性が良いと言えます。

10. Webアプリ開発とAPI開発の考え方の違い

Spring Bootでは、 Webアプリ開発とAPI開発の両方を行えますが、考え方には明確な違いがあります。 Webアプリ開発は「画面をどう見せるか」が中心です。一方でAPI開発は「データをどう渡すか」が中心になります。

Webアプリ開発では、コントローラが画面名を返し、ユーザーにとって分かりやすい画面遷移を作ることが重要です。 Spring MVCと@Controllerは、この目的に最適化されています。

API開発では、 HTMLではなくデータを返すため、画面遷移という概念自体が存在しません。そのため、設計の視点も大きく異なります。初心者が混乱するのは、この二つを同じ感覚で考えてしまう点です。


@Controller
public class DataController {

    @GetMapping("/info")
    @ResponseBody
    public String info() {
        return "data only response";
    }
}

この例は@Controllerを使いながら、データ返却を行うケースです。 WebアプリとAPIの境界を理解する練習として、このような実装を試すのも効果的です。