Spring BootでThymeleafを使う準備！テンプレートエンジンの基本から導入まで
新人
「先輩、Spring Bootってよく聞くんですけど、いったい何なんですか？」
先輩
「Spring Bootは、JavaでWebアプリケーションを簡単に作るためのフレームワークだよ。設定が最小限で済むから、初心者でも扱いやすいんだ。」
新人
「なるほど。でも、テンプレートエンジンって必要なんですか？HTMLだけじゃダメなんですか？」
先輩
「いい質問だね。HTMLだけだと、動的なデータの表示が難しいんだ。テンプレートエンジンを使うことで、サーバー側で動的にHTMLを生成できるんだよ。」
新人
「じゃあ、Spring BootでThymeleafを使うとどう便利になるんですか？」
先輩
「それじゃあ、Spring BootとThymeleafの基礎から導入方法まで、一緒に見ていこうか！」
1. Spring Bootとは？
Spring Bootは、JavaのWebアプリケーションを効率よく開発するためのフレームワークです。従来のSpringフレームワークでは、複雑な設定ファイルやXML設定が必要でしたが、Spring Bootではそれらを自動化してくれるため、簡単に始めることができます。
Pleiades（プレアデス）を使えば、開発環境もすぐに整い、GradleプロジェクトとしてSpring Bootの機能を使ってアプリケーションを構築できます。
特に初心者にとっては、「最小限の設定ですぐに動く」点が魅力です。コントローラには@Controllerを使い、画面と連携した処理がスムーズに行えます。
2. なぜテンプレートエンジンが必要なのか？
テンプレートエンジンとは、サーバーサイドでHTMLファイルに動的なデータを埋め込む仕組みです。静的HTMLファイルでは、すべての内容が固定されており、ユーザーごとの情報や、日付・データベースの値を反映させることができません。
たとえば、ログインしたユーザー名を画面に表示したいとき、HTMLだけでは対応できません。そこでテンプレートエンジンの出番です。
テンプレートエンジンを使えば、Javaで用意したデータをHTMLに埋め込んで、画面ごとに異なる内容を表示できます。Spring Bootでは、Thymeleaf（タイムリーフ）というテンプレートエンジンがよく使われます。
3. Spring BootでThymeleafを使うと何が便利？
Spring BootとThymeleafを組み合わせると、Javaのコントローラクラスで用意したデータをHTMLにスムーズに反映できます。
Thymeleafは、HTMLファイルの中にth:textやth:eachといった属性を記述することで、動的にデータを表示できます。
これにより、次のようなことが簡単にできます：
- ユーザー一覧の表示
- 登録フォームの入力値の受け渡し
- 条件によって表示を切り替える
さらにThymeleafは、通常のHTMLとしてブラウザで開くこともできるため、デザインの確認も簡単に行えます。
4. Spring BootにThymeleafを導入する方法
Spring BootでThymeleafを使用するには、まずThymeleaf starterをプロジェクトに追加する必要があります。これはGradleのbuild.gradleファイルに必要な依存関係を記述することで行います。
Spring Boot Thymeleaf 設定では、このstarterを追加することで、テンプレートエンジンが自動的に有効になり、HTMLテンプレートと連携できるようになります。
以下のように、build.gradleのdependenciesセクションにThymeleafのstarterを追加してください。
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
implementation 'org.springframework.boot:spring-boot-starter-web'
}
この設定によって、Spring BootがThymeleafを自動的に読み込むようになり、HTMLファイルがテンプレートとして扱われるようになります。
また、上記に加えてspring-boot-starter-webも一緒に記述しておくことで、コントローラとテンプレートの連携が可能になります。
5. Pleiadesでの設定手順（依存関係の追加チェック）
Pleiades統合開発環境では、Gradleの設定ファイルを直接編集しなくても、プロジェクト作成時に必要なライブラリをチェックボックスで追加できます。ここでは、Spring BootプロジェクトにThymeleafを導入する手順をステップ形式で解説します。
- Pleiadesを起動して、「
ファイル」メニューから「新規 → Spring スターター・プロジェクト」を選択します。 - プロジェクト名を入力し、ビルドツールとして「Gradle」を選択します。
- 次のステップで「
依存関係の選択」画面が表示されます。ここで以下の2つにチェックを入れます。- Spring Web
- Thymeleaf
- 「
完了」ボタンをクリックして、プロジェクトを作成します。
以上の手順で、Spring Bootに必要なThymeleaf starterとSpring Webの依存関係がGradleに自動的に追加されます。
このように、Pleiadesではチェックボックスを使って簡単にSpring BootとThymeleafの設定ができるため、初心者でも手軽にテンプレートエンジンを導入できます。
6. 初期表示ページのテンプレート作成
Spring BootでThymeleaf starterの設定が完了したら、実際にHTMLテンプレートを作成し、@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 WelcomeController {
@GetMapping("/welcome")
public String welcome(Model model) {
model.addAttribute("username", "山田太郎");
return "welcome";
}
}
次に、src/main/resources/templatesディレクトリの中に、以下のようなwelcome.htmlファイルを作成します。
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8">
<title>ようこそ</title>
</head>
<body>
<h1 th:text="'ようこそ、' + ${username} + 'さん！'">ようこそ！</h1>
</body>
</html>
このテンプレートでは、Thymeleafのth:text属性を使用して、@Controllerから渡されたusernameの値を表示しています。
ブラウザで http://localhost:8080/welcome にアクセスすると、次のような画面が表示されます。
ようこそ、山田太郎さん！
このように、Spring BootにThymeleafを導入することで、サーバーサイドのデータを簡単にHTMLに表示できます。設定も少なく、特にSpring Boot Thymeleaf 設定は初心者にとって習得しやすい構成になっています。
また、テンプレートファイルは通常のHTMLとしても開けるため、デザイン確認にも便利です。テンプレートエンジンとしてのThymeleafは、開発中にも実行後にも扱いやすい点が大きな魅力です。
7. テンプレートフォルダの配置場所と命名ルール
ThymeleafでHTMLテンプレートを表示するには、テンプレートファイルを正しい場所に保存する必要があります。Spring Bootでは、HTMLテンプレートはすべてsrc/main/resources/templatesフォルダに配置する必要があります。
この場所は、Spring Bootが自動的にテンプレートとして認識してくれるディレクトリです。テンプレートファイルはHTML形式で、拡張子は.htmlにする必要があります。
Thymeleaf テンプレート 場所を間違えると、Spring BootがHTMLファイルを見つけられず、「テンプレートが見つかりません」というエラーが出るので注意しましょう。
例えば、welcome.htmlを表示させたい場合は、以下のように配置します：
- 正しいパス：
src/main/resources/templates/welcome.html - 間違ったパス例：
src/main/java/templates/welcome.html（←これはNG）
また、テンプレート名の命名ルールですが、特別な制限はありません。英数字で構成されていればOKです。ただし、Spring Bootの@Controllerのreturn値には拡張子をつけないようにしてください。
例えば、return "welcome";とすれば、Spring Bootはwelcome.htmlを探して表示してくれます。
8. テスト表示の手順（ブラウザで確認）
テンプレートとコントローラの設定が正しくできたら、Spring Bootアプリケーションを起動してブラウザで確認してみましょう。ここでは、初めての画面を表示させるためのSpring Boot HTML 表示の流れを紹介します。
Pleiadesで以下の手順を実行してください：
- 左側のプロジェクトエクスプローラーで、
DemoApplication.javaを右クリックし、「実行 → Java アプリケーション」を選択します。 - コンソールに「
Started DemoApplication in ...」というメッセージが出たら、起動成功です。 - ブラウザを開いて、
http://localhost:8080/welcomeにアクセスします。
正しく設定されていれば、画面には以下のように表示されます。
ようこそ、山田太郎さん！
もし画面が表示されない場合は、後述するミスの例と対処法を参考にしてください。
9. 初心者がやりがちなミスとその対処法
Spring BootとThymeleafを使う際に初心者がつまずきやすいポイントを紹介します。以下はよくあるミスとその原因、対処法です。
① テンプレートの配置場所が間違っている
原因：HTMLファイルをsrc/main/javaやresources/staticなどに置いている。
対処法：テンプレートは必ずsrc/main/resources/templatesフォルダに置いてください。
② HTMLファイルの拡張子を忘れる
原因：welcome.htmやwelcomeのように、拡張子が.htmlでない場合。
対処法：ファイル名は必ず.htmlで終わるようにしましょう。Thymeleaf テンプレート 場所と合わせてチェックするのがポイントです。
③ コントローラの戻り値に拡張子をつけてしまう
原因：コントローラでreturn "welcome.html";としている。
対処法：returnではファイル名のみを指定し、拡張子はつけないようにします。
return "welcome"; // OK
return "welcome.html"; // NG
④ パス設定が間違っている
原因：ブラウザでアクセスするURLと@GetMappingの値が一致していない。
対処法：@GetMapping("/welcome")と定義している場合は、http://localhost:8080/welcomeでアクセスします。
たとえば、URLを/helloにしたいなら、以下のように記述します。
@GetMapping("/hello")
public String hello(Model model) {
model.addAttribute("username", "田中花子");
return "hello";
}
この場合、テンプレートファイル名はhello.html、ブラウザからのアクセスURLはhttp://localhost:8080/helloとなります。
⑤ 起動しても画面が真っ白になる
原因：テンプレート内でThymeleafの属性を正しく書いていない場合や、HTML構文が不正なとき。
対処法：テンプレートの中でth:textなどを使う場合、必ずxmlns:th="http://www.thymeleaf.org"を<html>タグに記述しましょう。
<html xmlns:th="http://www.thymeleaf.org">
また、値が表示されない場合は、model.addAttribute()でデータを正しく渡しているか確認してください。
