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の学習を効率化したい方へ

この記事の内容をもっと深く知るには、以下の入門書が最適です。

Spring Framework超入門をAmazonで見る

元・職業訓練講師が直接指導【Spring Boot実践セミナー】

職業訓練講師が最短攻略！Spring Bootによる「商用バックエンド構築」とDI/AOPの極意。

累計120万PV超の技術メディア運営チームが贈る、商用開発基準の特別カリキュラム

職業訓練講師が最短攻略！Spring Bootによる「商用バックエンド構築」とDI/AOPの極意。

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