FreeMarker在保险电子保单/保函模板中的应用

一、FreeMarker简介

1.1 什么是FreeMarker

FreeMarker是一款基于Java的模板引擎，通过将模板与数据模型结合生成动态文本输出（如HTML、XML等）。其核心特点是：

分离视图与业务逻辑：模板文件（.ftl）与Java代码解耦，便于团队协作
轻量级跨平台：无需Servlet环境，可集成到任何Java项目中
丰富的模板语法：支持条件判断、循环、宏定义等编程结构

1.2 为何选择FreeMarker

在保险电子化场景中，FreeMarker的优势尤为突出：

法律合规性：生成的电子保单需符合《电子签名法》要求，FreeMarker可确保输出内容不可篡改
高性能批量处理：支持同时生成数万份保单模板，满足保险行业高并发需求
多格式输出：同一模板可适配PDF、HTML、JPG等电子保单格式

二、FreeMarker核心语法精要

2.1 基础语法结构

freemarker 复制代码

<#-- 注释不会输出 -->

${user.name!"默认值"}  <#-- 插值表达式，!提供默认值 -->

<#if policy.status == "ACTIVE">  <#-- 条件判断 -->
  保单有效
</#if>

2.2 保险业务专用语法

保单数据遍历

less 复制代码

<table>
<#list policies as policy>
  <tr class="${policy?item_cycle('odd','even')}">
    <td>${policy?counter}. ${policy.number}</td>
    <td>${policy.holderName?upper_case}</td>
    <td>${policy.effectiveDate?string('yyyy-MM-dd')}</td>
  </tr>
</#list>
</table>

注：?item_cycle实现斑马线效果，?string格式化日期

复杂逻辑处理

csharp 复制代码

<#-- 定义保费计算函数 -->
<#function calculatePremium age coverage>
    <#-- 基础费率 -->
    <#local baseRate = 1000>
    
    <#-- 高龄附加费逻辑 -->
    <#if age > 60>
        <#return baseRate * 1.5 * coverage>
    <#else>
        <#return baseRate * coverage>
    </#if>
</#function>

<#-- 调用函数并格式化输出 -->
保费：${calculatePremium(insuredAge, coverageAmount)?string.currency}

保费 = 基础费率 × 保额倍数 × 风险系数（如年龄、职业等）
?string.currency 是 FreeMarker 模板引擎中的一个 内置格式化函数 ，用于将数字转换为符合本地化货币格式的字符串（例如 $1,000.00 或 ¥1,000.00）

2.3 安全控制

ruby 复制代码

<#-- 防止XSS攻击 -->
${userInput?html}

<#-- 空值处理 -->
${policy.beneficiary!"未指定"}  <#-- 默认值 -->
${(policy.claimAmount!0)?string.currency}  <#-- 数值保险 -->

三、保险行业应用场景

3.1 电子保单生成

典型流程：

数据准备：从核心系统获取保单数据（投保人、险种、条款等）
模板渲染：通过FreeMarker生成HTML/PDF格式保单
电子签名：调用CA证书进行数字签名
交付存储：推送至客户邮箱/APP并归档

模板示例：

css 复制代码

<#macro policyHeader>
  <header>
    <img src="/static/logo.png" alt="保险公司Logo">
    <h1>电子保单（保单号：${policy.number})</h1>
    <p>生效日期：${policy.effectiveDate?string('yyyy年MM月dd日')}</p>
  </header>
</#macro>

<@policyHeader/>

四、与html的区别

.ftl（FreeMarker Template Language）和.html（Hypertext Markup Language）是两种不同用途的文件格式，主要区别如下：

4.1 核心区别

对比维度	.ftl 文件	.html 文件
本质	模板文件，包含动态逻辑（如条件、循环、变量插值）	静态网页文件，仅描述页面结构和内容，无动态逻辑
语法	支持FTL指令（如`<#if>`、`<#list>`）、插值（`${variable}`）和注释（`<#-- -->`）	仅支持HTML标签（如`<div>`、`<p>`）和基础脚本（JavaScript/CSS）
动态性	可动态生成内容（如根据数据渲染保单条款列表）	静态展示，需依赖JavaScript或后端技术实现动态效果
数据绑定	直接通过数据模型（如Java对象、Map）填充变量	需通过AJAX或后端渲染（如JSP）动态绑定数据
输出结果	可生成HTML、XML、纯文本等多种格式	仅输出HTML页面

4.2 能否直接使用HTML模板？

可以，但有限制
- 静态内容 ：若模板无需动态数据（如固定格式的免责声明），可直接用.html。
- 混合使用 ：FreeMarker允许在.ftl中嵌入原生HTML标签，但需通过FTL指令处理动态部分。例如：
  less 复制代码
```
<html>
  <body>
    <#-- FTL动态逻辑 -->
    <#if policy.active>
      <h1>${policy.title}</h1>  <#-- 动态插值 -->
    </#if>
  </body>
</html>
```
不可行的情况
- 需要动态逻辑 ：如循环渲染保单列表（<#list>）、条件判断（<#if>）等，必须使用.ftl。
- 数据格式化 ：FreeMarker提供内置函数（如日期格式化${date?string('yyyy-MM-dd')}），HTML无法直接实现。

4.3 保险行业应用建议

优先使用.ftl
- 电子保单：动态填充投保人信息、条款、保费计算等。
- 批量生成 ：通过<#list>快速生成多份保单模板。
HTML的适用场景
- 静态框架 ：如固定页眉/页脚，通过<#include>引入到.ftl中。
- 样式预览 ：设计阶段用HTML快速布局，再迁移逻辑到.ftl。

4.4 总结

.ftl：适合需要动态数据绑定、逻辑控制的场景（如保险保单模板）。
.html ：仅适合纯静态内容或作为.ftl的组成部分。

若业务需求涉及动态生成（如电子保单），必须使用FreeMarker模板引擎处理.ftl文件。