Thymeleaf 3.0升级至3.1后模板渲染空指针问题求助

问题背景 #

我的Spring Boot应用通过极简Thymeleaf配置将HTML渲染为PDF，升级Spring Boot 3时同步把Thymeleaf从3.0升级至3.1。核心变化是WebContext的构造方式：3.0版本基于HttpServletRequest/HttpServletResponse构建，3.1版本改为基于IWebExchange构建。

升级后的控制器代码：

override fun previewDataController(
    webExchange: IWebExchange,
    objId: UUID,
): ResponseEntity<ByteArray> {
    val context = WebContext(webExchange, webExchange.locale)
    val pdfData = someService.previewData(context, objId)
    ...
}

调用templateEngine.process渲染模板时，单元测试报错：

Caused by: org.springframework.expression.spel.SpelEvaluationException: EL1007E: Property or field 'name' cannot be found on null

调试可见context中的object属性非空，但模板中${object.name}仍提示object为null。

咨询问题 #

1. 这种获取IWebExchange对象的方式是否正确？Spring会自动注入吗？
2. 升级Thymeleaf 3.1是否遗漏了必要配置？
3. 是否是测试上下文配置导致的问题？

问题解答 #

1. IWebExchange的注入方式是否正确？ #

正确。在Spring WebFlux（或适配WebExchange的Spring MVC场景）中，控制器方法直接声明IWebExchange参数时，Spring会自动注入当前请求对应的WebExchange实例，无需额外配置。但需注意：如果应用是传统Spring MVC（非WebFlux），要确认是否引入了spring-boot-starter-webflux或相关适配依赖，否则可能无法识别该参数类型。

2. 升级Thymeleaf 3.1是否遗漏配置？ #

Thymeleaf 3.1针对WebContext的属性传递机制有调整，核心排查点：

• 3.1版本的WebContext默认不再直接暴露model中的属性作为顶级变量，需确认object的放入时机：如果是通过context.setVariable("object", obj)，要检查调用是否在templateEngine.process之前；若用重载构造方法传入model，需确认model参数传递正确；
• Thymeleaf 3.1对SpEL表达式解析的严格性提升，未声明的变量会直接报错，可在模板中添加空值判断${object?.name}辅助排查；
• 确保依赖版本一致：Spring Boot 3.x对应的Thymeleaf 3.1版本，需保证所有Thymeleaf相关依赖（如thymeleaf-spring6）版本统一，避免混合旧版本引发兼容性问题。

3. 是否是测试上下文配置导致的问题？ #

大概率是测试环境的问题，常见原因：

• 单元测试未正确模拟IWebExchange实例：使用MockMvc或WebTestClient时，需确保模拟的WebExchange包含正确的上下文属性传递逻辑；
• 测试时模板引擎配置缺失：测试上下文可能未加载完整的Thymeleaf自动配置，导致WebContext的属性解析机制异常；
• 服务层测试未正确传递WebContext：若someService.previewData中对context的变量操作在测试环境未正确执行，可在测试中手动调用context.setVariable("object", testObj)，再调用templateEngine.process验证是否仍报错。

内容的提问来源于stack exchange，提问作者John P