"不兼容改进"设置

优质

小牛编辑

126浏览

2023-12-01

它要做什么

该设置指定了 FreeMarker 的版本号，那么就不会100%向后兼容bug修复和改进 你想要启用 已经实现的内容。通常来说，默认把它留在2.3.0(最大向后兼容版本)是一个坏主意。

在新项目中，应该将它设置为实际使用的FreeMarker版本号。而在老项目中，那么最好也将它设置的高一些，最好检查一下哪些修改是激活状态(可以在 Configuration(Version) 构造方法的API JavaDoc文档中找到它们)，至少不仅仅是 "不兼容改进" 第三版本号(小版本)设置提高。通常来讲，只要为该设置增加最后的版本号，那么这些修改的风险就会小很多。

Bug修复和改进是完全向后兼容的，同样，它们也是重要的安全更新，不管 "不兼容改进" 如何设置都是启用的。

该设置的一个重要结果是应用程序可以检查声明的 FreeMarker 最小版本需求是否达到。比如你设置了2.3.22，但是应用程序却意外部署到了 FreeMarker 2.3.21，那么FreeMarker就会出问题，告诉你需要一个更高的版本。最后，请求的修复/改进不会作用于低版本。

如何设置

这个不兼容改进的设置在 Configuration 级别。它可以在多种方式下设置(假设我们想将它设置为2.3.22)：

创建 freemarker.template.Configuration 对象，比如：
```
... = new Configuration(Configuration.VERSION_2_3_22)
```
或者，使用初始化设置来更改 Configuration 单例，比如：
```
cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_22)
```
或者，如果使用properties文件来配置FreeMarker (*.properties 文件或者 java.util.Properties 对象)，添加：
```
incompatible_improvements=2.3.22
```

或者，如果通过 FreemarkerServlet 来配置FreeMarker，那么将 init-param 添加到 web.xml 中：

<init-param>
    <param-name>incompatible_improvements</param-name>
    <param-value>2.3.22</param-value>
</init-param>

但是，在应用程序中 如果设置了 object_wrapper (也就是 Configuration.setObjectWrapper(ObjectWrapper))，那么要知道很重要的一点，BeansWrapper 和它的子类(最重要的是， DefaultObjectWrapper) 有它们自己独立的 incompatibleImprovements 属性，还有一些修复/改进会被它激活，而不是通过 Configuration 的相似设置。如果你没有在任何地方设置过 object_wrapper，那么不需要知道这点，因为，和 Configuration 一样，默认的 object_wrapper 也有相同的 "不兼容改进"。但是，如果设置了 object_wrapper，那么就不要忘了设置 ObjectWrapper 自己的 incompatibleImprovements 属性，此外还有 Configuration。(请注意，对于 Configuration 来说，有不同的 "不兼容改进" 也是可以的，而对于 ObjectWrapper，则有它自己的选择。) 至于 DefaultObjectWrapper (对于 BeansWrapper 也是一样的，只是不同的类名而已) 参看这里如何来设置它。