本章节将详细介绍如何使用 Spring Boot. 它覆盖了诸如构建系统、自动配置和如何运行应用等主题. 我们还介绍一些 Spring Boot 最佳实践. 虽然 Spring Boot 并没有什么特别 (它只是另一个您可以使用的类库) ,但仍然有一些建议可以让您的开发工作变得更加容易.

如果您是刚开始使用 Spring Boot,那么在深入本部分之前,您应该先阅读 入门部分 .

1. 构建系统

强烈推荐您选择一个支持 依赖管理 的构建系统, 您可以使用它将 artifact 发布到 Maven Central 仓库. 我们建议您选择 Maven 或者 Gradle. Spring Boot 虽然也可以使用其它构建系统 (如 Ant) 配合工作,但它们不会得到特别好的支持.

1.1. 依赖管理

每一次 Spring Boot 发行版都提供了一个它所支持的依赖清单. 实际上,您不需要为构建配置提供任何依赖的版本,因为 Spring Boot 已经帮您管理这些了. 当您升级 Spring Boot 时,这些依赖也将以一致的方式进行升级.

如果您觉得有必要,您仍然可以指定一个版本并覆盖 Spring Boot 所推荐的.

该清单包含了全部可以与 Spring Boot 一起使用的 spring 模块以及第三方类库,可作为 标准依赖清单 (spring-boot-dependencies) ,并且可以与 Maven 和 Gradle 一起使用.

Spring Boot 的每一次发行都会基于一个 Spring Framework 版本,因此我们强烈建议您不要指定它的版本.

要了解有关将 Spring Boot 与 Maven 结合使用的信息,请参阅 Spring Boot 的 Maven 插件的文档

1.2. Gradle

要了解如何使用 Spring Boot 和 Gradle,请参阅 Spring Boot 的 Gradle 插件文档:

1.3. Ant

可以使用 Apache Ant+Ivy 构建 Spring Boot 项目. spring-boot-antlib “AntLib” 模块也可以帮助 Ant 创建可执行 jar 文件.

要声明依赖,可参考以下一个典型的 ivy.xml 文件内容:

<ivy-module version="2.0">
    <info organisation="org.springframework.boot" module="spring-boot-sample-ant" />
    <configurations>
        <conf name="compile" description="everything needed to compile this module" />
        <conf name="runtime" extends="compile" description="everything needed to run this module" />
    </configurations>
    <dependencies>
        <dependency org="org.springframework.boot" name="spring-boot-starter"
            rev="${spring-boot.version}" conf="compile" />
    </dependencies>
</ivy-module>

一个典型的 build.xml 大概是这样:

<project
    xmlns:ivy="antlib:org.apache.ivy.ant"
    xmlns:spring-boot="antlib:org.springframework.boot.ant"
    name="myapp" default="build">

    <property name="spring-boot.version" value="2.6.11" />

    <target name="resolve" description="--> retrieve dependencies with ivy">
        <ivy:retrieve pattern="lib/[conf]/[artifact]-[type]-[revision].[ext]" />
    </target>

    <target name="classpaths" depends="resolve">
        <path id="compile.classpath">
            <fileset dir="lib/compile" includes="*.jar" />
        </path>
    </target>

    <target name="init" depends="classpaths">
        <mkdir dir="build/classes" />
    </target>

    <target name="compile" depends="init" description="compile">
        <javac srcdir="src/main/java" destdir="build/classes" classpathref="compile.classpath" />
    </target>

    <target name="build" depends="compile">
        <spring-boot:exejar destfile="build/myapp.jar" classes="build/classes">
            <spring-boot:lib>
                <fileset dir="lib/runtime" />
            </spring-boot:lib>
        </spring-boot:exejar>
    </target>
</project>
如果您不想使用 spring-boot-antlib 模块,请参阅 howto.html “How-to”.

1.4. Starters

Starter 是一组惯例依赖描述资源, 可以包含在应用程序中. 从 starter 中,您可以获得所需的所有 Spring 和相关技术的一站式支持,无须通过示例代码和复制粘贴来获取依赖. 比如,如果您要使用 Spring 和 JPA 进行数据库访问,那么只需要在项目中包含 spring-boot-starter-data-jpa 依赖即可.

starter 包含了许多依赖可以使您的项目快速启动和运行,并且支持的依赖的可传递性.

命名含义

官方 的所有 starter 都遵循类似的命名规则: spring-boot-starter-* ,其中 * 是特定类型的应用. 这个命名结构可以帮助您找到您需要的 starter. 许多 IDE 中 Maven 集成允许您按名称搜索依赖. 例如,安装了 Eclipse 或者 STS 插件后,您可以简单地在 POM 编辑器中按下 ctrl-space 并输入 spring-boot-starter 来获取完整的列表.

正如 “创建自己的 starter” 章节所述,第三方的 starter 命名不应该以 spring-boot 开头, 因为它是官方 Spring Boot artifacts 所保留的规则. 例如,有一个第三方 starter 项目叫做 thirdpartyproject,它通常会命名为 thirdpartyproject-spring-boot-starter.

Spring Boot 在 org.springframework.boot 组下提供了以下 starter:

Table 1. Spring Boot 应用类 starters
Name Description

spring-boot-starter

核心的 starter, 包含自动配置,日志和 YAML

spring-boot-starter-activemq

使用 Apache ActiveMQ 传递 JMS 消息的 Starter

spring-boot-starter-amqp

使用 Spring AMQP 和 Rabbit MQ Starter

spring-boot-starter-aop

使用 Spring AOP 和 AspectJ 的面向切面编程的 Starter

spring-boot-starter-artemis

使用 Apache Artemis 传递 JMS 消息的 Starter

spring-boot-starter-batch

使用 Spring Batch 的 Starter

spring-boot-starter-cache

使用 Spring Framework 的缓存支持的 Starter

spring-boot-starter-data-cassandra

使用 Cassandra distributed database 和 Spring Data Cassandra 的 Starter

spring-boot-starter-data-cassandra-reactive

使用 Cassandra distributed 和 Spring Data Cassandra Reactive Starter

spring-boot-starter-data-couchbase

使用 Couchbase document-oriented database 和 Spring Data Couchbase Starter

spring-boot-starter-data-couchbase-reactive

使用 Couchbase document-oriented database 和 Spring Data Couchbase Reactive Starter

spring-boot-starter-data-elasticsearch

使用 Elasticsearch 搜索分析引擎和 Spring Data Elasticsearch 的 Starter

spring-boot-starter-data-jdbc

使用 Spring Data JDBC 的 Starter

spring-boot-starter-data-jpa

使用 Hibernate 的 Spring Data JPA 的 Starter

spring-boot-starter-data-ldap

使用 Spring Data LDAP 的 Starter

spring-boot-starter-data-mongodb

使用 MongoDB 文档数据库 和 Spring Data MongoDB 的 Starter

spring-boot-starter-data-mongodb-reactive

使用 MongoDB 文档数据库 和 Spring Data MongoDB Reactive Starter

spring-boot-starter-data-neo4j

使用 Spring Data Neo4j 支持 Neo4j graph database 的 Starter

spring-boot-starter-data-r2dbc

使用 Spring Data R2DBC 的 Starter

spring-boot-starter-data-redis

使用 Spring Data Redis 和 Lettuce 客户端支持 Redis key-value 数据存储 的 Starter

spring-boot-starter-data-redis-reactive

使用 Spring Data Redis reactive 和 Lettuce 客户端支持 Redis key-value 数据存储 的 Starter

spring-boot-starter-data-rest

使用 Spring Data REST 将 Spring Data 存储库以 REST 形式暴露的 Starter

spring-boot-starter-freemarker

使用 FreeMarker 视图构建 MVC web 应用程序

spring-boot-starter-groovy-templates

使用 Groovy Templates 视图构建 MVC web 应用程序

spring-boot-starter-hateoas

使用 Spring MVC 和 Spring HATEOAS 构建超媒体 RESTful web 应用程序

spring-boot-starter-integration

使用 Spring Integration 的 Starter

spring-boot-starter-jdbc

使用 HikariCP 连接池的 JDBC 的 Starter

spring-boot-starter-jersey

使用 JAX-RS 和 Jersey 构建 RESTful web 应用程序. spring-boot-starter-web 的替代方法.

spring-boot-starter-jooq

使用 jOOQ 访问 SQL 数据库. spring-boot-starter-data-jpa 或 spring-boot-starter-jdbc 的替代方法.

spring-boot-starter-json

json 读写的 Starter

spring-boot-starter-jta-atomikos

使用 Atomikos 的 JTA transactions 的 Starter

spring-boot-starter-mail

使用 Java Mail 和 Spring Framework 邮件发送的 Starter

spring-boot-starter-mustache

使用 Mustache 视图构建 web 应用程序的 Starter

spring-boot-starter-oauth2-client

使用 Spring Security 的 OAuth2/OpenID Connect 客户端功能的 Starter

spring-boot-starter-oauth2-resource-server

使用 Spring Security 的 OAuth2 资源服务器功能的 Starter

spring-boot-starter-quartz

使用 Quartz scheduler 的 Starter

spring-boot-starter-rsocket

构建 RSocket 客户端 和 服务端的 Starter.

spring-boot-starter-security

使用 Spring Security 的 Starter

spring-boot-starter-test

使用 JUnit Jupiter, Hamcrest 和 Mockito 等库测试 Spring Boot 应用程序的 Starter

spring-boot-starter-thymeleaf

使用 Thymeleaf 视图构建 MVC web 应用程序

spring-boot-starter-validation

使用 Hibernate Validator 进行 Java Bean Validation 的 Starter

spring-boot-starter-web

使用 Spring MVC 构建 web (包括 RESTful) 应用程序. 使用 Tomcat 作为默认的嵌入式容器.

spring-boot-starter-web-services

使用 Spring Web Services 的 Starter

spring-boot-starter-webflux

使用 Spring Framework 对 Reactive Web 的支持来构建 WebFlux 应用程序的 Starter

spring-boot-starter-websocket

使用 Spring Framework 对 WebSocket 的支持来构建 WebSocket 应用程序的 Starter

除了应用程序的 starter 外,以下 starter 可用于添加 生产就绪 特性:

Table 2. Spring Boot 生产类 starters
Name Description

spring-boot-starter-actuator

使用 Spring Boot 的 Actuator 的 Starter,该启动器提供了生产就绪功能,可帮助您监视和管理应用程序

最后,Spring Boot 还包含以下 starter,如果您想要排除或切换其他特定技术,可以使用以下 starter:

Table 3. Spring Boot 技术类 starters
Name Description

spring-boot-starter-jetty

使用 Jetty 作为嵌入式容器. spring-boot-starter-tomcat 的替代方法

spring-boot-starter-log4j2

使用 Log4j2 来记录日志. spring-boot-starter-logging 的替代方法

spring-boot-starter-logging

使用 Logback 来记录日志. 默认的日志 starter

spring-boot-starter-reactor-netty

使用 Reactor Netty 作为嵌入的 reactive HTTP server.

spring-boot-starter-tomcat

使用 Tomcat 作为嵌入 servlet 容器. spring-boot-starter-web 使用此作为默认 Servlet 容器

spring-boot-starter-undertow

使用 Undertow 作为嵌入 servlet 容器. spring-boot-starter-tomcat 的替代方法

要了解如何交换技术方面的信息,请参阅 swapping web server 和 logging system.

有关其它社区贡献的 starter 列表,请参阅 GitHub 上的 spring-boot-starters 模块中的 README file 文件.

2. 组织你的代码

Spring Boot 不需要任何特定的代码布局,但是有一些最佳实践是很有用的.

2.1. 使用 “default” 包

当一个类没有 package 声明时,它就被认为是在 default 包中. 通常不鼓励使用 default 包, 应该避免使用. 对于使用 @ComponentScan、@ConfigurationPropertiesScan ,@EntityScan 或者 @SpringBootApplication 注解的 Spring Boot 应用,这样可能会导致特殊问题发生, 因为每一个 jar 中的每一个类将会被读取到.

我们建议您使用 Java 推荐的包命名约定,并使用域名的反向形式命名 (例如 com.example.project) .

2.2. 定位主类

我们通常建议您将主类放在其它类之上的包（根包）中, @SpringBootApplication 注解 注解通常放在主类上,它隐式定义了某些项目的包扫描的起点. 例如,如果您在编写一个 JPA 应用程序,则被 @SpringBootApplication 注解的类所属的包将被用于搜索标记有 @Entity 注解的类.

使用根包还允许组件扫描仅应用于您的项目.

如果您不想使用 @SpringBootApplication, 则可以通过导入的 @EnableAutoConfiguration 和 @ComponentScan 注解来定义该行为,因此也可以使用它们来替代.

以下是一个经典的包结构:

com
 +- example
     +- myapplication
         +- MyApplication.java
         |
         +- customer
         |   +- Customer.java
         |   +- CustomerController.java
         |   +- CustomerService.java
         |   +- CustomerRepository.java
         |
         +- order
             +- Order.java
             +- OrderController.java
             +- OrderService.java
             +- OrderRepository.java

MyApplication.java 文件声明了 main 方法,附带了 @SpringBootApplication 注解.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}

3. 配置类

Spring Boot 支持基于 Java 的配置. 虽然可以在 SpringApplication 中使用 XML 配置源数据,但我们通常建议主配置源为 @Configuration 类. 通常,一个很好的选择是将定义了 main 方法的类作为 @Configuration.

许多 Spring 的 XML 配置示例已经在 Internet 上发布了. 如果可能的话, 您无论如何都应该尝试着使用等效的基于 Java 的配置方式,搜索 Enable* 注解可以帮到您不少忙.

3.1. 导入额外的配置类

你不需要把所有的 @Configuration 放在一个类中. @Import 注解可用于导入其他配置类. 或者,您可以使用 @ComponentScan 自动扫描所有的 Spring 组件,包括 @Configuration 类.

3.2. 导入 XML 配置

如果您一定要使用基于 XML 的配置,我们仍建议您使用 @Configuration 类. 您可以使用 @ImportResource 注解来加载 XML 配置文件.

4. 自动配置

Spring Boot 自动配置尝试根据您添加的 jar 依赖自动配置 Spring 应用. 例如,如果 classpath 下存在 HSQLDB,并且您没有手动配置任何数据库连接 bean,那么 Spring Boot 将自动配置一个内存数据库.

您需要通过将 @EnableAutoConfiguration 或者 @SpringBootApplication 注解添加到其中一个 @Configuration 类之上以启用自动配置.

您应该只添加一个 @SpringBootApplication 或 @EnableAutoConfiguration 注解. 我们通常建议您仅将一个或另一个添加到您的主要 @Configuration 类中.

4.1. 平滑替换自动配置

自动配置是非侵入的,您可以随时定义自己的配置来代替自动配置的特定部分. 例如,如果您添加了自己的 DataSource bean, 默认的嵌入式数据库支持将不会自动配置.

如果您需要了解当前正在应用的自动配置,以及为什么使用,请使用 --debug 开关启动应用. 这样做可以为核心 logger 启用调试日志,并记录到控制台.

4.2. 禁用指定的自动配置类

如果您发现正在使用不需要的自动配置类,可以通过使用 @SpringBootApplication 的 exclude 属性来禁用它们:

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class MyApplication {

}

如果类不在 classpath 下,您可以使用注解的 excludeName 属性并指定完全类名.

如果您更喜欢使用 @EnableAutoConfiguration 而不是 @SpringBootApplication ,则还可以使用 exclude 和 excludeName.

最后,您还可以通过 spring.autoconfigure.exclude 属性控制要排除的自动配置类列表.

您可以同时使用注解和 property 定义 exclusions
尽管自动配置类是 public 的,但被认为是 public API 的唯一方面是可用于禁用自动配置的类的名称. 这些类的实际内容 (例如嵌套配置类或 Bean 方法) 仅供内部使用,我们不建议直接使用它们. ,

5. Spring Bean 与依赖注入

您可以自由使用任何标准的 Spring Framework 技术来定义您的 bean 以及它们的依赖注入. 我们通常建议使用构造器注入，并使用 @ComponentScan 来查找 bean。

如果您按照上述的建议 (将应用类放在根包中) 来组织代码,则可以添加无参的 @ComponentScan 或使用隐式包含它的 @SpringBootApplication 注解. 所有应用组件 (@Component、@Service、@Repository、@Controller 等) 将自动注册为 Spring Bean.

以下是一个 @Service Bean, 其使用构造器注入的方式获取一个必需的 RiskAssessor bean.

import org.springframework.stereotype.Service;

@Service
public class MyAccountService implements AccountService {

    private final RiskAssessor riskAssessor;

    public MyAccountService(RiskAssessor riskAssessor) {
        this.riskAssessor = riskAssessor;
    }

    // ...

}

如果一个 bean 有多个构造函数，你需要用 @Autowired 标记你希望 Spring 使用的那个：

import java.io.PrintStream;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class MyAccountService implements AccountService {

    private final RiskAssessor riskAssessor;

    private final PrintStream out;

    @Autowired
    public MyAccountService(RiskAssessor riskAssessor) {
        this.riskAssessor = riskAssessor;
        this.out = System.out;
    }

    public MyAccountService(RiskAssessor riskAssessor, PrintStream out) {
        this.riskAssessor = riskAssessor;
        this.out = out;
    }

    // ...

}
请注意,构造器注入允许 riskAssessor 字段被修饰为 final,这表示以后它不能被更改.

6. 使用 @SpringBootApplication 注解

很多 Spring Boot 开发者总是希望他们的应用程序使用自动配置、组件扫描并能够在他们的 "application class" 上定义额外的配置. 可以使用单个 @SpringBootApplication 注解来启用这三个功能，即：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

// Same as @SpringBootConfiguration @EnableAutoConfiguration @ComponentScan
@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}
@SpringBootApplication 还提供别名以自定义 @EnableAutoConfiguration 和 @ComponentScan 的属性.

这些功能都不是强制性的,您可以选择单个注解来启用他特定的特性. 例如,您可能不想在应用程序中使用组件扫描或配置属性扫描：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.Import;

@SpringBootConfiguration(proxyBeanMethods = false)
@EnableAutoConfiguration
@Import({ SomeConfiguration.class, AnotherConfiguration.class })
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}

在此示例中,除了程序没有自动检测到 @Component 注解的类和 @ConfigurationProperties 注解的类和显式导入了用户定义的 Bean 之外, MyApplication 就像其他任何 Spring Boot 应用程序一样 (请参阅 @Import) .

7. 运行您的应用

将应用程序打包成 jar 可执行文件并使用嵌入式 HTTP 服务器的最大优点之一就是您可以像运行其他应用程序一样运行应用程序. 调试 Spring Boot 应用程序也是很简单,您不需要任何特殊的 IDE 插件或者扩展.

本章节仅涵盖基于 jar 的打包方式,如果您选择将应用打包为　war　文件,则应该参考您的服务器和　IDE　文档.

7.1. 使用 IDE 运行

您可以使用 IDE 运行 Spring Boot 应用, 就像运行一个简单的 Java 应用程序一样,但是首先您需要导入项目, 导入步骤取决于您的 IDE 和构建系统. 大多数 IDE 可以直接导入 Maven 项目, 例如 Eclipse 用户可以从 File 菜单中选择 Import…​ → Existing Maven Projects .

如果您无法将项目直接导入到 IDE 中, 则可以使用构建插件生成 IDE 元数据 (metadata). Maven 包含了 Eclipse 和 IDEA 的插件, Gradle 也为 各种 IDE 提供了插件.

如果您不小心运行了两次 web 应用,您将看到一个 “Port already in use” (端口已经被使用) 错误. STS 用户可以使用 Relaunch 按钮运行以确保现有的任何实例都已关闭,而不是使用 Run 按钮.

7.2. 作为打包应用运行

如果您使用 Spring Boot Maven 或者 Gradle 插件创建可执行 jar,可以使用 java -jar 命令运行应用. 例如:

$ java -jar target/myapplication-0.0.1-SNAPSHOT.jar

也可以在运行打包应用程序时开启远程调试支持. 该功能允许您将调试器附加到打包的应用中:

$ java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n \
       -jar target/myapplication-0.0.1-SNAPSHOT.jar

7.3. 使用 Maven 插件

Spring Boot Maven 插件包含一个可用于快速编译和运行应用程序的 run goal. 应用程序以快速形式运行,就像在 IDE 中一样. 以下示例展示了运行 Spring Boot 应用程序的典型 Maven 命令:

$ mvn spring-boot:run

您可能还想使用 MAVEN_OPTS 操作系统环境变量,如下例所示:

$ export MAVEN_OPTS=-Xmx1024m

7.4. 使用 Gradle 插件

Spring Boot Gradle 插件包含一个 bootRun 任务,可用于以快速形式运行应用程序. 每当应用 org.springframework.boot 和 java 插件时都会添加 bootRun 任务:

$ gradle bootRun

您可能还想使用 JAVA_OPTS 操作系统环境变量:

$ export JAVA_OPTS=-Xmx1024m

7.5. 热交换

由于 Spring Boot 应用程序只是普通的 Java 应用程序, 因此 JVM 热插拔是可以开箱即用. JVM 热插拔在可替换字节码方面有所限制. 想要更完整的解决方案,可以使用 JRebel.

spring-boot-devtools 模块包含了对快速重新启动应用程序的支持. 有关详细信息,请参阅本章后面的 热插拔的 How-to 部分.

8. 开发者工具

Spring Boot 包含了一套工具,可以使应用开发体验更好. spring-boot-devtools 模块可包含在任何项目中,以提供额外的开发时 (development-time) 功能. 要启用 devtools 支持,只需要将模块依赖添加到您的构建配置中即可:

Maven
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>
Gradle
dependencies {
    developmentOnly("org.springframework.boot:spring-boot-devtools")
}
Devtools 可能会导致类加载问题，尤其是在多模块项目中。 诊断类加载问题 解释了如何诊断和解决它们.
当运行完全打包的应用时,开发者工具将会自动禁用. 如果您的应用使用了 java -jar 方式或者特殊的类加载器启动, 那么它会被认为是一个生产级别应用. 你可以通过使用 spring.devtools.restart.enabled 系统属性来控制这种行为, 不管用什么类加载器来启动你的应用程序，要启用 devtools ， 可以设置 -Dspring.devtools.restart.enabled=true 系统属性. 在生产环境中运行 devtools 会带来安全风险的， 绝对不能这样做,要禁用 devtools , 请排除依赖关系或设置 -Dspring.devtools.restart.enabled = false 系统属性.
将 Maven 的依赖标记为 optional 或者在 Gradle 中使用 developmentOnly 是防止您的项目被其他模块使用时 devtools 被应用到其它模块的最佳方法.
重新打包的归档文件默认情况下不包含 devtools. 如果要使用某些 远程 devtools 功能, 你需要禁用 excludeDevtools 构建属性以把 devtools 包含进来. 使用 Maven 插件时,请将 excludeDevtools 属性设置为 false. 使用 Gradle 插件时, 将任务的类路径配置为包括 "developmentOnly" 配置.

8.1. 诊断类加载问题

如 重启 (Restart) 与重载 (Reload) 章节描述, 重启功能是通过使用两个类加载器实现的。对于大多数应用程序，这种方法效果很好. 但是，它有时会导致类加载问题，尤其是在多模块项目中。

要诊断类加载问题是否确实是由 devtools 及其两个类加载器引起的，请 尝试禁用重新启动。 如果这解决了您的问题，请 自定义重新启动类加载器 以包含您的整个项目。

8.2. Property 默认值

Spring Boot 所支持的一些库使用了缓存来提高性能. 例如, 模板引擎 将缓存编译后的模板,以避免重复解析模板文件. 此外,Spring MVC 可以在服务静态资源时添加 HTTP 缓存头.

虽然缓存在生产中非常有用, 但它在开发过程可能会产生相反的效果, 让您不能及时看到刚才在应用中作出的更改. 因此,spring-boot-devtools 将默认禁用这些缓存选项.

一般是在 application.properties 文件中设置缓存选项. 例如,Thymeleaf 提供了 spring.thymeleaf.cache 属性. 您不需要手动设置这些属性,spring-boot-devtools 会自动应用合适的开发时 (development-time) 配置.

下表列出了所有应用的属性:

Name Default Value

server.error.include-binding-errors

always

server.error.include-message

always

server.error.include-stacktrace

always

server.servlet.jsp.init-parameters.development

true

server.servlet.session.persistent

true

spring.freemarker.cache

false

spring.groovy.template.cache

false

spring.h2.console.enabled

true

spring.mustache.cache

false

spring.mvc.log-resolved-exception

true

spring.reactor.debug

true

spring.template.provider.cache

false

spring.thymeleaf.cache

false

spring.web.resources.cache.period

0

spring.web.resources.chain.cache

false
如果您不希望应用默认属性,则可以在 application.properties 中将 spring.devtools.add-properties 设置为 false.

由于在开发 Spring MVC 和 Spring WebFlux 应用程序时需要有关 Web 请求的更多信息,因此 developer tools 建议您为 web 日志记录组启用 DEBUG 日志记录. 这将为您提供有关传入请求,正在处理的处理程序,响应结果等的信息. 如果您希望记录所有请求详细信息 (包括潜在的敏感信息) , 则可以打开 spring.mvc.log-request-details 或 spring.codec.log-request-details 配置属性.

8.3. 自动重启

使用 spring-boot-devtools 的应用在 classpath 下的文件发生更改时会自动重启. 这对于使用 IDE 工作而言可能是一个非常棒的功能,因为它为代码变更提供了非常快的反馈. 默认情况下,将监视 classpath 指向的所有目录. 请注意,某些资源 (如静态资源和视图模板) 不需要重启应用.

触发重启

由于 DevTools 监视 classpath 资源, 触发重启的唯一方式是更新 classpath. 无论您使用的是 IDE 还是其中一个构建插件，都必须重新编译修改后的文件以触发重新启动。使 classpath 更新的方式取决于您使用的 IDE:

  • 在 Eclipse 中,保存修改的文件将更新 classpath,从而触发重启.

  • 在 IntelliJ IDEA 中,构建项目 (Build +→+ Build Project) 将产生相同的效果.

  • 如果使用构建插件,Maven 运行 mvn compile 或 Gradle 运行 gradle build 将触发重启.

只要 forking 设置为 enabled,您可以使用受支持的构建工具 (如 Maven 或 Gradle) 来重启应用,因为 DevTools 需要隔离应用类加载器才能正常运行. 默认情况下,当在 classpath 下检测到 DevTools 时, Gradle 和 Maven 会这么做.
自动重启功能与 LiveReload (实时重载) 一起使用效果更棒. 阅读 LiveReload 章节以获取更多信息. 如果您使用 JRebel, 自动重启将会被禁用,以支持动态类重载,但其他 devtools 功能 (如 LiveReload 和 property 覆盖) 仍然可以使用.
DevTools 依赖于应用上下文的关闭钩子,以在重启期间关闭自己. 如果禁用了关闭钩子 (SpringApplication.setRegisterShutdownHook(false) ) ,它将不能正常工作.
DevTools 需要自定义 ApplicationContext 使用到的 ResourceLoader. 如果您的应用已经提供了一个,它将被包装起来,因为不支持在 ApplicationContext 上直接覆盖 getResource 方法.
使用 AspectJ 编织时不支持自动重启。
重启 (Restart) 与重载 (Reload)

Spring Boot 通过使用两个类加载器来提供了重启技术. 不改变的类 (例如,第三方 jar) 被加载到 base 类加载器中. 经常处于开发状态的类被加载到 restart 类加载器中. 当应用重启时,restart 类加载器将被丢弃,并重新创建一个新的. 这种方式意味着应用重启比冷启动要快得多,因为省去 base 类加载器的处理步骤,并且可以直接使用.

如果您觉得重启还不够快,或者遇到类加载问题,您可以考虑如 ZeroTurnaround 的 JRebel 等工具. 他们是通过在加载类时重写类来加快重新加载.

8.3.1. 条件评估变更日志

默认情况下,每次应用重启时,都会记录显示条件评估增量的报告. 该报告展示了在您进行更改 (如添加或删除 bean 以及设置配置属性) 时对应用自动配置所作出的更改.

要禁用报告的日志记录,请设置以下属性:

spring:
  devtools:
    restart:
      log-condition-evaluation-delta: false

8.3.2. 排除资源

某些资源在更改时不一定需要触发重启. 例如,Thymeleaf 模板可以实时编辑. 默认情况下,更改 /META-INF/maven, /META-INF/resources, /resources, /static, /public, 或者 /templates 不会触发重启, 但会触发 live reload. 如果您想自定义排除项,可以使用 spring.devtools.restart.exclude 属性. 例如,仅排除 /static 和 /public,您可以设置以下内容:

spring:
  devtools:
    restart:
      exclude: "static/**,public/**"
如果要保留这些默认值并添加其他排除项 ,请改用 spring.devtools.restart.additional-exclude 属性.

8.3.3. 监视附加路径

如果您想在对不在 classpath 下的文件进行修改时重启或重载应用,请使用 spring.devtools.restart.additional-paths 属性来配置监视其他路径的更改情况. 您可以使用 上述 的 spring.devtools.restart.exclude 属性来控制附加路径下的文件被修改时是否触发重启或只是 live reload.

8.3.4. 禁用重启

您如果不想使用重启功能,可以使用 spring.devtools.restart.enabled 属性来禁用它. 一般情况下,您可以在 application.properties 中设置此属性 (重启类加载器仍将被初始化,但不会监视文件更改) .

如果您需要完全禁用重启支持 (例如,可能它不适用于某些类库) ,您需要在调用 SpringApplication.run(…​) 之前将 System 属性 spring.devtools.restart.enabled System 设置为 false. 例如:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        System.setProperty("spring.devtools.restart.enabled", "false");
        SpringApplication.run(MyApplication.class, args);
    }

}

8.3.5. 使用触发文件

如果您使用 IDE 进行开发,并且时时刻刻在编译更改的文件,或许您只是希望在特定的时间内触发重启. 为此,您可以使用 “trigger file” (触发文件),这是一个特殊文件,您想要触发重启检查时,必须修改它.

更改文件只会触发检查,只有在 Devtools 检查到它需要做某些操作时才会触发重启,可以手动更新触发文件,也可以通过 IDE 插件更新.

要使用触发文件,请设置 spring.devtools.restart.trigger-file 属性指向触发文件的路径.

例如,如果您的项目具有以下结构
src
+- main
   +- resources
      +- .reloadtrigger

然后,您的 trigger-file 属性将是:

spring:
  devtools:
    restart:
      trigger-file: ".reloadtrigger"

现在仅在更新 src/main/resources/.reloadtrigger 时才发生重启.

您也许想将 spring.devtools.restart.trigger-file 设置成一个 全局配置,以使得所有的项目都能应用此方式.

某些 IDE 具有使您不必手动更新触发器文件的功能. Spring Tools for Eclipse 的 Spring 工具和 IntelliJ IDEA (Ultimate Edition) 都具有这种支持. 使用 Spring Tools, 您可以从控制台视图使用 "重新加载" 按钮 (只要您的 trigger-file 名为 .reloadtrigger) . 对于 IntelliJ,您可以按照其 文档中的说明 进行操作.

8.3.6. 自定义重启类加载器

正如之前的 重启 (Restart) 与重载 (Reload) 部分所述,重启功能是通过使用两个类加载器来实现的. 如果出现了问题，您可能需要自定义由哪个类加载器加载的内容。

默认情况下,IDE 中任何打开的项目将使用 “restart” 类加载器加载,任何常规的 .jar 文件将使用 “base” 类加载器加载. 如果您使用 mvn spring-boot:run 或 gradle bootRun 也是如此：包含您的 @SpringBootApplication 的项目使用 “restart” 类加载器加载，其他所有内容都使用 “base” 类加载器。

您可以通过创建 META-INF/spring-devtools.properties 文件来指示 Spring Boot 使用不同的类加载器加载项目的一部分。

spring-devtools.properties 文件可以包含以 restart.exclude. 和 restart.include. 为前缀的属性. include 元素是加载到 “restart” 类加载器的项, exclude 元素是加载到 “base” 类加载器的项. 属性值是一个应用到 classpath 的正则表达式. 例如:

restart:
  exclude:
    companycommonlibs: "/mycorp-common-[\\w\\d-\\.]+\\.jar"
  include:
    projectcommon: "/mycorp-myproj-[\\w\\d-\\.]+\\.jar"
所有属性键名必须是唯一的. 只要有一个属性以 restart.include 或 restart.exclude 开头,才会被考虑.
classpath 下的所有 META-INF/spring-devtools.properties 文件将被加载,您可以将它们打包进工程或者类库中为项目所用.

8.3.7. 已知限制

重新启动功能对使用标准 ObjectInputStream 反序列化的对象无效. 您如果需要反序列化数据,可能需要使用 Spring 的 ConfigurableObjectInputStream 配合 Thread.currentThread().getContextClassLoader().

遗憾的是,一些第三方类库在没有考虑上下文类加载器的情况下使用了反序列化. 您如果遇到此问题,需要向原作者提交修复请求.

8.4. LiveReload

spring-boot-devtools 模块包括了一个内嵌 LiveReload 服务器,它可在资源发生更改时触发浏览器刷新. 您可以从 livereload.com 上免费获取 Chrome、Firefox 和 Safari 平台下对应的 LiveReload 浏览器扩展程序.

如果您不想在应用运行时启动 LiveReload 服务器,可以将 spring.devtools.livereload.enabled 属性设置为 false.

您一次只能运行一个 LiveReload 服务器. 在启动应用之前,请确保没有其他 LiveReload 服务器正在运行. 如果在 IDE 中启动了多个应用,那么只有第一个应用的 LiveReload 生效.
要在文件更改时触发 LiveReload,必须启用 自动重启.

8.5. 全局设置

您可以通过将以下任何文件添加到 $HOME/.config/spring-boot 目录来配置全局 devtools 设置:

  1. spring-boot-devtools.properties

  2. spring-boot-devtools.yaml

  3. spring-boot-devtools.yml

在此文件中添加的任何属性将应用到您的计算机上所有使用了 devtools 的 Spring Boot 应用程序. 例如,始终使用 触发文件 来配置重启功能,您需要将以下属性添加到您的 spring-boot-devtools 文件中:

spring:
  devtools:
    restart:
      trigger-file: ".reloadtrigger"

默认情况下，$HOME 是用户主目录，如果需要自定义此位置，可以设置 SPRING_DEVTOOLS_HOME 环境变量或者 spring.devtools.home 系统属性。

如果在 $HOME/.config/spring-boot 中找不到 devtools 配置文件,则在 $HOME 目录的根目录中搜索是否存在 .spring-boot-devtools.properties 文件. 这使您可以与不支持 $HOME/.config/spring-boot 位置的较旧版本的 Spring Boot 上的应用程序共享 devtools 全局配置.

Profiles 不支持 devtools properties/yaml 文件.

任何在 .spring-boot-devtools.properties 中激活的 profiles 不会影响 指定 profile 的配置文件 的加载. 不支持在 YAML 和 Properties 文件中的配置特定于配置文件的文件名(格式为 spring-boot-devtools-<profile>.properties) 和 spring.config.activate.on-profile 子文档.

8.5.1. 配置文件系统监视器

FileSystemWatcher 的工作方式是按一定的时间间隔轮询更改类,然后等待定义好的一段时间以确保没有更多更改. 由于 Spring Boot 完全依赖 IDE 来编译文件并将其复制到 Spring Boot 可以读取文件的位置,因此您可能会发现,有时 devtools 重新启动应用程序时某些更改未反映出来. 如果您经常观察到此类问题,请尝试将 spring.devtools.restart.poll-interval 和 spring.devtools.restart.quiet-period 参数增加到适合您开发环境的值:

spring:
  devtools:
    restart:
      poll-interval: "2s"
      quiet-period: "1s"

现在每 2 秒轮询一次受监视的 classpath 目录是否有更改,并保持 1 秒钟的静默时间以确保没有其他类更改.

8.6. 远程应用

Spring Boot developer tools 不局限于本地开发. 在远程运行应用时也可以使用许多功能. 远程支持功能是可选的.，因为启用它可能会带来安全风险。只有在受信任的网络上运行或使用 SSL 保护时,才应启用它. 如果这两个选项都不满足,则不应使用 DevTools 的远程支持. 您永远不要在生产部署上启用支持.

如果要启用,您需要确保在重新打包的归档文件中包含 devtools:

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludeDevtools>false</excludeDevtools>
            </configuration>
        </plugin>
    </plugins>
</build>

之后您需要设置一个 spring.devtools.remote.secret 属性,像任何重要的密码或机密一样,该值应唯一且强壮,以免被猜测或强行使用.

远程 devtools 支持分为两部分: 接受连接的服务器端端点和在 IDE 中运行的客户端应用程序. 设置 spring.devtools.remote.secret 属性后,将自动启用服务器组件. 客户端组件必须手动启动.

Spring WebFlux 应用程序不支持远程开发工具。

8.6.1. 运行远程客户端应用

假设远程客户端应用运行在 IDE 中. 您需要在与要连接的远程项目相同的 classpath 下运行 org.springframework.boot.devtools.RemoteSpringApplication . 把要连接的远程 URL 作为必须参数传入.

例如,如果您使用的是 Eclipse 或 STS,并且有一个名为 my-app 的项目已部署到了 Cloud Foundry,则可以执行以下操作:

  • 在 Run 菜单中选择选择 Run Configurations…​.

  • 创建一个新的 Java Application “launch configuration”.

  • 浏览 my-app 项目.

  • 使用 org.springframework.boot.devtools.RemoteSpringApplication 作为主类.

  • 将 https://myapp.cfapps.io 作为 Program arguments (或者任何远程 URL) 传入.

运行的远程客户端将如下所示:

  .   ____          _                                              __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _          ___               _      \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` |        | _ \___ _ __  ___| |_ ___ \ \ \ \
 \\/  ___)| |_)| | | | | || (_| []::::::[]   / -_) '  \/ _ \  _/ -_) ) ) ) )
  '  |____| .__|_| |_|_| |_\__, |        |_|_\___|_|_|_\___/\__\___|/ / / /
 =========|_|==============|___/===================================/_/_/_/
 :: Spring Boot Remote :: 2.6.11

2015-06-10 18:25:06.632  INFO 14938 --- [           main] o.s.b.devtools.RemoteSpringApplication   : Starting RemoteSpringApplication on pwmbp with PID 14938 (/Users/pwebb/projects/spring-boot/code/spring-boot-project/spring-boot-devtools/target/classes started by pwebb in /Users/pwebb/projects/spring-boot/code)
2015-06-10 18:25:06.671  INFO 14938 --- [           main] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@2a17b7b6: startup date [Wed Jun 10 18:25:06 PDT 2015]; root of context hierarchy
2015-06-10 18:25:07.043  WARN 14938 --- [           main] o.s.b.d.r.c.RemoteClientConfiguration    : The connection to http://localhost:8080 is insecure. You should use a URL starting with 'https://'.
2015-06-10 18:25:07.074  INFO 14938 --- [           main] o.s.b.d.a.OptionalLiveReloadServer       : LiveReload server is running on port 35729
2015-06-10 18:25:07.130  INFO 14938 --- [           main] o.s.b.devtools.RemoteSpringApplication   : Started RemoteSpringApplication in 0.74 seconds (JVM running for 1.105)
由于远程客户端与实际应用使用的是同一个 classpath, 因此可以直接读取应用的 properties. 这也是 spring.devtools.remote.secret 属性为什么能被读取和传递给服务器进行身份验证的原因.
建议使用 https:// 作为连接协议,以便加密传输并防止密码被拦截.
如果您需要通过代理来访问远程应用,请配置 spring.devtools.remote.proxy.host 和 spring.devtools.remote.proxy.port 属性.

8.6.2. 远程更新

远程客户端使用了与 本地重启 相同的方式来监控应用 classpath 下发生的更改. 任何更新的资源将被推送到远程应用和触发重启 (如果要求) . 如果您正在迭代一个使用了本地没有的云服务的功能,这可能会非常有用. 通常远程更新和重启比完全重新构建和部署的周期要快得多.

在较慢的开发环境中,可能会发生等待期不够的情况,并且类中的更改可能会分为几批. 第一批类更改上传后,服务器将重新启动. 由于服务器正在重新启动,因此下一批不能发送到应用程序.

这通常通过 RemoteSpringApplication 日志中的警告来证明,即有关上载某些类失败的消息,然后进行重试. 但是,这也可能导致应用程序代码不一致,并且在上传第一批更改后无法重新启动.

如果您经常观察到此类问题,请尝试将 spring.devtools.restart.poll-interval 和 spring.devtools.restart.quiet-period 参数增加到适合您的开发环境的值: 请参阅 配置文件系统监视器 部分以配置这些属性.

文件只有在远程客户端运行时才被监控. 如果您在启动远程客户端之前更改了文件,文件将不会被推送到远程服务器.

9. 打包生产应用

可执行 jar 可用于生产部署,它们是独立 (self-contained,独立、自包含) 的,同样也适合云部署.

针对其他生产就绪功能,比如健康、审计和 REST 或者 JMX 端点指标,可以添加 spring-boot-actuator. 有关这方面的详细信息,请参见 actuator.html .

10. 下一步

您现在应该知道如何使用 Spring Boot 以及应该遵循哪些最佳实践. 接下来您可以深入地了解 Spring Boot 特性,或者您也可以跳过下一部分直接阅读 "` 生产就绪功能`" 方面的内容.