@Controllerと@RestControllerの違いを理解しよう
新人
「Spring BootでWebアプリケーションを作っているときに、@Controllerと@RestControllerというのを見かけたんですけど、違いがよくわかりません…」
先輩
「@Controllerと@RestControllerは、どちらもリクエストを処理するためのクラスを定義するものなんだけど、返す内容が違うんだよ」
新人
「返す内容？画面を表示するか、データを返すかってことですか？」
先輩
「その通り！それじゃあ、具体的にそれぞれがどんな役割を持っているのか、一緒に見ていこう！」
1. Spring Bootにおける@Controllerとは？
Spring Bootにおいて@Controllerは、Webアプリケーションで画面（HTMLファイル）を表示するために使うアノテーションです。主にユーザーからのリクエストに応じて、HTMLのテンプレートを返す役割を担っています。
この@Controllerを使うことで、テンプレートエンジン（例えばThymeleaf）を使って動的に画面を生成することができます。Spring MVCの基本的なコントローラーであり、画面表示が目的の場合はこちらを使うのが基本です。
以下は、@Controllerを使った簡単なサンプルコードです。
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 HelloController {
@GetMapping("/hello")
public String hello(Model model) {
model.addAttribute("message", "こんにちは、Spring Boot！");
return "hello";
}
}
このコードでは、ユーザーが/helloにアクセスすると、hello.htmlというテンプレートが表示され、messageという変数に「こんにちは、Spring Boot！」という値がセットされてHTMLに渡されます。
テンプレートファイル（HTML）は、resources/templatesフォルダ内に配置します。以下は、Thymeleafで記述したHTMLの例です。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>Hello Page</title>
</head>
<body>
<h1 th:text="${message}">ここにメッセージが表示されます</h1>
</body>
</html>
@Controllerは、HTML画面を表示するWebアプリケーションにおいて最も基本的でよく使われるアノテーションです。特に、ユーザーインターフェースを伴う開発では欠かせない存在です。
2. @RestControllerとは何か？どのような場面で使うのか？
@RestControllerは、Spring BootでWeb APIを作るときに使うアノテーションです。HTML画面を返すのではなく、JSONなどのデータをそのまま返す用途に使われます。
これは、@Controllerに加えて@ResponseBodyが自動的に付与されているような動作をするため、戻り値がそのままレスポンスとして出力される点が特徴です。
以下は、@RestControllerの例です。
package com.example.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ApiController {
@GetMapping("/api/hello")
public String helloApi() {
return "こんにちは、API！";
}
}
このコードでは、/api/helloにアクセスすると、文字列「こんにちは、API！」がそのままブラウザやHTTPクライアントに返されます。HTMLテンプレートは一切使用されず、返されるのはプレーンテキストやJSONです。
また、Javaのオブジェクトを返すと、Springが自動的にJSONに変換してレスポンスに含めてくれます。以下のように書くこともできます。
@RestController
public class UserApiController {
@GetMapping("/api/user")
public User getUser() {
return new User("太郎", 25);
}
}
このように書くと、返されたUserオブジェクトは自動でJSONに変換されます。ただし、この記事では@Controllerを中心に説明しており、@RestControllerはあくまで違いを理解するための補足とします。
ポイントは、@ControllerはHTML画面を返す、@RestControllerはデータ（JSONなど）を返すという使い分けです。ユーザーと直接やりとりする画面が必要なら@Controller、システム間のAPI通信を行うなら@RestControllerを選びましょう。
3. @Controllerと@RestControllerの違いをコードで比較してみよう
ここでは、@Controllerと@RestControllerの違いを、実際のコードを使って比較してみましょう。使い方の違いが理解しやすくなります。
まずは@Controllerを使って、テンプレートファイルを返すパターンです。HTMLページの表示が目的の場合に使います。
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 ViewController {
@GetMapping("/greeting")
public String greeting(Model model) {
model.addAttribute("message", "こんにちは、画面表示の例です");
return "greeting";
}
}
この例では、/greetingにアクセスするとgreeting.htmlが表示され、変数messageがHTMLに埋め込まれます。つまり、@Controllerは画面（ビュー）を返すときに使います。
次に、同じ内容を@RestControllerで実装した例を見てみましょう。
package com.example.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class GreetingApiController {
@GetMapping("/api/greeting")
public String greetingApi() {
return "こんにちは、APIのレスポンスです";
}
}
@RestControllerの場合はHTMLを返すのではなく、文字列やデータ（JSONなど）を直接返します。ブラウザに表示されるのは「こんにちは、APIのレスポンスです」というテキストだけで、テンプレートファイルは使いません。
このように、@Controllerはテンプレートを使ったHTML画面の表示に向いており、@RestControllerはJSONや文字列などのデータを返す用途に向いています。
初心者のうちは、ユーザーが画面で操作するWebアプリケーションを作る際は@Controllerを使い、データだけを提供するAPIを作るときには@RestControllerを使う、という使い分けを覚えておくとよいでしょう。
4. @Controllerを使ったHTML出力と@RestControllerを使ったJSON出力の違い
ここでは、@Controllerを使ったHTML出力と、@RestControllerを使ったJSON出力の違いをさらに詳しく見ていきましょう。
まず、@Controllerを使ってユーザー情報を画面に表示する例です。
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 UserViewController {
@GetMapping("/user/view")
public String viewUser(Model model) {
model.addAttribute("name", "山田太郎");
model.addAttribute("age", 30);
return "user";
}
}
テンプレートファイル（user.html）は、以下のように記述します。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>ユーザー情報</title>
</head>
<body>
<h2>ユーザー名：<span th:text="${name}"></span></h2>
<h2>年齢：<span th:text="${age}"></span></h2>
</body>
</html>
このように@Controllerを使えば、画面にHTML形式で情報を表示することができます。テンプレートエンジン（この例ではThymeleaf）を使って、変数の値を埋め込みながら動的にHTMLを生成します。
次に、@RestControllerを使って同じユーザー情報をJSONで返す場合の例を見てみましょう。
package com.example.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserApi {
@GetMapping("/api/user")
public User getUser() {
return new User("山田太郎", 30);
}
public static class User {
private String name;
private int age;
public User(String name, int age) {
this.name = name;
this.age = age;
}
public String getName() { return name; }
public int getAge() { return age; }
}
}
このコードでは、/api/userにアクセスすると、ユーザー情報がJSON形式で返されます。画面を表示するのではなく、データだけを提供する用途に向いています。
{"name":"山田太郎","age":30}
このように、@Controllerと@RestControllerは、返すものが大きく異なります。HTML画面を返したい場合は@Controller、データをJSONで提供したい場合は@RestControllerを使うという使い分けが基本です。
また、テンプレートファイルを使う場合はresources/templatesにHTMLを置く必要があります。一方で@RestControllerは、テンプレートを一切使わずにレスポンスを生成できるという違いがあります。
実際の開発では、ユーザーが直接操作するページは@Controllerで作り、システム同士が通信するAPI部分は@RestControllerを使うという役割分担がされます。
初心者の方にとっては、まずは@Controllerを使ってHTML画面を表示するWebアプリケーションをしっかり作れるようになることが大切です。REST APIや@RestControllerの使い方は、もう少し慣れてからでも十分に対応できます。
5. 初心者が間違えやすいポイントと注意点（@Controllerと@RestControllerの使い分け）
Spring Bootで@Controllerと@RestControllerを使い分ける際、初心者がよく陥る「違い 理解」のミスがあります。ここでは、実際の開発でよくある「初心者 ミス」や「Controller エラー」について、分かりやすく整理していきます。
まず最も多いのが、@ControllerでHTMLテンプレートを返すつもりが、@ResponseBodyを付け忘れていて、うまくデータが表示されないというケースです。
たとえば、以下のようなコードを書いたとします。
@Controller
public class SampleController {
@GetMapping("/test")
public String test() {
return "これはテキストです";
}
}
この場合、return "これはテキストです";は、テンプレート名と解釈されてtemplates/これはテキストです.htmlを探しにいってしまい、「テンプレートが見つからない」というController エラーになります。
本当に文字列を返したい場合は、@Controllerではなく@RestControllerを使う、または@ResponseBodyを付ける必要があります。
@Controller
public class SampleController {
@GetMapping("/text")
@ResponseBody
public String text() {
return "これはテキストのレスポンスです";
}
}
また、@RestControllerを使っているのにテンプレートファイルを返そうとすると、今度は逆に画面が表示されず文字列がそのままブラウザに表示されてしまうというミスもあります。
初心者のうちは、「HTML画面を返す場合は@Controller」「データを返す場合は@RestController」というルールを守ることがとても重要です。
もう一つの注意点として、テンプレートエンジンの設定ミスもよくあります。@Controllerを使っているのにテンプレートフォルダにHTMLファイルが無かったり、ファイル名が一致していなかったりすると、画面は正しく表示されません。
エラー内容としては、「Whitelabel Error Page」や「TemplateInputException」などが表示されるため、テンプレートの配置場所やファイル名は正確に設定するようにしましょう。
6. Spring Bootでの実践的な@Controllerの使い方まとめ
ここでは、実践で使える@Controllerの基本的な書き方と、初心者が押さえておきたいポイントを整理しておきます。
まず、@Controllerを使うときは、HTMLテンプレートを表示することが目的です。Spring Bootでは、テンプレートファイルはsrc/main/resources/templatesの中に配置し、Thymeleafを使ってHTMLの中にJavaの値を埋め込むことができます。
以下のようにModelにデータを詰めて、テンプレートに渡すのが基本です。
@Controller
public class ProductController {
@GetMapping("/product")
public String showProduct(Model model) {
model.addAttribute("name", "りんご");
model.addAttribute("price", 150);
return "product";
}
}
そして、HTMLテンプレート（product.html）には、以下のようにデータを埋め込みます。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>商品情報</title>
</head>
<body>
<h2 th:text="'商品名：' + ${name}"></h2>
<h2 th:text="'価格：' + ${price} + '円'"></h2>
</body>
</html>
このように、Spring BootとThymeleafを使えば、画面に動的な情報を表示するWebアプリケーションを簡単に作成できます。
また、複数の画面やURLを扱うときには、@GetMappingや@PostMappingを使い分けて、リクエストごとに異なる処理やテンプレートを返すことができます。
実際の開発では、コントローラーを「機能ごと」に分けるのもおすすめです。たとえば、「ユーザー情報」「商品情報」「注文処理」などの機能単位で、コントローラークラスを分けて管理することで、コードが見やすくなり、保守性も高まります。
7. @Controllerを使って学ぶおすすめの方法
最後に、@Controllerの使い方を初心者がしっかりと身につけるための学習方法をご紹介します。
まずは、実際にHTMLテンプレートを使って画面にデータを表示する簡単なアプリを作ってみましょう。たとえば、「プロフィール表示アプリ」や「商品一覧画面」などが良い練習になります。
また、URLによって異なる画面を出し分けるなど、@GetMappingの使い方も意識しておくと理解が深まります。
さらに、Thymeleafの書き方もセットで学んでおくとよいでしょう。th:textやth:eachなどの基本的な構文を使えば、ループ処理や条件分岐もテンプレート内で実現できます。
また、初心者がよく混乱するのが「テンプレートファイルの名前」と「returnする文字列」の関係です。return "user";と書いたら、user.htmlを探しにいくというルールを忘れずに覚えておきましょう。
「Controller エラーが出たけど、何が間違っているのかわからない」と感じたときは、resources/templatesにHTMLファイルがあるか、ファイル名は正しいか、スペルミスはないか、などを順番にチェックする癖をつけることが大切です。
Spring Bootを使ったWeb開発では、最初に学ぶのがこの@Controllerとテンプレートエンジンを使った画面表示です。ここをしっかり理解しておけば、他の部分もスムーズに学んでいけます。
もし慣れてきたら、@RestControllerを使ったAPI開発にもチャレンジしてみましょう。データ通信の仕組みやJSON形式の扱い方も、後からしっかり学べば問題ありません。
