Apache Tomcat® - 迁移指南 - Tomcat 10.0.x

常规

请首先阅读常规迁移指南页面，了解 Apache Tomcat^® 版本之间的迁移或升级的常见注意事项。

从 9.0.x 迁移到 10.0.x

本节列出了 9.0.x 和 10.0.x 之间所有已知更改，这些更改可能会在升级时导致向后兼容性问题。

需要 Java 8

Apache Tomcat 10.0.x 需要 Java 8 或更高版本。这与 Tomcat 9.0.x 保持不变。

规范 API

Apache Tomcat 10 支持 Jakarta Servlet 5.0、Jakarta Server Pages 3.0、Jakarta Expression Language 4.0、JakartaWebSocket 2.0 和 Jakarta Authentication 2.0 规范。

Tomcat 9.0.x 和 Tomcat 10.0.x 之间存在重大破坏性更改。规范 API 使用的 Java 包已从 javax... 更改为 jakarta...。有必要针对新 API 重新编译 Web 应用程序。

Tomcat 可以使用适用于 Jakarta EE 的 Apache Tomcat 迁移工具在部署时将现有的 Web 应用程序从 Java EE 8 转换为 Jakarta EE 9。要使用此功能，应将 Web 应用程序放置在主机 legacyAppBase 文件夹中（默认名为 webapps-javaee），它们将被转换为主机 appBase 文件夹中（默认名为 webapps）的等效 Jakarta EE Web 应用程序。

或者，可以使用适用于 Jakarta EE 的 Apache Tomcat 迁移工具或任何类似的转换工具来提前受益于更快的部署时间和更精确的转换配置选项。

Servlet 5.0 API

Java 包已从 javax.servlet 更改为 jakarta.servlet。

服务器页面 3.0

Java 包已从 javax.servlet.jsp 更改为 jakarta.servlet.jsp。

表达式语言 4.0

Java 包已从 javax.el 更改为 jakarta.el。

WebSocket 2.0

Java 包已从 javax.websocket 更改为 jakarta.websocket。

身份验证 4.0

Java 包已从 javax.security.auth.message 更改为 jakarta.security.auth.message。

内部 API

虽然 Tomcat 10 内部 API 与 Tomcat 9 广泛兼容，但细节级别已发生许多更改，且它们在二进制上不兼容。与 Tomcat 内部交互的自定义组件的开发人员应查看相关 API 的 JavaDoc。

特别需要注意的是

GenericPrincipal.getPassword() 已被移除。

web.xml 默认值

conf/web.xml 将默认请求和响应字符编码设置为 UTF-8。

会话管理

默认情况下已禁用重启时的会话持久性。它可以在 conf/context.xml 中或每个 Web 应用程序中重新启用。

HTTP/2

HTTP/1.1 和 HTTP/2 连接器之间重复的配置设置已从 HTTP/2 连接器中移除，现在它将从关联的 HTTP/1.1 连接器继承这些设置。

日志记录

日志记录实现现在仅在日志文件中需要写入内容时才创建日志文件。

访问日志模式

为了与 httpd 保持一致，%D 模式现在以微秒而不是毫秒记录请求时间。要以毫秒为单位记录请求时间，请使用 %{ms}T。

升级 10.0.x

在将 Apache Tomcat 实例从一个 Tomcat 10 版本升级到另一个版本时，尤其是在为 $CATALINA_HOME 和 $CATALINA_BASE 使用单独位置时，有必要确保配置文件中的任何更改（例如新属性和默认值更改）都作为升级的一部分应用。为了帮助识别这些更改，可以使用以下表单查看 Tomcat 10 不同版本中的配置文件之间的差异。

Tomcat 10.0.x 值得注意的更改

Tomcat 开发人员的目标是使每个补丁版本与前一个版本完全向后兼容。有时，为了修复错误，有必要打破向后兼容性。在大多数情况下，这些更改不会被注意到。本节列出了不完全向后兼容且在升级时可能导致中断的更改。

从 10.0.3 开始，HostConfig.check(String) 方法的语义已更改。该方法不会在调用该方法之前将应用程序标记为已服务，而是在检查资源之前将应用程序标记为已服务，然后在检查完成后取消标记应用程序为已服务。如果在调用该方法时将应用程序标记为已服务，则该方法将为 NO-OP。
从 10.0.9 开始，由于机密传输保证，Tomcat 在添加“Cache-Control: private”时不再添加“Expires”HTTP 响应头。对于未明确设置自己的标头但依赖于 Tomcat 以前行为的应用程序，这可能会导致缓存行为发生变化。如果您希望禁用缓存，则需要在应用程序中明确配置它。有关更多信息，请参阅 BZ 65513。
在 10.0.11 及更高版本中，由于现在使用 java.nio.file.Files 的 Commons FileUpload 更新分支，使用多部分上传的应用程序需要确保 JVM 配置有足够的直接内存来存储所有正在进行的多部分上传。
在 10.0.14 及更高版本中，系统属性 org.apache.juli.AsyncLoggerPollInterval 不再使用。

Tomcat 10.0.x 配置文件差异

从下面的框中选择一个配置文件、旧版本和新版本，然后单击“查看差异”以查看差异。差异将显示在一个新选项卡/窗口中。

注意：如果没有差异，您将看到一个错误页面。

您还可以从工作副本中使用类似于以下的 Git 命令

git diff 10.0.0 10.0.12 -- conf/

内容

目录

常规