SpringBoot中怎么搭建Freemaker环境

发布时间：2021-07-08 16:37:38 作者：Leah
来源：亿速云阅读：189

# SpringBoot中怎么搭建Freemarker环境

## 一、Freemarker简介

### 1.1 什么是Freemarker
FreeMarker是一款基于Java的模板引擎，主要专注于MVC模式中的视图层（View层）。它通过将模板与数据模型结合生成动态内容，支持HTML、XML、PDF等多种输出格式。

**核心特性：**
- 轻量级模板引擎，无Servlet依赖
- 强大的表达式语言（FTL）
- 支持条件判断、循环等逻辑控制
- 模板与业务逻辑完全分离
- 国际化支持

### 1.2 与其他模板引擎对比
| 特性        | Freemarker | Thymeleaf | JSP       |
|------------|------------|-----------|-----------|
| 语法复杂度   | 中等        | 简单       | 复杂       |
| 性能        | 高         | 中等       | 中等       |
| 静态化支持   | 优秀        | 一般       | 不支持     |
| 学习曲线    | 平缓        | 平缓       | 陡峭       |

## 二、环境准备

### 2.1 开发工具要求
- JDK 1.8+
- Maven 3.6+
- IntelliJ IDEA（推荐）或Eclipse
- SpringBoot 2.5.x+

### 2.2 创建SpringBoot项目
通过Spring Initializr创建基础项目：
```bash
https://start.spring.io/

选择依赖： - Spring Web - Freemarker - Lombok（可选）

三、基础配置

3.1 Maven依赖配置

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

3.2 配置文件详解

application.yml配置示例：

spring:
  freemarker:
    # 模板文件后缀
    suffix: .ftl
    # 模板加载路径（多个用逗号分隔）
    template-loader-path: classpath:/templates/
    # 是否启用缓存（开发建议关闭）
    cache: false
    # 内容类型设置
    content-type: text/html
    # 编码设置
    charset: UTF-8
    # 其他配置
    settings:
      classic_compatible: true
      number_format: 0.##

3.3 目录结构规范

推荐项目结构：

src/
├── main/
│   ├── java/
│   └── resources/
│       ├── static/    # 静态资源
│       └── templates/ # 模板文件
│           ├── common/ # 公共模板
│           └── pages/  # 页面模板

四、基础使用

4.1 第一个Freemarker示例

创建Controller：

@Controller
public class HelloController {
    @GetMapping("/hello")
    public String hello(Model model) {
        model.addAttribute("message", "Hello Freemarker!");
        return "hello";
    }
}

创建模板hello.ftl：

<!DOCTYPE html>
<html>
<head>
    <title>Freemarker Demo</title>
</head>
<body>
    <h1>${message}</h1>
</body>
</html>

4.2 常用语法详解

变量输出

${user.name}  <!-- 标准输出 -->
${user.name!} <!-- 空值处理 -->
${user.name!'默认值'} <!-- 带默认值 -->

条件判断

<#if score >= 90>
    优秀
<#elseif score >= 60>
    及格
<#else>
    不及格
</#if>

循环遍历

<#list users as user>
    <div>${user_index + 1}. ${user.name}</div>
</#list>

五、高级功能

5.1 自定义指令

实现TemplateDirectiveModel：

public class AuthDirective implements TemplateDirectiveModel {
    @Override
    public void execute(Environment env, Map params, 
                       TemplateModel[] loopVars,
                       TemplateDirectiveBody body) {
        // 权限检查逻辑
        if (hasPermission()) {
            body.render(env.getOut());
        }
    }
}

注册指令：

@Configuration
public class FreemarkerConfig {
    
    @Autowired
    private freemarker.template.Configuration configuration;
    
    @PostConstruct
    public void setSharedVariable() {
        configuration.setSharedVariable("auth", new AuthDirective());
    }
}

模板中使用：

<@auth>
    <!-- 受保护内容 -->
</@auth>

5.2 宏定义

宏相当于可复用的模板片段：

<#macro pagination total pageSize=10>
    <div class="pagination">
        <#list 1..(total/pageSize)?ceiling as p>
            <a href="?page=${p}">${p}</a>
        </#list>
    </div>
</#macro>

<!-- 使用宏 -->
<@pagination total=120 />

5.3 包含与导入

<!-- 包含其他模板 -->
<#include "header.ftl">

<!-- 导入宏定义库 -->
<#import "/common/macro.ftl" as m>
<@m.pagination />

六、最佳实践

6.1 错误处理方案

全局错误页面配置：

@ControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(Exception.class)
    public ModelAndView handleError(HttpServletRequest req, Exception e) {
        ModelAndView mav = new ModelAndView();
        mav.addObject("error", e.getMessage());
        mav.setViewName("error");
        return mav;
    }
}

错误模板error.ftl：

<h1>系统错误</h1>
<p>${error!''}</p>

6.2 性能优化建议

缓存配置：

spring:
  freemarker:
    cache: true # 生产环境开启
    settings:
      template_update_delay: 3600 # 更新间隔(秒)

预编译模板：

Template template = configuration.getTemplate("template.ftl");
template.process(dataModel, writer);

6.3 安全防护措施

防XSS攻击：

${content?html} <!-- HTML转义 -->
${content?js_string} <!-- JS转义 -->

禁用危险指令：

configuration.setNewBuiltinClassResolver(
    TemplateClassResolver.SAFER_RESOLVER);

七、常见问题排查

7.1 模板加载失败

问题现象：出现TemplateNotFoundException

解决方案： 1. 检查template-loader-path配置 2. 确认文件扩展名匹配（如.ftl） 3. 检查文件编码是否为UTF-8

7.2 变量解析异常

问题现象：undefined或null错误

调试技巧：

<#-- 调试变量是否存在 -->
${.data_model?keys}

<#-- 调试变量类型 -->
${variable?api.class.name}

7.3 性能问题分析

使用Actuator监控：

management:
  endpoints:
    web:
      exposure:
        include: freemarker

八、完整示例项目

8.1 项目结构

demo-freemarker/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           ├── config/
│   │   │           ├── controller/
│   │   │           └── DemoApplication.java
│   │   └── resources/
│   │       ├── static/
│   │       └── templates/
│   │           ├── common/
│   │           ├── pages/
│   │           └── layout.ftl
├── pom.xml

8.2 核心代码示例

布局模板layout.ftl：

<#macro main title>
<!DOCTYPE html>
<html>
<head>
    <title>${title}</title>
    <link rel="stylesheet" href="/css/style.css">
</head>
<body>
    <#include "header.ftl">
    <#nested>
    <#include "footer.ftl">
</body>
</html>
</#macro>

页面继承使用：

<#import "/templates/common/layout.ftl" as layout>
<@layout.main title="用户中心">
    <h1>欢迎, ${user.name}</h1>
    <!-- 页面具体内容 -->
</@layout.main>

九、总结与扩展

9.1 技术总结

Freemarker在SpringBoot中的集成非常简便
通过合理的模板组织可以提高代码复用率
适合生成静态化内容和高性能场景

9.2 扩展方向

与PDF生成工具（如Flying Saucer）结合
实现邮件模板动态渲染
对接CMS系统作为模板引擎

9.3 学习资源推荐

官方文档：https://freemarker.apache.org/docs/
Spring官方参考：https://docs.spring.io/spring-framework/docs/current/reference/html/web.html#mvc-view-freemarker
《Freemarker模板引擎实战》

本文共计约5400字，详细介绍了SpringBoot集成Freemarker的全流程，包含基础配置、高级功能、最佳实践等内容。实际开发中应根据项目需求灵活调整配置方案。 “`

注：由于Markdown文档的实际字数统计与编辑器有关，以上内容在标准Markdown编辑器中的纯文本字数约为5400字。如需精确字数，建议在具体编辑环境中进行校验。