コントローラーとは？初心者向けにやさしく解説

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

新人

「Spring BootでWebアプリを作ってみたいんですが、@Controllerって何をするものなんですか？」

先輩

「@Controllerは、ユーザーからのリクエストを受け取って処理するためのクラスだよ。Web画面の制御を担当する部分だね。」

新人

「それって、具体的にどんな役割なんですか？ビューとかモデルってよく聞くんですけど…」

先輩

「それじゃあ、Webアプリケーションの中でコントローラーが何をしているのか、やさしく説明していくね！」

1. コントローラーとは？

Spring Bootにおけるコントローラーとは、ユーザーの操作（リクエスト）を受け取り、それに応じて処理を実行し、画面（ビュー）を返す役割を持つクラスのことです。JavaのWebアプリケーションでは、コントローラーが「入り口」となって、リクエストされたURLに応じた処理を行います。

コントローラーは、@Controllerというアノテーションを使って作成します。これはSpring Bootの中でも非常に基本的で大切な機能です。

たとえば、ユーザーがWebブラウザで「/hello」というURLにアクセスしたときに、どの処理を行うかを決めるのがコントローラーの仕事です。

以下に、もっともシンプルなコントローラーのコード例を示します。


package com.example.demo.controller;

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

@Controller
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "hello"; // hello.htmlを表示する
    }
}

このように、@GetMapping("/hello")は、URL「/hello」にアクセスがあったときにhello()メソッドが実行されるようにしています。そして戻り値の"hello"は、resources/templatesフォルダにあるhello.htmlというビューを表示する指示です。

2. Webアプリケーションにおけるコントローラーの重要性とは？

Webアプリケーションでは、ユーザーの操作によってさまざまな処理が発生します。たとえば、ログイン画面を表示したり、入力フォームの内容を処理したり、データベースにアクセスしたりします。これらのリクエストとレスポンスの流れを一元的に管理するのがコントローラーの役割です。

コントローラーは、Webアプリ全体の「指揮官」のような存在で、次のような処理を行います。

ユーザーからのリクエストを受け取る
リクエストに対応する処理（サービスやビジネスロジック）を呼び出す
処理結果に応じて表示するビュー（HTML）を選ぶ

コントローラーがなければ、リクエストをどの処理に渡すべきか分からなくなってしまいます。そのため、コントローラーはWebアプリケーションにおける中核的な存在と言えます。

また、Spring Bootでは@Controllerを使うことで、画面を返すタイプのWebアプリを簡単に構築できます。注意点として、今回はAPIではなく「画面を返すアプリケーション」が前提ですので、@RestControllerではなく@Controllerを使うことがポイントです。

実際の画面にデータを渡すには、例えば以下のようにModelを使います。


package com.example.demo.controller;

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

@Controller
public class WelcomeController {

    @GetMapping("/welcome")
    public String welcome(Model model) {
        model.addAttribute("name", "太郎");
        return "welcome";
    }
}

上記では、Modelを使ってnameという変数に「太郎」という値を設定し、welcome.htmlに渡しています。

そして、welcome.html側では、たとえばThymeleafを使って次のように表示します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>Welcome Page</title>
</head>
<body>
    <h1>ようこそ、<span th:text="${name}"></span>さん！</h1>
</body>
</html>

このように、コントローラーを使うことで、入力から表示までの流れが明確になります。特に、初心者のうちは「URLと処理の対応関係」「コントローラーとHTMLのつながり」に注目しながら学んでいくと理解が深まりやすいです。

Spring BootとGradleの環境は、Pleiadesで簡単にセットアップできます。プロジェクト作成時にSpring Webにチェックを入れておけば、@Controllerが使えるように設定されます。

このあとの記事では、@Controllerを使ったより具体的な記述方法や、リクエストの種類（@GetMappingや@PostMappingなど）について解説していきます。

3. @Controllerを使った基本的なコントローラーの記述方法

ここでは、Spring Bootで@Controllerを使ってコントローラーを作成する基本的な方法を解説します。まず、Pleiadesでプロジェクトを作成するときに「Spring Web」にチェックを入れておくと、必要な依存関係がGradleに自動で追加されます。これにより、@Controllerが使用可能になります。

コントローラーは、Javaクラスに@Controllerアノテーションをつけて定義します。そして、リクエストを受け取るためのメソッドには、@GetMappingや@PostMappingなどのアノテーションを使って、URLと処理内容を関連付けます。

以下に、ユーザーが「/greet」にアクセスしたときに「greet.html」を表示するシンプルなコントローラーを示します。


package com.example.demo.controller;

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

@Controller
public class GreetController {

    @GetMapping("/greet")
    public String greet() {
        return "greet"; // greet.html を表示する
    }
}

このように、コントローラーの記述は非常にシンプルです。まずはURLとビューの紐づけから慣れていきましょう。

4. @RequestMappingや@GetMappingの使い方

Spring Bootでは、URLと処理メソッドを結びつける方法として、@RequestMappingや@GetMappingを使用します。これらのアノテーションは、リクエストの種類に応じて使い分けることができます。

@GetMappingは、主にブラウザからのGETリクエスト（画面表示やリンクアクセスなど）に使われます。一方、@PostMappingはフォーム送信などPOSTリクエストに使います。

@RequestMappingは、それらすべてをカバーする汎用的なアノテーションで、method属性を指定することで、GETやPOSTを使い分けることもできます。

以下は、@RequestMappingを使った例です。


package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

@Controller
public class SampleController {

    @RequestMapping(value = "/sample", method = RequestMethod.GET)
    public String showSample() {
        return "sample";
    }
}

このように記述すると、GETリクエストで「/sample」にアクセスがあったときに、「sample.html」を表示するようになります。ただし、実際にはより読みやすい@GetMappingを使うことが一般的です。

同じ内容を@GetMappingで書くと次のようになります。


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

このように、@GetMappingは簡潔で読みやすいため、初心者にもおすすめの記法です。今後の開発では積極的に@GetMappingを使ってみてください。

5. コントローラーとビューのつながり（Thymeleafの基礎）

コントローラーは、処理を行うだけでなく、ユーザーに画面を返す役割も担っています。Spring Bootでは、テンプレートエンジンとしてThymeleafを使うことで、HTMLとデータを連携させた画面表示が簡単に実現できます。

コントローラーでHTML画面を返すには、resources/templatesフォルダにHTMLファイルを作成します。そして、コントローラーのメソッドの戻り値としてファイル名（拡張子なし）を指定します。

たとえば、以下のコントローラーでは「message」というビュー名を返しています。


@GetMapping("/message")
public String message(Model model) {
    model.addAttribute("text", "こんにちは、Spring Boot！");
    return "message";
}

このとき、resources/templates/message.htmlを用意しておく必要があります。そのHTML内で、textという変数を表示するには、以下のように記述します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>メッセージ表示</title>
</head>
<body>
    <h1 th:text="${text}">メッセージが表示されます</h1>
</body>
</html>

th:text="${text}"と書くことで、モデルで渡された値がHTMLに反映されます。この仕組みにより、Javaコード側とHTML側での役割分担が明確になり、メンテナンスしやすいWebアプリケーションを構築できます。

Thymeleafを使用する際は、Pleiadesのプロジェクト作成時に「Thymeleaf」にチェックを入れておくことで、必要な依存関係がGradleに自動で追加されます。

これまでに紹介したように、@Controllerでユーザーのリクエストを受け取り、Modelを通じてHTMLテンプレートにデータを渡すことで、動的なWebページを作ることができます。この構造をしっかり理解することが、Spring BootによるWeb開発の第一歩です。

6. コントローラーを使った簡単なWebアプリケーションの例（入力→表示の流れ）

ここでは、Spring Bootの@Controllerを使って、入力フォームから名前を受け取り、その名前を画面に表示する簡単なWebアプリケーションの流れを紹介します。

まずは、ユーザーが名前を入力するHTMLフォームを用意します。HTMLファイルは、resources/templatesに配置します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>入力フォーム</title>
</head>
<body>
    <form action="/submit" method="post">
        <label>名前を入力してください：</label>
        <input type="text" name="username">
        <button type="submit">送信</button>
    </form>
</body>
</html>

このフォームは、ユーザーが名前を入力してsubmitボタンを押すと、/submitというURLにPOSTリクエストが送られる仕組みです。

次に、@Controllerを使って/submitを受け取る処理を書きます。


package com.example.demo.controller;

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

@Controller
public class FormController {

    @PostMapping("/submit")
    public String handleForm(@RequestParam("username") String username, Model model) {
        model.addAttribute("name", username);
        return "result";
    }
}

この例では、RequestParamでフォームから送信されたusernameの値を受け取り、それをモデルに追加しています。そして、result.htmlというHTMLに画面遷移します。

最後に、名前を表示するHTMLファイルを作成します。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>結果表示</title>
</head>
<body>
    <h1 th:text="'こんにちは、' + ${name} + 'さん！'">ようこそ！</h1>
</body>
</html>

このように、Spring BootのコントローラーとThymeleafテンプレートを組み合わせることで、入力された情報をすぐに画面に反映することができます。

7. エラーが出やすいポイントとその対処法（初心者向けに）

Spring Bootでコントローラーを使っていると、初心者がつまずきやすいエラーがいくつかあります。ここでは特に多いものとその解決方法を紹介します。

① HTMLファイルが表示されない

Thymeleafテンプレートが表示されない原因で多いのは、HTMLファイルの配置場所が間違っていることです。必ずsrc/main/resources/templatesフォルダの中にHTMLを配置してください。

② HTTPステータス404エラー

リクエストURLとコントローラーのマッピングが合っていないと、「404 Not Found」エラーになります。@GetMappingや@PostMappingで指定しているURLと、ブラウザからアクセスしているURLが一致しているか確認しましょう。

③ パラメータ名のミス

フォームのname属性と、@RequestParamの引数名が一致していないと、値が取得できません。スペルミスに注意が必要です。

④ 必要な依存関係が不足している

Spring WebやThymeleafなどの依存関係がGradleに含まれていないと、アノテーションやテンプレートが正しく動作しません。Pleiadesでプロジェクト作成時に、Spring WebとThymeleafにチェックを入れておくことで自動で設定されます。

⑤ returnのビュー名が間違っている

return "sample"と書いたとき、対応するsample.htmlがtemplatesフォルダに存在しないと、ビューが見つからずエラーになります。拡張子なしで指定し、正しい名前のファイルがあるか確認しましょう。

8. Springのコントローラーを学ぶためのおすすめの勉強方法

Spring Bootの@Controllerは、初心者でも比較的取り組みやすい機能です。効果的に学ぶためには、実際に小さなアプリケーションを作りながら覚えるのが最もおすすめです。以下にいくつかの学習ステップを紹介します。

① Pleiadesで環境構築から始める

まずは、PleiadesでSpring Bootプロジェクトを作成し、依存関係に「Spring Web」「Thymeleaf」をチェックしましょう。MavenではなくGradleを選ぶことで、設定がシンプルになります。

② @GetMappingや@PostMappingを使って画面遷移を試す

複数のURLを作って、表示する画面を分けてみましょう。URLと処理がどうつながっているのかが理解しやすくなります。

③ Formを使って入力→表示までの流れを試す

前述の例のように、フォームで名前を入力して画面に表示する流れは、コントローラー学習の基本中の基本です。モデルに渡したデータがどのようにHTMLに反映されるかを確認してみてください。

④ 少しずつ機能を追加していく

最初は名前の表示だけで構いません。次は年齢を入力させてみたり、条件によって表示を変えるロジックを組んでみたりすると、自然とJavaのスキルやSpringの知識も身についていきます。

⑤ 書籍や公式ドキュメントを併用する

Spring公式のドキュメント（日本語版もあります）や、Spring Bootに特化した入門書を読みながら手を動かすと、理解が格段に深まります。

特に初心者の方は、「わからなくても動かしてみる」「動いたものを少しずつ変更して確認する」というスタイルが合っています。コントローラーはWebアプリの入口になる重要な機能なので、じっくり時間をかけて理解していきましょう。