@Controllerとは？コントローラの基本概念と役割を完全ガイド！初心者でもわかるSpring MVCの使い方

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

新人

「Spring MVCの@Controllerって何に使うんですか？なんだか難しそうで…」

先輩

「@Controllerは、Webアプリケーションでユーザーからのリクエストを受け取り、必要な処理を行って結果を画面に返す役割があるんだ。」

新人

「なるほど！でも実際にどんなふうに使うんですか？」

先輩

「それじゃあ、@Controllerの基本的な使い方を一緒に見ていこう！」

1. @Controllerとは？

@Controllerは、Spring MVCでWebアプリケーションを開発する際に使用するアノテーションです。主にユーザーからのリクエストを受け取り、必要な処理を行った後にHTMLなどのビューを返す役割があります。@Controllerは、Javaクラスの上に付けることで、そのクラスがコントローラとして機能することをSpringに伝えます。

Webアプリケーションにおいて、ユーザーがブラウザからURLを入力したり、ボタンをクリックしたときに、そのリクエストを処理する場所が必要です。そこで活躍するのが@Controllerです。例えば、ユーザーが「ホームページを見たい」とリクエストを送ったとき、@Controllerがそのリクエストをキャッチして、どのHTMLを表示すべきかを決定します。

Spring MVCの「MVC」とは、「Model（モデル）」「View（ビュー）」「Controller（コントローラ）」の略です。@Controllerは、この中で「C」の役割を担い、モデルとビューをつなぐ架け橋のような存在です。

2. コントローラの役割と基本概念

コントローラは、ユーザーからのリクエストを受け取り、その内容に応じた処理を行い、結果をビューに渡します。例えば、「商品の一覧を見たい」というリクエストがあれば、商品データを取得してHTMLページに表示します。このとき、リクエストのURLやボタンのクリックなどがトリガーとなり、コントローラが動き出します。

Spring MVCでは、@Controllerを使ってJavaクラスを作成し、その中で@RequestMappingや@GetMappingを使って特定のURLとメソッドを紐づけます。これにより、どのURLでどのメソッドが呼び出されるのかが明確になります。

以下に、基本的な@Controllerのコード例を示します。


package com.example.demo.controller;

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

@Controller
public class HomeController {

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

上記のコードでは、@Controllerをクラスにつけることで、このクラスがコントローラであることを示しています。@GetMapping("/")は、ブラウザで「/」（ルートURL）にアクセスしたときに、homeメソッドが呼び出されることを意味しています。このメソッドは"home"という文字列を返しており、これはresources/templates/home.htmlというビュー（HTMLファイル）を表示することを指しています。

【実行結果のイメージ】


ホームページへようこそ！

実行すると、ブラウザに「ホームページへようこそ！」と表示されます。このように、コントローラはリクエストを受け取り、適切なHTMLを返す役割を担っています。

なお、開発環境としてはpleiadesを使用し、プロジェクト作成時にはSpring BootのチェックボックスでSpring Webを選択して依存関係を追加します。ビルドツールはGradleを選び、設定もpleiades内で簡単に行えます。

注意点として、今回の記事では@RestControllerは使用していません。あくまでHTMLを返すことに焦点を当てた@Controllerに絞って解説しています。

3. @Controllerの基本的な使い方（簡単なコード例付き）

ここでは、@Controllerの基本的な使い方を紹介します。ユーザーがWebブラウザで特定のURLにアクセスしたとき、そのリクエストを処理し、HTMLページを表示するまでの流れを確認しましょう。

まずは、簡単なコントローラの作成方法を見ていきます。以下は、ユーザーが「/greeting」というURLにアクセスしたときに、「greeting.html」というビューを返すサンプルコードです。


package com.example.demo.controller;

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

@Controller
public class GreetingController {

    @GetMapping("/greeting")
    public String greeting(Model model) {
        model.addAttribute("message", "こんにちは、Spring MVCの世界へようこそ！");
        return "greeting";
    }
}

上記のコードでは、@Controllerでクラスを定義し、@GetMapping("/greeting")でURLとメソッドを紐づけています。メソッド内では、Modelを使用してビューにデータを渡しています。ここでは"message"というキーでメッセージを追加し、ビュー側でこれを表示できるようにしています。

次に、ビュー（HTMLファイル）の内容を以下に示します。


<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title>挨拶ページ</title>
</head>
<body>
    <h1 th:text="${message}">デフォルトメッセージ</h1>
</body>
</html>

【実行結果のイメージ】


こんにちは、Spring MVCの世界へようこそ！

実行すると、ブラウザに上記のような挨拶メッセージが表示されます。このように、@Controllerを使うことで、簡単にユーザーリクエストに応じたページ表示が可能です。

4. リクエストとレスポンスの流れ

Spring MVCでは、ユーザーがURLにアクセスすることでリクエストが発生し、そのリクエストがコントローラに届きます。コントローラは適切な処理を行い、結果をビューに渡してユーザーへレスポンスを返します。この一連の流れは、Webアプリケーションにおいて非常に重要な概念です。

以下に、リクエストからレスポンスまでの流れを簡単にまとめます。

ユーザーがブラウザでURLを入力（例：「/greeting」）。
リクエストがSpring MVCのディスパッチャサーブレットに到達。
ディスパッチャサーブレットが該当する@Controllerを探す。
該当メソッドが実行され、処理結果が生成される。
ビューに処理結果を渡し、HTMLページを生成。
ユーザーにHTMLとしてレスポンスを返却。

上記の手順により、ユーザーは求める情報をブラウザで確認できます。この流れを理解することで、どこで何が起きているのかを把握でき、エラー発生時の原因特定がしやすくなります。

5. Viewへのデータ渡し方法

コントローラからビューへデータを渡すことで、動的なWebページを作成できます。Spring MVCでは、主にModelやModelAndViewを使用します。ここでは、Modelを使用したシンプルな例を見てみましょう。


package com.example.demo.controller;

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

@Controller
public class ProductController {

    @GetMapping("/product")
    public String product(Model model) {
        model.addAttribute("name", "ノートパソコン");
        model.addAttribute("price", 150000);
        return "product";
    }
}

このコードでは、商品名と価格をビューに渡しています。対応するproduct.htmlのコードは以下の通りです。


<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title>商品情報</title>
</head>
<body>
    <h1>商品情報</h1>
    <p>商品名: <span th:text="${name}">商品名が表示されます</span></p>
    <p>価格: <span th:text="${price}">価格が表示されます</span> 円</p>
</body>
</html>

【実行結果のイメージ】


商品情報
商品名: ノートパソコン
価格: 150000 円

実行すると、上記のように商品情報が表示されます。モデルを使うことで、さまざまなデータを簡単にビューへ渡すことが可能です。

開発環境にはpleiadesを使用し、プロジェクト作成時はSpring Bootの依存関係でSpring Webを選択してください。ビルドツールはGradleを指定し、src/main/resources/templatesにHTMLファイルを配置することで、簡単にビューが適用されます。

6. @Controllerを使った簡単なWebアプリケーション作成例

ここでは、@Controllerを活用して、簡単な商品一覧ページを表示するWebアプリケーションを作成してみましょう。ユーザーが「/products」というURLにアクセスすると、複数の商品名と価格が表示されるようにします。

まず、以下のようにProductControllerクラスを作成し、商品の情報をリストで保持してビューに渡します。


package com.example.demo.controller;

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

import java.util.Arrays;
import java.util.List;

@Controller
public class ProductController {

    @GetMapping("/products")
    public String products(Model model) {
        List<String> productList = Arrays.asList("ノートパソコン", "スマートフォン", "イヤホン", "モニター");
        model.addAttribute("products", productList);
        return "products";
    }
}

上記のコードでは、@GetMapping("/products")で「/products」というURLを指定し、Modelを通じてproductListをproductsというキーでビューに渡しています。

次に、ビューとなるproducts.htmlを作成します。


<!DOCTYPE html>
<html lang="ja">
<head>
    <meta charset="UTF-8">
    <title>商品一覧</title>
</head>
<body>
    <h1>商品一覧</h1>
    <ul>
        <li th:each="product : ${products}" th:text="${product}">商品名が表示されます</li>
    </ul>
</body>
</html>

【実行結果のイメージ】


商品一覧
・ノートパソコン
・スマートフォン
・イヤホン
・モニター

実行すると、上記のように商品一覧がブラウザに表示されます。th:eachを使ってリスト内の要素を順に表示し、動的なHTML生成を実現しています。

開発手順のポイント:
- pleiadesでプロジェクトを作成し、Spring Webを依存関係として追加します。
- ビルドツールはGradleを選択してください。
- HTMLファイルはsrc/main/resources/templatesに配置します。

7. よくあるエラーとその解決方法

@Controllerを使う際に、初心者がよく遭遇するエラーとその解決方法を紹介します。エラーを早く解決することで、スムーズに開発を進めることができます。

エラー1: 404エラー（ページが見つからない）

原因: URLとメソッドのマッピングが間違っている場合や、HTMLファイルの名前が正しくないと発生します。 解決方法: @GetMappingのURLが正しいか、ビューのファイル名が正しいかを確認してください。


// 誤りの例（URLが間違っている）
@GetMapping("/product-list")
public String productList() {
    return "products"; // ビュー名が"products.html"と一致しているか確認
}

修正後:「/products」へのアクセスで正しく表示されます。

エラー2: TemplateInputException（テンプレートが見つからない）

原因: HTMLファイルがtemplatesフォルダに配置されていない場合に発生します。 解決方法: HTMLは必ずsrc/main/resources/templatesフォルダ内に配置してください。

エラー3: データが表示されない

原因: Modelへのデータ追加が正しく行われていない場合に起こります。 解決方法: model.addAttribute("products", productList);のキー名がビュー側と一致しているか確認してください。

エラー4: サーバーが起動しない

原因: Gradleのビルドエラーや依存関係の不足が原因です。 解決方法: build.gradleの依存関係にspring-boot-starter-webが含まれているか確認し、再ビルドしてください。


dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

8. @Controllerを学ぶ際のポイントと今後の学習ステップ

@Controllerを使った基本的なWebアプリケーション作成の流れを学んだら、次はさらに応用的な内容に取り組んでみましょう。以下のポイントを押さえておくと、より実践的な開発が可能になります。

学習ポイント

URLマッピングの理解: @GetMappingや@PostMappingを使い分けて、異なるリクエスト方法に対応しましょう。
パス変数とリクエストパラメータの扱い: ユーザーからの入力値を取得し、動的なページ表示に挑戦してください。
フォーム入力処理: フォームからのデータ送信を処理し、ユーザーの情報を受け取る方法を学びましょう。
エラーハンドリング: エラー発生時にユーザーにわかりやすいメッセージを表示できるようにしましょう。

今後学ぶべき内容

@RequestMappingの詳細な使い方
POSTリクエストの処理方法とフォームバリデーション
セッションやクッキーの利用方法
データベース連携（Spring Data JPAの導入）
エラーハンドリングと例外処理の実装

最後に、実際にコードを書いて動かすことが理解への近道です。エラーが出たときは焦らず、コードと設定を一つずつ確認しながら解決していきましょう。今回学んだ内容を活かして、実際のWebアプリケーション作成に挑戦してみてください！

まとめ

この記事では、@Controllerを中心としたSpring MVCの基本概念、Webアプリケーション開発におけるリクエスト処理の流れ、Modelを用いたデータの受け渡し、@GetMappingによるURLマッピング、さらにビュー表示までの動作を丁寧に整理しました。とくに初心者がつまずきやすいポイントとして、コントローラクラスの配置、テンプレートフォルダの役割、templates配下にHTMLを置かなければエラーになる点、Modelのキー名が一致しないとデータが画面に表示されない点など、実務でも重要となる基本事項をSEOキーワードを多く交えながら解説しています。

Spring MVCの仕組みであるMVCモデル（Model・View・Controller）を理解し、@ControllerがどのようにURLリクエストを受け取るか、またHTMLを返す仕組みがどのように構築されるのかを把握することは、今後の学習や実践で必ず役立ちます。特に、pleiades環境でSpring BootとGradleを組み合わせ、Spring Web依存関係を追加する開発手順は、初心者が効率的に学習を進めるための重要な工程です。

SEO対策としては、「Spring MVC」「@Controller」「リクエストとレスポンスの流れ」「Modelによるデータ渡し」「URLマッピング」「テンプレートエンジン」「Thymeleaf」「Spring Boot 開発手順」「初心者向け Webアプリケーション開発」などの関連キーワードを多く盛り込み、検索エンジンが理解しやすいように構成しています。Webアプリケーション開発の基礎を体系的に理解しておくことで、エラー発生時の原因追跡も容易になり、効率的なデバッグが可能になります。

最後に、以下のような簡単なサンプルコードを使いながら、今回学んだことを振り返りつつ、実際の開発でどのように活用できるかを確認しておきましょう。

サンプルプログラム


package com.example.demo.controller;

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

@Controller
public class SummaryController {

    @GetMapping("/summary-sample")
    public String summary(Model model) {
        model.addAttribute("title", "まとめページのサンプル表示");
        model.addAttribute("description", "この記事では@Controllerを中心にSpring MVCの基本を学びました。");
        return "summary";
    }
}

このコードでは、@Controllerを使った基本的なルーティング、Modelによるデータ渡しの実例を示しています。実際のWebアプリケーション開発では、このようにURLごとにメソッドを分け、柔軟で拡張性の高い構築が可能になります。また、SEO的にも検索キーワードを意識したタイトルや説明文を画面に表示することで、ユーザーと検索エンジンの双方にとって有益なコンテンツを提供できます。

新卒エンジニアと先輩社員の振り返り会話

新人: 「今日学んだ@Controllerの仕組みですが、URLにアクセスするとどうやってメソッドが呼ばれるのか、ようやく理解できました！」

先輩: 「そうだね。Spring MVCはディスパッチャサーブレットがリクエストを受け取り、適切なコントローラを探して実行してくれるんだ。」

新人: 「Modelにデータを入れるとビューで表示できるのも便利ですね！Thymeleafとの組み合わせで動的ページが作れるのは面白いです。」

先輩: 「その通り。実務では、このModelの使い方がとても重要。キー名が違うだけで表示されなくなるから気をつけよう。」

新人: 「あと、templatesフォルダに置かないとビューが読み込まれないっていうのも覚えました！」

先輩: 「いい感じだね。今回学んだ基礎を押さえておけば、次のステップであるフォーム入力やPOSTリクエスト、JPAとの連携にもスムーズに進めるよ。」

新人: 「もっと練習して、実際に簡単なWebアプリケーションを作ってみます！」

この記事を読んだ人からの質問

@Controllerとは？コントローラの基本概念と役割を完全ガイド！初心者でもわかるSpring MVCの使い方

1. @Controllerとは？

2. コントローラの役割と基本概念

【実行結果のイメージ】

3. @Controllerの基本的な使い方（簡単なコード例付き）

【実行結果のイメージ】

4. リクエストとレスポンスの流れ

5. Viewへのデータ渡し方法

【実行結果のイメージ】

6. @Controllerを使った簡単なWebアプリケーション作成例

【実行結果のイメージ】

7. よくあるエラーとその解決方法

エラー1: 404エラー（ページが見つからない）

エラー2: TemplateInputException（テンプレートが見つからない）

エラー3: データが表示されない

エラー4: サーバーが起動しない

8. @Controllerを学ぶ際のポイントと今後の学習ステップ

学習ポイント

今後学ぶべき内容

まとめ

この記事を読んだ人からの質問

プログラミング初心者からのよくある疑問／質問を解決します

@Controllerとは何ですか？どのような役割がありますか？

@Controllerは、Spring MVCでWebアプリケーション開発を行う際に使用するアノテーションで、ユーザーからのリクエストを受け取り、処理結果をHTMLなどのビューに渡す役割を担います。

関連記事: