简介本资源是一套完整的SpringBoot集成Freemarker实战项目源码包面向Java Web开发初学者与中级工程师解决模板引擎在现代Spring生态中快速落地与深度配置的常见痛点。压缩包共275个文件涵盖82个Freemarker模板.ftl、71个Java控制器与配置类、35个前端交互脚本.js、21个样式文件.css及配套图片、XML配置、SQL脚本等完整呈现前后端协同渲染的工程结构包体大小2.39MB轻量易导入。已有144人学习下载。资源直接提供可运行的项目骨架包含标准目录组织、全量配置项说明如template-loader-path、cache策略、典型FTL语法示例条件判断、列表遍历、日期格式化、自定义指令预留接口以及BootstrapFont Awesome等主流CSS库集成助开发者零调试启动并理解视图层最佳实践。1. SpringBoot Freemarker 不是“配个 suffix 就完事”的模板集成而是视图层工程化落地的关键一环很多刚从 SpringMVC 迁移过来的开发者看到spring-boot-starter-freemarker就以为只是把.jsp换成.ftl改个后缀、加个依赖、写个return index就能跑通——结果在真实项目里卡在静态资源 404、中文乱码、日期格式不生效、自定义指令报TemplateException甚至上线后发现模板缓存没关导致热更新失效。这不是 Freemarker 本身的问题而是 SpringBoot 对模板引擎的抽象层FreeMarkerViewResolverFreeMarkerConfigurer与传统配置方式存在隐式契约它默认启用缓存、强制校验模板路径合法性、对Model数据序列化有严格类型约束。本项目springboot-freemarker-master.rar所含的完整前端资源包bootstrap.css、animate.css、datepicker3.css、chosen.css等共 9 类 CSS 文件恰恰说明一个可交付的 Freemarker 视图工程必须同时解决「模板语法正确性」「静态资源路径一致性」「浏览器端 JS/CSS 加载时序」「服务端数据渲染边界控制」四大问题。适合正在做后台管理界面、内部运营系统、PDF 报表生成或需要强定制化 HTML 输出的 Java 开发者尤其适用于不能使用 Vue/React 做前后端分离、但又要求 UI 层具备响应式与交互能力的中型政企项目。2. Freemarker 在 SpringBoot 中的加载机制与路径解析逻辑深度拆解SpringBoot 并非简单地将.ftl文件当作纯文本读取而是通过FreeMarkerViewResolver构建完整的视图解析链路。理解其加载顺序和路径映射规则是避免TemplateNotFoundException和静态资源错位的根本前提。2.1 模板加载器TemplateLoader的三级查找路径Freemarker 的TemplateLoader实际由SpringTemplateLoader封装其查找逻辑遵循classpath → file → URL优先级。但在 SpringBoot 中默认仅启用ClassTemplateLoader即只从 classpath 下加载。关键在于spring.freemarker.template-loader-path的值如何影响TemplateLoader初始化若配置为classpath:/templates/推荐则FreeMarkerConfigurer会创建ClassTemplateLoader根路径为classpath:/templates/若配置为file:/opt/app/templates/则启用FileTemplateLoader此时需确保应用有对应目录读取权限且该路径不参与 jar 包打包若未显式配置template-loader-pathSpringBoot 2.3 会 fallback 到classpath:/templates/但 SpringBoot 2.2 及更早版本 fallback 为classpath:/极易导致模板被误加载到static/或public/目录下而失败提示application.yml中的配置必须严格匹配路径语义。例如spring: freemarker: template-loader-path: classpath:/templates/ suffix: .ftl content-type: text/html charset: UTF-8注意template-loader-path末尾的/不可省略否则FreeMarkerViewResolver会将index解析为classpath:/templatesindex而非classpath:/templates/index.ftl2.2 视图解析器ViewResolver的命名匹配规则与前缀/后缀作用域FreeMarkerViewResolver的prefix和suffix并非字符串拼接那么简单而是参与View实例构建的元数据。其解析流程如下Controller 返回逻辑视图名indexFreeMarkerViewResolver调用getPrefix() viewName getSuffix()得到模板路径index.ftlTemplateLoader根据template-loader-path查找classpath:/templates/index.ftl若找到返回FreeMarkerView实例若未找到抛出TemplateNotFoundException这里的关键陷阱在于prefix是路径前缀不是文件名前缀。例如spring: freemarker: prefix: admin/ template-loader-path: classpath:/templates/则index会被解析为classpath:/templates/admin/index.ftl而非classpath:/templates/index.ftl。项目中提供的bootstrap-datetimepicker.css等资源若放在templates/下会导致 CSS 路径错误必须明确区分模板文件放templates/静态资源放static/。2.3 静态资源与 Freemarker 模板的协同加载机制项目压缩包中包含bootstrap.css、animate.css等 9 个 CSS 文件它们绝不能放在templates/目录下。SpringBoot 的ResourceHttpRequestHandler默认将classpath:/static/、classpath:/public/、classpath:/resources/、classpath:/META-INF/resources/映射为/路径。因此正确组织方式为src/main/resources/ ├── templates/ │ └── index.ftl ← Freemarker 模板 └── static/ ├── css/ │ ├── bootstrap.css │ ├── animate.css │ └── datepicker3.css └── js/ └── chosen.js在index.ftl中引用方式必须为绝对路径link relstylesheet href/css/bootstrap.css link relstylesheet href/css/animate.css script src/js/chosen.js/script注意Freemarker 模板中不能使用th:href{/css/bootstrap.css}Thymeleaf 语法也不能用contextPathJSP 语义。SpringBoot 的静态资源映射是 Servlet 容器级行为与模板引擎无关直接/开头即可。2.4 字符编码与 Content-Type 的双重校验链spring.freemarker.charsetUTF-8仅控制 Freemarker 引擎读取.ftl文件时的解码方式而spring.freemarker.content-typetext/html决定 HTTP 响应头Content-Type。二者必须一致否则浏览器可能因 BOM 或编码声明冲突导致中文乱码。验证方法启动应用后访问/index用浏览器开发者工具查看 Network → Response Headers →Content-Type是否为text/html;charsetUTF-8再检查index.ftl文件属性是否为 UTF-8 无 BOM 编码。实际操作中常因 IDE 默认保存为 GBK 导致模板内中文显示为??。解决方案IntelliJ IDEAFile → Settings → Editor → File Encodings设置Global Encoding和Project Encoding均为 UTF-8勾选Transparent native-to-ascii conversionMaven 编译插件强制编码plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration encodingUTF-8/encoding /configuration /plugin3. Freemarker 模板语法在 SpringBoot 上的实战约束与安全边界Freemarker 语法强大但在 SpringBoot 环境中并非所有特性都开箱即用。项目中sweetalert.css和chosen.css的存在暗示了需要在模板中嵌入 JS 交互逻辑这直接触发 Freemarker 的表达式求值边界、HTML 转义策略、以及 Model 数据序列化限制。3.1${}表达式求值的三层上下文与空值处理SpringBoot 默认启用 Freemarker 的classic_compatible模式SpringBoot 2.2这意味着${user.name}在user为 null 时会抛出NullPointerException而非返回空字符串。这是与老版本 Freemarker 的关键差异。必须显式使用!操作符处理空值!-- 安全写法 -- p用户名${user.name!匿名用户}/p p邮箱${user.email!未填写}/p !-- 危险写法可能 500 错误 -- p用户名${user.name}/p更进一步SpringBoot 的FreeMarkerView会对 Model 中的java.util.Date、java.time.LocalDateTime等类型自动注册DefaultObjectWrapper但不会自动注册java.time.format.DateTimeFormatter。因此${now?string(yyyy-MM-dd HH:mm:ss)}要求now必须是Date或Calendar类型若传入LocalDateTime会报freemarker.core.NonHashException。解决方案Controller 层统一转换GetMapping(/dashboard) public String dashboard(Model model) { model.addAttribute(now, Date.from(Instant.now())); // 转为 Date model.addAttribute(items, Arrays.asList(A, B, C)); return dashboard; }3.2#list遍历中的集合判空与分页控制项目含chosen.css典型用于多选下拉组件意味着模板中需渲染selectoption列表。Freemarker 的#list要求集合非 null否则报错。常见错误写法#list users as user option value${user.id}${user.name}/option /#list当users为null时崩溃。正确写法必须结合??判空与!默认值#if users?? users?size 0 select classchosen-select #list users as user option value${user.id!}${user.name!未知}/option /#list /select #else p暂无用户数据/p /#if注意users?size是 Freemarker 内置函数但users.size()是 Java 方法调用在 SpringBoot 默认配置下被禁用出于安全考虑。若需启用方法调用必须在application.yml中显式配置spring: freemarker: settings: classic_compatible: false object_wrapper: freemarker.ext.beans.BeansWrapper3.3 自定义指令Directive的注册与 SpringBean 注入限制datepicker3.css对应日期选择器常需封装为datePicker idstart /形式。Freemarker 自定义指令需实现TemplateDirectiveModel接口但无法直接注入 Spring Bean因为指令实例由 Freemarker 引擎创建不受 Spring IoC 管理。标准做法是在FreeMarkerConfigurerBean 中注册指令并通过Configuration获取 Spring 上下文Configuration public class FreemarkerConfig { Autowired private ApplicationContext applicationContext; Bean public FreeMarkerConfigurer freeMarkerConfigurer() { FreeMarkerConfigurer configurer new FreeMarkerConfigurer(); configurer.setTemplateLoaderPath(classpath:/templates/); configurer.setFreemarkerSettings(Collections.singletonMap( shared_variables, Collections.singletonMap(datePicker, new DatePickerDirective(applicationContext)) )); return configurer; } }DatePickerDirective构造器接收ApplicationContext在execute()方法中通过applicationContext.getBean()获取 Servicepublic class DatePickerDirective implements TemplateDirectiveModel { private final ApplicationContext context; public DatePickerDirective(ApplicationContext context) { this.context context; } Override public void execute(Environment env, Map params, TemplateModel[] loopVars, TemplateDirectiveBody body) throws TemplateException, IOException { // 从 Spring 容器获取 service DateService dateService context.getBean(DateService.class); String html dateService.generatePickerHtml((String) params.get(id)); env.getOut().write(html); } }3.4 模板缓存策略与开发/生产环境差异化配置项目未提供application-dev.yml/application-prod.yml但必须明确Freemarker 默认开启缓存spring.freemarker.cachetrue这在开发阶段会导致修改.ftl后必须重启应用才能生效。而生产环境必须开启缓存以提升性能。正确配置方式# application-dev.yml spring: freemarker: cache: false settings: template_update_delay: 0s # 立即检测模板变更 # application-prod.yml spring: freemarker: cache: true settings: template_update_delay: 3600s # 1小时检查一次 number_format: 0.########## # 避免科学计数法验证缓存是否生效启动应用后修改index.ftl内容刷新页面。若内容未变则缓存生效若立即变化则cachefalse生效。4. SpringBoot Freemarker 工程化落地的 5 个硬性检查清单一个可交付的 Freemarker 视图工程不能只满足“能跑”而要通过以下 5 项硬性检查。每项失败都会导致线上故障或维护成本飙升。4.1 模板路径合法性校验防TemplateNotFoundExceptionSpringBoot 2.3 对template-loader-path做了严格校验路径必须以classpath:或file:开头且不能包含..路径穿越。执行以下命令验证# 打包后检查 jar 包内 templates 目录结构 jar -tf target/springboot-freemarker-master.jar | grep templates/ # 输出应包含templates/index.ftl、templates/admin/user.ftl 等若输出为空说明maven-resources-plugin未将src/main/resources/templates/复制进 jar。检查pom.xml是否遗漏build resources resource directorysrc/main/resources/directory includes include**/*.ftl/include include**/*.properties/include /includes /resource /resources /build4.2 静态资源 HTTP 状态码验证防 404使用 curl 直接测试 CSS/JS 资源是否可访问curl -I http://localhost:8080/css/bootstrap.css # 正确响应应为 # HTTP/1.1 200 OK # Content-Type: text/css # Content-Length: 198720 curl -I http://localhost:8080/css/missing.css # 正确响应应为 # HTTP/1.1 404 Not Found若返回404但路径确认存在检查spring.web.resources.static-locations是否被覆盖# 错误配置会覆盖默认值 spring: web: resources: static-locations: classpath:/custom-static/ # 正确配置追加而非覆盖 spring: web: resources: static-locations: classpath:/static/,classpath:/public/,classpath:/resources/4.3 Freemarker 表达式安全沙箱验证防 XSSFreemarker 默认对${}输出做 HTML 转义但#escape x as x?html块内可关闭转义。项目含sweetalert.css常配合 JS 弹窗需确保用户输入不被直接?no_esc渲染!-- 危险用户可控内容未转义 -- ${userInput?no_esc} !-- 安全默认已转义无需额外操作 -- ${userInput}验证方法在 Controller 中传入scriptalert(1)/script观察页面源码是否被转义为lt;scriptgt;alert(1)lt;/scriptgt;。若未转义检查spring.freemarker.settings是否误设output_formatHTML应为HTMLOutputFormat实例。4.4 日期/数字格式化全局一致性检查项目含datepicker3.css和bootstrap-datetimepicker.css说明存在大量时间展示场景。必须统一?string格式避免不同模板用不同格式如yyyy-MM-ddvsyyyy/MM/dd。在application.yml中配置全局格式spring: freemarker: settings: datetime_format: yyyy-MM-dd HH:mm:ss date_format: yyyy-MM-dd time_format: HH:mm:ss number_format: 0.00然后在模板中直接使用${order.createTime?string} ← 输出2024-05-20 14:30:22 ${order.amount?string} ← 输出123.454.5 Freemarker 版本兼容性矩阵验证spring-boot-starter-freemarker的版本与底层 Freemarker 引擎强绑定。SpringBoot 2.7.x 使用 Freemarker 2.3.31而 SpringBoot 3.2.x 使用 Freemarker 2.3.32。若手动升级 Freemarker 版本可能触发TemplateException: Unknown directive如新版本支持#ftl ...指令旧版不识别。验证当前版本mvn dependency:tree | grep freemarker # 输出示例[INFO] - org.springframework.boot:spring-boot-starter-freemarker:jar:2.7.18:compile # [INFO] | \- org.freemarker:freemarker:jar:2.3.31:compile若需降级如适配老项目必须同步调整dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-freemarker/artifactId exclusions exclusion groupIdorg.freemarker/groupId artifactIdfreemarker/artifactId /exclusion /exclusions /dependency dependency groupIdorg.freemarker/groupId artifactIdfreemarker/artifactId version2.3.28/version !-- 与 SpringBoot 2.3.x 兼容 -- /dependency5. 基于springboot-freemarker-master.rar的快速初始化脚手架构建拿到springboot-freemarker-master.rar后不要直接解压覆盖现有项目。应将其作为标准化脚手架按以下步骤初始化新工程确保结构清晰、职责分离、可维护性强。5.1 资源目录标准化迁移流程解压springboot-freemarker-master.rar提取 CSS/JS 文件按 SpringBoot 规范重建目录# 创建标准目录结构 mkdir -p src/main/resources/templates mkdir -p src/main/resources/static/css mkdir -p src/main/resources/static/js # 迁移 CSS保留原始文件名不重命名 cp style.css bootstrap.css bootstrap.min.css animate.css \ datepicker3.css font-awesome.css sweetalert.css \ bootstrap-datetimepicker.css bootstrap-datetimepicker.min.css \ src/main/resources/static/css/ # 迁移 JS项目未提供 JS但 chosen.css 需配套 chosen.js wget https://cdnjs.cloudflare.com/ajax/libs/chosen/1.9.1/chosen.jquery.min.js \ -O src/main/resources/static/js/chosen.jquery.min.js5.2application.yml最小化安全配置模板基于项目需求生成生产就绪的application.ymlspring: profiles: active: prod freemarker: template-loader-path: classpath:/templates/ suffix: .ftl content-type: text/html charset: UTF-8 cache: true request-context-attribute: request expose-spring-macro-helpers: true settings: template_update_delay: 3600s datetime_format: yyyy-MM-dd HH:mm:ss date_format: yyyy-MM-dd time_format: HH:mm:ss number_format: 0.00 output_format: HTMLOutputFormat api_builtin_enabled: false # 禁用危险内置函数 web: resources: add-mappings: true cache: period: 3600 chain: gzip: true # 生产环境强制关闭 devtools spring.devtools.restart.enabled: false management.endpoints.web.exposure.include: health,info,metrics5.3index.ftl基础骨架与资源加载验证模板创建src/main/resources/templates/index.ftl集成所有 CSS 并验证加载!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleFreemarker 主页/title !-- Bootstrap 核心 CSS -- link relstylesheet href/css/bootstrap.min.css !-- 动画支持 -- link relstylesheet href/css/animate.css !-- 日期选择器 -- link relstylesheet href/css/datepicker3.css link relstylesheet href/css/bootstrap-datetimepicker.min.css !-- 图标字体 -- link relstylesheet href/css/font-awesome.css !-- SweetAlert 弹窗 -- link relstylesheet href/css/sweetalert.css !-- Chosen 下拉增强 -- link relstylesheet href/css/chosen.css /head body classanimated fadeIn div classcontainer mt-5 h1SpringBoot Freemarker 已就绪/h1 p当前时间strong${.now?string(yyyy-MM-dd HH:mm:ss)}/strong/p !-- 验证 Chosen 初始化 -- select classform-control chosen-select>// Application.java SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }// IndexController.java Controller public class IndexController { GetMapping(/) public String home(Model model) { model.addAttribute(now, new Date()); return index; // 自动匹配 templates/index.ftl } }启动应用后访问http://localhost:8080/若页面正常显示、动画生效、Chosen 下拉框可展开、浏览器控制台无 404 报错则脚手架构建成功。此时可基于此结构按业务模块在templates/下创建admin/、user/子目录实现视图分层。本文还有配套的精品资源点击获取