Spring Boot 中使用 Mustache 模板引擎指南

1. 概述

本文将重点介绍在 Spring Boot 应用中使用 Mustache 模板生成 HTML 内容。Mustache 是一款无逻辑模板引擎，因其简洁性广受欢迎。需要了解基础知识的读者，可参考我们的 Mustache 入门教程。

2. Maven 依赖

要在 Spring Boot 中使用 Mustache，需在 pom.xml 中添加专用 Starter：

<dependency>            
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mustache</artifactId>
</dependency>
<dependency> 
    <groupId>org.springframework.boot</groupId> 
    <artifactId>spring-boot-starter-web</artifactId> 
</dependency>

⚠️ 注意：必须同时引入 spring-boot-starter-web 依赖。

3. 创建模板

通过示例创建一个简单的 MVC 应用，展示网页上的文章列表。首先编写文章内容模板：

<div class="starter-template">
    {{#articles}}
    <h1>{{title}}</h1>
    <h3>{{publishDate}}</h3>
    <h3>{{author}}</h3>
    <p>{{body}}</p>
    {{/articles}}
</div>

保存为 article.html，并在 index.html 中引用：

<div class="container">
    {{>layout/article}}
</div>

✅ 说明：

layout 是子目录名
article 是模板文件名
默认模板扩展名是 .mustache，可通过配置覆盖：
```
spring.mustache.suffix:.html
```

4. 控制器实现

编写文章展示控制器：

@GetMapping("/article")
public ModelAndView displayArticle(Map<String, Object> model) {

    List<Article> articles = IntStream.range(0, 10)
      .mapToObj(i -> generateArticle("Article Title " + i))
      .collect(Collectors.toList());

    model.put("articles", articles);

    return new ModelAndView("index", model);
}

关键点：

控制器返回文章列表供页面渲染
模板中的 {{#articles}}...{{/articles}} 标签负责遍历列表
generateArticle() 方法生成包含随机数据的 Article 实例
❌ 注意：控制器返回的模型键名必须与模板标签完全一致

测试代码：

@Test
public void givenIndexPage_whenContainsArticle_thenTrue() {

    ResponseEntity<String> entity 
      = this.restTemplate.getForEntity("/article", String.class);
 
    assertEquals(entity.getStatusCode(), HttpStatus.OK);
    assertTrue(entity.getBody()
      .contains("Article Title 0"));
}

启动命令：

mvn spring-boot:run

访问 http://localhost:8080/article 效果：

5. 处理默认值

当未提供占位符值时，Mustache 会抛出异常。为避免此问题，可配置全局默认值：

@Bean
public Mustache.Compiler mustacheCompiler(
  Mustache.TemplateLoader templateLoader, 
  Environment environment) {

    MustacheEnvironmentCollector collector
      = new MustacheEnvironmentCollector();
    collector.setEnvironment(environment);

    return Mustache.compiler()
      .defaultValue("Some Default Value")
      .withLoader(templateLoader)
      .withCollector(collector);
}

✅ 优势：所有未定义变量将自动使用默认值，避免运行时错误。

6. 在 Spring MVC 中集成

若不使用 Spring Boot，需手动集成 Spring MVC。首先添加依赖：

<dependency>
    <groupId>com.github.sps.mustache</groupId>
    <artifactId>mustache-spring-view</artifactId>
    <version>1.4</version>
</dependency>

最新版本可在 Maven Central 查询。

配置 MustacheViewResolver 替代默认视图解析器：

@Bean
public ViewResolver getViewResolver(ResourceLoader resourceLoader) {
    MustacheViewResolver mustacheViewResolver
      = new MustacheViewResolver();
    mustacheViewResolver.setPrefix("/WEB-INF/views/");
    mustacheViewResolver.setSuffix(".mustache");
    mustacheViewResolver.setCache(false);
    
    MustacheTemplateLoader mustacheTemplateLoader 
      = new MustacheTemplateLoader();
    mustacheTemplateLoader.setResourceLoader(resourceLoader);
    mustacheViewResolver.setTemplateLoader(mustacheTemplateLoader);
    
    return mustacheViewResolver;
}

配置要点：

prefix：模板存储路径
suffix：模板文件扩展名
templateLoader：负责加载模板的资源加载器

7. 总结

本教程介绍了：

Spring Boot 中集成 Mustache 模板
在 UI 中渲染集合元素
为变量提供默认值避免错误
使用 MustacheViewResolver 集成 Spring MVC

完整源码请访问 GitHub 仓库。

Persistence

REST

Security