【译】Spring Boot 2.0 官方迁移指南
前提
希望本文档将帮助您把应用程序迁移到 Spring Boot 2.0。
在你开始之前
首先, Spring Boot 2.0 需要 Java 8 或更高版本 。不再支持 Java 6 和 7 了。
在 Spring Boot 2.0 中,许多配置属性被重新命名/删除,开发人员需要更新
application.properties
/
application.yml
相应的配置。为了帮助你解决这一问题,Spring Boot 发布了一个新
spring-boot-properties-migrator
模块。一旦作为该模块作为依赖被添加到你的项目中,它不仅会分析应用程序的环境,而且还会在启动时打印诊断信息,而且还会在运行时为您暂时迁移属性。在您的应用程序迁移期间,这个模块是必备的:
mvn spring-boot:run -Dspring-boot.run.profiles=prod
Surefire 默认值
以前的
include/exclude
模式已与最新的 Surefire 默认设置保持一致。如果依赖于此插件,需要相应地更新插件配置。之前对应的配置如下:
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management' // <-- add this to your build.gradle
注意:依赖管理插件仍然是 spring-boot-gradle-plugin 的传递依赖项,所以不需要在 buildscript 配置中将其列为类路径依赖项。
建立可执行的 Jars 和 Wars
bootRepackage
任务已经被替换成
bootJar
和
bootWar
任务,分别用于构建可执行的
jar
包和
war
包。
配置更新
BootRun
,
BootJar
和
BootWar
任务现在都使用
mainClassName
的属性来配置主类的名称。这使得三个特定于引导的任务相互一致,并将其与 Gradle 自己的应用程序插件进行对齐。
Spring Boot 特性
默认动态代理策略
Spring Boot 默认使用 CGLIB 做动态代理代理(基于类的动态代理),包括对 AOP 的支持。如果你需要基于接口的动态代理,你需要将
spring.aop.proxy-target-class
设置为
false
。
SpringApplication
Web 环境
Spring Boot 应用程序现在可以在更多模式下运行,因此
spring.main.web-environment
现在不推荐使用,
spring.main.web-application-type
属性可以提供更多的支持。
如果您想确保应用程序不启动 Web 服务器,则必须将该属性更改为:
MyProperties target = Binder.get(environment)
.bind("app.acme", MyProperties.class)
.orElse(null);
由于现在内置了轻松绑定,因此只要使用其中一种支持的格式,就可以请求任何属性而不必关心案例:
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
默认安全
安全自动配置不再公开选项,并尽可能使用 Spring Security 默认值。一个明显的副作用是使用 Spring Security 的内容协商进行授权(表单登录)。
默认用户
默认情况下,Spring Boot 使用生成的密码配置单个用户。用户可以使用
spring.security.user.*
属性进行配置。要进一步定制用户或添加其他用户,您将不得不公开一个
UserDetailsService
bean。
AuthenticationManager Bean
如果您想将 Spring Security
AuthenticationManager
作为 bean 公开,请覆盖
authenticationManagerBean
您的方法
WebSecurityConfigurerAdapter
并为其添加注释
@Bean
。
OAuth2
从功能的 Spring Security OAuth 项目 迁移到核心 Spring Security 。不再为依赖关系提供依赖管理,Spring Boot 2 通过 Spring Security 5 提供 OAuth 2.0 客户端支持 。
如果您依赖尚未迁移的 Spring Security OAuth 功能,则需要在其他 jar 上添加依赖项,请查看 文档 以获取更多详细信息。我们还继续支持 Spring Boot 1.5,以便旧版应用程序可以继续使用它,直到提供升级路径。
执行器安全
执行器不再有单独的安全自动配置(
management.security.*
属性消失)。
sensitive
每个端点的标志也没有在安全配置中变得更加明确。如果您依赖于此行为,则需要创建或调整您的安全配置,以保护您选择角色的端点。
例如,假设以下配置:
http
.authorizeRequests()
.requestMatchers(EndpointRequest.to("health", "flyway")).permitAll()
.requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole("MY_ADMIN")
...
需要注意的是在
2.x
,
health
和
info
在默认情况下启用(与
health
默认情况下不显示其细节)。为了与这些新的默认值一致,
health
已被添加到第一个匹配器。
使用 SQL 数据库
配置数据源
默认连接池已从 Tomcat 切换到 HikariCP。如果您过去
spring.datasource.type
在基于 Tomcat 的应用程序中强制使用 Hikari,现在可以删除重写。
特别是,如果你有这样的设置:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
WARN 消息隐含的’打开在视图’
从现在起,未明确启用的应用程序
spring.jpa.open-in-view
将在启动过程中收到警告消息。虽然这种行为是一种友好的默认行为,但如果您没有完全意识到为您做了什么,这可能会导致问题。此消息可确保您了解可在查看呈现期间执行数据库查询。如果你没有问题,你可以明确地配置这个属性来消除警告信息。
JPA 和 Spring Data
在 Spring Boot 1.x 中,一些用户正在扩展
HibernateJpaAutoConfiguration
以将高级自定义应用于自动配置
EntityManagerFactory
。为了防止发生这种错误的用例,Spring Boot 2 中不再可能扩展它。
为了支持这些用例,现在可以定义一个
HibernatePropertiesCustomizer
bean,它可以完全控制 Hibernate 属性,包括注册在上下文中声明为 bean 的 Hibernate 拦截器的能力。
Flyway
Flyway 配置键被移动到
spring
命名空间(即
spring.flyway
)
升级到 Spring Boot 2 将会将 Flyway 升级
3.x
到
5.x
。为确保模式升级顺利进行,请按照以下说明操作:
-
首先将您的
1.5.x
Spring Boot 应用程序升级到 Flyway 4,请参阅 Maven 和 Gradle 的说明。 - 一旦您的架构升级到了 Flyway 4,升级到 Spring Boot 2 并再次运行迁移以将您的应用程序移植到 Flyway 5。
Liquibase
Liquibase 配置键被移动到
spring
命名空间(即
spring.liquibase
)
数据库初始化
基本
DataSource
初始化现在仅针对嵌入式数据源启用,并将在您使用生产数据库时立即关闭。新的
spring.datasource.initialization-mode
(替换
spring.datasource.initialize
)提供更多的控制。
更新默认的’创建 - 删除’处理
spring.jpa.hibernate.ddl-auto
属性默认为只有在没有使用 Liquibase 或 Flyway 等模式管理器时才使用嵌入式数据库进行创建。一旦检测到模式管理器,默认更改为
none
。
整合 NoSQL
Redis
现在使用的是
Lettuce
而不是
Jedis
作为 Redis 驱动程序
spring-boot-starter-redis
。如果您使用更高级别的Spring Data 构造,则应该发现变化是透明的。我们仍然支持 Jedis,如果您愿意,通过排除
io.lettuce:lettuce-core
并添加
redis.clients:jedis
,则可以自由切换依赖项。
Elasticsearch
Elasticsearch 已经升级到 6.0+。与
Elastic 宣布嵌入式 Elasticsearch 不再受支持一致
,自动配置
NodeClient
已被删除。
TransportClient
可以通过使用
spring.data.elasticsearch.cluster-nodes
提供要连接的一个或多个节点的地址来自动配置。
高速缓存
用于缓存的专用 Hazelcast 自动配置。
无法自动配置常规
HazelcastInstance
和专用
HazelcastInstance
缓存。因此,该
spring.cache.hazelcast.config
属性已不再可用。
批量
在启动时执行批处理作业的 CommandLineRunner 的顺序为 0。
测试
Mockito 1.x
Mockito 1.x 不再支持
@MockBean
和
@SpyBean
。如果你不用
spring-boot-starter-test
来管理你的依赖关系,你应该升级到 Mockito 2.x.
Spring Boot Actuator
Spring Boot 2 为 Actuator 带来了重要变化,无论是内部还是面向用户,请查阅 参考指南中 的 更新部分 和 新的Actuator API文档 。
您应该期望编程模型,配置密钥和某些端点的响应格式发生变化。Actuator 现在在 Spring MVC,Spring WebFlux 和Jersey 上得到本地支持。
构建
Actuator 的代码分为两个模块:现有的
spring-boot-actuator
和新的
spring-boot-actuator-autoconfigure
。如果您使用原始模块(
spring-boot-actuator
)导入 actuator,请考虑使用
spring-boot-starter-actuator
启动器替代它。
Keys 的配置结构
Endpoints 基础配置 key 已经统一:
旧的属性 | 新的属性 |
---|---|
endpoints.<id>.*
|
management.endpoint.<id>.*
|
endpoints.cors.*
|
management.endpoints.web.cors.*
|
endpoints.jmx.*
|
management.endpoints.jmx.*
|
management.address
|
management.server.address
|
management.context-path
|
management.server.servlet.context-path
|
management.ssl.*
|
management.server.ssl.*
|
management.port
|
management.server.port |
基本路径
所有 endpoints 默认情况下都已移至
/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
,你就可以在下面的路径到达终点健康:
/management/application/health
。
如果你想恢复 1.x 的行为(即具有
/health
代替
/actuator/health
),设置以下属性:
management.endpoints.web.exposure.include=*
您可以通过以下方式显式启用
/shutdown
端点:
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env
Endpoint changes
1.x 端点 | 2.0 端点(改变) |
---|---|
/actuator
|
不再可用。 但是,在
management.endpoints.web.base-path
的根目录中有一个映射,它提供了到所有暴露端点的链接。
|
/auditevents
|
该
after
参数不再需要
|
/autoconfig
|
重命名为
/conditions
|
/docs
|
不再可用 |
/health
|
现在有一个
management.endpoint.health.show-details
选项
never
,
always
,
when-authenticated
,而不是依靠
sensitive
标志来确定
health
端点是否必须显示全部细节。 默认情况下,
/actuator/health
公开并且不显示细节。
|
/trace
|
重命名为
/httptrace
|
端点属性已更改如下:
-
endpoints.<id>.enabled
已经转移到了management.endpoint.<id>.enabled
-
endpoints.<id>.id
没有替换(端点的 ID 不再可配置) -
endpoints.<id>.sensitive
没有替代品(请参见 执行器安全 ) -
endpoints.<id>.path
已经转移到了management.endpoints.web.path-mapping.<id>
端点格式
/actuator/mappings
端点大改变
JSON 格式已经更改为现在正确地包含有关上下文层次结构,多个
DispatcherServlets,
部署的 Servlet 和 Servlet 过滤器的信息。详情请参阅
#9979
。
Actuator API 文档的 相关部分 提供了一个示例文档。
/actuator/httptrace
端点大改变
响应的结构已经过改进,以反映端点关注跟踪 HTTP 请求 - 响应交换的情况。
迁移自定义端点
如果您有自定义执行器端点,请 查看专用博客文章 。该团队还撰写了一个 wiki 页面,介绍 如何将现有的执行器端点迁移 到新的基础架构。
Metrics
Spring Boot 自己的指标已被支持取代,包括自动配置,用于 icrometer 和 dimensional 指标。
设置 icrometer
如果您的 Spring Boot 2.0 应用程序已依赖于 Actuator,则 icrometer 已在此处并自动配置。如果您希望将度量标准导出到 Prometheus,Atlas 或 Datadog 等外部注册表,Micrometer 将为许多注册表提供依赖关系; 您可以使用
spring.metrics.*
属性配置您的应用程序以导出到特定的注册表。
迁移定制计数器/量表
您可以通过以下方式创建各种指标,而不是在应用程序代码中注入
CounterService
或
GaugeService
的实例:
-
注入
MeterRegistry
和调用方法。 -
直接调用静态方法
Counter featureCounter = Metrics.counter("feature");
。
开发者工具
热拔插
由于 Spring Loaded 项目被搁置,它在 Spring Boot 的支持已被删除。我们建议使用 Devtools。
Devtools 远程调试隧道
已经从 Devtools 中删除了对通过 HTTP 进行隧道远程调试的支持。
已删除的功能
以下功能不再可用:
- CRaSH 支持
- Spring Mobile 的自动配置和依赖关系管理。
- Spring Social 的自动配置和依赖关系管理。
-
依赖关系管理
commons-digester
。
依赖版本
以下库的最低支持版本已更改:
- Elasticsearch 5.6
- Gradle 4
- Hibernate 5.2
- Jetty 9.4
- Spring Framework 5
- Spring Security 5
- Tomcat 8.5
参考资料
https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.0-Migration-Guide
前提
希望本文档将帮助您把应用程序迁移到 Spring Boot 2.0。