FreeMarker null 值处理

在 FreeMarker 模板引擎中，处理 null 值是一个常见且关键的问题。如果不妥善处理 null，模板渲染时容易抛出异常或显示错误内容。本文将从 核心概念、操作步骤、常见错误、注意事项、使用技巧、最佳实践 与 性能优化 等多个维度，全面讲解 FreeMarker 中 null 值的处理，帮助你快速掌握关键知识并实践。

---

一、核心概念

1. null 的含义

• null 表示一个变量没有被赋值或不存在。
• 在 FreeMarker 中，访问 null 值会抛出异常，除非使用 ! 运算符进行处理。

2. missing 与 null 的区别

• missing：表示变量未定义或不存在（例如未传入模型中）。
• null：表示变量存在，但值为 null（例如 Java 中 map.put("key", null)）。
• 在 FreeMarker 中，missing 和 null 都会被视为“空值”，但处理方式略有不同。

---

二、操作步骤（详细）

1. 检查变量是否存在（是否为 missing）

<#if user??>
  <p>User exists: ${user.name}</p>
<#else>
  <p>User does not exist.</p>
</#if>

2. 检查变量是否为 null

<#if user?? && user == null>
  <p>User is null.</p>
</#if>

3. 使用 ! 运算符提供默认值

<#-- 如果 user 为 null 或 missing，返回空字符串 -->
${user!}

<#-- 如果 user.name 为 null 或 missing，返回 "Guest" -->
Hello, ${user.name!"Guest"}

4. 使用 ?? 运算符判断是否存在

<#if user.name??>
  <p>Name: ${user.name}</p>
<#else>
  <p>Name is not available.</p>
</#if>

5. 使用 ! 和嵌套结构

<#-- 安全访问嵌套属性 -->
${user.address.city!"Unknown City"}

6. 使用 default 指令

<#assign name = user.name!"Default Name">

7. 条件判断中使用 ! 和 ??

<#if (user.name!"") == "">
  <p>Name is empty or missing.</p>
</#if>

---

三、常见错误与注意事项

1. 访问 null 或 missing 变量导致异常

${user.name}  <#-- 如果 user 为 null 或 missing，抛出异常 -->

✅ 解决方法：

${user.name!"Guest"}

2. null 与 "" 混淆

<#if user.name == "">
  <p>Name is empty.</p>
</#if>

⚠️ 问题：如果 user.name 是 null，比较会失败。

✅ 解决方法：

<#if (user.name!"") == "">
  <p>Name is empty or missing.</p>
</#if>

3. ?? 无法判断 null 类型（需配合判断）

<#if user?? && user != null>
  <p>User is not null.</p>
</#if>

4. ! 运算符使用不当导致逻辑错误

<#assign age = user.age!0>

⚠️ 问题：如果 age 是字符串类型，转换为 0 会导致逻辑错误。

✅ 解决方法：确保类型匹配或使用类型判断。

---

四、使用技巧

1. 设置默认值链（多级 fallback）

${user.nickname!user.username!"Anonymous"}

2. 使用 ! 和 ?? 结合条件判断

<#if user?? && user.name??>
  <p>Welcome, ${user.name}</p>
<#else>
  <p>Please login.</p>
</#if>

3. 使用 ?has_content 判断是否为空

<#if user.name?has_content>
  <p>Hello, ${user.name}</p>
<#else>
  <p>No name provided.</p>
</#if>

?has_content 会判断是否为 null、""、0、false、[]、{} 等“空”值。

4. 使用 #if 与 ! 简化判断

<#if user.name!"">
  <p>Name: ${user.name}</p>
</#if>

---

五、最佳实践

1. 数据模型中避免 null 值

• 在 Java 层尽量使用默认值或空对象，避免将 null 传入模板。
• 例如使用 Optional 或空字符串替代。

2. 使用 ! 提供默认值

• 所有变量访问都应使用 !，避免模板抛出异常。

3. 使用 ?has_content 替代多重判断

• 更加简洁，适用于字符串、数字、集合等类型。

4. 对嵌套结构使用 ! 保护访问

• 如 user.address.city! 可防止中间对象为 null。

5. 使用 #assign 缓存常用值

<#assign name = user.name!"Guest">
Hello, ${name}

---

六、性能优化

1. 减少模板中逻辑判断

• 模板中尽量避免复杂的 if、else 判断，应在 Java 层预处理。

2. 使用 ?has_content 替代多次 ?? 判断

• ?has_content 是优化过的内置函数，性能优于多个 ?? 判断。

3. 避免在模板中频繁调用方法

• 方法调用会影响性能，建议将结果预计算后传入模板。

4. 启用缓存提高模板渲染效率

Configuration cfg = new Configuration(Configuration.VERSION_2_3_31);
cfg.setTemplateCacheSize(100);
cfg.setTemplateUpdateDelay(3600);  // 每小时检查一次模板更新

---

七、总结

技术点	说明	推荐用法
! 运算符	提供默认值	${user.name!"Guest"}
?? 运算符	判断是否存在	<#if user??>
?has_content	判断是否为空值	<#if user.name?has_content>
#assign	缓存常用变量	<#assign name = user.name!"Guest">
嵌套访问	安全访问嵌套结构	${user.address.city!"Unknown"}

---

八、参考示例代码（Java + FTL）

Java 代码

Map<String, Object> model = new HashMap<>();

// user 为 null
model.put("user", null);

// userWithEmptyName 存在但 name 为空
Map<String, String> userWithEmptyName = new HashMap<>();
userWithEmptyName.put("name", "");
model.put("userWithEmptyName", userWithEmptyName);

// userList 为 null
model.put("userList", null);

FTL 模板

<h2>Null 值处理示例</h2>

<#-- 情况1：user 为 null -->
<#if user??>
  <p>User exists: ${user.name!"No Name"}</p>
<#else>
  <p>User is missing.</p>
</#if>

<#-- 情况2：userWithEmptyName 存在但 name 为空 -->
<#if userWithEmptyName.name?has_content>
  <p>Name: ${userWithEmptyName.name}</p>
<#else>
  <p>Name is empty.</p>
</#if>

<#-- 情况3：userList 为 null -->
<#list userList![] as user>
  <p>${user.name}</p>
</#list>

---

九、结语

FreeMarker 中 null 值的处理是模板开发中不可忽视的一环。通过合理使用 !、??、?has_content 等操作符，可以有效避免模板渲染异常，提升代码健壮性与可维护性。推荐在 Java 层尽量避免 null 值，并在模板中统一使用默认值机制进行处理，以构建更加安全、高效的模板系统。

✅ 最终建议：

• 所有变量访问都应使用 ! 提供默认值；
• 优先使用 ?has_content 替代多重判断；
• 避免在模板中执行复杂逻辑；
• 在 Java 层预处理数据，减少模板负担。