Spring MVCのViewResolver設定とThymeleafの連携方法とよくあるエラーの解決

Spring MVCのViewResolver設定：Thymeleaf連携とよくあるエラー

先生と生徒の会話形式で理解しよう

生徒

「Spring MVCでThymeleafを使って画面表示しようとしたんですが、うまく表示されなくて困っています…」

先生

「なるほど。Spring MVCとThymeleafを連携させるには、ViewResolverの設定が重要なポイントになりますよ。」

生徒

「ViewResolverって何ですか？設定が必要なんですか？」

先生

「はい、ViewResolverの設定次第で、HTMLファイルが正しく解釈されないこともあるんです。今回は設定方法と、初心者がハマりやすいエラーの原因と対策も丁寧に解説していきましょう。」

1. Spring MVCにおけるViewResolverとは？

Spring MVCでは、コントローラーが返すView名（例えば"index"など）をもとに、実際に表示するHTMLテンプレートを探す仕組みが必要です。この役割を担うのがViewResolverです。Thymeleafを使う場合、このViewResolverをThymeleaf用に設定する必要があります。

例えば、コントローラーで次のように書くとします：


@GetMapping("/hello")
public String helloPage(Model model) {
    model.addAttribute("message", "こんにちは、Thymeleaf！");
    return "hello";
}

この場合、Springは「hello.html」というテンプレートファイルを探しますが、どのディレクトリにあるか、どうやってレンダリングするかはViewResolverが決めています。

2. Spring BootでのThymeleaf設定方法

Spring Bootを使っている場合は、実はThymeleafのViewResolverは自動的に設定されています。デフォルトでは以下のような設定です：

テンプレートのパス：src/main/resources/templates/
ファイル拡張子：.html
Content-Type：text/html

ですので、例えば「hello.html」を表示したい場合、以下のようなファイルをtemplatesフォルダに置くだけでOKです。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Hello Page</title>
</head>
<body>
    <h1 th:text="${message}">固定メッセージ</h1>
</body>
</html>

3. application.propertiesに書くThymeleafのViewResolver設定

カスタマイズしたい場合は、application.propertiesに以下のような設定を追加できます。


spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html
spring.thymeleaf.mode=HTML
spring.thymeleaf.encoding=UTF-8
spring.thymeleaf.cache=false

prefixやsuffixを変えれば、別のディレクトリにテンプレートを置くこともできます。cache=falseは開発中にテンプレートの変更がすぐ反映されるようにするための設定です。

4. よくあるエラーとその対策

ThymeleafとSpring MVCを使っていると、初心者がつまずきやすいエラーがいくつかあります。代表的なものを見てみましょう。

テンプレートが見つからない

コントローラーで返すView名に対して、対応するHTMLが見つからないと次のようなエラーになります：


org.springframework.web.servlet.view.InternalResourceViewResolver: No matching resource found for view name [hello]

これは、HTMLファイルの場所や拡張子が正しくない場合に発生します。設定したprefix・suffixを見直しましょう。

Thymeleafの構文エラー

テンプレート内のth:textやth:eachで書き方を間違えると、画面が表示されなかったり、変数が展開されなかったりします。

例：


<!-- NG: スペルミス -->
<p th:tex="${message}">Hello</p>
<!-- OK -->
<p th:text="${message}">Hello</p>

データがnullになる

コントローラー側でモデルに値を入れ忘れると、テンプレートで表示できません。次のようにModelにちゃんとデータを入れましょう。


@GetMapping("/sample")
public String sample(Model model) {
    model.addAttribute("name", "太郎");
    return "sample";
}

5. Spring Bootを使わない場合のViewResolver設定

Spring Bootを使っていない従来型のSpring MVCでは、Java ConfigやXMLでViewResolverを明示的に設定する必要があります。

Java Configでの設定例：


@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
    @Bean
    public SpringResourceTemplateResolver templateResolver() {
        SpringResourceTemplateResolver resolver = new SpringResourceTemplateResolver();
        resolver.setPrefix("/WEB-INF/views/");
        resolver.setSuffix(".html");
        resolver.setTemplateMode(TemplateMode.HTML);
        resolver.setCharacterEncoding("UTF-8");
        return resolver;
    }

    @Bean
    public SpringTemplateEngine templateEngine() {
        SpringTemplateEngine engine = new SpringTemplateEngine();
        engine.setTemplateResolver(templateResolver());
        return engine;
    }

    @Bean
    public ViewResolver viewResolver() {
        ThymeleafViewResolver resolver = new ThymeleafViewResolver();
        resolver.setTemplateEngine(templateEngine());
        resolver.setCharacterEncoding("UTF-8");
        return resolver;
    }
}

/WEB-INF/views/というディレクトリ構成にしている点がポイントです。

6. ViewResolver設定をデバッグする方法

うまくHTMLが表示されないときは、ログを確認することが大事です。application.propertiesでログレベルをDEBUGに設定して、テンプレートの解決プロセスを見ましょう。


logging.level.org.springframework.web=DEBUG
logging.level.org.thymeleaf=DEBUG

これで、Springがどのテンプレートを探しに行っているかがログに出力され、問題の特定がしやすくなります。

まとめ

Spring MVCとThymeleaf連携の要点整理

Spring MVCにおけるViewResolverの役割は、コントローラーから返される論理的なビュー名を、実際のテンプレートファイルへと結び付ける重要な仕組みです。特にThymeleafを利用する場合には、テンプレートの配置場所や拡張子、文字コードの設定などが正しく整っていることが前提となります。Spring Boot環境ではこれらの設定が自動化されているため、初心者でも比較的簡単に画面表示まで到達できますが、設定の意味を理解していないとエラー発生時に原因特定が難しくなります。

本記事では、Spring MVCとThymeleafの連携において重要となるViewResolver設定について、基本から実践的なトラブル対応までを丁寧に整理しました。特に、prefixやsuffixの設定はテンプレートの検索パスを決定するため、ディレクトリ構成と一致しているかを確認することが重要です。また、開発時にはキャッシュを無効化することで変更内容を即時反映させることができ、効率的な開発につながります。

よくあるエラーとしては、テンプレートファイルが見つからない問題や、Thymeleafの構文ミス、Modelへの値設定忘れなどが挙げられます。これらは一見すると複雑に見えますが、ログ出力を活用して処理の流れを確認することで、多くの場合は迅速に解決可能です。特にログレベルをDEBUGに設定することで、Springがどのテンプレートを探索しているのかが明確になり、問題の切り分けが容易になります。

また、Spring Bootを利用しない従来型のSpring MVCでは、ViewResolverを手動で定義する必要があり、テンプレートエンジンやリゾルバの設定を正しく組み合わせることが求められます。この場合、設定クラスの記述ミスやBean定義の不足によって表示エラーが発生することもあるため、設定内容を一つ一つ丁寧に確認することが重要です。

サンプルプログラムで振り返る


@Controller
public class SummaryController {

    @GetMapping("/summary")
    public String summary(Model model) {
        model.addAttribute("title", "ViewResolverとThymeleafのまとめ");
        model.addAttribute("message", "設定を正しく行うことで安定した画面表示が可能になります");
        return "summary";
    }
}


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>まとめページ</title>
</head>
<body>
    <h1 th:text="${title}">タイトル</h1>
    <p th:text="${message}">メッセージ</p>
</body>
</html>

実行結果のイメージ


ViewResolverとThymeleafのまとめ
設定を正しく行うことで安定した画面表示が可能になります

このように、コントローラーで設定した値がテンプレートに正しく反映されることで、Spring MVCとThymeleafの連携が正常に機能していることが確認できます。基本的な流れとしては、リクエスト受信からコントローラー処理、Modelへのデータ格納、ViewResolverによるテンプレート解決、そしてHTMLレンダリングという一連の処理が重要なポイントになります。

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

生徒

「Spring MVCとThymeleafの連携って、最初は難しそうに見えましたが、流れを理解するとだいぶ整理できました。」

先生

「そうですね。特にViewResolverの役割を理解すると、なぜテンプレートが表示されるのかが見えてきます。」

生徒

「prefixやsuffixの設定が間違っていると、テンプレートが見つからないエラーになる理由も納得できました。」

先生

「その通りです。設定とディレクトリ構成は必ず一致させることが大切です。」

生徒

「あと、ログをDEBUGにすると調査がしやすいのも勉強になりました。」

先生

「実務ではログ確認は非常に重要です。エラーを恐れずに原因を一つずつ確認していきましょう。」

生徒

「これでSpring MVCとThymeleafの基本はしっかり理解できた気がします。」

先生

「良いですね。次はフォーム連携やバリデーションにも挑戦してみましょう。」

生成AIを基礎から学びたい方へ

ChatGPTなどの生成AIをこれから学びたい方に向けて、AIスキルアカデミーの口コミ・評判、料金、無料セミナーの内容を詳しくまとめています。

AIスキルアカデミーの口コミ・評判を詳しく見る

スタースクール：社会人向け実務教育プロジェクト

【職業訓練講師が直接指導】

社会人向けSpring Boot実務セミナー｜職業訓練講師が教えるWebシステム構築の極意

Java入門からSpring Boot実務まで。現場で絶賛される「設計の型」を最短距離で習得。

技術記事の内容を、自分の「スキル」へ変える。

職業訓練講師が最短攻略！社会人向けSpring Bootによる「商用Webシステム構築」の実践。

モダンJava開発の事実上の標準Spring Boot。本セミナーでは、その圧倒的利便性の核にある「DI（依存性の注入）」を完全解剖。「設定より規約」を体現した効率的なアーキテクチャ設計を学び、ThymeleafやSpring Data JPAを組み合わせた、現場で必須となるWebシステムの作り方を60分で濃縮体験します。