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

新人

「先輩、Spring Bootで使われているThymeleafって何ですか？テンプレートエンジンって言われても、いまいちピンとこないです。」

先輩

「Thymeleaf（タイムリーフ）は、HTMLにJavaのデータを埋め込んで動的に画面を作るためのテンプレートエンジンだよ。Spring MVCでよく使われているんだ。」

新人

「なるほど！HTMLにJavaの値を表示できるんですね。どうやってデータを渡すんですか？」

先輩

「良い質問だね。では、まずThymeleafとは何かをしっかり理解してから、変数の扱い方や定義方法を見ていこう。」

1. Thymeleafとは何か（テンプレートエンジンの概要）

Thymeleafは、Javaで作った値をHTMLの中に埋め込むためのテンプレートエンジンです。Spring BootやSpring MVCの標準ビューとして利用されており、サーバーサイドで生成したデータをHTML画面に簡単に反映できます。テンプレートエンジンとは、静的なHTMLファイルに動的な値を差し込む仕組みのことを指します。

例えば、サーバー側で取得したユーザー名や商品情報などを、Thymeleafを使ってHTMLの中に出力できます。JSPと似ていますが、ThymeleafはHTML構文に沿って記述できるのが特徴で、HTMLファイルとして直接ブラウザで確認できる点が便利です。

Thymeleafを導入すると、開発者はHTMLを保ちながらサーバー側の変数を自然に扱えるため、テンプレートエンジンの中でも特に人気があります。

2. Thymeleafで変数を扱う目的（HTMLとの連携や表示の仕組み）

Thymeleafでは、HTMLとJavaのデータを連携させるために「変数」を利用します。この変数は、サーバー側のSpringコントローラから渡された値をHTML内で表示するための橋渡し役です。

たとえば、Springの@ControllerクラスでModelオブジェクトを使ってデータを渡すと、Thymeleafテンプレートで${}構文を用いてその値を取得できます。これによって、動的に値を埋め込むことができます。

基本的には、コントローラがHTMLにデータを渡す → ThymeleafがそれをHTML内で表示、という流れです。

では、具体的にどのように変数を定義して使うのか、順を追って見ていきましょう。

3. コントローラからThymeleafにデータを渡す流れの全体像

Thymeleafで変数を使うには、まずSpringのコントローラ側で値を準備し、それをModelオブジェクト経由でテンプレートに渡します。このときに使うのがModelクラスです。pleiadesでGradleプロジェクトを作成すれば、必要な依存関係も簡単に追加できます。

次のコードは、Springのコントローラで変数を定義し、Thymeleafに渡す基本的な例です。


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("name", "田中太郎");
        return "hello";
    }
}

上記では、Modelに「name」という変数を追加し、値として「田中太郎」を設定しています。この変数は、ThymeleafのHTMLテンプレートで呼び出すことができます。

次に、Thymeleaf側で変数を表示するHTMLを書いてみましょう。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Hello Page</title>
</head>
<body>
    <h1 th:text="'こんにちは、' + ${name} + 'さん！'">こんにちは、ゲストさん！</h1>
</body>
</html>

このHTMLでは、th:text属性を使って${name}変数を展開しています。結果として、ブラウザには「こんにちは、田中太郎さん！」と表示されます。


こんにちは、田中太郎さん！

このように、Thymeleafでは変数を通してサーバーサイドの値をHTMLに反映できます。これがThymeleaf変数定義の基本的な流れです。

次の記事では、th:withを使ったローカル変数の定義方法や、スコープを意識した使い分けをさらに詳しく解説していきます。

4. Thymeleafで変数を定義する方法（th:withやローカル変数の使い方）

Thymeleafでは、ページ全体で使う変数だけでなく、一時的に使う「ローカル変数」を定義することもできます。このときに利用するのがth:with属性です。th:withを使うことで、テンプレートの中に一時的な変数を作成し、複雑な式を整理したり、見やすくしたりすることができます。

例えば、複数の変数を組み合わせて表示したい場合に、いちいち${}の中で計算を書くと読みづらくなります。そんなときにth:withを使えば、HTMLの一部で一時的な変数を定義して扱えます。


<div th:with="greeting='こんにちは', userName=${name}">
    <p th:text="${greeting} + '、' + ${userName} + 'さん！'">こんにちは、ゲストさん！</p>
</div>

このようにth:withの中で複数の変数を定義できます。上記の例では、greetingとuserNameをローカル変数として扱っています。変数はカンマ区切りで複数指定でき、定義したブロック内でのみ有効です。

この仕組みを使うと、同じテンプレート内で何度も同じ式を書く必要がなくなり、コードの保守性が上がります。Thymeleafのth:withは、HTML構造を保ちながらロジックを分かりやすく整理できる便利な機能です。

新人

「なるほど、th:withを使うと一時的な変数を作れるんですね。でも、Modelで渡した変数とは違うんですか？」

先輩

「そうだね。Modelで渡すのはコントローラからテンプレートに渡す全体的な変数で、th:withで定義するのはテンプレート内だけで使うローカル変数なんだ。使い分けることで、コードが整理されて読みやすくなるよ。」

5. コントローラからModelに値を渡す方法（@Controller＋Modelオブジェクト）

Thymeleafの変数は、コントローラで定義したModelオブジェクトを介してテンプレートに渡されます。Modelとは、サーバーからビューにデータを送るためのオブジェクトで、Spring MVCでは最も基本的なデータ受け渡しの仕組みです。

pleiadesを使ってGradleプロジェクトを作成している場合、Spring Boot Starter Thymeleafを依存関係として追加すれば、自動的にThymeleafがビューとして設定されます。

次の例では、複数の変数をModelに追加してThymeleafに渡しています。


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 SampleController {

    @GetMapping("/user")
    public String user(Model model) {
        model.addAttribute("name", "山田花子");
        model.addAttribute("age", 28);
        model.addAttribute("city", "東京");
        return "user";
    }
}

上記のコードでは、ユーザー名・年齢・都市をそれぞれ変数としてModelに登録しています。これらの値は、Thymeleafテンプレート内で${name}や${age}のように参照できます。

この方法によって、サーバーサイドで処理したデータをHTMLに動的に表示できるようになります。例えば、ユーザー情報や商品リスト、検索結果なども同じ仕組みで扱えます。

新人

「Modelにデータを入れると、それがThymeleafで表示できるようになるんですね！じゃあ、Modelに入れなかった変数は使えないんですか？」

先輩

「その通り。Modelに追加していないデータはThymeleaf側では認識できないよ。必要なデータはすべてModelを通して渡すのが基本ルールだね。」

6. HTML側で変数を参照する方法（${}式の使い方）

ThymeleafのHTMLテンプレートでは、変数を${}構文を使って参照します。この構文はEL式と呼ばれ、Modelから渡されたデータをテンプレート内で取り出すための基本的な書き方です。

次の例では、コントローラから渡された3つの変数をHTMLに出力しています。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>User Info</title>
</head>
<body>
    <h1 th:text="'ユーザー情報'">ユーザー情報</h1>
    <p>名前：<span th:text="${name}">ゲスト</span></p>
    <p>年齢：<span th:text="${age}">0</span>歳</p>
    <p>居住地：<span th:text="${city}">未設定</span></p>
</body>
</html>

このコードでは、th:text属性を使ってそれぞれの変数を表示しています。Modelから渡された値がHTMLに自動的に反映され、動的な画面が生成されます。


ユーザー情報
名前：山田花子
年齢：28歳
居住地：東京

このように、Thymeleafでは変数を簡単に埋め込むことができるため、画面表示の仕組みをJavaコードから分離できます。HTMLデザイナーとエンジニアが分業しやすいのもThymeleafの魅力です。

また、${}式はオブジェクトのプロパティにもアクセスできます。たとえば、ModelにUserオブジェクトを追加した場合、${user.name}や${user.email}のようにドット記法で値を取得できます。


model.addAttribute("user", new User("佐藤次郎", "jiro@example.com"));


<p th:text="${user.name}">名前</p>
<p th:text="${user.email}">メール</p>

このように、Thymeleafの変数参照構文はシンプルでわかりやすく、SpringのModelとの連携もスムーズです。初心者でも仕組みを理解すれば、テンプレートを自由にカスタマイズできるようになります。

次の記事では、Thymeleafの変数スコープやセッションとの関係について、もう一歩踏み込んで解説していきます。

7. 変数スコープの考え方（リクエストスコープ・セッションスコープ・アプリケーションスコープ）

Thymeleafでは、変数を扱う際に「スコープ」という概念を理解しておくことが大切です。スコープとは、変数がどの範囲で有効かを表す仕組みのことです。例えば、ある画面だけで使える変数もあれば、ログイン中ずっと保持したい変数もあります。これを制御するのがスコープの役割です。

Spring MVCでよく使われるスコープには、主に「リクエストスコープ」「セッションスコープ」「アプリケーションスコープ」の3種類があります。

リクエストスコープは、1回のリクエスト内だけで有効な変数です。ページを再読み込みしたり、別のURLに移動したりすると値は消えます。最もよく使われるスコープで、Modelで渡す変数は基本的にこのスコープに属します。

セッションスコープは、ユーザーごとに保持されるスコープです。ログイン情報や一時的な状態を保持したい場合に使われ、ブラウザを閉じるまで値が保持されます。

アプリケーションスコープは、アプリ全体で共有されるスコープです。全ユーザーで共通の設定値や統計データなどを扱うときに利用されます。

新人

「なるほど！スコープによって変数が生きている範囲が違うんですね。でも、Thymeleafでどうやってスコープを区別するんですか？」

先輩

「良い質問だね。Thymeleafでは、${}の前にスコープ名を付けることで明示的に指定できるんだ。例えば${session.userName}のように書けば、セッションスコープの変数を参照できるよ。」

8. スコープごとの使い分け例（リクエスト属性とセッション属性の実践）

それでは実際に、リクエストスコープとセッションスコープの使い分けを見てみましょう。まずはリクエストスコープです。これは通常のModelを使って値を渡す方法で、ページの再表示のたびに新しい値が渡されます。


@GetMapping("/request-scope")
public String requestScope(Model model) {
    model.addAttribute("message", "リクエストスコープの値です");
    return "scope";
}

次に、セッションスコープを使う場合はHttpSessionを利用します。セッションスコープの変数は、ユーザーがサイトを利用している間ずっと保持されるため、ログイン状態の管理などに便利です。


@GetMapping("/session-scope")
public String sessionScope(HttpSession session) {
    session.setAttribute("sessionMessage", "セッションスコープの値です");
    return "scope";
}

ThymeleafのHTML側では、スコープを明示的に指定して変数を参照します。


<p th:text="${message}">リクエストの値</p>
<p th:text="${session.sessionMessage}">セッションの値</p>

このように、リクエストスコープの変数は${message}で直接参照できますが、セッションスコープの値は${session.xxx}のように「session.」を付けてアクセスします。これを覚えておくと、スコープの違いによる混乱を防げます。

また、アプリケーションスコープを使いたい場合は、ServletContextを通じて値を設定します。全ユーザーに共通する情報を管理したいときに便利です。


@Autowired
private ServletContext context;

@GetMapping("/app-scope")
public String appScope() {
    context.setAttribute("appMessage", "アプリケーション全体の共通メッセージ");
    return "scope";
}


<p th:text="${application.appMessage}">アプリケーション共通メッセージ</p>

このように、Thymeleafではスコープを指定するだけで簡単にアクセスできます。Spring MVCと組み合わせることで、画面間でのデータ共有を柔軟に実現できます。

新人

「セッションに保存した変数は、別のページでも使えるんですね！でも、リクエストスコープの値は毎回消えるんですか？」

先輩

「その通り。リクエストスコープは一時的な通信で使われるものだから、次のリクエストでは初期化されるんだ。必要に応じてセッションスコープを使い分けるのがポイントだね。」

9. よくある間違いと注意点（変数が表示されない・スコープの混同など）

Thymeleafを使う初心者がよくつまずくのが、変数が表示されないという問題です。この原因の多くはスコープの扱い方にあります。例えば、Modelで設定したリクエストスコープの変数を、別ページで${}で参照しようとしても表示されません。これはリクエストが切り替わっているためです。

また、セッションスコープに値を入れたのに表示されない場合は、HTML側で${session.変数名}の形式を忘れているケースが多いです。Thymeleafでは、スコープを明示しないとデフォルトでリクエストスコープが参照される点に注意しましょう。

もう一つの典型的な間違いは、変数名の不一致です。Java側でmodel.addAttribute("userName", "山田太郎");と設定したのに、テンプレート側で${username}のように小文字で書いてしまうと、値は表示されません。変数名は完全一致で参照されるため、大文字小文字も区別されます。

さらに、th:text属性を付け忘れていると、Thymeleafが値を展開しません。単にHTML内に${name}と書いても認識されないので、必ずth:text="${name}"のように書く必要があります。

もし画面に何も表示されない場合は、まず次の点を確認しましょう。

ModelやSessionに変数を正しく追加しているか
HTML側でスコープ指定（session.など）を忘れていないか
変数名の綴りが正しいか
th:text属性を付けているか

これらを確認すれば、ほとんどの「変数が表示されない」問題は解決できます。

新人

「あっ、前に値が表示されなかったのは、th:textを忘れてたのが原因かもしれません！」

先輩

「そうだね。ThymeleafはHTMLとして成立する書き方を重視しているから、属性を正しく指定するのが大事なんだ。慣れてくれば、スコープと変数の関係が自然に分かるようになるよ。」

Thymeleafのスコープを理解することで、アプリケーションの状態管理やデータ表示が格段にやりやすくなります。リクエスト属性とセッション属性を正しく使い分けることが、安定したWebアプリ開発の第一歩です。

まとめ

ここまで、Spring Boot開発において欠かせないテンプレートエンジンであるThymeleaf（タイムリーフ）の変数定義と活用方法について詳しく解説してきました。Thymeleafは、JavaのサーバーサイドロジックとフロントエンドのHTMLをスムーズに連携させるための強力なツールです。

本記事のポイントを振り返ると、まずはModelオブジェクトを利用してコントローラからテンプレートへデータを渡すという基本の流れが重要であることが分かりました。また、テンプレート内部だけで一時的に利用するth:withによるローカル変数の定義は、複雑になりがちなHTMLコードをスッキリと整理し、可読性を高めるために非常に有効なテクニックです。

さらに、エンジニアとしてステップアップするためには、変数のスコープ（有効範囲）を正しく理解することが不可欠です。リクエストごとにリセットされるリクエストスコープ、ユーザーのセッション中保持されるセッションスコープ、そしてアプリケーション全体で共有されるアプリケーションスコープ。これらを適切に使い分けることで、ユーザー体験（UX）の向上や、バグの少ない堅牢なシステム構築が可能になります。

実践的なサンプルプログラム：ユーザー管理画面の応用例

学習の締めくくりとして、これまでに学んだ「Modelへの格納」「th:withでの変数定義」「プロパティ参照」をすべて盛り込んだ実践的なコードを確認しましょう。


// コントローラ側：ユーザー情報とステータスを渡す
@GetMapping("/profile")
public String viewProfile(Model model, HttpSession session) {
    // ユーザーオブジェクトをModelに追加
    User user = new User("佐藤健一", "satou@example.com", "プレミアム会員");
    model.addAttribute("currentUser", user);
    
    // システムの更新日時をセッションに保持
    session.setAttribute("lastLogin", "2026年1月27日");
    
    return "profile";
}


<div class="user-container" th:with="isPremium=${currentUser.status == 'プレミアム会員'}">
    <h2 th:text="${currentUser.name} + ' 様のマイページ'">ユーザー名</h2>
    
    <div class="status-badge" th:if="${isPremium}">
        <span class="badge bg-gold">プレミアムランク</span>
    </div>
    
    <ul class="info-list">
        <li>メールアドレス：<span th:text="${currentUser.email}">mail@example.com</span></li>
        <li>最終ログイン：<span th:text="${session.lastLogin}">2026/01/01</span></li>
    </ul>
    
    <p class="note" th:text="${isPremium} ? 'いつもご利用ありがとうございます。' : '通常プランを利用中です。'">
        メッセージが表示されます
    </p>
</div>

このサンプルでは、th:withを使って「プレミアム会員かどうか」という判定結果をisPremiumというローカル変数に格納しています。こうすることで、同じ判定式を何度も書かずに済み、後から条件が変わった際（例えば「特別会員」もプレミアム扱いにするなど）の修正が1箇所で完了するため、メンテナンス性が飛躍的に向上します。

Thymeleafの変数操作に慣れることは、Spring Boot習得の最短ルートと言っても過言ではありません。今回紹介したエラーチェックのポイントやスコープの概念を意識しながら、ぜひ実際のプロジェクトでも積極的に活用してみてください。

先生と生徒の振り返り会話

生徒

「先生、まとめまで読んでようやく全体像が見えてきました！コントローラでmodel.addAttributeして、HTML側で${}で受け取る。これが基本のキャッチボールなんですね。」

先生

「その通り！良い例えだね。データの受け渡しが基本だけど、現場ではさらにth:withを使って、HTMLの中で読みやすく計算したり、条件を整理したりすることも多いんだよ。」

生徒

「th:withは便利そうですね。あと、さっき間違えそうになったんですけど、セッションのデータを見るときは${session.変数名}って書かないといけないんですよね？」

先生

「正解。そこを忘れると『値が入っているはずなのに表示されない！』という沼にハマってしまうんだ。リクエストとセッションの境界線を意識できるようになると、一人前のSpringエンジニアに大きく近づけるよ。」

生徒

「変数名の大文字小文字にも気をつけます。Thymeleafはエラーが分かりにくいこともあるから、一つずつ丁寧に確認するのが大事ですね。ありがとうございました！」

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

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

Thymeleaf（タイムリーフ）とは具体的にどのような役割を持つツールなのですか？

Thymeleafは、Javaを用いたWeb開発、特にSpring BootやSpring MVCにおいて標準的に利用される「テンプレートエンジン」です。その主な役割は、サーバーサイドで生成・処理されたJavaのデータをHTMLに埋め込み、ユーザーのブラウザに表示する「動的なWebページ」を作成することです。静的なHTMLファイルに対して、プログラムから渡された変数やリスト、オブジェクトなどの値を差し込む仕組みを提供します。JSP（JavaServer Pages）の進化形のような立ち位置ですが、HTMLの構文を崩さずに記述できるため、ブラウザで直接ファイルを開いてもデザインが崩れにくいという大きなメリットがあります。

Thymeleaf 変数の定義方法をわかりやすく解説｜初心者向けテンプレート入門