Spring Boot 2.0 迁移指南（1.5.x~2.0.x）

Spring Boot 2.0 Migration Guide 原文地址 选择性翻译 时间：2021-10

文档的宗旨是为开发人员提供主要模块内容的指南帮助开发人员将应用迁移到 Spring Boot.20。

一、开始前的准备工作

1.1、升级版本推荐

在升级前，保证你现在的应用对应的 Spring Boot 版本至少是 1.5.x 的版本。这样可以让你使用该文档进行升级的时候，减少依赖冲突的问题。

1.2、检查依赖问题

将版本升级到 Spring Boot 2.0 必然存在部分依赖定位的问题，所以需要查看对比 [1.5x](https://docs.spring.io/spring-boot/docs/1.5.x/reference/html/appendix-dependency-versions.html) 和 [2.0.x](https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/appendix-dependency-versions.html) 评估升级对系统的影响，相应的需要重新管理对应的依赖定位 以及依赖版本。

在进行 Spring Boot 2.0 迁移的同时需要关注对应的 Spring Cloud 版本兼容问题。

可以通过 Spring Cloud 官网查询得到 ，对应不同版本，可通过连接跳转对应的版本记录页。
目前最新的关系表格如下：

Spring Cloud Dalston, Edgware, Finchley, and Greenwich 已经不在维护。

1.3、检查自定义配置问题

部分自定义配置将在升级后发生变更，部分配置可能呗自动配置类替代，升级前确定好自身项目中存在了哪些配置。
譬如：配置文件 application.properties 、 bootstrap.properties、 其他位置的文件配置 。Bean 配置，分散在 基础包依赖中的、项目中的各类配置文件等。

1.4、检查基础系统问题

Spring Boot 2.0 仅支持 Java8 + ，低于 Java8 不在被支持。
并且 Spring Boot 2.0 要求 Spring Framework 5.x 以上

二、Spring Boot 2.0 升级

梳理完项目相关依赖后，将项目升级到 Spring Boot 2.0.x 中的最新的稳定版本，而不是 Spring Boot 2.0.0.RELEASE ，最新的版本已经修复了很多的问题。

同样的建议分阶段升级，优先升级到 Spring Boot 2.0.x 然后在上级到 2.1.x 以此类推，循序渐进。

2.1、Configuration properties migration

在 Spring Boot 2.0 中很多 配置信息会被更名、移除 升级的时候需要更新相关的 application.properties/application.yml 。

Spring Boot 提供了 spring-boot-proerties-migrator 模块，暂时在项目中引用该模块，该模块会在运行时分析并打印相关提示信息。

升级完后记得移除该模块。

2.2、升级相关阅读材料

Spring Boot 2.0.0 Release Notes
Upgrading to Spring Framework 5.0

三、Spring Boot 功能特性

3.1、默认代理模式

当前版本下 Spring Boot 默认使用 CGLIB Proxy，包括 AOP 的支持。
如果需要使用基于接口的 JDK 动态代理，需要如下配置 spring.aop.proxy-target-class=false

3.2、Spring Application

3.2.1、Web Environment

Spring Boot 应用支持多模式运行，所以 spring.main.web-environment 属性废弃，使用 spring-main-web-application-type 替代。

如果想让应用使用非 web 模式运行，需要如下配置 spring.main.web-application-type=none 。

Bean 配置下，可以通过 SpringApplication#setWebApplicationType 设置

3.2.2、Sprinb Boot Application Events Changes

添加新的事件 ApplicationStartedEvent 。
在上下文 refresh 启动后，应用程序和命令行运行前发送 ApplicationStartedEvent 事件。
在所有应用程序和命令执行完后发送 ApplicationReadyEvent 事件，表示应用准备好能够处理请求了。

3.3、Externalized Configuration

3.3.1、Relaxed Binding

• @ConditionalOnProperty
  属性配置规范格式： xxx.my-property 而不是 xxx.myProperty
  If you were using the prefix attribute you can now simply put the full key using the name or value attributes.
  （待验证，prefix 是否失效）

3.3.2、Binding on static methods

Spring Boot 2.x 不在在支持静态属性绑定，获取方式，可以使用静态的 getter setter 进行返回。

3.3.3、@ConfigurationProperties Validation

加了 @Validated , @ConfigurationProperties 将会对对象强制进行校验。

3.3.4、Configuration Location

·
Spring Boot 外部化配置

spring.config.location 会替换默认的扫描路径
spring.config.additional-location 添加配置的扫描路径，注意如果同名在resources的配置文件会优先加载

4、Developing Web Applications

4.1、Embedded containers package structure

为了能够支持 reactive 用例，内置容器包结构进行大的变更。

EmbeddedServletContainer 重命名为 WebServer 。同时包名由 org.springframework.boot.context.embedded 重新定位为 org.springframework.boot.web.server 。

相应地，EmbeddedServletContainerCustomizer 改名为 WebServerFactoryCustomizer 。

例如：如果你之前使用 TomcatEmbeddedServletContainerFactory 回调接口定义了内置 tomcat 容器。现在需要使用
TomcatServletWebServerFactory 。或者，你如果使用了 EmbeddedServletContainerCustomizer ，你现在需要使用
TomcatServletWebServerFactory 。

4.2、Servlet 属性变更

部分 server.* 的属性移动变更为 server.servlet ,表格如下：

4.3、Web Starter 依赖变更

为了支持新的模块 Spring WebFlux ，Spring-boot-starter-web 不在依赖 spring-boot-starter-mustache 、 spring-boot-starter-freemarker 、 spring-boot-starter-thymeleaf 。
开发人人员需根据自身需求，引用相关配置模块。

4.4、Template Engines

Thymeleaf

Spring Boot 2 使用 Thymeleaf 3。
Thymelefa Starter 不在依赖 thymeleaf-layout-dialect 。使用到的需要自行进行依赖。

Mustache Templates Default File Extension

以前 Mustanche templates 默认扩展名为 .html 。
当前版本 .mustache 变为官方的指定扩展名。
如果仍然需要自定义扩展名，可以通过 spring.mustache.sufix 进行配置。

4.5、Jackson / JSON Supprot

在 2.0 中，jackson 默认时间配置由 JSR-310 改为了 ISO-8601 。
如果仍然想要使用原先 JSR-310 配置，可以追加如下配置 spring.jackson.serialization.write-dates-as-timestamps=true 。

新的 spring-boot-starter-json starter 引用了 jackson-datatype-jdk8, jackson-datatype-jsr310 and jackson-module-parameter-names。

4.6、Spring MVC Path Matching Default Behavior Change

Spring MVC suffix Path 匹配发生变更，如： GET /projects/spring-boot.json 将被 @GetMapping("/projects/spring-boot) 适配。

4.7、Servlet Filters

Servlet Filter 默认的 调度类型为 DipatcherType.REQUEST 。如果要更改，需要通过 FilterRegistrationBean 。

4.8、RestemplateBuilder

requestFactory(ClientHttpRequestFactory) 被新方法 requestFactory(Supplier requestFactorySupplier) 替代。

4.9、WebJars Locator

Spring Boot 1.x 依赖的 org.webjars:webjars-locator. webjars-locator 命名不是很好。如果依赖了 org.webjars:webjars-locator 应该使用 org.webjars:webjars-locator-core 替代

4.10、Custom DispatcherServlet registration

如果有通过 ServletRegistrationBean 自定义的 DispatcherServlet ，还要提供一个 DispatcherServletPath 让其他字间能够注册 servlet path 。

自定义注册的时候，一种更好的方式是通过 DispatcherServletRegistrationBean 实现 DispatcherServletPath 。

4.11、Security

Spring Boot 2 极大的简化了 security 默认配置，通知让自定义 security 更简单。

Spring Boot 2 通过单一配置行为替代了多个的自动配置类。同时只要实现了自己的 WebSecurityConfigurerAdapter， 将会以自己的配置为主。

相关属性配置：

security.basic.authorize-mode
security.basic.enabled
security.basic.path
security.basic.realm
security.enable-csrf
security.headers.cache
security.headers.content-security-policy
security.headers.content-security-policy-mode
security.headers.content-type
security.headers.frame
security.headers.hsts
security.headers.xss
security.ignored
security.require-ssl
security.sessions

关于 Security 更多变更信息

4.12、Default Security （默认安全配置）

Spring security 自动配置不在暴露更多的选项配置，所以应该尽可能的使用默认配置。
Spring Boot 2.x 对比 Spring Boot 1.5 在 security的默认配置上并没有太大的偏差。需要注意的比如静态资源： /css/**, /js/**, /images/**, /webjars/**, /**/favicon.ico。
在 Spring Boot2.x 中需要主动配置，暴露。参考

4.13、Default User

Spring Boot2.x 中的 Spring Security 默认配置了一个用户，并生成对应的密码。
可以通过 spring.security.user.* 自定义用户信息。但是如果需要支持多用户，需要通过 UserDetailService 替代。

4.14、AuthenticationManager Bean

如果需要暴露 Spring Security AuthenticationManager 为 Bean，需要在 WebSecurityConfigurerAdapter 中实现方法 authenticationManagerBean ，并通过 @Bean 声明。

5、Working with SQL Databases

略（没用到提到的工具）
主要提到了 JPA、等。

6、Working with NoSQL Technologies

6.1、Redis

Spring Boot 2.x spring-boot-starter-data-redis 依赖中的Jedis 将被 Lettuce 替代。Lettuce 称为默认的驱动客户端。如果想要使用高版本的 Spring Data 组件，就需要适配新的方法。

不过 spring-boot-starter-data-redis 仍然支持使用 Jedis ，这就需要引入依赖 redis.clients:jedis，剔除依赖 io.lettuce:lettuce-core。

如果使用 Lettuce 作为默认Redis 驱动，同时选择使用连接池时需要自己添加依赖 commons-pool2。

6.2、Elasticsearch

Elasticsearch已经升级到5.4+。
根据Elastic的声明，不再支持嵌入式Elasticsearch, NodeClient的自动配置已经被移除。
可以使用 spring.data.elasticsearch 自动配置TransportClient。 提供一个或多个要连接的节点的地址的群集节点。

7、Spring Boot Actuator

Spring Boot 2 中 actuator 组件用户接口和代码都发生了很大的变更，相关的变更需要参考

• 参考指南（以2.1.5.RELEASE，2.0.9无法访问）
• Actuator API 文档

在 Spring Boot 2.x 中 Spring MVC 、Spring WebFlux 和 Jersey 默认支持 Actuator 。
同时应该预料到某些端点在编程模型，配置key和相应格式上的变化。

7.1、Build

Actuator 代码分裂成两个模块：

• 已有的： spring-boot-actuator
• 新的：spring-boot-actuator-autoconfigure

如果还想使用 spring-boot-actuator原来的功能，需要使用新的模块 spring-boot-starter-actuator 替代。

7.2、Configuration Keys Strcture

端点配置变更表

7.3、Base Path

所有端点默认以 /actuator 为请求路径前缀。

management.server.servlet.context-path现在和 server.servlet.context-path等价。（党配置了 management.server.port 时有效）
此外，你也可以通过 management.endpoints.web.base-path 设置管理端点的基础访问路径。

举个例子，假如设置了 management.server.servlet.context-path=/management 和management.endpoints.web.base-path=/application，此时访问 health 端点，访问路径为：/management/application/health

如果想要沿用1.x时的访问（例如：使用 /health 而非 /actuator/health ）,可以配置：management.endpoints.web.base-path=/

7.4、Audit Event API Change

AuditEventRepository 提供了带有所有可选参数的方法。

7.5、Endpoints

让 actuator 端点能够通过 HTTP 访问需要两个条件

• 端点 enabled 允许被访问
• 端点 exposed 被暴露出来

默认情况下

• 无论应用中是否存在并配置了 Spring Security ，都只开放了 /health 和 /info 端点。
• 除了 /shutdown 端点外所有的端点都是 enabled ，能够被访问的。

你可以通过如下配置暴露所有端点

management.endpoints.web.exposure.include=*

你可以通过如下配置，设置 /shutdown 为 enabled

management.endpoint.shutdown.enabled=true

暴露出所有 enabled 的web端点，除了 env 端点外

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env

端点变更如下

• endpoints..enabled 变更为 management.endpoint..enabled
• endpoints.<id>.id 没有发生变更，（id 不在支持配置）
• endpoints.<id>.sensitive 没有发生变更（参考）
• endpoints..path 变更为 management.endpoints.web.path-mapping.

  7.6、Endpoint Format

  /actuator/mappings 和 /actuator/httptrace 进行全面改造，显示信息更详细，更对参考 Actuator API 文档

7.7、Migrate Custom Endpoints

存在定义的端口，需要参考相关博客文章。该团队也写了相关的wiki 页面，来节视如何把已有的自定义的 Actuator 端点迁移到新的设施上。

8、Metrics