Developing with Spring Boot

1. Build Systems

强烈建议您选择支持依赖项管理并且可以使用发布到“Maven Central”存储库的构件的构建系统。我们建议您选择Maven或Gradle。让Spring Boot与其他构建系统(例如Ant)协同工作是可能的，但它们并没有得到特别好的支持。

1.1. Dependency Management

每个版本的Spring Boot都提供了它所支持的依赖项的精选列表。实际上，您不需要在构建配置中为这些依赖项中的任何一个提供版本，因为Spring Boot会为您管理这些依赖项。当您升级Spring Boot本身时，这些依赖项也会以一致的方式升级。

You can still specify a version and override Spring Boot’s recommendations if you need to do so.

精选的列表包含您可以与Spring Boot一起使用的所有Spring模块，以及一个精炼的第三方库列表。该列表作为标准的Bills of Material(Spring-Boot-Dependency)提供，可与Maven和Gradle一起使用。

Each release of Spring Boot is associated with a base version of the Spring Framework. We highly recommend that you not specify its version.

1.2. Maven

要了解如何在Maven中使用Spring Boot，请参阅Spring Boot的Maven插件的文档：

参考(HTML和PDF)
接口

1.3. Gradle

要了解如何将Spring Boot与Gradle配合使用，请参阅Spring Boot的Gradle插件的文档：

参考(HTML和PDF)
接口

1.4. Ant

可以使用ApacheAnt+Ivy构建一个Spring Boot项目。Spring-ot-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="3.0.0" />

    <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>

If you do not want to use the spring-boot-antlib module, see the howto.html “How-to” .

1.5. Starters

启动器是一组方便的依赖项描述符，您可以将其包括在应用程序中。您可以获得所需的所有Spring和相关技术的一站式商店，而不必遍历示例代码和复制粘贴大量依赖项描述符。例如，如果您希望开始使用Spring和JPA进行数据库访问，请在您的项目中包含Spring-ot-starter-data-jpa依赖项。

启动器包含许多依赖项，您需要这些依赖项使项目快速启动和运行，并具有一组一致的、受支持的可传递依赖项。

What is in a name

所有官方启动器都遵循类似的命名模式；Spring-ot-starter-*，其中*是一种特定类型的应用程序。此命名结构旨在帮助您在需要查找启动器时提供帮助。许多IDE中的Maven集成允许您按名称搜索依赖项。例如，安装了适当的Eclipse或Spring工具插件后，您可以在POM编辑器中按ctrl-space，然后键入“Spring-ot-starter”以获得完整的列表。

正如“创建您自己的starter一节中所解释的，第三方启动器不应该以Spring-Boot开头，因为它是为官方的Spring Boot构件保留的。相反，第三方启动者通常以项目名称开头。例如，名为Third-partyProject的第三方启动项目通常将命名为thirdpartyproject-spring-boot-starter.

以下应用启动器由Spring Boot在org.springFrawork.boot组下提供：

Table 1. Spring Boot application starters
Name	Description
`SpringBoot-starter`	核心启动器，包括自动配置支持、日志记录和YAML
`spring-boot-starter-amqp`	使用弹簧AMQP和兔子MQ的启动器
`spring-boot-starter-aop`	使用Spring AOP和AspectJ进行面向方面编程的入门级
`spring-boot-starter-artemis`	使用ApacheArtemis的JMS消息传递入门
`spring-boot-starter-batch`	使用Spring Batch的启动器
`spring-boot-starter-cache`	使用Spring框架缓存支持的入门工具
`spring-boot-starter-data-cassandra`	使用Cassandra分布式数据库和Spring Data Cassandra的入门
`spring-boot-starter-data-cassandra-reactive`	使用Cassandra分布式数据库和Spring Data Cassandra Reactive的入门
`spring-boot-starter-data-couchbase`	使用Couchbase面向文档的数据库和Spring Data Couchbase的入门
`spring-boot-starter-data-couchbase-reactive`	使用Couchbase面向文档的数据库和Spring Data Couchbase Reactive的入门
`spring-boot-starter-data-elasticsearch`	使用Elasticearch搜索和分析引擎和Spring Data Elasticearch的入门
`spring-boot-starter-data-jdbc`	使用Spring Data JDBC的入门工具
`spring-boot-starter-data-jpa`	将Spring data JPA与Hibernate结合使用的入门工具
`spring-boot-starter-data-ldap`	使用Spring Data LDAP的入门工具
`spring-boot-starter-data-mongodb`	使用MongoDB面向文档的数据库和Spring Data MongoDB的入门工具
`spring-boot-starter-data-mongodb-reactive`	使用MongoDB面向文档的数据库和Spring Data MongoDB反应式的入门
`spring-boot-starter-data-neo4j`	使用Neo4j图形数据库和Spring Data Neo4j的入门
`spring-boot-starter-data-r2dbc`	使用Spring Data R2DBC的入门工具
`spring-boot-starter-data-redis`	将Redis键值数据存储与Spring data Redis和lettuce客户端结合使用的入门工具
`spring-boot-starter-data-redis-reactive`	将Redis键值数据存储与Spring data Redis Active和lettuce客户端结合使用的入门工具
`spring-boot-starter-data-rest`	使用Spring data rest通过REST公开Spring数据存储库的入门工具
`spring-boot-starter-freemarker`	使用FreeMarker视图构建MVC Web应用程序的入门工具
`spring-boot-starter-graphql`	使用Spring GraphQL构建GraphQL应用程序的入门工具
`spring-boot-starter-groovy-templates`	使用Groovy模板视图构建MVC Web应用程序的入门工具
`spring-boot-starter-hateoas`	使用Spring MVC和Spring HATEOAS构建基于超媒体的RESTful Web应用程序的入门工具
`spring-boot-starter-integration`	使用Spring集成的入门工具
`spring-boot-starter-jdbc`	用于在HikariCP连接池中使用JDBC的入门工具
`spring-boot-starter-jersey`	使用JAX-RS和Jersey构建REST风格的Web应用程序的入门级。`spring-boot-starter-web`的替代方案
`spring-boot-starter-jooq`	使用jOOQ通过JDBC访问SQL数据库的入门工具。`spring-boot-starter-data-jpa`或`spring-boot-starter-jdbc`的替代方案
`spring-boot-starter-json`	用于读写json的启动器
`spring-boot-starter-mail`	使用Java Mail和Spring框架的电子邮件发送支持的入门
`spring-boot-starter-mustache`	使用Mustache视图构建Web应用程序的入门工具
`spring-boot-starter-oauth2-client`	使用Spring Security的OAuth2/OpenID Connect客户端功能的入门
`spring-boot-starter-oauth2-resource-server`	使用Spring Security的OAuth2资源服务器功能的入门工具
`spring-boot-starter-quartz`	使用Quartz调度器的启动程序
`spring-boot-starter-rsocket`	用于构建RSocket客户端和服务器的入门工具
`spring-boot-starter-security`	使用Spring Security的入门知识
`spring-boot-starter-test`”测试	使用JUnit Jupiter、Hamcrest和Mockito库测试Spring Boot应用程序的入门程序
`spring-boot-starter-thymeleaf`	使用百里叶视图构建MVC Web应用程序的入门工具
`spring-boot-starter-validation`	将Java Bean验证与Hibernate Validator一起使用的入门工具
`spring-boot-starter-web`	使用Spring MVC构建Web应用程序(包括RESTful应用程序)的入门工具。使用Tomcat作为默认的嵌入式容器
`spring-boot-starter-web-services`	使用Spring Web服务的入门级
`spring-boot-starter-webflux`	使用Spring框架的反应式Web支持构建WebFlux应用程序的入门工具
`spring-boot-starter-websocket`	使用Spring框架的WebSocket支持构建WebSocket应用程序的入门工具

除应用启动程序外，还可以使用以下启动程序添加生产就绪功能：

Table 2. Spring Boot production starters
Name	Description
`spring-boot-starter-actuator`	使用Spring Boot的Actuator的入门工具，它提供生产就绪功能来帮助您监控和管理您的应用程序

最后，Spring Boot还包括以下启动器，如果您想要排除或交换特定的技术方面，可以使用它们：

Table 3. Spring Boot technical starters
Name	Description
`spring-boot-starter-jetty`	将Jetty用作嵌入式Servlet容器的启动器。`spring-boot-starter-tomcat`的替代方案
`spring-boot-starter-log4j2`	使用Log4j2进行日志记录的启动器。`spring-boot-starter-logging`的替代方案
`spring-boot-starter-logging`	使用Logback进行日志记录的启动器。默认日志记录启动器
`spring-boot-starter-reactor-netty`	启动器，用于使用Reader Netty作为嵌入式反应式HTTP服务器。
`spring-boot-starter-tomcat`	将Tomcat用作嵌入式Servlet容器的启动器。`spring-boot-starter-web`使用的默认Servlet容器启动器
`spring-boot-starter-undertow`	将Undertow用作嵌入式Servlet容器的启动器。`spring-boot-starter-tomcat`的替代方案

要了解如何交换技术方面，请参阅交换Web服务器和日志记录系统的操作方法文档。

For a list of additional community contributed starters, see the README file in the spring-boot-starters module on GitHub.

2. Structuring Your Code

Spring Boot不需要任何特定的代码布局即可工作。然而，有一些最佳实践是有帮助的。

2.1. Using the “default” Package

当一个类不包含包声明时，它被认为是在“默认包”中。一般不鼓励使用“默认包”，应该避免使用。它可能会给使用@ComponentScan、@ConfigurationPropertiesScan、@EntityScan或@SpringBootApplication注释的Spring Boot应用程序带来特别的问题，因为每个JAR中的每个类都是被读取的。

We recommend that you follow Java’s recommended package naming conventions and use a reversed domain name (for example, com.example.project).

2.2. Locating the Main Application Class

我们通常建议您将主应用程序类定位在根包中，而不是其他类。@SpringBootApplication注释通常放在您的主类上，它隐含地为某些项目定义了一个基本的“搜索包”。例如，如果您正在编写一个JPA应用程序，@SpringBootApplication注释类的包将用于搜索@Entity项。使用根包还允许组件扫描仅应用于您的项目。

If you do not want to use @SpringBootApplication, the @EnableAutoConfiguration and @ComponentScan annotations that it imports defines that behavior so you can also use those instead.

下面的清单显示了典型的布局：

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，如下所示：

Java

Kotlin

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); } }

import org.springframework.boot.autoconfigure.SpringBootApplication import org.springframework.boot.runApplication @SpringBootApplication class MyApplication fun main(args: Array<String>) { runApplication<MyApplication>(*args) }

3. Configuration Classes

Spring Boot支持基于Java的配置。尽管可以将SpringApplication与XML源代码一起使用，但我们通常建议您的主要源代码是单个@Configuration类。通常，定义main方法的类很适合作为主要@configuration。

Many Spring configuration examples have been published on the Internet that use XML configuration. If possible, always try to use the equivalent Java-based configuration. Searching for Enable* annotations can be a good starting point.

3.1. Importing Additional Configuration Classes

您不需要将所有@configuration放入单个类中。@Import注释可用于导入其他配置类。或者，您可以使用@ComponentScan自动获取所有的Spring组件，包括@Configuration类。

3.2. Importing XML Configuration

如果您一定要使用基于XML的配置，我们建议您仍然从@Configuration类开始。然后，您可以使用@ImportResource注释来加载XML配置文件。

4. Auto-configuration

Spring Boot自动配置尝试根据您添加的JAR依赖项自动配置您的Spring应用程序。例如，如果HSQLDB在您的类路径上，并且您没有手动配置任何数据库连接Bean，那么Spring Boot将自动配置内存中的数据库。

您需要选择加入自动配置，方法是将@EnableAutoConfiguration或@SpringBootApplication注释添加到您的一个@Configuration类中。

You should only ever add one @SpringBootApplication or @EnableAutoConfiguration annotation. We generally recommend that you add one or the other to your primary @Configuration class only.

4.1. Gradually Replacing Auto-configuration

自动配置是非侵入性的。在任何时候，您都可以开始定义自己的配置来替换自动配置的特定部分。例如，如果您添加自己的DataSourceBean，则默认的嵌入式数据库支持将退出。

如果您需要找出当前应用了什么自动配置以及原因，可以使用--DEBUG开关启动您的应用程序。这样做可以启用选定核心记录器的调试日志，并将条件报告记录到控制台。

4.2. Disabling Specific Auto-configuration Classes

如果您发现正在应用您不希望应用的特定自动配置类，则可以使用@SpringBootApplication的Exclude属性禁用它们，如下例所示：

Java

Kotlin

import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration; @SpringBootApplication(exclude = { DataSourceAutoConfiguration.class }) public class MyApplication { }

import org.springframework.boot.autoconfigure.SpringBootApplication import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration @SpringBootApplication(exclude = [DataSourceAutoConfiguration::class]) class MyApplication

如果类不在类路径上，您可以使用注释的excludeName属性并指定完全限定名。如果您更喜欢使用@EnableAutoConfiguration而不是@SpringBootApplication，也可以使用Exclude和ExcludeName。最后，您还可以通过使用spring.aufigure.exclude属性来控制要排除的自动配置类的列表。

You can define exclusions both at the annotation level and by using the property.

Even though auto-configuration classes are public, the only aspect of the class that is considered public API is the name of the class which can be used for disabling the auto-configuration. The actual contents of those classes, such as nested configuration classes or bean methods are for internal use only and we do not recommend using those directly.

5. Spring Beans and Dependency Injection

您可以自由使用任何标准的Spring框架技术来定义您的Bean及其注入的依赖项。我们通常推荐使用构造函数注入来连接依赖项，并使用@ComponentScan来查找Bean。

如果按照上面的建议构建代码(将应用程序类放在顶层包中)，则可以添加不带任何参数的@ComponentScan，或者使用隐式包含它的@SpringBootApplication注释。您的所有应用程序组件(@Component、@Service、@Repository、@控制器等)都自动注册为SpringBean。

下面的示例显示了一个@ServiceBean，它使用构造函数注入来获取所需的RiskassessorBean：

Java

Kotlin

import org.springframework.stereotype.Service; @Service public class MyAccountService implements AccountService { private final RiskAssessor riskAssessor; public MyAccountService(RiskAssessor riskAssessor) { this.riskAssessor = riskAssessor; } // ... }

import org.springframework.stereotype.Service @Service class MyAccountService(private val riskAssessor: RiskAssessor) : AccountService

如果一个Bean有多个构造函数，您将需要将您希望Spring使用的构造函数标记为@Autwire：

Java

Kotlin

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; } // ... }

import org.springframework.beans.factory.annotation.Autowired import org.springframework.stereotype.Service import java.io.PrintStream @Service class MyAccountService : AccountService { private val riskAssessor: RiskAssessor private val out: PrintStream @Autowired constructor(riskAssessor: RiskAssessor) { this.riskAssessor = riskAssessor out = System.out } constructor(riskAssessor: RiskAssessor, out: PrintStream) { this.riskAssessor = riskAssessor this.out = out } // ... }

Notice how using constructor injection lets the riskAssessor field be marked as final, indicating that it cannot be subsequently changed.

6. Using the @SpringBootApplication Annotation

许多Spring Boot开发人员喜欢他们的应用程序使用自动配置、组件扫描，并能够在他们的“应用程序类”上定义额外的配置。可以使用单个@SpringBootApplication注释来启用这三个功能，即：

@EnableAutoConfiguration：启用Spring Boot的自动配置机制
@ComponentScan：在应用程序所在的包上启用@ComponentScan扫描(参见最佳实践)
@SpringBootConfiguration：允许在上下文中注册额外的Bean或导入额外的配置类。在集成测试中帮助配置检测配置的Spring标准的替代方案。

Java

Kotlin

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); } }

import org.springframework.boot.autoconfigure.SpringBootApplication import org.springframework.boot.runApplication // same as @SpringBootConfiguration @EnableAutoConfiguration @ComponentScan @SpringBootApplication class MyApplication fun main(args: Array<String>) { runApplication<MyApplication>(*args) }

@SpringBootApplication also provides aliases to customize the attributes of @EnableAutoConfiguration and @ComponentScan.

这些功能都不是必需的，您可以选择用它启用的任何功能来替换该单个注释。例如，您可能不想在应用程序中使用组件扫描或配置属性扫描：

Java

Kotlin

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); } }

import org.springframework.boot.SpringBootConfiguration import org.springframework.boot.autoconfigure.EnableAutoConfiguration import org.springframework.boot.docs.using.structuringyourcode.locatingthemainclass.MyApplication import org.springframework.boot.runApplication import org.springframework.context.annotation.Import @SpringBootConfiguration(proxyBeanMethods = false) @EnableAutoConfiguration @Import(SomeConfiguration::class, AnotherConfiguration::class) class MyApplication fun main(args: Array<String>) { runApplication<MyApplication>(*args) }

在本例中，MyApplication与任何其他Spring Boot应用程序类似，不同之处在于@Component注释的类和@ConfigurationProperties-annotated类不会被自动检测，并且用户定义的Bean被显式导入(参见@Import)。

7. Running Your Application

将应用程序打包为JAR并使用嵌入式HTTP服务器的最大优势之一是，您可以像运行其他应用程序一样运行应用程序。该示例适用于调试Spring Boot应用程序。您不需要任何特殊的IDE插件或扩展。

This section only covers jar-based packaging. If you choose to package your application as a war file, see your server and IDE documentation.

7.1. Running From an IDE

您可以从您的IDE中将Spring Boot应用程序作为Java应用程序运行。但是，您首先需要导入项目。导入步骤因您的IDE和构建系统而异。大多数IDE可以直接导入Maven项目。例如，Eclipse用户可以选择<…>导入代码文件菜单中的→现有Maven项目。

如果不能将项目直接导入到IDE中，则可以使用生成插件生成IDE元数据。Maven包含用于Eclipse和IDEA的插件。Gradle为各种IDE提供插件。

If you accidentally run a web application twice, you see a “Port already in use” error. Spring Tools users can use the Relaunch button rather than the Run button to ensure that any existing instance is closed.

7.2. Running as a Packaged Application

如果使用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. Using the Maven Plugin

Spring Boot Maven插件包含一个run目标，可用于快速编译和运行您的应用程序。应用程序以分解形式运行，就像它们在IDE中所做的那样。以下示例显示了运行Spring Boot应用程序的典型Maven命令：

$ mvn spring-boot:run

您可能还希望使用MAVEN_OPTS操作系统环境变量，如下例所示：

$ export MAVEN_OPTS=-Xmx1024m

7.4. Using the Gradle Plugin

Spring Boot Gradle插件还包括一个bootRun任务，可用于以分解形式运行您的应用程序。每当您应用org.springFrawork.boot和Java插件时，都会添加bootRun任务，如下例所示：

$ gradle bootRun

您可能还希望使用JAVA_OPTS操作系统环境变量，如下例所示：

$ export JAVA_OPTS=-Xmx1024m

7.5. Hot Swapping

由于Spring Boot应用程序是普通的Java应用程序，JVM热插拔应该可以开箱即用。JVM热插拔在某种程度上受到它可以替代的字节码的限制。要获得更完整的解决方案，可以使用JRebel。

SpringBoot-DevTools模块还包括对应用程序快速重启的支持。有关详细信息，请参阅热插拔“操作指南”。

8. Developer Tools

Spring Boot包括一组额外的工具，可以让应用程序开发体验更愉快一些。Spring-Boot-DevTools模块可以包含在任何项目中，以提供额外的开发时功能。要包括DevTools支持，请将模块依赖项添加到您的构建中，如以下Maven和Gradle清单所示：

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 might cause classloading issues, in particular in multi-module projects. Diagnosing Classloading Issues explains how to diagnose and solve them.

Developer tools are automatically disabled when running a fully packaged application. If your application is launched from java -jar or if it is started from a special classloader, then it is considered a “production application”. You can control this behavior by using the spring.devtools.restart.enabled system property. To enable devtools, irrespective of the classloader used to launch your application, set the -Dspring.devtools.restart.enabled=true system property. This must not be done in a production environment where running devtools is a security risk. To disable devtools, exclude the dependency or set the -Dspring.devtools.restart.enabled=false system property.

Flagging the dependency as optional in Maven or using the developmentOnly configuration in Gradle (as shown above) prevents devtools from being transitively applied to other modules that use your project.

Repackaged archives do not contain devtools by default. If you want to use a certain remote devtools feature, you need to include it. When using the Maven plugin, set the excludeDevtools property to false. When using the Gradle plugin, configure the task’s classpath to include the developmentOnly configuration.

8.1. Diagnosing Classloading Issues

如Restart vs Reload部分所述，重新启动功能是通过使用两个类加载器实现的。对于大多数应用程序，此方法运行良好。但是，它有时会导致类加载问题，特别是在多模块项目中。

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

8.2. Property Defaults

Spring Boot支持的几个库使用缓存来提高性能。例如，模板引擎缓存已编译的模板，以避免重复解析模板文件。此外，在为静态资源提供服务时，Spring MVC可以向响应添加HTTP缓存头。

虽然缓存在生产中非常有用，但在开发过程中可能会适得其反，使您无法看到刚刚在应用程序中所做的更改。因此，Spring-Boot-DevTools在默认情况下禁用缓存选项。

缓存选项通常由应用程序.Properties文件中的设置配置。例如，Thymeleaf提供了spring.thoreleaf.cache属性。Spring-Boot-DevTools模块自动应用合理的开发时配置，而不需要手动设置这些属性。

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

Name Default Value

Name	Default Value
`server.error.include-binding-errors`	`始终`
`server.error.clude-消息`	`始终`
`server.error.clude-stacktrace`	`始终`
`server.servlet.jsp.init-parameters.development`	`True`
`server.servlet.session.persistent`	`True`
`spring.freemarker.cache`	`FALSE`
`spring.graph ql.graph iql.Enabled`	`True`
`spring.groovy.template.cache`	`FALSE`
`spring.h2.console.Enabled`	`True`
`spring.mustahe.servlet.cache`	`FALSE`
`spring.mvc.log-resolved-exception`	`True`
`spring.reactor.debug`	`True`
`spring.template.Provider.cache`	`FALSE`
`spring.thoreleaf.cache`	`FALSE`
`spring.web.resources.cache.period`	`0`
`spring.web.resource ces.chain.cache`	`FALSE`

server.error.include-binding-errors

始终

server.error.clude-消息

始终

server.error.clude-stacktrace

始终

server.servlet.jsp.init-parameters.development

True

server.servlet.session.persistent

True

spring.freemarker.cache

FALSE

spring.graph ql.graph iql.Enabled

True

spring.groovy.template.cache

FALSE

spring.h2.console.Enabled

True

spring.mustahe.servlet.cache

FALSE

spring.mvc.log-resolved-exception

True

spring.reactor.debug

True

spring.template.Provider.cache

FALSE

spring.thoreleaf.cache

FALSE

spring.web.resources.cache.period

0

spring.web.resource ces.chain.cache

FALSE

If you do not want property defaults to be applied you can set spring.devtools.add-properties to false in your application.properties.

由于您在开发Spring MVC和Spring WebFlux应用程序时需要更多关于Web请求的信息，因此开发人员工具建议您为web日志记录组启用调试日志记录。这将为您提供有关传入请求、哪个处理程序正在处理它、响应结果以及其他详细信息的信息。如果您希望记录所有请求详细信息(包括潜在的敏感信息)，可以打开spring.mvc.log-请求-详细信息或spring.codec.log-请求-详细信息配置属性。

8.3. Automatic Restart

只要类路径上的文件发生更改，使用Spring-Boot-DevTools的应用程序就会自动重新启动。当在IDE中工作时，这可能是一个有用的功能，因为它为代码更改提供了一个非常快速的反馈循环。默认情况下，会监视类路径上指向某个目录的任何条目是否有更改。注意，某些资源，如静态资源和视图模板，不需要重新启动应用程序。

Triggering a restart

在DevTools监视类路径资源时，触发重启的唯一方法是更新类路径。无论您使用的是IDE还是某个构建插件，都必须重新编译修改后的文件以触发重启。更新类路径的方式取决于您使用的工具：

在Eclipse中，保存修改后的文件会导致类路径更新并触发重启。
在IntelliJ IDEA中，构建项目(<代码>Build+→+Build Project)具有相同的效果。
如果使用构建插件，运行MVN Compilefor Maven或Gradle Build将触发重启。

If you are restarting with Maven or Gradle using the build plugin you must leave the forking set to enabled. If you disable forking, the isolated application classloader used by devtools will not be created and restarts will not operate properly.

Automatic restart works very well when used with LiveReload. See the LiveReload section for details. If you use JRebel, automatic restarts are disabled in favor of dynamic class reloading. Other devtools features (such as LiveReload and property overrides) can still be used.

DevTools relies on the application context’s shutdown hook to close it during a restart. It does not work correctly if you have disabled the shutdown hook (SpringApplication.setRegisterShutdownHook(false)).

DevTools needs to customize the ResourceLoader used by the ApplicationContext. If your application provides one already, it is going to be wrapped. Direct override of the getResource method on the ApplicationContext is not supported.

Automatic restart is not supported when using AspectJ weaving.

Restart vs Reload

Spring Boot提供的重启技术通过使用两个类加载器来工作。不更改的类(例如，来自第三方JAR的类)被加载到基础类加载器中。您正在积极开发的类被加载到重新启动类加载器中。当应用程序重新启动时，重新启动类加载器被丢弃，并创建一个新的类加载器。这种方法意味着应用程序重启通常比“冷启动”快得多，因为基础类加载器已经可用并已填充。

如果您发现应用程序的重启不够快，或者遇到类加载问题，您可以考虑从ZeroTurnround重新加载技术，如JRebel。它们的工作方式是在加载时重写类，以使其更易于重新加载。

8.3.1. Logging Changes in Condition Evaluation

默认情况下，每次应用程序重新启动时，都会记录一份显示条件评估增量的报告。该报告显示在您进行更改(如添加或删除Bean以及设置配置属性)时对应用程序自动配置的更改。

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

Properties

Yaml

spring.devtools.restart.log-condition-evaluation-delta=false

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

8.3.2. Excluding Resources

某些资源在更改时不一定需要触发重启。例如，可以就地编辑百里叶模板。默认情况下，更改/meta-INF/maven、/meta-INF/resource、/resource、/静态、/public或/Templates中的资源不会触发重启，但会触发活动重新加载。如果您想要自定义这些排除，您可以使用spring.devtools.restart.exclude属性。例如，要仅排除/静态和/public，您需要设置以下属性：

Properties

Yaml

spring.devtools.restart.exclude=static/**,public/**

spring:
  devtools:
    restart:
      exclude: "static/**,public/**"

If you want to keep those defaults and add additional exclusions, use the spring.devtools.restart.additional-exclude property instead.

8.3.3. Watching Additional Paths

当您更改不在类路径上的文件时，您可能希望重新启动或重新加载应用程序。为此，请使用spring.devtools.restart.additional-paths属性配置其他路径以监视更改。您可以使用前面描述的spring.devtools.restart.exclude属性来控制其他路径下的更改是否会触发完全重启或实时重新加载。

8.3.4. Disabling Restart

如果您不想使用重新启动功能，可以使用spring.devtools.restart.Enabled属性禁用它。在大多数情况下，您可以在应用程序中设置此属性。属性(这样做仍然会初始化重新启动的类加载器，但它不会监视文件更改)。

如果您需要完全禁用重新启动支持(例如，因为它不能与特定库一起使用)，则需要在调用SpringApplication.run(…)之前将spring.devtools.restart.Enabled系统属性设置为False)，如下例所示：

Java

Kotlin

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); } }

import org.springframework.boot.SpringApplication import org.springframework.boot.autoconfigure.SpringBootApplication @SpringBootApplication object MyApplication { @JvmStatic fun main(args: Array<String>) { System.setProperty("spring.devtools.restart.enabled", "false") SpringApplication.run(MyApplication::class.java, *args) } }

8.3.5. Using a Trigger File

如果您使用的是持续编译更改的文件的IDE，您可能更喜欢仅在特定时间触发重新启动。为此，您可以使用“触发文件”，这是一个特殊的文件，当您想要实际触发重新启动检查时，必须对其进行修改。

Any update to the file will trigger a check, but restart only actually occurs if Devtools has detected it has something to do.

若要使用触发器文件，请将spring.devtools.restart.trigger-file属性设置为触发器文件的名称(不包括任何路径)。触发器文件必须出现在类路径上的某个位置。

例如，如果您有一个具有以下结构的项目：

src
+- main
   +- resources
      +- .reloadtrigger

则您的触发器文件属性将为：

Properties

Yaml

spring.devtools.restart.trigger-file=.reloadtrigger

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

现在，只有在更新src/main/resources/.reloadtrigger后才会重新启动。

You might want to set spring.devtools.restart.trigger-file as a global setting, so that all your projects behave in the same way.

某些IDE具有使您不必手动更新触发器文件的功能。Spring Tools for Eclipse和IntelliJ Idea(旗舰版)都有这样的支持。使用Spring Tools，您可以使用Console视图中的“ReLoad”按钮(只要您的触发器文件被命名为.reloadrigger)。对于IntelliJ IDEA，您可以按照其文档中的说明进行操作。

8.3.6. Customizing the Restart Classloader

如前面Restart vs Reload部分所述，重新启动功能是通过使用两个类加载器实现的。如果这会导致问题，您可能需要定制由哪个类加载器加载的内容。

默认情况下，IDE中任何打开的项目都是用“重新启动”类加载器加载的，而任何常规的.jar文件都是用“基”类加载器加载的。如果您使用MVN SpringBootRun：Run或Gradle bootRun，情况也是如此：包含@SpringBootApplication的项目使用“重新启动”类加载器加载，其他所有内容都使用“基本”类加载器加载。

您可以通过创建一个META-INF/spring-devtools.properties文件来指示Spring Boot使用不同的类加载器加载项目的各个部分。春运工具属性文件可以包含以restart.exclude和restart.include为前缀的属性。Include元素是应该放入“重新启动”类加载器中的项，而Exclude元素是应该放入“基本”类加载器中的项。该属性的值是应用于类路径的正则表达式模式，如下例所示：

Properties

Yaml

restart.exclude.companycommonlibs=/mycorp-common-[\\w\\d-\\.]+\\.jar
restart.include.projectcommon=/mycorp-myproj-[\\w\\d-\\.]+\\.jar

restart:
  exclude:
    companycommonlibs: "/mycorp-common-[\\w\\d-\\.]+\\.jar"
  include:
    projectcommon: "/mycorp-myproj-[\\w\\d-\\.]+\\.jar"

All property keys must be unique. As long as a property starts with restart.include. or restart.exclude. it is considered.

All META-INF/spring-devtools.properties from the classpath are loaded. You can package files inside your project, or in the libraries that the project consumes.

8.3.7. Known Limitations

重新启动功能不能很好地处理使用标准ObjectInputStream反序列化的对象。如果您需要反序列化数据，您可能需要将SpringConfigurableObjectInputStream与Thread.currentThread().getContextClassLoader().结合使用

不幸的是，几个第三方库在没有考虑上下文类加载器的情况下进行了反序列化。如果您发现了这样的问题，您需要向原始作者请求修复。

8.4. LiveReload

SpringBoot-DevTools模块包含一个嵌入式LiveReload服务器，可用于在资源更改时触发浏览器刷新。从livereload.com可以免费获得适用于Chrome、Firefox和Safari的LiveReload浏览器扩展。

如果不想在应用程序运行时启动LiveReload服务器，可以将spring.devtools.livereload.enabled属性设置为<代码>FALSE 。

You can only run one LiveReload server at a time. Before starting your application, ensure that no other LiveReload servers are running. If you start multiple applications from your IDE, only the first has LiveReload support.

To trigger LiveReload when a file changes, Automatic Restart must be enabled.

8.5. Global Settings

您可以通过将以下任何文件添加到$HOME/.config/SpringBoot目录来配置全局DevTools设置：

Spring-Boot-Devtools.Properties
SpringBoot-Devtools.yaml
SpringBoot-Devtools.yml

添加到这些文件的任何属性都适用于计算机上使用DevTool的所有Spring Boot应用程序。例如，要将Restart配置为始终使用触发器文件，您需要将以下属性添加到Spring-ot-DevTools文件中：

Properties

Yaml

spring.devtools.restart.trigger-file=.reloadtrigger

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

默认情况下，$HOME是用户的主目录。若要自定义此位置，请设置SPUNG_DevTools_HOME环境变量或spring.devtools.home系统属性。

If devtools configuration files are not found in $HOME/.config/spring-boot, the root of the $HOME directory is searched for the presence of a .spring-boot-devtools.properties file. This allows you to share the devtools global configuration with applications that are on an older version of Spring Boot that does not support the $HOME/.config/spring-boot location.

DevTools属性/YAML文件不支持配置文件。

在.Spring-Boot-Devtools.Properties中激活的任何配置文件都不会影响配置文件的加载。不支持Yaml和属性文件中的配置文件特定文件名(格式为spring-boot-devtools-<；profile>；.properties)和spring.config.activate.on-profileDocuments)。

8.5.1. Configuring File System Watcher

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

Properties

Yaml

spring.devtools.restart.poll-interval=2s
spring.devtools.restart.quiet-period=1s

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

受监视的类路径目录现在每2秒轮询一次更改，并保持1秒的静默期以确保没有额外的类更改。

8.6. Remote Applications

Spring Boot开发人员工具并不局限于本地开发。您还可以在远程运行应用程序时使用多个功能。远程支持是选择加入的，因为启用它可能会带来安全风险。仅当在受信任的网络上运行或使用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.emote.ret属性。就像任何重要的密码或秘密一样，该值应该是唯一和强的，这样它就不能被猜测或暴力强迫。

远程DevTools支持分两部分提供：接受连接的服务器端端点和在IDE中运行的客户端应用程序。当设置了spring.devtools.emote.ret属性时，服务器组件将自动启用。客户端组件必须手动启动。

Remote devtools is not supported for Spring WebFlux applications.

8.6.1. Running the Remote Client Application

远程客户端应用程序设计为从您的IDE内部运行。您需要使用与您连接到的远程项目相同的类路径来运行org.springframework.boot.devtools.RemoteSpringApplication。应用程序的唯一必需参数是它连接到的远程URL。

例如，如果您使用的是Eclipse或Spring工具，并且您有一个已部署到Cloud Foundry的名为my-app的项目，您将执行以下操作：

选择<代码>运行配置…<><代码>运行菜单中的。
新建Java应用程序“启动配置”。
浏览my-app项目。
使用org.springframework.boot.devtools.RemoteSpringApplication作为主类。
将<代码>代码添加到 >程序参数 (或任何您的远程URL)。

正在运行的远程客户端可能类似于以下清单：

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

2022-11-24T17:03:45.349Z  INFO 20660 --- [           main] o.s.b.devtools.RemoteSpringApplication   : Starting RemoteSpringApplication v3.0.0 using Java 17.0.5 with PID 20660 (/Users/myuser/.m2/repository/org/springframework/boot/spring-boot-devtools/3.0.0/spring-boot-devtools-3.0.0.jar started by myuser in /opt/apps/)
2022-11-24T17:03:45.353Z  INFO 20660 --- [           main] o.s.b.devtools.RemoteSpringApplication   : No active profile set, falling back to 1 default profile: "default"
2022-11-24T17:03:46.281Z  INFO 20660 --- [           main] o.s.b.d.a.OptionalLiveReloadServer       : LiveReload server is running on port 35729
2022-11-24T17:03:46.364Z  INFO 20660 --- [           main] o.s.b.devtools.RemoteSpringApplication   : Started RemoteSpringApplication in 2.675 seconds (process running for 3.514)

Because the remote client is using the same classpath as the real application it can directly read application properties. This is how the spring.devtools.remote.secret property is read and passed to the server for authentication.

It is always advisable to use https:// as the connection protocol, so that traffic is encrypted and passwords cannot be intercepted.

If you need to use a proxy to access the remote application, configure the spring.devtools.remote.proxy.host and spring.devtools.remote.proxy.port properties.

8.6.2. Remote Update

远程客户端以与本地重启相同的方式监视您的应用程序类路径的更改。任何更新的资源都会被推送到远程应用程序，并且(如果需要)会触发重新启动。如果在使用本地没有的云服务的功能上迭代，这会很有帮助。通常，远程更新和重新启动比完整的重建和部署周期快得多。

在较慢的开发环境中，可能会出现静默期不够的情况，类中的更改可能会分成几批。在上传第一批类更改后重启服务器。下一批无法发送到应用程序，因为服务器正在重新启动。

这通常表现为在RemoteSpringApplication日志中警告无法上载某些类，并随后重试。但这也可能导致应用程序代码不一致，在上传第一批更改后无法重启。如果您经常观察到此类问题，请尝试将spring.devtools.restart.poll-interval和spring.devtools.restart.quiet-period参数增加到适合您的开发环境的值。有关配置这些属性的信息，请参阅配置文件系统观察器一节。

Files are only monitored when the remote client is running. If you change a file before starting the remote client, it is not pushed to the remote server.

9. Packaging Your Application for Production

可执行JAR可用于生产部署。由于它们是独立的，因此也非常适合基于云的部署。

对于附加的“生产就绪”特性，比如运行状况、审计和度量REST或JMX端点，可以考虑添加Spring-ot-Actuator。有关详细信息，请参阅actuator.html。

10. What to Read Next

现在，您应该了解如何使用Spring Boot，以及应该遵循的一些最佳实践。现在，您可以继续深入了解特定的Spring Boot特性，也可以跳到前面阅读有关Spring Boot的“生产就绪”方面的内容。