Freemarker 的基础概念与语法解析

# 1. Freemarker 概述 ## 1.1 什么是Freemarker Freemarker是一款用于生成文本输出（例如HTML网页）的模板引擎，它可以基于模板和数据模型来生成输出文本。与传统的JSP、Velocity等模板引擎相比，Freemarker具有更加灵活、强大的特点。 ## 1.2 Freemarker 的应用领域 Freemarker广泛应用于Web开发中，特别是在MVC架构中作为视图（View）的模板引擎，如Spring MVC、Struts等框架中都可以看到它的身影。除此之外，Freemarker也可以用于邮件模板、静态页面生成、报表生成等场景。 ## 1.3 Freemarker 的特点与优势 - **强大的表达能力**：Freemarker支持丰富的内建函数、指令以及灵活的语法，能够满足复杂模板的需求。 - **易于学习与使用**：Freemarker的语法简洁明了，上手快，适合不同水平的开发者使用。 - **与数据交互方便**：Freemarker可以方便地与各种数据源交互，如Java对象、数据库、RESTful API等，使得模板的动态化更加便捷。 - **高度可定制化**：Freemarker支持自定义函数、指令的扩展，能够满足项目中特定的定制需求。希望这段内容符合您的要求，接下来我将按照相同的格式继续为您撰写后续章节的内容。 # 2. Freemarker 的基础语法 ### 2.1 变量与数据模型在使用Fremarker的过程中，变量与数据模型是非常重要的概念。Freemarker模板通过数据模型来获取数据并进行处理，在模板中可以通过变量来引用数据模型中的值。下面是使用Freemarker定义变量与数据模型的示例代码： ```freemarker <#assign name = "John Doe"> <#assign age = 25> <#assign hobbies = ["reading", "music", "traveling"]> <p>My name is ${name}.</p> <p>I am ${age} years old.</p> <p>My hobbies are:</p> <ul> <#list hobbies as hobby> <li>${hobby}</li> </#list> </ul> ``` 在上述代码中，我们使用`<#assign>`语句定义了三个变量：name、age和hobbies。其中，name的值为"John Doe"，age的值为25，hobbies的值为一个包含三个元素的列表。在模板中使用`${}`语法可以访问变量的值。运行以上代码，将会输出以下结果： ``` My name is John Doe. I am 25 years old. My hobbies are: - reading - music - traveling ``` ### 2.2 条件判断与循环 Freemarker提供了条件判断语句和循环语句，可以根据条件执行不同的代码块，或者对一组数据进行循环处理。以下是一个使用条件判断和循环的示例代码： ```freemarker <#assign score = 80> <#if score >= 90> <p>优秀</p> <#elseif score >= 80> <p>良好</p> <#elseif score >= 70> <p>中等</p> <#else> <p>不及格</p> </#if> <#list 1..5 as number> <p>循环第${number}次</p> </#list> ``` 在上述代码中，我们使用`<#if>`语句判断score的值，根据不同的条件输出不同的结果。在条件判断之后，使用`<#list>`语句对1到5之间的数字进行循环，并输出循环的次数。运行以上代码，将会输出以下结果： ``` 良好循环第1次循环第2次循环第3次循环第4次循环第5次 ``` ### 2.3 Freemarker 中的注释在Freemarker模板中，可以使用注释来对模板进行说明，增加可读性。注释的内容不会在最终的输出中显示。以下是一个使用注释的示例代码： ```freemarker <#-- 这是一个注释，用于说明模板的作用 --> <p>Hello, World!</p> ``` 在上述代码中，我们使用`<#-- -->`来添加注释。这段注释对模板的作用进行了解释。 ### 2.4 Freemarker 中的数据输出与格式化在Freemarker模板中，通过`${}`语法可以输出数据的值。除了直接输出数据的值外，我们还可以对输出的格式进行一些控制。以下是一个使用输出与格式化的示例代码： ```freemarker <#assign price = 50.5> <p>The price is ${price}</p> <p>The price with 2 decimal places is ${price?string("0.00")}</p> ``` 在上述代码中，我们定义了一个变量price，并使用`${price}`将其输出。在第二行中，使用`${price?string("0.00")}`对输出进行了格式化，保留了两位小数。运行以上代码，将会输出以下结果： ``` The price is 50.5 The price with 2 decimal places is 50.50 ``` 这样，我们就介绍了Freemarker的基础语法，包括变量与数据模型的使用、条件判断与循环、注释的添加以及数据的输出与格式化。在实际的应用中，可以根据不同的需求灵活运用这些语法来生成动态的内容。 # 3. Freemarker 模板的创建与组织在这一节中，我们将学习如何创建和组织Freemarker模板，包括模板文件的结构、模板引入与包含以及模板的共享变量。 #### 3.1 Freemarker 模板文件的结构 Freemarker模板通常以`.ftl`作为文件扩展名，它们可以包含普通文本、Freemarker标签和指令。一个简单的Freemarker模板如下所示： ```html <!DOCTYPE html> <html> <head> <title>Welcome</title> </head> <body> <h1>Welcome ${user}!</h1> </body> </html> ``` 在上面的例子中，`${user}`表示一个Freemarker变量，它将在模板渲染时被替换为实际的数值。 #### 3.2 Freemarker 模板引入与包含 Freemarker提供了模板引入和包含的功能，可以通过`<#include>`来引入其他模板文件。例如，我们可以将页面头部和尾部独立成两个模板文件，然后在其他模板中引入： ```html <#include "header.ftl">  <#include "footer.ftl"> ``` 这样做有助于减少重复代码，并使模板更易于维护。 #### 3.3 Freemarker 模板的共享变量在Freemarker中，我们可以定义一些全局共享的变量，这些变量可以在多个模板中被引用。我们可以通过`shared_variable`来定义一个共享变量： ```html <#assign shared_variable="This is a shared variable"> ``` 在其他模板中，我们可以直接引用这个共享变量`${shared_variable}`。通过以上内容，我们学习了Freemarker模板的创建与组织方式。在下一节中，我们将介绍Freemarker的内建函数与指令。 # 4. Freemarker 内建函数与指令在Freemarker中，除了基本的语法之外，还内建了许多函数和指令，可以帮助我们更方便地处理数据和控制模板的渲染。接下来我们将详细介绍这些内建函数和指令的用法。 #### 4.1 常用内建函数的介绍与使用 Freemarker提供了丰富的内建函数，包括字符串处理、数学计算、集合操作等功能，下面我们将逐一介绍几个常用的内建函数，并给出示例代码演示其使用方法。 **示例代码：** ```java <#assign message = "Hello, World!">  Length of message: ${message?length}  Uppercase: ${message?upper} <#assign numbers = [1, 2, 3, 4, 5]>  Sum of numbers: ${numbers?sum} <#assign map = {"name": "John", "age": 30}>  <#list map?keys as key> ${key}: ${map[key]} </#list> ``` **代码总结：** - `?length` 函数用于获取字符串长度 - `?upper` 函数将字符串转换为大写 - `?sum` 函数用于计算列表元素的和 - `?keys` 函数用于获取Map的键集合 - 使用`<#list>`指令遍历Map数据 **结果说明：** - `message?length` 输出 13，表示字符串"Hello, World!"的长度 - `message?upper` 输出 "HELLO, WORLD!"，表示字符串的大写形式 - `numbers?sum` 输出 15，表示列表中数字的总和 - 遍历Map输出键值对的内容在上述示例中，我们演示了字符串处理、列表操作、Map操作等常用内建函数的使用方法和效果。 #### 4.2 Freemarker 的内建指令及其功能除了内建函数，Freemarker还提供了一些内建指令，用于控制模板的渲染、循环、条件判断等。下面我们将介绍几个常用的内建指令，并给出示例代码演示其功能和用法。 **示例代码：** ```java <#assign count = 5>  <#if count > 0> Count is positive <#else> Count is non-positive </#if>  <#list 1..5 as i> ${i} </#list>  <#include "header.ftl">  <#function greeting name> Hello, ${name}! </#function>  ${greeting("John")} ``` **代码总结：** - 使用`<#if>`指令进行条件判断 - 使用`<#list>`指令进行循环输出 - 使用`<#include>`指令导入其他模板 - 使用`<#function>`指令定义自定义函数 **结果说明：** - 根据`count`的值进行条件判断并输出相应内容 - 使用`<#list>`指令循环输出1到5的数字 - 导入名为"header.ftl"的模板文件 - 定义了一个名为`greeting`的自定义函数，并进行调用输出在上述示例中，我们演示了Freemarker中的条件判断、循环输出、模板导入和自定义函数定义的内建指令及其功能。 # 5. Freemarker 与数据交互在本章中，我们将探讨Freemarker模板与数据进行交互的相关内容。作为模板引擎，Freemarker通常需要与后端数据进行交互，以展示动态内容。我们将重点介绍Freemarker与Java数据交互、数据库数据交互以及其他数据源的交互。 ### 5.1 Freemarker 与 Java 数据交互在实际应用中，我们经常需要将后端Java代码中的数据传递到Freemarker模板中进行展示。下面是一个简单的示例，演示了如何在Java中准备数据，并在Freemarker模板中使用这些数据。 ```java // Java代码 Map<String, Object> data = new HashMap<>(); data.put("username", "John Doe"); data.put("age", 28); data.put("gender", "Male"); Configuration cfg = new Configuration(Configuration.VERSION_2_3_31); cfg.setClassForTemplateLoading(FreemarkerDemo.class, "/"); Template template = cfg.getTemplate("hello.ftl"); try (StringWriter out = new StringWriter()) { template.process(data, out); System.out.println(out.getBuffer().toString()); } catch (IOException | TemplateException e) { e.printStackTrace(); } ``` ```ftl  <!DOCTYPE html> <html> <head> <title>Welcome</title> </head> <body> <h1>Welcome, ${username}!</h1> <p>Age: ${age}</p> <p>Gender: ${gender}</p> </body> </html> ``` 上述示例中，我们在Java代码中准备了一个包含用户名、年龄和性别的Map数据，并使用Freemarker模板将这些数据动态展示在页面上。 ### 5.2 Freemarker 与数据库数据交互除了与Java数据交互外，Freemarker还可以与数据库进行交互，动态展示数据库中的数据。下面是一个简单的示例，演示了如何在Freemarker模板中展示数据库查询结果。 ```java // Java代码 List<User> userList = userDao.getAllUsers(); Configuration cfg = new Configuration(Configuration.VERSION_2_3_31); cfg.setClassForTemplateLoading(FreemarkerDemo.class, "/"); Template template = cfg.getTemplate("userList.ftl"); try (StringWriter out = new StringWriter()) { template.process(userList, out); System.out.println(out.getBuffer().toString()); } catch (IOException | TemplateException e) { e.printStackTrace(); } ``` ```ftl  <!DOCTYPE html> <html> <head> <title>User List</title> </head> <body> <h1>User List</h1> <table> <tr> <th>Username</th> <th>Email</th> </tr> <#list userList as user> <tr> <td>${user.username}</td> <td>${user.email}</td> </tr> </#list> </table> </body> </html> ``` 上述示例中，我们从数据库中获取了用户列表，然后在Freemarker模板中通过遍历用户列表的方式动态展示用户数据。 ### 5.3 Freemarker 与其他数据源的交互除了与Java和数据库进行数据交互外，Freemarker还可以与其他数据源进行交互，比如文件系统、网络接口等。在实际应用中，我们可以根据具体场景，灵活地使用Freemarker与各种数据源进行交互，实现动态页面展示的功能。通过本章的学习，我们了解了Freemarker如何与不同数据源进行交互，实现动态内容展示的功能。在实际开发中，合理灵活地使用Freemarker与各种数据源进行交互，将大大提升页面的动态展示能力。 # 6. Freemarker 的高级应用 #### 6.1 Freemarker 的自定义函数与指令在实际应用中，如果我们发现 Freemarker 内建的函数与指令不能满足我们的需求，我们可以通过自定义函数与指令来扩展 Freemarker 的功能。 ##### 6.1.1 自定义函数我们可以通过编写 Java 类来实现自定义函数，并将其注册到 Freemarker 的配置类中。 **场景**：假设我们需要一个自定义函数来将字符串的首字母转换为大写。首先，我们需要创建一个 Java 类，例如 `StringUtils`，并实现一个静态方法 `capitalize()`： ```java public class StringUtils { public static String capitalize(String value) { if (value != null && value.length() > 0) { return Character.toUpperCase(value.charAt(0)) + value.substring(1); } return value; } } ``` 然后，在 Freemarker 配置类中，我们将这个自定义函数注册到配置中： ```java @Configuration public class FreemarkerConfig { @Autowired private freemarker.template.Configuration freemarkerConfig; @PostConstruct public void registerCustomFunctions() { freemarkerConfig.setSharedVariable("capitalize", new StringUtils()); } } ``` 现在，我们就可以在 Freemarker 模板中使用自定义函数 `capitalize` 了： ```html <p>Welcome, ${capitalize(user.name)}!</p> ``` 上述代码中，我们可以通过 `${capitalize(user.name)}` 来将 `user.name` 的首字母转换为大写。 ##### 6.1.2 自定义指令类似自定义函数，我们也可以编写自定义的指令来实现特定的功能。下面我们以一个简单的示例来演示如何定义自定义指令。 **场景**：假设我们希望在 Freemarker 模板中可以直接输出当前时间。首先，我们需要创建一个 Java 类，例如 `CurrentTimeDirective`，并实现 `TemplateDirectiveModel` 接口： ```java public class CurrentTimeDirective implements TemplateDirectiveModel { @Override public void execute(Environment env, Map params, TemplateModel[] loopVars, TemplateDirectiveBody body) throws TemplateException, IOException { Date currentTime = new Date(); String formattedTime = formatTime(currentTime); Writer out = env.getOut(); out.write(formattedTime); } private String formatTime(Date time) { SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"); return sdf.format(time); } } ``` 然后，在 Freemarker 配置类中，我们将这个自定义指令注册到配置中： ```java @Configuration public class FreemarkerConfig { @Autowired private freemarker.template.Configuration freemarkerConfig; @PostConstruct public void registerCustomDirectives() { freemarkerConfig.setSharedVariable("currentTime", new CurrentTimeDirective()); } } ``` 现在，我们就可以在 Freemarker 模板中使用自定义指令 `currentTime` 了： ```html <p>Current time: <@currentTime/></p> ``` 上述代码中，我们通过 `<@currentTime/>` 的方式来调用自定义指令，并将当前时间输出到页面中。 #### 6.2 Freemarker 的异常处理与模板继承在实际开发中，异常处理和模板继承是非常重要的功能。以下将介绍 Freemarker 中异常处理的方法和模板继承的使用。 ##### 6.2.1 异常处理 Freemarker 提供了多种异常处理方式，包括捕获异常和自定义异常处理器。 **捕获异常**：我们可以使用 `<#attempt>` 和 `<#recover>` 来捕获并处理异常。 ```html <#attempt> <p>${user.name}</p> <#recover> <p>Oops, an error occurred while processing the user data.</p> </#attempt> ``` 上述代码中，如果在输出 `${user.name}` 时抛出异常，将会执行 `<#recover>` 中的内容。 **自定义异常处理器**：我们也可以编写自定义的异常处理器来处理异常。 ```java public class CustomTemplateExceptionHandler implements TemplateExceptionHandler { @Override public void handleTemplateException(TemplateException te, Environment env, Writer out) throws TemplateException { log.error("An error occurred during template processing", te); try { out.write("Oops, an error occurred. Please try again later."); } catch (IOException e) { throw new TemplateException("Error writing to the output writer", env); } } } ``` 然后，在 Freemarker 配置类中，我们将这个自定义异常处理器注册到配置中： ```java @Configuration public class FreemarkerConfig { @Autowired private freemarker.template.Configuration freemarkerConfig; @PostConstruct public void registerExceptionHandler() { freemarkerConfig.setTemplateExceptionHandler(new CustomTemplateExceptionHandler()); } } ``` 将上述代码添加到配置类中后，当模板处理过程中出现异常时，将会执行自定义的异常处理器中的代码。 ##### 6.2.2 模板继承模板继承是一种常用的技术，它可以帮助我们实现页面的复用和模板的组合。在 Freemarker 中，我们可以使用 `<#include>` 和 `<#nested>` 来实现模板继承。 **定义父模板**：父模板用于定义整体的页面结构。 ```html <!DOCTYPE html> <html> <head> <title>My Website</title> <link rel="stylesheet" href="style.css"> </head> <body> <div id="header"> <h1>Welcome to My Website</h1> </div> <div id="content"> <#nested/> </div> <div id="footer"> © 2021 My Website </div> </body> </html> ``` **定义子模板**：子模板继承父模板，并可以填充内容。 ```html <#import "parent_template.ftl" as parent> <@parent.template> <#override slot="content"> <h2>About Us</h2> <p>We are a leading company in the industry.</p> </#override> </@parent.template> ``` 上述代码中，我们使用 `<#override>` 来填充内容，并通过 `<@parent.template>` 来引用父模板。最终，子模板会继承父模板，并将填充的内容插入到父模板中指定的位置。 #### 6.3 Freemarker 的性能优化技巧为了提高 Freemarker 模板的渲染性能，我们可以采取一些优化技巧。以下是一些常见的性能优化技巧： - 使用 `<#local>` 来限定局部变量的作用范围，避免不必要的全局变量。 - 使用 `<#assign>` 语句来缓存结果，避免重复计算。 - 使用 `<#include>` 来引入其他模板文件，将大模板拆分为多个小模板，提高模板的复用性。 - 使用 `<#compress>` 来压缩输出的 HTML 代码，减小文件大小。 - 避免在模板中频繁使用复杂的逻辑判断和循环，可以在后端进行处理，减轻模板的负担。通过以上的优化技巧，我们可以显著提升 Freemarker 模板的渲染性能，提升系统的整体效率。在本章中，我们介绍了 Freemarker 的自定义函数与指令的使用方法，以及异常处理和模板继承的技巧。同时，我们也分享了一些优化技巧，帮助您提升 Freemarker 的性能。希望本章内容对您有所帮助。