09_Spring Boot 整合 Freemarker 模板引擎的坑
1.背景：
springboot 版本：3.0.2
2. 引入依赖
在 pom.xml 中添加：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Spring Boot Freemarker 依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-freemarker</artifactId>
</dependency>
3. 配置 freemarker
application.yml 中进行如下配置
spring:
freemarker:
cache: false
charset: UTF-8
check-template-location: true
content-type: text/html
expose-request-attributes: true
expose-session-attributes: true
request-context-attribute: request
4. 编写控制层代码
- 需要使用
@Controller，而非@RestController。 @Controller用于返回视图页面，@RestController会默认返回 JSON，不适合页面跳转。
示例：
@Controller
public class FreemarkerController {
@GetMapping("/freemarker")
public String freemarkerTest(Model model) {
model.addAttribute("message", "Hello Freemarker!");
return "freemarker"; // 视图名称，对应模板文件
}
}
5. 模板文件位置与命名
- Freemarker模板文件放置于
src/main/resources/templates/目录。 - 即模板文件命名为
freemarker.ftl。
目录结构示例：
src
└─ main
└─ resources
└─ templates
└─ freemarker.ftl
freemarker.ftl 模板内容如下：
<!DOCTYPE html>
<html>
<head lang="en">
<meta charset="UTF-8">
<title>Freemarker</title>
</head>
<body>
</body>
</html>
6. 启动项目
启动后访问地址，并没有想象中的顺利，直接报错了。
第一次报错：404 错误
- 可能是缓存或项目未正确构建导致。
- 解决：执行 Maven
clean，重新编译打包，再启动。
第二次报错：还是 404 错误
经过查询才知道，Spring Boot 2.2.0 起，默认模版后缀名为 ftlh。
解决方案：
- 将模板文件后缀由
.ftl改为.ftlh。 - 确认模板文件路径和名称与返回视图名一致。
例如：
templates/freemarker.ftlh
控制器返回：
return "freemarker"; // 自动匹配 freemarker.ftlh
templates/freemarker.ftlh
控制器返回：
return "freemarker"; // 自动匹配 freemarker.ftlh
Spring Boot 2.2.0 及以上版本 Freemarker 模板后缀名默认是 .ftlh，而不是传统的 .ftl。