Spring5.1 升级指南

Upgrading to Version 5.1 JDK 11

Spring Framework 5.1 requires JDK 8 or higher and specifically supports JDK 11 (as the next long-term support release) for the first time. We strongly recommend an upgrade to Spring Framework 5.1 for any applications targeting JDK 11, delivering a warning-free experience on the classpath as well as the module path.

Please note that developing against JDK 11 is not officially supported with any older version of the core framework. Spring Framework 5.0.9+ and 4.3.19+ just support deploying Java 8 based applications to a JVM 11 runtime environment (using -target 1.8; see below), accepting JVM-level warnings on startup.

ASM

Spring Framework 5.1 uses a patched ASM 7.0 fork which is prepared for JDK 11/12 and their new bytecode levels but not battle-tested yet. Spring Framework 5.1.x will track further ASM revisions on the way to JDK 12, also hardening bytecode compatibility with JDK 11.

For a defensive upgrade strategy, consider compiling your application code with JDK 8 as a target (-target 1.8), simply deploying it to JDK 11. This makes your bytecode safer to parse not only for Spring's classpath scanning but also for other bytecode processing tools.

CGLIB

Spring Framework 5.1 uses a patched CGLIB 3.2 fork that delegates to JDK 9+ API for defining classes at runtime. Since this code path is only active when actually running on JDK 9 or higher (in particular necessary on JDK 11 where an alternative API for defining classes has been removed), side effects might show up when upgrading existing applications to JDK 11.

Spring has a fallback in place which tries to mitigate class definition issues, possibly leading to a JVM warning being logged, whereas the standard code path delivers a warning-free experience on JDK 11 for regular class definition purposes. Consider revisiting your class definitions and bytecode processing tools in such a scenario, upgrading them to JDK 11 policies.

Core Container

The core container has been fine-tuned for Graal compatibility (native images on Substrate VM) and generally optimized for less startup overhead and less garbage collection pressure. As part of this effort, several introspection algorithms have been streamlined towards avoiding unnecessary reflection steps, potentially causing side effects for annotations declared outside of well-defined places.

Nested Configuration Class Detection

As per their original definition, nested configuration classes are only detected on top-level @Configuration or other @Component-stereotyped classes now, not on plain usage of @Import or @ComponentScan. Older versions of Spring over-introspected nested classes on non-stereotyped classes, causing significant startup overhead in some scenarios.

In case of accidentally relying on nested class detection on plain classes, simply declare those containing classes with a configuration/component stereotype.

Web Applications

Forwarded Headers

"Forwarded" and "X-Forwarded-*" headers, which reflect the client's original address, are no longer checked individually in places where they apply, e.g. same origin CORS checks, MvcUriComponentsBuilder, etc.

Applications are expected to use one of:

• Spring Framework's own ForwardedHeaderFilter.
• Support for forwarded headers from the HTTP server or proxy.

Note that ForwardedHeaderFilter can be configured in a safe mode where it checks and discards such headers so they cannot impact the application.

Encoding Mode of DefaultUriBuilderFactory

The encoding mode of DefaultUriBuilderFactory has been switched to enforce stricter encoding of URI variables by default. This could impact any application using the WebClient with default settings, or any application using DefaultUriBuilderFactory directly. See the "Encoding URIs" section and also the Javadoc for DefaultUriBuilderFactory#setEncodingMode.

Content Negotiation for Error Responses

The produces condition of an @RequestMapping no longer impacts the content type of error responses.

Multipart and Query Values

The integration with Apache Commons FileUpload now aggregates multipart parameter values with other request parameters from the query, as required by Servlet spec, section 3.1. Previously it returned only multipart parameter values if present.

HTTP OPTIONS

The built-in support for HTTP OPTIONS in @RequestMapping methods now consistently adds HTTP OPTIONS as one of the supported HTTP methods, whereas previously it did not.

---

升级到 5.1 版 JDK 11

Spring Framework 5.1 需要 JDK 8 或更高版本，并且首次特别支持 JDK 11（作为下一个长期支持版本）。我们强烈建议针对 JDK 11 的任何应用程序升级到 Spring Framework 5.1，在类路径和模块路径上提供无警告体验。

请注意，任何旧版本的核心框架都不正式支持针对 JDK 11 进行开发。Spring Framework 5.0.9+ 和 4.3.19+ 仅支持将基于 Java 8 的应用程序部署到 JVM 11 运行时环境（使用-target 1.8; 见下文），在启动时接受 JVM 级警告。

ASM

Spring Framework 5.1 使用已修补的 ASM 7.0 分支，它为 JDK 11/12 及其新字节码级别做好准备，但尚未经过实战测试。Spring Framework 5.1.x 将在通往 JDK 12 的过程中跟踪进一步的 ASM 修订，同时加强与 JDK 11 的字节码兼容性。

-target 1.8对于防御性升级策略，请考虑以JDK 8 作为目标（

CGLIB

Spring Framework 5.1 使用已修补的 CGLIB 3.2 分支，该分支委托给 JDK 9+ API 以在运行时定义类。由于此代码路径仅在实际运行在 JDK 9 或更高版本上时才有效（特别是在 JDK 11 上需要用于定义类的替代 API），因此在将现有应用程序升级到 JDK 11 时可能会出现副作用。

Spring 有一个备用方案，它试图缓解类定义问题，可能导致记录 JVM 警告，而标准代码路径在 JDK 11 上提供无警告体验，用于常规类定义目的。考虑在这种情况下重新访问您的类定义和字节码处理工具，将它们升级到 JDK 11 策略。

核心容器

核心容器已针对 Graal 兼容性（Substrate VM 上的本机图像）进行了微调，并且通常针对更少的启动开销和更少的垃圾收集压力进行了优化。作为这项工作的一部分，一些自省算法已被简化，以避免不必要的反射步骤，这可能会导致在定义明确的位置之外声明的注释的副作用。

嵌套配置类检测

根据它们的原始定义，嵌套配置类现在仅在顶级@Configuration或其他@Component定型类中检测到，而不是在@Import或的普通使用中检测到@ComponentScan。旧版本的 Spring 在非原型类上过度内省嵌套类，在某些情况下会导致显着的启动开销。

如果不小心依赖于普通类的嵌套类检测，只需使用配置/组件构造型声明包含类的那些。

网络应用程序

转发的标头

"Forwarded"和"X-Forwarded-*"headers 反映了客户的原始地址，不再在它们适用的地方单独检查，例如同源 CORS 检查MvcUriComponentsBuilder等。

应用程序应使用以下之一：

• Spring 框架自己的ForwardedHeaderFilter.
• 支持来自 HTTP 服务器或代理的转发标头。

请注意，ForwardedHeaderFilter可以将其配置为安全模式，在该模式下，它会检查并丢弃此类标头，因此它们不会影响应用程序。

编码方式DefaultUriBuilderFactory

DefaultUriBuilderFactory默认情况下，已切换编码模式以强制对 URI 变量进行更严格的编码。这可能会影响使用WebClient默认设置的任何应用程序，或DefaultUriBuilderFactory直接使用的任何应用程序。请参阅“编码 URI ”部分以及DefaultUriBuilderFactory#setEncodingMode.

错误响应的内容协商

的产生条件@RequestMapping不再影响错误响应的内容类型。

多部分和查询值

根据 Servlet 规范第 3.1 节的要求，与 Apache Commons FileUpload 的集成现在将多部分参数值与查询中的其他请求参数聚合在一起。以前它只返回多部分参数值（如果存在）。

HTTP 选项

方法中对 HTTP OPTIONS 的内置支持@RequestMapping现在始终将 HTTP OPTIONS 添加为受支持的 HTTP 方法之一，而以前它没有。