Spring MVC 中使用 FreeMarker 模板引擎

1. 概述

FreeMarker 是 Apache 软件基金会下的一个基于 Java 的模板引擎。和其它模板引擎类似，FreeMarker 主要用于 MVC 架构中生成 HTML 页面。本文将介绍如何在 Spring MVC 项目中配置并使用 FreeMarker 来替代传统的 JSP 模板。

本文不会深入讲解 Spring MVC 的基础用法，如需了解可参考 Spring MVC 教程。同样地，也不会全面介绍 FreeMarker 的所有功能，更多细节请访问 FreeMarker 官网。

2. Maven 依赖

由于这是一个基于 Maven 的项目，首先需要在 pom.xml 文件中添加必要的依赖项：

<dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker</artifactId>
    <version>2.3.23</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context-support</artifactId>
    <version>${spring.version}</version>
</dependency>

3. 配置说明

接下来我们进入项目的配置环节。这是一个基于注解的 Spring 项目，因此不展示 XML 配置方式。

3.1. Spring Web 配置

我们需要创建一个类来配置 Web 组件，并使用以下注解：@EnableWebMvc、@Configuration 和 @ComponentScan：

@EnableWebMvc
@Configuration
@ComponentScan({"com.baeldung.freemarker"})
public class SpringWebConfig extends WebMvcConfigurerAdapter {
    // 所有 Web 相关的配置都将在这里完成
}

3.2. 配置 ViewResolver

Spring MVC 提供了 ViewResolver 接口，用于将视图名称映射为实际的视图对象。我们使用的是 FreeMarkerViewResolver，它来自 spring-webmvc 依赖。

该对象需要设置运行时使用的参数。例如，我们将配置视图解析器只处理以 .ftl 结尾的视图：

@Bean 
public FreeMarkerViewResolver freemarkerViewResolver() { 
    FreeMarkerViewResolver resolver = new FreeMarkerViewResolver(); 
    resolver.setCache(true); 
    resolver.setPrefix(""); 
    resolver.setSuffix(".ftl"); 
    return resolver; 
}

⚠️ 注意：这里的缓存控制只建议在调试或开发阶段关闭，生产环境应保持开启状态以提升性能。

3.3. FreeMarker 模板路径配置

接着我们要指定模板文件所在的目录路径：

@Bean 
public FreeMarkerConfigurer freemarkerConfig() { 
    FreeMarkerConfigurer freeMarkerConfigurer = new FreeMarkerConfigurer(); 
    freeMarkerConfigurer.setTemplateLoaderPath("/WEB-INF/views/ftl/");
    return freeMarkerConfigurer; 
}

3.4. 控制器配置

现在可以通过 Spring Controller 来处理并渲染 FreeMarker 模板：

@RequestMapping(value = "/cars", method = RequestMethod.GET)
public String init(@ModelAttribute("model") ModelMap model) {
    model.addAttribute("carList", carList);
    return "index";
}

前面配置好的 FreeMarkerViewResolver 会自动把返回的视图名 index 映射到对应的 .ftl 模板文件上。

4. FreeMarker HTML 模板

4.1. 创建简单的 HTML 模板

现在我们来编写一个使用 FreeMarker 的 HTML 模板。在这个例子中，我们在 Model 中加入了一个汽车列表（carList），FreeMarker 可以通过循环遍历这个列表来展示内容。

当用户访问 /cars 接口时，Spring 会使用传入的 Model 数据处理模板。其中 <#list> 是 FreeMarker 的指令，表示对 model["carList"] 进行迭代，每次迭代将当前元素命名为 car 并渲染对应的内容块。

此外，模板中还使用了 FreeMarker 表达式 ${car.make} 来访问每个 car 对象的属性值：

<div id="header">
  <h2>FreeMarker Spring MVC Hello World</h2>
</div>
<div id="content">
  <fieldset>
    <legend>Add Car</legend>
    <form name="car" action="add" method="post">
      Make : <input type="text" name="make" /><br/>
      Model: <input type="text" name="model" /><br/>
      <input type="submit" value="Save" />
    </form>
  </fieldset>
  <br/>
  <table class="datatable">
    <tr>
      <th>Make</th>
      <th>Model</th>
    </tr>
    <#list model["carList"] as car>
      <tr>
        <td>${car.make}</td>
        <td>${car.model}</td>
      </tr>
    </#list>
  </table>
</div>

样式美化后，页面效果如下：

5. Spring Boot 支持

如果使用的是 Spring Boot，那就更简单了，只需引入 starter 依赖即可：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-freemarker</artifactId>
    <version>2.3.4.RELEASE</version>
</dependency>

然后将模板文件放在 src/main/resources/templates 目录下即可，Spring Boot 会自动完成诸如 FreeMarkerConfigurer 和 FreeMarkerViewResolver 的默认配置。

✅ 简单粗暴，开箱即用！

6. 总结

本文介绍了如何在 Spring MVC 应用中集成 FreeMarker 模板引擎。当然，FreeMarker 的能力远不止于此，想深入研究的话可以前往 Apache FreeMarker 官网获取更多信息。

示例代码已上传至 GitHub。

Persistence

REST

Security