应自定义TemplateRenderException统一封装模板引擎异常，通过工具方法或AOP拦截渲染调用，记录结构化日志并安全兜底，结合@ControllerAdvice全局处理，兼顾可观测性与安全性。
Java中使用Thymeleaf或FreeMarker做模板渲染时，框架本身不会直接抛出 TemplateRenderException（该类并非Spring或Thymeleaf/Freemarker官方异常），它通常是项目自定义的业务异常。封装的核心目标是：统一捕获底层模板引擎异常（如TemplateProcessingException、IOException、TemplateException等），转化为可识别、可处理、带上下文信息的 TemplateRenderException，并避免敏感信息泄露。
定义清晰的 TemplateRenderException
继承 RuntimeException，包含模板名、变量数据摘要、原始异常等关键字段，便于日志追踪和前端提示：
- 构造函数支持传入模板路径（如
"email/welcome.html"）、渲染参数标识（如"userId=123"）、原始异常 - 重写
toString()或提供getDetailMessage()，隐藏堆栈但保留必要上下文（如“渲染模板 email/welcome.html 失败：变量 name 为空”） - 不暴露原始异常的完整堆栈给前端，避免模板路径、服务器路径等敏感信息泄漏
统一拦截模板渲染调用点
不要在每个 templateEngine.process() 或 template.process() 处手动 try-catch，而是封装成工具方法或AOP切面：
- 提供
TemplateRenderer.render(String templateName, Map<String, Object> vars)工具方法，内部捕获TemplateProcessingException（Thymeleaf）、TemplateException+IOException（FreeMarker），统一包装为TemplateRenderException - 若用 Spring MVC，可对
@Controller中返回ModelAndView的方法做 AOP 增强，捕获视图解析阶段异常（注意：需区分是模板渲染失败还是视图解析失败） - 对异步邮件/消息模板渲染场景，务必在业务层显式捕获并转换，避免异常穿透到线程池
补充上下文与安全兜底
仅抛异常不够，要提升可观测性和容错能力：
立即学习“Java免费学习笔记（深入）”；
- 记录结构化日志：模板名、参数 key 集合（不打全量值，避免敏感数据）、异常类型、时间戳；可加 MDC 标记 traceId
- 对非开发环境，自动 fallback 到默认提示模板（如 “内容加载失败，请稍后再试”），而非直接 500 页面
- 若参数含用户输入，渲染前做基础校验（如必填字段非空、长度限制），提前失败比模板里报
NullPointerException更友好
与 Spring Boot 自动配置协同
利用 Spring Boot 的错误处理机制，让 TemplateRenderException 被全局异常处理器识别：
- 在
@ControllerAdvice中添加@ExceptionHandler(TemplateRenderException.class)，返回统一错误响应或跳转友好错误页 - 配置
spring.thymeleaf.cache=false（开发）和spring.freemarker.cache=false加速问题定位，但生产必须开启缓存 - 避免在
application.properties中设置spring.thymeleaf.enabled=true后却未引入依赖，这类启动期问题应由健康检查提前暴露
