Spring Boot 3.3.0 正式发布-工具盒子

从 Spring Boot 3.2 进行升级 {#从-spring-boot-32-进行升级}

Jersey Observability（可观察性） {#jersey-observability可观察性}

Micrometer 1.13 已放弃对 Jersey 的支持，转而使用 Jersey 的 jersey-micrometer 模块。如果你的应用使用 Jersey 指标，请在升级时添加对 org.glassfish.jersey.ext:jersey-micrometer 依赖。

为了支持 Jersey 的可观察下，MetricsApplicationEventListener 已被替换为 ObservationApplicationEventListener。如果你之前使用 JerseyTagsProvider 自定义标签（Tag），现在需要实现一个 JerseyObservationConvention bean 来完成此功能。

删除了 Dropwizard 指标的 Dependency Management {#删除了-dropwizard-指标的-dependency-management}

Dropwizard Metrics 的 Dependency management 理已删除。Spring Boot 并不直接依赖于 Dropwizard Metrics，因此不需要特定的版本。如果你的应用直接依赖于 Dropwizard Metrics，请更新你的构建配置，以指定满足其需求的版本。

Prometheus Client 1.x {#prometheus-client-1x}

Spring Boot 3.3 包含对 Prometheus 客户端 1.x 的支持。该版本的客户端包含一些破坏性更改，例如对导出指标名称的更改。在 Prometheus 维护者添加该支持之前，1.x 客户端不支持使用 Prometheus Push Gateway。

如果你想继续使用 0.x 版本的 Prometheus 客户端，请从依赖中移除 io.micrometer:micrometer-registry-prometheus，并添加 io.micrometer:micrometer-registry-prometheus-simpleclient。Spring Boot 包含 simpleclient 的自动配置，但已过时，将在 Spring Boot 3.5.0 中移除。

有关更详细的迁移指南，请参阅 Micrometer wiki 的这一部分。

Flyway 10 {#flyway-10}

本版本升级到 Flyway 10。与之前的版本相比，Flyway 10 的模块化程度更高，对多个数据库的支持已转移到一些新的、特定于数据库的模块中。如果你正在使用以下数据库，请相应更新你的依赖：

DB2 (flyway-database-db2)
Derby (flyway-database-derby)
HSQLDB (flyway-database-hsqldb)
Informix (flyway-database-informix)
PostgreSQL (flyway-database-postgresql)
Redshift (flyway-database-redshift)
SAP HANA (flyway-database-saphana)
Snowflake (flyway-database-snowflake)
Sybase ASE (flyway-database-sybasease)

Infinispan 15 {#infinispan-15}

此版本升级到 Infinispan 15。Infinispan 15 提高了其 Jakarta EE 基线，因此其 -jakarta 模块（如 infinispan-core-jakarta 模块）已不复存在。请使用它们的标准替代模块，如 infinispan-core。

Git Commit ID Maven Plugin {#git-commit-id-maven-plugin}

插件已升级至 8.0.x。作为此次升级的一部分，默认日期格式现为 yyyy-MM-dd'T'HH:mm:ssXXX。这与 Maven 的可复现构建功能（Reproducible Builds Feature）兼容。

最低要求的变化 {#最低要求的变化}

原生构建工具 {#原生构建工具}

如果你使用原生构建工具（Native Build Tools）通过 GraalVM 构建项目，请确保你使用的插件至少是 0.10.x 版本。Maven 用户在使用 Spring Boot Boot 版本时应该会自动获得正确的版本。

Gradle 用户应更新 plugins 中的插件版本：

plugins {
  // ...
  id 'org.graalvm.buildtools.native' version '0.10.2'
  // ...
}

详见 #39068。

最新和最值得关注的地方 {#最新和最值得关注的地方}

你可以查看更改日志，了解配置更改的完整概览。

CDS 支持 {#cds-支持}

CDS（Class Data Sharing）是一种JVM功能，可以帮助减少 Java 应用的启动时间和内存占用。Spring Boot 现在支持轻松创建与 CDS 兼容的布局。通过使用 jarmode tools 提取 uber JAR，可以创建此布局。

java -Djarmode=tools -jar your-application.jar extract

这将在 your-application/lib 文件夹中创建 your-application/your-application.jar 和所需的库。然后就可以使用 java -jar your-application/your-application.jar 执行应用程序了。

目前，jarmode tools 支持两种命令：

extract，如上。它取代了 -Djarmode=layertools extract。
list-layers，它取代了 -Djarmode=layertools list-layers。

运行：

java -Djarmode=tools -jar your-application.jar help <command>

如果你在 Gradle build 文件中使用了 layers.enabled = false，或在 Maven 的 pom.xml 中使用了 <layers><enabled>false</enabled></layers>，请注意，禁用层（Disabling Layers）不再阻止包含 jarmode JAR。你可以在 BootJar 或 BootWar task 上使用 includeTools，或者在 spring-boot-maven-plugin 中使用 <configuration><includeTools>false</includeTools></configuration> 来进行设置。

可观察性的改进 {#可观察性的改进}

现在可通过属性为简单、直接和流监听器（Stream Listener）以及 RabbitTemplate 启用观察功能。

添加了对 Micrometer @SpanTag 注解的支持。

为 Brave 和 OpenTelemetry 都新增了对带标签字段的支持。同时，还为 Brave 新增了对本地字段的支持。

添加了 process InfoContributor，可通过 management.info.process.enabled=true 启用。

如果没有显式设置应用名称，现在会将 unknown_service 用于 OpenTelemetry。这使 Spring Boot 默认值与 OpenTelemetry 规范保持一致。

Apache Pulsar {#apache-pulsar}

属性 spring.pulsar.listener.observation-enabled 和 spring.pulsar.template.observations-enabled 的默认值从 true 更改为 false。这样做是为了统一 observation-enabled 属性的默认值，现在所有的属性都默认为 false。如果你依赖 Pulsar 的观察功能（Observations）并且没有显式启用它们，请将属性 spring.pulsar.listener.observation-enabled=true 和 spring.pulsar.template.observations-enabled=true 添加到你的配置中以恢复旧的行为。

Brave 和 Zipkin {#brave-和-zipkin}

Brave 已更新到 6.0，Zipkin 也已更新到 3.0。升级后，Spring Boot 中的 Zipkin 支持增加了新功能，例如指定向 Zipkin API 报告数据的编码。详情请参见 #39049。

新的基于 JDK HttpClient 的 Zipkin Sender 已经实现。该 Sender 仅依赖于 JDK，并将成为 Spring Boot 3.5.0 中的默认 Sender，取代 WebClient 和 RestTemplate Sender 实现。

Apache Pulsar 的改进 {#apache-pulsar-的改进}

现在有一些属性可以 spring.pulsar.client.failover 命名空间下配置 Pulsar 的集群级故障转移。

Spring Security 的改进 {#spring-security-的改进}

如果设置了其中一个属性，JwtAuthenticationConverter（或 ReactiveJwtAuthenticationConverter）现在会自动配置：

spring.security.oauth2.resourceserver.jwt.authority-prefix
spring.security.oauth2.resourceserver.jwt.principal-claim-name
spring.security.oauth2.resourceserver.jwt.authorities-claim-name

服务连接 {#服务连接}

支持 Apache ActiveMQ Artemis {#支持-apache-activemq-artemis}

新增了对 Apache ActiveMQ Artemis 的服务连接支持。Testcontainers 支持适用于 ArtemisContainer 容器，Docker Compose 支持适用于 apache/activemq-artemis 镜像。

支持 ActiveMQ Classic 官方镜像 {#支持-activemq-classic-官方镜像}

ActiveMQ 服务连接现在支持 apache/activemq-classic docker 镜像和 ActiveMQContainer 测试容器（Testcontainer）。

对 LDAP 的支持 {#对-ldap-的支持}

通过 osixia/openldap 容器为 LDAP 添加了服务连接支持

Bitnami 容器镜像 {#bitnami-容器镜像}

除了 Cassandra、Elasticsearch、MariaDB、MySQL、MongoDB、Neo4j、PostgreSQL、RabbitMQ 和 Redis 等几种支持技术的官方镜像之外，Docker Compose 的 Spring Boot 支持还能检测和配置来自 Bitnami 的容器。

虚拟线程（Virtual Threads） {#虚拟线程virtual-threads}

如果 Context 中有可用的 AsyncTaskExecutor，它现在就会在 Websocket ChannelRegistration 上注册。如果使用虚拟线程，这通常是一个启用了虚拟线程的 SimpleAsyncTaskExecutor，从而使 Websockets 支持虚拟线程。

批处理事务管理器 {#批处理事务管理器}

引入了 @BatchTransactionManager 注解，以便更轻松地配置 Spring Batch 以使用自定义事务管理器。更多信息，请参阅更新后的文档。

Base64 资源 {#base64-资源}

现在，可以使用 base64: 前缀将资源加载为 Base64 编码的文本值。这对 SSL 证书等资源非常有用，如下所示：

spring:
  ssl:
    bundle:
      pem:
        mybundle:
          keystore:
            certificate: "base64:LS0tLS1CRUdJTi..."
            private-key: "base64:QmFnIEF0dHJpYn..."

SBOM 执行器端点 {#sbom-执行器端点}

spring-boot-actuator 模块现在包含了一个新的 SBOM 端点。默认情况下，端点将为位于 jar 中的 META-INF/sbom/bom.json 或 META-INF/sbom/application.cdx.json 文件提供服务。

此外，spring-boot-parent-starter POM 中还提供了额外的配置，使 SBOM 插件更易于配置。更多详情，请参阅文档。

文档更新 {#文档更新}

Spring Boot 文档已迁移到 Antora，提供了更多的结构和更好的搜索功能。

使用 SNI 自动配置嵌入式 Web 服务器 SSL {#使用-sni-自动配置嵌入式-web-服务器-ssl}

在使用 SSL/TLS 配置 Tomcat、Netty 或 Undertow 嵌入式 Web 服务器时，现在可以为每个主机名配置具有唯一信任材料（Trust Material）的多个主机名，以支持服务器名称指示（Server Name Indication，SNI）。有关配置选项的更多信息，请参阅更新后的文档。

依赖升级 {#依赖升级}

Spring Boot 3.3.0 迁移到多个 Spring 项目的新版本：

此外，还更新了许多第三方依赖项，其中比较值得注意的有以下几项：

杂项 {#杂项}

除上述更改外，还有许多细微的调整和改进，包括：

当活动云平台（Active Cloud Platform）为空时，设置 spring.config.activate.on-cloud-platform=none 将与之匹配。
新增了在错误响应中包含 path 字段的配置选项。这可由 server.error.include-path 属性控制。默认为 always。
WebFlux DefaultErrorAttributes 现在使用 request.requestPath().value() 来填充 path 错误属性。
添加了 server.tomcat.threads.max-queue-capacity 属性，用于配置 Tomcat Wweb 服务器 Connector 的最大队列大小。
现在，Configuration Processor 会检查 additional-spring-configuration-metadata.json 中是否有多余的 key，如果有，就会失败。
添加了名为 spring.task.execution.pool.shutdown.accept-tasks-after-context-close 的属性，用于控制在 Context Shutdown 被启动后，ThreadPoolTaskExecutor 是否接受任务。
添加了 server.reactive.session.max-sessions 属性，以便在使用 WebFlux 时控制最大 Session 数。
ExecutionContextSerializer Bean 现在会自动应用于 Spring Batch 配置。如果没有提供，则使用 DefaultExecutionContextSerializer。
由四种支持的 Web 服务器（Jetty、Netty、Tomcat 和 Undertow）生成的启动日志信息现在更加一致了。
为 JMS 连接添加了 client-id 和 subscription-durable 属性。
如果一个类实现了多个 servlet 接口（如 Filter 或 Servlet），它现在将针对所有接口进行注册（例如，filter 和 servlet 各注册一次）。
新的响应式 sessions Actuator 端点现在可以返回给定用户名的 session。
Environment 的默认 Profiles 现在包含在 env Atuator 端点的响应中。
新增了一个名为 spring.liquibase.ui-service 的属性，用于指定 Liquibase 使用的默认 UI 服务 logger。
添加了新属性 spring.security.saml2.relyingparty.registration.*.name-id-format 以指定 SAML 注册的 NameID 格式。
添加了新属性 server.mime-mappings，允许配置额外的自定义 MIME 类型映射。
jakarta.inject:jakarta.inject-api 现已包含在 Spring Boot 的 Dependency Management 中。
git-commit-id-maven-plugin 的日期格式已更改为 yyyy-MM-dd'T'HH:mm:ssXXX，以便进行可重现的构建。详见 #39606。
spring-boot-starter-jetty 默认不再包含 jetty-jndi。如果需要 JNDI 支持，请在依赖中添加 org.eclipse.jetty:jetty-jndi。
在 Windows 上，即使应用的依赖数量极多，现在也能使用 mvn spring-boot:run 启动应用程序了。在 3.3.0 之前，由于 classpath 的长度，启动应用时会出现 "The filename or extension is too long"（件名或扩展名太长）的异常。
新属性 spring.data.jdbc.dialect 可用于设置 Spring Data JDBC 的方言。如果未设置，将自动检测方言。
在 CloudFoundryVcapEnvironmentPostProcessor 和 ConfigDataEnvironmentPostProcessor 之间增加更多的间隔。
Cassandra 驱动的坐标从 com.datastax.oss 更改为 org.apache.cassandra。
将新属性 management.observations.long-task-timer.enabled 设置为 false 现在可以防止为每个观测点（Observation）创建 LongTaskTimer。
基础设施角色中的 Bean 现在可自动排除在延迟始化（Lazy Initialization）之外。
Spring Config 现在可在解析属性时使用 Environment 中的 Conversion Service。
将新属性 spring.docker.compose.start.skip 设为 never，以便始终执行 Docker Compose 启动命令。
新增了 spring.graphql.websocket.keep-alive 属性。
如果定义了 ManagedClassNameFilter Bean，JPA 自动配置现在会使用 ManagedClassNameFilter Bean。
新增了 spring.rabbitmq.template.allow-list-patterns 属性。

Spring Boot 3.3.0 中的弃用内容 {#spring-boot-330-中的弃用内容}

ZipkinRestTemplateBuilderCustomizer 和 ZipkinWebClientBuilderCustomizer 改为新的 ZipkinHttpClientBuilderCustomizer。
-Djarmode=layertools extract 改为 -Djarmode=tools extract --layers
-Djarmode=layertools list 改为 -Djarmode=tools list-layers
将 BootJar 和 BootWar task 中的 layers.includeLayerTools 改为 includeTools。
<layers><enabled>...</enabled></layers> 改为 <includeTools>...</includeTools>
用于声明 Actuator 端点的 @ServletEndpoint、@ControllerEndpoint 和 @RestControllerEndpoint 注解已被弃用。取而代之的是，应用应使用 @Endpoint / @ReadOperation / @WriteOperation 模型来贡献端点。参见 #31768。