Thymeleaf 変数スコープの種類と特徴まとめ｜初心者でもわかるリクエストスコープとセッションスコープ

Thymeleaf 変数スコープの種類と特徴まとめ

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

新人

「先輩、Thymeleafで画面にデータを表示する時に、スコープっていう言葉をよく聞くんですけど、これは何なんですか？」

先輩

「良い質問だね。Thymeleafのスコープというのは、変数をどの範囲で使えるかを決める仕組みなんだ。Spring MVCとThymeleafを組み合わせた時、データはControllerからViewへ渡されるけど、そのときに“どのスコープにデータを置くか”で、見える範囲が変わるんだよ。」

新人

「なるほど！じゃあ、スコープを使い分けることでデータの扱い方が変わるんですね？」

先輩

「その通り。特にThymeleafでは、リクエストスコープ・セッションスコープ・アプリケーションスコープの3種類がよく使われるから、それぞれの特徴をしっかり理解しておこう。」

1. Thymeleafのスコープとは？

Thymeleafのスコープとは、変数（データ）がどの範囲で有効かを示す仕組みです。Spring BootなどでThymeleafを使うとき、@Controllerから値をView（HTMLテンプレート）に渡すことが多いですよね。このとき、どのスコープに値を保存するかによって、そのデータがどこまでアクセスできるかが変わります。

たとえば、ユーザーがWebページにアクセスしてフォームを送信する場面を想像してみましょう。フォーム入力の結果を一時的に表示するだけなら、リクエストスコープで十分です。しかし、ログイン状態など複数ページにまたがって保持したいデータは、セッションスコープを使う必要があります。

SpringのModelオブジェクトを使うと、自動的にリクエストスコープでデータが管理されます。つまり、次のようなControllerコードを書けば、Thymeleaf側でその値を参照できるわけです。


@Controller
public class ScopeExampleController {

    @GetMapping("/scope")
    public String showScopeExample(Model model) {
        model.addAttribute("message", "リクエストスコープのサンプルです");
        return "scopeExample";
    }
}

この場合、messageという変数はリクエストスコープに格納され、Thymeleafテンプレートからアクセスできます。


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

このようにThymeleafのスコープは、変数をどの範囲で利用できるかを制御する大切な要素です。リクエストスコープ・セッションスコープ・アプリケーションスコープなどを理解することで、より柔軟なデータ管理ができるようになります。

2. 変数スコープの必要性

では、なぜThymeleafで「変数スコープ」を理解する必要があるのでしょうか？実は、Webアプリケーションでは「いつ・どこで・どのデータが使えるか」を明確にしないと、意図しないデータの上書きや、情報の漏洩につながる可能性があるからです。

例えば、ユーザーがログインした情報を毎回入力させるのは不便ですよね。そのような場合、セッションスコープを使って「ログイン中のユーザー情報」を保存すれば、ページ間で保持できます。しかし、リクエストスコープを使ってしまうと、ページを移動した瞬間に情報が消えてしまいます。

逆に、セッションスコープをむやみに使いすぎると、不要な情報が残ってメモリを圧迫してしまうこともあります。そのため、状況に応じて適切なスコープを選択することが重要です。

また、Thymeleafのテンプレート内では、スコープに応じて変数の参照方法も異なります。通常は${変数名}で参照できますが、スコープを明示したい場合は次のように書けます。


<p th:text="${#request.getAttribute('message')}"></p>
<p th:text="${#session.getAttribute('user')}"></p>

このように、Thymeleafではスコープを明示することで、どこに保存されているデータかを明確にできます。これにより、変数の衝突や混乱を防ぐことができるのです。

リクエストスコープは短期的なデータ保持、セッションスコープはユーザー単位の中期保持、アプリケーションスコープは全体共有用の長期保持と考えると覚えやすいでしょう。

Thymeleaf スコープの理解は、Spring MVCとThymeleafを組み合わせた開発で避けて通れない重要なテーマです。初心者のうちは、まずリクエストスコープを中心に使いながら、必要に応じて他のスコープを試してみるのがおすすめです。

3. リクエストスコープの仕組みと使い方

Thymeleafで最もよく使われるスコープが「リクエストスコープ」です。リクエストスコープとは、ユーザーがWebページにアクセスしてからレスポンスを受け取るまでの間だけ有効なスコープのことです。つまり、1回のリクエスト処理中にだけデータが保持されます。Spring MVCでは、Modelオブジェクトを使って値を設定すると、自動的にリクエストスコープで扱われます。

新人

「先輩、リクエストスコープって一番よく使うんですか？」

先輩

「そうだね。フォーム入力の結果を一度だけ表示したり、検索結果を画面に出すときなんかに使うんだ。ページをリロードすると消えるのが特徴だよ。」

次の例では、ControllerクラスでModelを使ってメッセージを渡しています。このデータはリクエストスコープで保持され、Thymeleafのテンプレートで表示できます。


@Controller
public class RequestScopeController {

    @GetMapping("/hello")
    public String showMessage(Model model) {
        model.addAttribute("greeting", "こんにちは、Thymeleafのリクエストスコープです！");
        return "hello";
    }
}

上記のコードでは、greetingという変数がリクエストスコープに保存されます。Thymeleaf側でこの変数を使ってデータを表示するには、次のように書きます。


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

このように、Thymeleaf リクエストスコープは、短期的なデータ表示に最適です。ページの遷移ごとに新しいリクエストが発生するため、不要なデータが残る心配もありません。ログイン情報のような永続的なデータではなく、一時的な表示データに使うのが基本です。

4. セッションスコープの使い方と注意点

次に紹介するのは「セッションスコープ」です。セッションスコープは、同じユーザーが複数のページを行き来する間もデータを保持できるスコープです。たとえばログイン情報やショッピングカートの中身など、ユーザー単位で継続的に使うデータを保持するときに便利です。

新人

「なるほど！じゃあ、ログイン中のユーザー情報なんかはセッションスコープで管理するんですね？」

先輩

「その通り。SpringではHttpSessionを使ってデータを格納できるよ。ただし、セッションスコープは便利だけど、使いすぎるとメモリを圧迫することがあるから注意が必要なんだ。」

セッションスコープを使うには、ControllerでHttpSessionオブジェクトを利用します。


@Controller
public class SessionScopeController {

    @GetMapping("/login")
    public String login(HttpSession session) {
        session.setAttribute("userName", "山田太郎");
        return "sessionExample";
    }

    @GetMapping("/mypage")
    public String myPage() {
        return "sessionExample";
    }
}

Thymeleafテンプレートでは、セッションスコープの値にアクセスするために、#sessionを使います。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
    <p>ログインユーザー: <span th:text="${#session.getAttribute('userName')}"></span></p>
</body>
</html>

このように、セッションスコープに格納されたデータは、ログイン後のページでも継続して利用できます。ただし、ログアウト処理やセッションタイムアウト時にはデータが削除されるため、必ず破棄タイミングを意識して設計することが大切です。

また、セッションを使う場合は、スレッドセーフでないオブジェクトを共有しないように気をつけましょう。複数ユーザーが同時アクセスすると予期しない動作が起こることがあります。Thymeleaf セッションスコープはとても便利ですが、必要最小限の利用を心がけるのがポイントです。

5. アプリケーションスコープの利用場面

最後に「アプリケーションスコープ」について見てみましょう。アプリケーションスコープは、アプリ全体で共有されるスコープです。どのユーザーからのリクエストでも同じデータを参照できるため、サイト全体で共通して利用する設定値や統計情報の保持に向いています。

新人

「アプリケーションスコープは、どんなときに使うんですか？」

先輩

「例えば、サイト全体のアクセスカウントとか、定数設定の一覧を保持しておく場合に使うね。アプリ全体で1つだけのデータを共有したいときに役立つよ。」

アプリケーションスコープにデータを設定するには、ServletContextを使います。Spring MVCでも簡単に扱えます。


@Controller
public class ApplicationScopeController {

    @Autowired
    private ServletContext servletContext;

    @GetMapping("/init")
    public String initData() {
        servletContext.setAttribute("siteName", "Thymeleaf学習サイト");
        return "appExample";
    }

    @GetMapping("/info")
    public String showInfo() {
        return "appExample";
    }
}

Thymeleaf側では、#servletContextを使ってアプリケーションスコープの値にアクセスします。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<body>
    <p>サイト名: <span th:text="${#servletContext.getAttribute('siteName')}"></span></p>
</body>
</html>

このように、アプリケーションスコープはすべてのユーザーに共通のデータを保持できますが、書き換えには注意が必要です。ひとつのユーザーが更新すると、他のユーザーにも影響してしまうためです。そのため、主に定数や読み取り専用の情報を格納する用途で使うのが一般的です。

Thymeleaf アプリケーションスコープを正しく使うことで、全体的なデータの管理がシンプルになります。特に運用管理ページや設定情報の表示において有効です。開発時には、リクエストスコープ・セッションスコープ・アプリケーションスコープの違いを意識しながら設計すると、後のメンテナンスも容易になります。

6. スコープの使い分け方（どのスコープをいつ使うべきか）

新人

「先輩、ここまででリクエストスコープ、セッションスコープ、アプリケーションスコープの違いは分かってきたんですが、実際にどの場面でどれを使うべきか迷ってしまいそうです。」

先輩

「良い質問だね。これは開発現場でもよくある悩みなんだ。基本的な考え方として、“データをどのくらいの期間・どの範囲で保持したいか”でスコープを選ぶといいよ。」

たとえば、フォームの入力内容や検索結果のように「一度だけ表示すればいい」ものは、リクエストスコープを使います。これはページを更新すると消えるため、短期的なデータ保持に最適です。

一方で、ログイン情報やユーザーの状態を保持したい場合は、セッションスコープが便利です。ページ間を移動してもデータが残るため、ユーザー単位での継続的な利用に向いています。

そして、全ユーザー共通で使用する定数やサイト情報などは、アプリケーションスコープに格納します。サイト全体のアクセス数や固定設定などに適しています。

以下のように整理して覚えておくと良いでしょう。


【リクエストスコープ】
・一時的なデータの受け渡しに使う
・フォームやメッセージ表示などに最適

【セッションスコープ】
・ユーザー単位でデータを保持
・ログイン情報や状態管理に最適

【アプリケーションスコープ】
・全体共通データを保持
・設定情報や統計データに最適

スコープの選択を誤ると、意図しない動作を引き起こすことがあります。たとえば、本来リクエストスコープで十分なデータをセッションスコープに入れてしまうと、古い情報が残って再表示されることがあります。Thymeleaf スコープを正しく使い分けることは、バグの少ないWebアプリを作る第一歩なのです。

7. よくある間違いとデバッグ方法（変数が表示されない・スコープの混同など）

新人

「先輩、テンプレートに書いた変数が表示されないことがあるんですが、どこが原因なんでしょうか？」

先輩

「それは、スコープの指定ミスや変数名の一致漏れがよくある原因だね。たとえば、Controllerで設定した変数がリクエストスコープにあるのに、Thymeleaf側でセッションスコープを見にいっているケースなんかが典型的だよ。」

Thymeleafで変数が表示されない場合、まず確認すべきポイントは次の3つです。

Controllerで設定したスコープと、テンプレートで参照しているスコープが一致しているか
変数名のスペルミスや大文字小文字の違いがないか
データがnullの状態でテンプレートを表示していないか

特に、セッションスコープやアプリケーションスコープを扱う場合、Thymeleafでは明示的にスコープ名を指定する必要があります。


<!-- 正しいスコープ参照の例 -->
<p th:text="${#request.getAttribute('message')}"></p>
<p th:text="${#session.getAttribute('userName')}"></p>
<p th:text="${#servletContext.getAttribute('siteName')}"></p>

もし変数が表示されないときは、ブラウザのデベロッパーツールや、サーバー側のログを確認して、Controller側で値が正しく設定されているかを確かめましょう。Spring MVCでは、Modelの内容をデバッグ出力することで確認することもできます。


System.out.println(model.asMap());

このように、Thymeleaf スコープの混同や変数の渡し漏れは初心者に多いミスです。特にpleiadesでGradleプロジェクトを作成している場合、Controllerが正しいアノテーションで認識されているか（@Controllerが付与されているか）も確認しましょう。

新人

「確かに、@RestControllerを使っていたときは画面が表示されませんでした…」

先輩

「そうそう。今回はThymeleafでViewを返す構成だから、@Controllerを使わないとHTMLテンプレートを正しく返せないんだ。スコープ以前にそこが重要なポイントなんだよ。」

Thymeleaf スコープに関する不具合は、変数の範囲とアノテーションの組み合わせを見直すだけで解決するケースが多いです。焦らず一つずつ確認していきましょう。

8. Thymeleafでスコープを正しく理解するコツ

新人

「だいぶ理解できてきました！最後に、Thymeleafのスコープを正しく使うコツを教えてください。」

先輩

「一番のコツは、“どのデータを、どの範囲で使いたいのか”を意識することだね。それさえ整理できれば、自然とスコープの選択も正しくなるよ。」

Thymeleaf スコープを理解するには、次のポイントを覚えておくと良いでしょう。

リクエストスコープは一時的なデータ表示に
セッションスコープはユーザー単位の情報保持に
アプリケーションスコープは全体共有データに

また、変数が表示されないときは、焦らずスコープを確認し、Controllerの設定を見直しましょう。スコープを理解すると、Thymeleafのテンプレートがぐっと使いやすくなります。

Spring MVC＋Thymeleafの開発では、スコープを正しく使うことがデータの受け渡しの基本です。pleiadesでGradleプロジェクトを組む場合でも、ControllerとViewの流れをしっかり意識していれば、スコープに関するトラブルはほとんど防げます。

最後に覚えておきたいのは、Thymeleaf スコープは単なる変数の置き場所ではなく、アプリケーション全体の「データの流れ」を設計するための重要な仕組みであるということです。正しいスコープ選択ができるようになると、コードの見通しが良くなり、保守もしやすくなります。

新人

「ありがとうございます！これで、どのスコープを使えばいいか迷わずに済みそうです！」

先輩

「その調子！Thymeleaf スコープを理解すれば、データの受け渡しがもっとスマートになるから、実際にプロジェクトでどんどん試していこう。」

こうしてThymeleaf スコープを正しく使い分ける力を身につければ、Spring MVCの開発効率が格段に上がります。リクエスト・セッション・アプリケーション、それぞれの特徴を意識して設計していきましょう。