@Controllerとは？基本概念と役割を完全ガイド！初心者でもわかるSpring MVCの使い方
新人
「先輩、SpringでWebアプリケーションを作るときに@Controllerってよく見かけるんですけど、これは何ですか？」
先輩
「いい質問だね！@Controllerは、Spring MVCでWebページを表示するためのクラスを作るときに使うアノテーションなんだ。ユーザーからのリクエストを受け取って、適切なHTMLを返す役割があるんだよ。」
新人
「なるほど、リクエストを受け取るってどういうことですか？」
先輩
「じゃあ、これから@Controllerの基本的な使い方と役割について詳しく見ていこう！」
1. @Controllerとは？
@Controllerは、Spring FrameworkのMVCアーキテクチャで使用されるアノテーションで、ユーザーからのHTTPリクエストを受け取り、適切なビュー（HTMLページなど）を返すための役割を持っています。これにより、Webアプリケーションの画面表示やデータのやり取りがスムーズに行えます。
例えば、Webブラウザで「http://localhost:8080/hello」にアクセスしたときに、画面に「こんにちは、Spring!」と表示させることができます。これを実現するのが@Controllerです。
2. @Controllerの役割と基本的な使い方
ここでは、実際に@Controllerを使って簡単なWebページを表示させる方法を解説します。開発環境はPleiadesを使用し、ビルドツールはGradleを利用します。
2.1 プロジェクトの作成方法（Pleiades使用）
- Pleiadesを起動し、新規Springプロジェクトを作成します。
- プロジェクト名を入力し、ビルドツールはGradleを選択します。
- 依存関係の設定画面で、Spring Webにチェックを入れて追加します。
- 完了をクリックしてプロジェクトを生成します。
2.2 コントローラクラスの作成
次に、リクエストを受け取るためのコントローラクラスを作成します。以下が基本的なコード例です。
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を表示
}
}
2.3 Viewファイルの作成
リクエストに対応するHTMLファイルを作成します。src/main/resources/templatesフォルダにhello.htmlを作成してください。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>Hello Page</title>
</head>
<body>
<h1>こんにちは、Spring!</h1>
</body>
</html>
2.4 アプリケーションの実行と確認
- Pleiadesの左側のパッケージエクスプローラーで
DemoApplication.javaを右クリック。 - 実行 > Spring Boot アプリケーションを選択して実行します。
- ブラウザで
http://localhost:8080/helloにアクセス。
ブラウザに「こんにちは、Spring!」と表示されれば成功です。
こんにちは、Spring!
3. @Controllerを使った基本的なルーティングの方法
@Controllerを使用すると、ユーザーがWebブラウザからアクセスしたURLに応じて、特定のメソッドを実行させることができます。これを「ルーティング」と呼びます。ルーティングは、ユーザーからのリクエストを正しい処理に結び付ける重要な仕組みです。
Spring MVCでは、@GetMappingや@PostMappingなどのアノテーションを使用してルーティングを設定します。今回は、ブラウザからのアクセスを想定した@GetMappingの基本的な使い方を解説します。
3.1 単純なルーティングの例
以下のコードでは、ブラウザで/welcomeにアクセスすると、welcome.htmlが表示されます。
package com.example.demo.controller;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class WelcomeController {
@GetMapping("/welcome")
public String showWelcomePage() {
return "welcome";
}
}
このコードのポイントは以下の通りです。
@Controller：クラスがコントローラであることを示します。@GetMapping("/welcome")：/welcomeへのGETリクエストを受け付けます。return "welcome"：welcome.htmlというテンプレートを表示します。
3.2 Viewファイルの作成と確認
src/main/resources/templatesディレクトリに以下のwelcome.htmlを作成してください。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>Welcome Page</title>
</head>
<body>
<h1>ようこそ、Spring MVCの世界へ！</h1>
</body>
</html>
Pleiadesでプロジェクトを実行後、ブラウザでhttp://localhost:8080/welcomeにアクセスすると以下のように表示されます。
ようこそ、Spring MVCの世界へ！
4. Viewへのデータの渡し方（Modelの使い方）
Webアプリケーションでは、ユーザーに単純なHTMLを表示するだけでなく、データを画面に渡すことがよくあります。Spring MVCでは、Modelクラスを使ってデータをViewに渡すことができます。
4.1 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 UserController {
@GetMapping("/user")
public String showUserPage(Model model) {
model.addAttribute("username", "太郎");
return "user";
}
}
model.addAttribute("username", "太郎")は、usernameというキーで「太郎」という値をViewに渡しています。
4.2 Viewでデータを表示
上記のコントローラに対応するuser.htmlを作成します。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>User Page</title>
</head>
<body>
<h1>ユーザー情報</h1>
<p>ユーザー名: <span th:text="${username}"></span></p>
</body>
</html>
Pleiadesでプロジェクトを実行し、ブラウザでhttp://localhost:8080/userにアクセスすると、以下のように表示されます。
ユーザー情報
ユーザー名: 太郎
5. 実際のコード例とその解説
ここでは、ユーザーが名前を入力して挨拶を表示する簡単なWebアプリケーションを作成します。フォームの入力値を受け取り、画面に反映させる方法を解説します。
5.1 コントローラの作成
package com.example.demo.controller;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
@Controller
public class GreetingController {
@GetMapping("/greeting")
public String showForm() {
return "greetingForm";
}
@PostMapping("/greeting")
public String submitForm(@RequestParam("name") String name, Model model) {
model.addAttribute("greetingMessage", "こんにちは、" + name + "さん！");
return "greetingResult";
}
}
5.2 入力フォームの作成
次に、名前を入力するフォームを作成します。greetingForm.htmlを作成してください。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>挨拶フォーム</title>
</head>
<body>
<h1>名前を入力してください</h1>
<form action="/greeting" method="post">
<label for="name">名前:</label>
<input type="text" id="name" name="name" required>
<button type="submit">送信</button>
</form>
</body>
</html>
5.3 結果表示ページの作成
入力された名前を表示する結果用ページを作成します。greetingResult.htmlを以下の内容で作成してください。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>挨拶結果</title>
</head>
<body>
<h1 th:text="${greetingMessage}">ここに挨拶が表示されます</h1>
</body>
</html>
5.4 実行と確認
- Pleiadesでアプリケーションを実行します。
- ブラウザで
http://localhost:8080/greetingにアクセスします。 - 名前を入力し、「送信」をクリックします。
- 次のように入力した名前が表示されます。
こんにちは、花子さん！
6. 実践！簡単なWebアプリケーションの作成手順
ここでは、実際に簡単なWebアプリケーションを作成する手順を詳しく解説します。Pleiadesを使用して、ユーザーが自分の名前を入力し、挨拶を表示するアプリケーションを作成します。
6.1 プロジェクトの作成（Pleiades使用）
- Pleiadesを起動し、新規Springプロジェクトを作成します。
- プロジェクト名をgreeting-appと入力します。
- ビルドツールはGradleを選択します。
- 依存関係の画面で、Spring Webにチェックを入れて追加します。
- 「完了」をクリックし、プロジェクトを生成します。
6.2 コントローラの作成
次に、GreetingControllerクラスを作成し、ルーティングを設定します。
package com.example.greetingapp.controller;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
@Controller
public class GreetingController {
@GetMapping("/greeting")
public String showForm() {
return "greetingForm";
}
@PostMapping("/greeting")
public String submitForm(@RequestParam("name") String name, Model model) {
model.addAttribute("greetingMessage", "こんにちは、" + name + "さん！");
return "greetingResult";
}
}
6.3 Viewファイルの作成
ユーザーが名前を入力するフォーム用HTMLファイルを作成します。
src/main/resources/templates/greetingForm.htmlに以下の内容を追加してください。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>挨拶フォーム</title>
</head>
<body>
<h1>名前を入力してください</h1>
<form action="/greeting" method="post">
<label for="name">名前:</label>
<input type="text" id="name" name="name" required>
<button type="submit">送信</button>
</form>
</body>
</html>
次に、挨拶結果を表示するHTMLファイルを作成します。
src/main/resources/templates/greetingResult.htmlに以下の内容を追加してください。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>挨拶結果</title>
</head>
<body>
<h1 th:text="${greetingMessage}">ここに挨拶が表示されます</h1>
</body>
</html>
6.4 アプリケーションの実行
- Pleiadesで
GreetingAppApplication.javaを右クリック。 - 実行 > Spring Boot アプリケーションを選択して実行します。
- ブラウザで
http://localhost:8080/greetingにアクセスします。 - 名前を入力し、送信ボタンをクリックすると結果が表示されます。
実行結果は以下のように表示されます。
こんにちは、太郎さん！
7. よくあるエラーとその解決方法
Spring MVCで開発を進める中で、初心者がつまずきやすいエラーとその解決方法を紹介します。
7.1 Whitelabel Error Pageが表示される
原因: ビューのファイル名が一致していない、またはtemplatesディレクトリにHTMLファイルがない場合に発生します。
解決方法:
- コントローラで返す文字列とHTMLファイル名が一致しているか確認する。
- HTMLファイルは必ず
src/main/resources/templates内に配置する。
7.2 TemplateInputExceptionエラーが発生する
原因: Thymeleafで参照する変数が存在しない場合に発生します。
解決方法:
- コントローラで
model.addAttribute()が正しく設定されているか確認する。 - Thymeleafで使用する変数名とコントローラで指定した名前が一致しているか確認する。
7.3 サーバーが起動しない
原因: application.propertiesの設定ミスやポートの競合が考えられます。
解決方法:
- 他のアプリケーションが同じポートを使用していないか確認する。
- ポート番号を変更するには
application.propertiesに以下を追加します。
server.port=8081
7.4 404 Not Foundが表示される
原因: 指定したURLが存在しない、もしくはルーティングが正しく設定されていない場合に発生します。
解決方法:
- コントローラの
@GetMappingや@PostMappingのURLが正しいか確認する。 - ブラウザのURLに誤りがないか確認する。
8. 次のステップと今後の学習ポイント
今回の記事では、@Controllerを使用して基本的なルーティング、データの渡し方、簡単なWebアプリケーションの作成方法を学びました。次のステップとして、以下の学習をおすすめします。
8.1 フォームバリデーションの実装
ユーザーが入力するデータを検証し、入力ミスを防ぐ方法を学びましょう。@ValidやBindingResultを使うことで実現できます。
8.2 複数ページ間の遷移
複数のページを作成し、それらを遷移させる方法を学ぶことで、より実用的なWebアプリケーションが作れるようになります。
8.3 データベースとの連携
Spring Data JPAを使うことで、データベースにデータを保存したり取得することが可能になります。次回はこの技術を取り入れたアプリケーション作成を目指しましょう。
8.4 セッション管理と認証
ユーザーのログイン情報を管理する方法を学ぶと、さらに本格的なWebアプリケーションが作成できます。
このように、@Controllerを基礎として、さまざまな機能を組み合わせていくことで、実用的なアプリケーションが開発できるようになります。引き続き実践を重ね、ステップアップしていきましょう！
まとめ
今回の記事では、Spring MVCにおける@Controllerの役割や基本的な使い方について、初めてWebアプリケーションを学ぶ方でも理解できるように、画面表示の流れに沿って丁寧に解説してきました。@Controllerは、Webアプリケーションにおいてブラウザからのリクエストを受け取り、どの画面を表示するかを判断する重要な存在です。URLと処理を結び付けるルーティング、HTMLファイルを返すビュー制御、Modelを使ったデータの受け渡しなど、Web開発の基礎となる考え方がすべてこの@Controllerを中心に構成されています。
記事の前半では、@Controllerがどのような役割を持ち、どのタイミングで呼び出されるのかを確認しました。単にHTMLを表示するだけでなく、ユーザーの操作に応じて処理を分岐させたり、必要なデータを画面に渡したりすることで、動きのあるWebアプリケーションを実現できることが理解できたはずです。@GetMappingや@PostMappingを使ったルーティングの設定は、URL設計の基本でもあり、後々REST APIや認証処理を学ぶ際の土台になります。
また、Modelを使った値の受け渡しでは、コントローラ側で準備したデータをHTMLに表示する仕組みを体験しました。th:textなどの属性を使うことで、Javaの値と画面表示が自然につながり、サーバーサイドとフロントエンドが連携していることを実感できたのではないでしょうか。フォーム送信の例では、ユーザー入力を受け取り、結果を別画面に表示する流れを通して、実際のWebアプリケーションに近い構造を学びました。
エラー対策の章では、初心者がつまずきやすいポイントも整理しました。404エラーやWhitelabel Error Pageは、ControllerとViewの関係を理解することで原因を冷静に切り分けられるようになります。こうした経験を積み重ねることで、トラブルに強い開発者へと成長していけます。
まとめとしてのサンプルプログラム
最後に、今回学んだ内容を振り返るためのシンプルな@Controllerの例を見てみましょう。URLにアクセスするとメッセージを画面に表示する、基本を押さえた構成です。
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 SummaryController {
@GetMapping("/summary")
public String showSummary(Model model) {
model.addAttribute("message", "Controllerの基本が理解できました");
return "summary";
}
}
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<title>まとめページ</title>
</head>
<body>
<h1 th:text="${message}">ここにメッセージが表示されます</h1>
</body>
</html>
生徒：「最初は@Controllerって難しそうだと思っていましたが、画面を表示するための入り口だと考えると、だいぶ分かりやすくなりました。」
先生：「その理解はとても大切ですね。ControllerはWebアプリケーション全体の流れを整理する役割を持っています。」
生徒：「URLとメソッドが結び付いていて、そこからHTMLが表示される流れがようやく頭の中でつながりました。」
先生：「その感覚があれば、次にRestControllerやデータベース連携を学ぶときもスムーズですよ。」
生徒：「Modelでデータを渡せるようになったので、動きのある画面が作れそうです。」
先生：「ぜひ色々な画面を作って試してみてください。手を動かすことが一番の近道です。」
この記事を読んだ人からの質問
