Spring Boot 中文文档 2.7.18-SNAPSHOT

浅笑_微梦2024-02-29 17:05

Spring Boot 中文文档

官方文档

说明：本文档翻译的版本：2.7.18-SNAPSHOT。

1. 法规（Legal）

Copyright © 2012-2023

您可以复制本文件供自己使用或向他人分发，但不得收取任何费用，无论是以印刷品还是电子版分发，每份复制件均应包含本版权声明。

2. 获取帮助（Getting Help）

如果在使用 Spring Boot 过程中遇到麻烦，我们很乐意帮忙！

  • 请访问文档 How-to documents。它为常见的大多数问题提供了解决方案。
  • 学习更多有关 Spring 的基础知识。Spring Boot 是在很多其他的 Spring 项目上构建的。可以访问 spring.io 来获取更多其它的参考文档。如果你刚刚开始学习 Spring，请参考下面指南的内容.
  • 如果你希望问一下问题。Spring官方会时时关注 stackoverflow.com 上有关使用 spring-boot的问题.
  • 如果在使用 Spring Boot 过程中发现bug，请访问 github.com/spring-projects/spring-boot/issues 页面反馈该bug。

::: tip 提示

Spring Boot 的所有内容都是开源的，包括文档！如果你发现文档有问题，或想提高文档的质量，请访问https://github.com/spring-projects/spring-boot/tree/2.7.x 参与文档的修订过程。

:::

3. 文档概述（Documentation Overview）

本章节简要介绍一下Spring Boot参考文档。它包含本文档其它部分的链接。

本文档的最新版本可在 docs.spring.io/spring-boot/docs/current/reference/ 上获取。

3.1 第一步（First Steps）

如果您要开始学习Spring Boot或Spring，请访问the following topics:

3.2 从早期版本升级（Upgrading From an Earlier Version）

您应始终确保运行的是受支持的 Spring Boot 版本。

根据您升级到的版本，您可以在此处找到一些额外的提示：

3.3 使用Spring Boot开发（使用 Spring Boot 开发）

准备开始使用Spring Boot了? 我们为您提供以下内容：

3.4 了解Spring Boot功能（Learning About Spring Boot Features）

需要了解更多有关Spring Boot的共享详情吗？ 下列内容包括了这些：

3.5 Web

如果您正在开发 Spring Boot Web应用程序，请阅读以下内容：

3.6 数据（Data）

如果您的应用程序要处理数据存储，可以在此处查看如何配置：

3.7 消息（Messaging）

如果您的应用程序使用任何报文传送协议，请参阅以下一个或多个章节：

3.8 IO

如果您的应用程序需要 IO 功能，请参阅以下一个或多个章节：

3.9 容器镜像（Container Images）

Spring Boot 为构建容器镜像提供了一流的支持。您可以在此阅读更多相关信息：

3.10 迁移到生产环境（Moving to Production）

当你准备将Spring Boot应用发布到生产环境时，我们提供了一些方法 ：

3.11 高级主题（Advanced Topics）

最后，我们为用户准备了一些高级功能：

4. 开始使用（Getting Started）

如果您要开始学习 Spring Boot 或 Spring，请先阅读本节内容。它回答了 "是什么？"、"怎么做？"和 "为什么？"等基本问题。其中包括 Spring Boot 简介和安装说明。我们将引导您构建第一个 Spring Boot 应用程序，并讨论一些核心原则。

4.1 Spring Boot 介绍（Introducing Spring Boot）

Spring Boot 可帮助您创建可运行的基于 Spring 的独立生产级应用程序。我们对 Spring 平台和第三方库保持开放的态度，因此您可以轻松上手。大多数 Spring Boot 应用程序只需要很少的 Spring 配置。

您可以使用 Spring Boot 创建 Java 应用程序，这些应用程序可以通过使用 java -jar 或更传统的 war 部署来启动。我们还提供了 "spring 脚本 "的命令行工具来启动。

我们的主要目标是：

  • 为所有 Spring 开发人员提供更快、更广泛的入门体验。
  • 开箱即用，但随着需求开始偏离默认值而迅速摆脱困境。
  • 提供大型项目通用的一系列非功能性特效（例如嵌入式服务器，安全性，度量标准，运行状况检查和外部化配置）。
  • 绝对没有代码生成，也不需要XML配置。

4.2 系统要求（System Requirements）

Spring Boot 2.7.18-SNAPSHOT 要求 Java 8 并兼容 Java 21。要求 Spring Framework 5.3.31 或以上版本。

为以下构建工具提供了明确的构建支持：

Build Tool Version
Maven 3.5+
Gradle 6.8.x, 6.9.x, 7.x, and 8.x
4.2.1 Servlet容器（Servlet Containers）

Spring Boot支持以下嵌入式servlet容器：

Name Servlet Version
Tomcat 9.0 4.0
Jetty 9.4 3.1
Jetty 10.0 4.0
Undertow 2.0 4.0

你可以将Spring Boot应用程序部署到任何兼容 Servlet 3.1 或 4.0 的容器。

4.3 安装Spring Boot

Spring Boot 可与 "经典 "Java 开发工具一起使用，也可作为命令行工具安装。无论哪种方式，您都需要 Java SDK v1.8 或更高版本。开始之前，应使用以下命令检查当前的 Java 安装：

shell 复制代码 
java -version

如果您是 Java 开发新手或如果想要尝试使用 Spring Boot，您可能想先试试 Spring Boot CLI（命令行界面）。否则，请继续阅读 "经典 "安装说明。

4.3.1 Java Developer安装说明（Installation Instructions for the Java Developer）

如果您想想使用标准Java库一样使用Spring Boot，请在类路径中包含相应的spring-boot-*.jar文件。Spring Boot不需要任何特殊工具集成，因此您可以使用任何IDE或文本编辑器。此外，Spring Boot应用程序没有什么特别之处，因此您可以像运行任何其他Java程序一样运行和调试Spring Boot应用程序。

虽然您可以复制Spring Boot jar文件，但我们通常建议您使用支持依赖关系管理的构建工具（例如Maven或Gradle）。

Maven安装（Maven Installation）

Spring Boot 兼容 Apache Maven 3.3 或更高版本。如果您尚未安装Maven，则可以按照 maven.apache.org 的说明进行操作。

::: tip 提示

在许多操作系统上， Maven 可以作为一个安装包进行安装. 如果您使用 OSX Homebrew，请尝试使用brew install maven。 Ubuntu 用户可以运行sudo apt-get install maven。 使用Chocolatey的 Windows 用户可以使用管理员cmd窗口运行choco install maven。

:::

Spring Boot使用groupId 为 org.springframework.boot 的依赖项。通常，您的Maven POM文件继承自spring-boot-starter-parent项目，并声明对一个或多个 "Starters" 依赖关系。Spring Boot还提供了一个可选的 Maven plugin来创建可执行jar。

有关 Spring Boot 和 Maven 使用的更多详情，请参阅 Maven 插件参考指南的 "开始使用"部分。

xml 复制代码 
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>example-project</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <!-- Inherit defaults from Spring Boot -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.18-SNAPSHOT</version>
    </parent>

    <!-- Add typical dependencies for a web application -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

    <!-- Package as an executable jar -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>
Gradle 安装（Gradle Installation）

Spring Boot 兼容 Gradle 6.8、6.9、7.x 和 8.x。 如果您尚未安装Gradle ，则可以按照 gradle.org的说明进行操作。

Spring Boot使用groupId 为 org.springframework.boot 的依赖项。通常，您的Maven POM文件继承自spring-boot-starter-parent项目，并声明对一个或多个 "Starters" 依赖关系。Spring Boot还提供了一个 Gradle plugin 可以用来简化依赖声明和创建可执行jar。

::: tip Gradle Wrapper

当你需要构建项目时，Gradle Wrapper 提供了一种 "obtaining" Gradle 的方法。它是一个小脚本库，您可以 在提交代码的同时进行构建操作。有关详细信息，请参阅 docs.gradle.org/current/userguide/gradle_wrapper.html。

:::

有关 Spring Boot 和 Gradle 使用的更多详情，请参阅 Gradle 插件参考指南的 "开始使用"部分。

4.3.2 安装Spring Boot CLI（Installing the Spring Boot CLI）

Spring Boot CLI（命令行界面）是一个命令行公交，可以用于快速创建 Spring 原型。它运行你运行 Groovy 脚本，这意味着您可以使用一种类似Java的语法，而无需太多模板代码。

你可能并不需要使用 CLI 来使用 Spring Boot，但它是一种无需IDE即可快速启动 Spring 应用程序的方法。

手动安装（Manual Installation）

你可以从Spring 软件存储库 中下载 spring-boot-cli-*-bin.zip 文件或 spring-boot-cli-*-bin.tar.gz 文件。

下载完成并解压之后，请按照文件夹中 INSTALL.txt 说明进行操作。总之，在 .zip 压缩文件的bin/目录中有一个 spring 脚本（Windows下是spring.bat ）。或者,，你可以使用 java -jar 运行 .jar 文件（该脚本可帮助您确保类路径设置正确）。

使用SDKMAN安装（Installation with SDKMAN!）

SDKMAN! （软件开发工具包管理器）可以用来管理多个版本的二进制SDK，包括 Groovy 和 Spring Boot CLI. 从 sdkman.io 获取SDKMAN!并使用一下命令安装 Spring Boot：

shell 复制代码 
$ sdk install springboot
$ spring --version
Spring CLI v2.7.18-SNAPSHOT

如果您使用CLI开发功能并希望访问您构建的版本，请使用以下命令：

shell 复制代码 
$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.7.18-SNAPSHOT-bin/spring-2.7.18-SNAPSHOT/
$ sdk default springboot dev
$ spring --version
Spring CLI v2.7.18-SNAPSHOT

上述说明安装了一个名为dev 的 spring 本地实例。它指向您的目标构建位置，因此每次重新构建 Spring Boot， spring 都是最新的。

您可以通过运行以下命令来查看它：

shell 复制代码 
$ sdk ls springboot

================================================================================
Available Springboot Versions
================================================================================
> + dev
* 2.7.18-SNAPSHOT

================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
OSX Homebrew 安装（OSX Homebrew Installation）

如果您使用的是 Mac 并使用 Homebrew，你可以通过以下命令安装 Spring Boot CLI：

shell 复制代码 
$ brew tap spring-io/tap
$ brew install spring-boot

Homebrew 会将 spring 安装到 /usr/local/bin 中。

::: tip 提示

如果您没有看到formula，你的安装Homebrew 不是最新的，在这种情况下，请运行brew update 并重试。

:::

MacPorts 安装（MacPorts Installation）

如果您使用的是 Mac 并使用 MacPorts，你可以通过以下命令安装 Spring Boot CLI：

shell 复制代码 
$ sudo port install spring-boot-cli
命令行（Command-line Completion）

Spring Boot CLI 包含 BASH 和 zsh shell 提供的命令行脚本。你可以在任意shell上运行 source 脚本（也称之为 spring）或者将它放到您个人或者 system-wide bash 完成初始化。在 Debian 系统上，system-wide 脚本位于 /shell-completion/bash ，启动一个新shell执行该文件下的所有脚本。例如，如果您使用 SDKMAN! 手动安装，要运行脚本，请使用以下命令：

shell 复制代码 
$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring <HIT TAB HERE>
  grab  help  jar  run  test  version

::: tip 提示

如果使用Homebrew或MacPorts安装Spring Boot CLI，则命令行脚本将其自动注册到shell。

:::

Windows Scoop 安装（Windows Scoop Installation）

如果您使用的是 Windows 并使用 Scoop，你可以通过以下命令安装 Spring Boot CLI：

> scoop bucket add extras
> scoop install springboot

Scoop 会将spring 安装到 ~/scoop/apps/springboot/current/bin 文件夹下。

::: tip 提示

如果您没有看到应用清单，你的安装 Scoop 不是最新的，在这种情况下，请运行scoop update 并重试。

:::

快速启动Spring CLI实例（Quick-start Spring CLI Example）

您可以使用以下Web应用程序来测试您的安装。首先，创建一个 app.groovy 文件，如下所示：

groovy 复制代码 
@RestController
class ThisWillActuallyRun {

    @RequestMapping("/")
    String home() {
        "Hello World!"
    }

}

然后使用shell来运行她，如下所示：

shell 复制代码 
$ spring run app.groovy

::: tip 提示

因为依赖项需要下载，应用程序的第一次运行速度很慢。后续启动则要快得多。

:::

在浏览器中打开 localhost:8080 。你可以看到以下输出：

Hello World!

4.4 开发第一个Spring Boot 应用程序（Developing Your First Spring Boot Application）

本节介绍如果开发一个简单的 "Hello World!" Web 应用程序，该应用程序突显了 Spring Boot 的一些主要功能。我们可以使用 Maven 来构建这个项目，大多数 IDE 都支持它。

::: tip 提示
spring.io 网站包含了许多使用 Spring Boot 的入门指南。如果您需要解决特定问题，请先检查一下。您可以跳转 start.spring.io 网站，从依赖管理搜索器中选择 "Web" starter，来快速的创建项目。这样操作会生成一个新的项目结构，以便于您可以 立即开始编码。

如果需要获取更多详细信息，参阅 start.spring.io user guide 。

:::

在开始之前，打开终端并运行以下命令以确保您安装了有效版本的 Java 和 Maven：

shell 复制代码 
$ java -version
java version "1.8.0_102"
Java(TM) SE Runtime Environment (build 1.8.0_102-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.102-b14, mixed mode)
shell 复制代码 
$ mvn -v
Apache Maven 3.5.4 (1edded0938998edf8bf061f1ceb3cfdeccf443fe; 2018-06-17T14:33:14-04:00)
Maven home: /usr/local/Cellar/maven/3.3.9/libexec
Java version: 1.8.0_102, vendor: Oracle Corporation

::: tip 提示

上述示例需要在您的文件夹中创建。后续说明中已经假定您已创建对应文件夹，并且它是您的当前目录。

:::

4.4.1 创建POM（Creating the POM）

我们需要先创建一个 Maven pom.xml 文件。 pom.xml 用来构建您的项目。 打开文件编辑器并添加以下内容：

xml 复制代码 
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>example</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.18-SNAPSHOT</version>
    </parent>

    <!-- Additional lines to be added here... -->

    <!-- (you only need this if you are using a milestone or snapshot version) -->
    <repositories>
        <repository>
            <id>spring-snapshots</id>
            <url>https://repo.spring.io/snapshot</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>spring-milestones</id>
            <url>https://repo.spring.io/milestone</url>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>spring-snapshots</id>
            <url>https://repo.spring.io/snapshot</url>
        </pluginRepository>
        <pluginRepository>
            <id>spring-milestones</id>
            <url>https://repo.spring.io/milestone</url>
        </pluginRepository>
    </pluginRepositories>
</project>

上述内容为您提供一个有效的构建。你可以运行 mvn package 来测试它（现在，你可以忽略"jar will be empty - no content was marked for inclusion!" 的警告）。

::: tip 提示

此时，您可以将项目导入IDE（大多数Java IDE包含对Maven的内置支持）。为简单起见，我们继续为此示例使用纯文本编辑器。

:::

4.4.2 添加路径依赖（Adding Classpath Dependencies）

您可以将 Spring Boot 提供的一些 "Starters" 添加到您的 classpath。我们的业务应用已经在POM的parent 部分使用了 spring-boot-starter-parent 。spring-boot-starter-parent 是一个特殊的 starter，它提供了很多 Maven 依赖的默认值。它还提供一个 dependency-management 标签，以便您可以省略依赖项中的 version 标签。

其他 "Starters" 提供了开发特定应用程序所需要的依赖项。由于我们正在开发Web应用程序，我们需要添加 spring-boot-starter-web 依赖项。在此之前，我们可以通过运行以下命令查看当前内容：

shell 复制代码 
$ mvn dependency:tree

[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT

mvn dependency:tree 命令会打印项目依赖项的树状展示。你可以看到 spring-boot-starter-parent 本身不提供依赖关系。如果需要添加必要的依赖项，请修改 pom.xml 并在parent 部分下方添加 spring-boot-starter-web 依赖项：

xml 复制代码 
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

如果再次运行 mvn dependency:tree 命令，您可以看到许多其它的依赖项，包含 Tomcat web 服务器和 Spring Boot 本身。

4.4.3 写代码（Writing the Code）

如果要完成我们的应用程序，我们需要创建一个 Java 文件。默认情况下，Maven 会编译 src/main/java 下的文件，所以您需要创建该文件夹结构，然后添加一个名为 src/main/java/MyApplication.java 的文件，如下所示：

java 复制代码 
package com.example;

@RestController
@SpringBootApplication
public class MyApplication {

    @RequestMapping("/")
    String home() {
        return "Hello World!";
    }

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

}

虽然这里代码不多，但是还有很多事情要做。在接下来的几个章节，我们将逐步介绍重要部分：

@RestController和@RequestMapping注解（The @RestController and @RequestMapping Annotations）

MyApplication 类的第一个注解是 @RestController。这就是 构造型 注解。它为阅读代码的人和Spring 提供标识，表明该类扮演着特定角色。在本示例中，我们的类是一个Web @Controller，因此 在处理传入的Web请求时，Spring会发现它。

@RequestMapping 注解提供了 "路由" 信息。它告诉 Spring 任何带有 / 路径的HTTP请求都应该映射到 home 方法。 @RestController 注解会告诉 Spring 直接将方法返回的字符串结果直接渲染返回给调用者。

::: tip 提示
@RestController 和@RequestMapping注解是Spring MVC注解（它们不是Spring Boot特有的）。有关详细信息，请参阅Spring文档中的MVC 部分。

:::

@SpringBootApplication 注解（The @SpringBootApplication Annotation）

第二个类上的注解是 @SpringBootApplication。这个注解被称之为 元组件 ，它将 @SpringBootConfiguration，@EnableAutoConfiguration 和 @ComponentScan组合在一起。

其中，我们最感兴趣的注解是 @EnableAutoConfiguration。@EnableAutoConfiguration 会让 Spring Boot 基于你添加的jar依赖关系"猜测"你想如何配置Spring。由于 spring-boot-starter-web 添加了 Tomcat 和 Spring MVC，因此自动配置会假定你正在开发Web应用程序并相应的配置Spring。

::: tip Starters and Auto-configuration

自动配置旨在与 "Starters" 配合使用，但是这两个概念并不直接相关。您可以自由选择jar依赖项。Spring Boot 仍然会尽力自动配置您的应用程序。

:::

main方法（The "main" Method）

我们应用程序的第一部分是 main 方法。这只是遵循应用程序入口点的Java约定的标准方法。我们的 main 方法的主要功能就是通过调用 Spring Boot 的 SpringApplication 类中的 run 方法. SpringApplication 引导应用程序，启动 Spring，然后启动自动配置的Tomcat Web服务器。我们需要将 MyApplication.class 作为一个参数传入 run 方法，来告诉 SpringApplication 哪个是 Spring 主组件。还可以通过命令行参数的形式传递 args 数组参数

4.4.4 运行示例（Running the Example）

至此，你的应用应该可以正常运行了。由于你使用了 spring-boot-starter-parent POM，因此你可以使用 run 命令来启动应用程序。在项目的根目录下，输入命令行 mvn spring-boot:run 用来启动应用程序。您会看到类似于以下内容的输出：

shell 复制代码 
$ mvn spring-boot:run

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v2.7.18-SNAPSHOT)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 2.222 seconds (JVM running for 6.514)

如果你使用浏览器打开 localhost:8080，你可以看到如下输出：

Hello World!

如果想退出应用程序，请按 ctrl-c。

4.4.5 创建一个可执行的Jar（Creating an Executable Jar）

最后，我们将创建一个完全独立的可执行jar文件，以便于在生产环境中运行。可执行jars （有时称为 "fat jars"）是包含编译过的类以及代码运行所需要的全部jar依赖项。

::: tip Executable jars and Java

Java 未提供加载嵌套jar文件（本身包含在jar中的jar文件夹）的标准方法。如果你想发布一个独立的应用程序，这可以会造成问题。

为了解决这个问题，许多开发人员使用 "uber "jar。uber jar 将应用程序所有依赖项中的所有类都打包到一个压缩包中。 这种方法的问题是很难看出应用程序中包含哪些库。如果在多个 jar 中使用相同的文件名（但内容不同），也会造成问题。

Spring Boot 采用 不同的方法 让你可以直接嵌套 jar。

:::

如果要创建可执行jar，我们需要将 spring-boot-maven-plugin 添加到 pom.xml。因此，需要在 dependencies 部分下方插入以下内容：

xml 复制代码 
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

::: tip 提示

spring-boot-starter-parent POM 的<executions> 标签中配置了 repackage goal. 如果你不适用父 POM，你需要自行声明该配置。详情请查看 plugin documentation。

xml 复制代码 
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <executions>
            <execution>
                <goals>
                    <goal>repackage</goal>
                </goals>
            </execution>
        </executions>
    </plugins>
</build>

:::

保存你的 pom.xml 文件，然后在命令行中执行 mvn package ，如下所示：

shell 复制代码 
$ mvn package

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myproject 0.0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] .... ..
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject ---
[INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:2.7.18-SNAPSHOT:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

如果你查看 target 文件夹，你可以看到 myproject-0.0.1-SNAPSHOT.jar。该文件大学应该在18 MB左右。如果需要查看jar里面，你可以使用 jar tvf，如下：

shell 复制代码 
$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar

你应该在target目录中还可以看到名为 myproject-0.0.1-SNAPSHOT.jar.original 的小文件。这是Maven在Spring Boot重新打包之前创建的原始jar文件。

如果要运行该应用程序，使用命令 java -jar ，如下：

shell 复制代码 
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v2.7.18-SNAPSHOT)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 2.536 seconds (JVM running for 2.864)

退出应用程序，请按 ctrl-c。

4.5 接下来要阅读的内容（What to Read Next）

本章节提供了一些 Spring Boot 的基础知识，让您开始编写自己的应用程序。如果您是以任务为导向的开发人员，你可能希望跳转到 spring.io 并查看一些 入门指南 ，这些指南解决了 "我如何使用 Spring？" 的问题。我们还有专门针对 Spring Boot "How-to" 的参考文档。

否则，下一步就是阅读 使用 Spring Boot 开发 。如果您非常着急，你可以提前阅读 Spring Boot 功能.

5. 升级 Spring Boot（Upgrading Spring Boot）

项目 wiki 提供如何从 Spring Boot 早期版本升级的说明。请按照 release notes 部分查找要升级到的版本。

升级说明总是版本说明的第一部分。如果您的版本落后一个以上，请确保您已经查看了所跳过版本的发行说明。

5.1 从 1.x 升级（Upgrading From 1.x）

如果您要从Spring Boot 的 1.x 版本升级，请查看项目 wiki 上的 "迁移指南"，其中提供了详细的升级说明。还可以查看 "发行说明" ，了解每个版本的 "新功能和值得注意的功能"。

5.2 升级到新功能版本（Upgrading to a New Feature Release）

升级到新功能版本时，一些属性可能会被重命名或移除。Spring Boot 提供了一种在启动的时候分析应用程序环境并打印分析结果的方法，而且还可以在运行时为您临时迁移属性。要启用该功能，请在您的项目中添加以下依赖关心：

xml 复制代码 
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

::: warning 警告

在使用 @PropertySource 时，较晚添加到环境中的属性将不会被考虑在内。

:::

::: tip 提示

完成迁移后，请确保从项目的依赖关系中移除该模块。

:::

5.3 升级 Spring Boot CLI（Upgrading the Spring Boot CLI）

要升级现有的 CLI ，请使用相应的软件包管理器的命令（例如， brew upgrade）。如果您手动安装了 CLI，请遵循 标准说明，记住需要更新的 PATH 环境变量，以便移除旧的引用。

5.4 接下来要阅读的内容（What to Read Next）

一旦您决定升级您的应用程序，您可以在本文档的其余部分找到有关特定功能的详细信息。

本 Spring Boot 文档就是针对该版本，因此您在这里找的任何信息都将会包含该版本的最新修改。

6. 使用 Spring Boot进行开发（Developing with Spring Boot）

本节详细介绍了如何使用Spring Boot。它涵盖考虑构建系统、自动配置以及如何运行应用程序等主题。我们还介绍一些 Spring Boot 最新做法。虽然 Spring Boot 没有什么特别之处（它只是你使用的一个库），它会有一些建议，当您遵循这些建议，可以使您的开发过程更容易一些。

如果您从 Spring Boot 开始，在进入本章节之前，你应该阅读 入门指南 。

6.1 构建系统（Build Systems）

强烈建议您选择一个 依赖管理 来构建项目，而且可以使用发布到 "Maven Central" 库的组件。我们建议您选择 Maven 或 Gradle。你也可以让 Spring Boot 和其它构建系统（例如Ant）配合使用，但是它们的支持并不完善。

6.1.1 依赖管理（Dependency Management）

Spring Boot 的每个版本都会提供其支持的依赖项列表。实际上，你不需要提供构建配置中依赖项的版本，因为Spring Boot 会为您管理这些依赖项。当您升级 Spring Boot 本身时，这些依赖项也会统一升级。

::: tip 提示

如果需要，您仍然可以指定依赖版本并覆盖 Spring Boot 的设置版本。

:::

列表中包含了所有的 Spring 模块，以及第三方库的详细列表。该列表以标准清单spring-boot-dependencies的形式提供，可以与 Maven 和 Gradle 一起使用。

::: warning 警告

Spring Boot 的每个版本都与 Spring Framework 的集成版本息息相关。我们强烈建议你不要指定它的版本。

:::

6.1.2 Maven

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

6.1.3 Gradle

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

6.1.4 Ant

使用 Apache Ant+Ivy 可以构建 Spring Boot 项目。此外，"AntLib" 模块 spring-boot-antlib 可以帮助 Ant 创建可执行jar。

如果要声明依赖关系， ivy.xml 文件应与下方示例类似：

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 文件应与下方示例类似：

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.7.18-SNAPSHOT"/>

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

::: tip 提示

如果不想使用 spring-boot-antlib 模块，请参阅 Build an Executable Archive From Ant without Using spring-boot-antlib 。

:::

6.1.5 Starters

场景启动器是一组依赖关系的描述，您可以将其包含在应用程序中。你可以获得所需的全部 Spring 以及相关技术的一站式服务，而无需搜索示例代码和复制粘贴依赖描述符。例如，如果您开始使用 Spring 和 JPA 进行数据库访问，请在项目中包含 spring-boot-starter-data-jpa 依赖。

场景启动器包含大量的依赖项，这些依赖项可以让项目快速启动和运行,并提供一套一致的、受支持的依赖项传递。

::: tip What is in a name

所有官方 场景启动器都遵循类型的命名模式； spring-boot-starter-*，其中 * 为特定类型的应用程序。这种命名结构的目的是需要查找场景启动器时提供帮助。许多集成开发环境中的 Maven 都可以让您按名称搜索依赖项。例如，如果安装了相应的 Eclipse 或 Spring 插件，就可以在 POM 编辑器中键入 ctrl-space 键，然后键入"spring-boot-starter"，查看完整列表。

在 "创建自己的场景启动器" 部分所述，第三方启动器不应该以spring-boot开头，因为spring-boot是 Spring Boot 官方库的专属开通。相反，第三方启动器通常以项目名称开通，例如，名为 thirdpartyproject 的第三方启动器通常会命名为thirdpartyproject-spring-boot-starter。

:::

以下场景启动器是 Spring Boot 官方提供的，都属于 org.springframework.boot 组：

表 1. Spring Boot 应用程序启动器

Name Description
spring-boot-starter 核心启动器，包括自动配置、日志记录和 YAML
spring-boot-starter-activemq 集成 Apache ActiveMQ 的 JMS messaging 启动器
spring-boot-starter-amqp 集成 Spring AMQP 和 Rabbit MQ 的启动器
spring-boot-starter-aop 集成 Spring AOP 和 AspectJ 进行面向切面编程的启动器
spring-boot-starter-artemis 集成 Apache Artemis 的 JMS messaging 启动器
spring-boot-starter-batch 集成 Spring Batch 的启动器
spring-boot-starter-cache 集成 Spring Framework 缓存支持的启动器
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 集成 Elasticsearch 搜索、分析引擎和 Spring Data Elasticsearch 的启动器
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 Reactive 的启动器
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 reactive 和 Lettuce 客户端的启动器
spring-boot-starter-data-rest 使用 Spring Data REST 和 Spring MVC 通过 REST 访问 Spring Data存储库的启动器
spring-boot-starter-freemarker 使用 FreeMarker 视图构建 MVC 网络应用程序的启动器
spring-boot-starter-graphql 使用 Spring GraphQL 构建 GraphQL 应用程序的启动器
spring-boot-starter-groovy-templates 使用 Groovy 模板视图构建 MVC 网络应用程序的启动器
spring-boot-starter-hateoas 使用 Spring MVC 和 Spring HATEOAS 构建基于超媒体的 RESTful 网络应用程序的启动器
spring-boot-starter-integration 集成 Spring Integration 的启动器
spring-boot-starter-jdbc 集成 HikariCP 连接池的JDBC启动器
spring-boot-starter-jersey 使用 JAX-RS 和 Jersey 构建 RESTful 网络应用程序的启动器。可以代替 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-jta-atomikos 使用 Atomikos 进行 JTA 事务的启动器
spring-boot-starter-mail 使用 Java Mail 和 Spring Framework 电子邮件支持发送的启动器
spring-boot-starter-mustache 使用 Mustache 视图构建网络应用程序的启动器
spring-boot-starter-oauth2-client 使用 Spring Security 的 OAuth2/OpenID 连接客户端功能的启动器
spring-boot-starter-oauth2-resource-server 使用 Spring Security 的 OAuth2 资源服务功能的启动器
spring-boot-starter-quartz 集成 Quartz scheduler 的启动器
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 使用 Thymeleaf 视图构建 MVC 应用程序的启动器
spring-boot-starter-validation 使用 Hibernate 验证器进行 Java Bean 验证的启动器
spring-boot-starter-web 使用 Spring MVC 构建Web（包括 RESTful）应用程序的启动器。使用 Tomcat 作为默认嵌入式容器
spring-boot-starter-web-services 集成 Spring Web Services 的启动器
spring-boot-starter-webflux 使用 Spring Framework 的 Reactive Web 支持构建 WebFlux 应用程序的启动器
spring-boot-starter-websocket 使用 Spring Framework 的 WebSocket 支持构建WebSocket启动器

除应用程序启动器外，还可使用以下启动器添加 production ready 功能：

表 2. Spring Boot 生产环境启动器

Name Description
spring-boot-starter-actuator 使用 Spring Boot 的 Actuator 的启动器，它提供production ready功能，帮助您监控和管理应用程序

最后，Spring Boot 还包括一些用于排除或交换特定技术方向的启动器：

表 3. Spring Boot 技术启动器

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 使用 Reactor Netty 作为嵌入式响应式 HTTP 服务器的启动器
spring-boot-starter-tomcat 使用 Tomcat 作为嵌入式 servlet 容器的启动器。使用默认 servlet 容器启动器 spring-boot-starter-web
spring-boot-starter-undertow 使用 Undertow 作为嵌入式 servlet 容器的启动器。可以替代 spring-boot-starter-tomcat

要深入了解技术交互方向的知识，请参阅r swapping web server 和 logging system。

::: tip 提示

有关其他社区贡献的启动器列表，请参阅 GitHub 上的spring-boot-starters模块的 README 文件 。

:::

6.2 构建你的代码（Structuring Your Code）

Spring Boot 不需要任何特定的代码结构。然而，也有一些最佳实现是很有帮助的。

6.2.1 使用默认包（Using the "default" Package）

当一个类不包含 package 声明。它通常被认为在一个"默认包"中。一般不建议使用 "默认包" ，应该避免使用。它会给使用 @ComponentScan, @ConfigurationPropertiesScan, @EntityScan或 @SpringBootApplication 注解的 Spring Boot 应用程序带来很多问题，因为每个 jar 中的每个类都会被读取。

::: tip 提示

我们建议您遵循 Java 推荐的软件包命名约定，并使用相反的域名（例如，com.example.project）。

:::

6.2.2 定位主程序类（Locating the Main Application Class）

我们通常建议将主程序类放到根包中。 @SpringBootApplication 注解 会放在主类上，它隐式地为某些项目定义了一个基础的 "search package" 。例如，如果你正在编写一个 JPA 应用程序，那么使用 @SpringBootApplication 注解的类所在的包将会搜索 @Entity 。使用根包还可以让组件只应用到你的项目。

::: tip 提示

如果你不使用 @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，如下所示：

java 复制代码 
@SpringBootApplication
public class MyApplication {

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

}

6.3 配置类（Configuration Classes）

Spring Boot 偏好基于 Java 的配置。虽然可以将. SpringApplication 和 XML 结合使用，但是我们通常建议您将一个 @Configuration 类作为主要来源。通常，定义的 main 方法的类适合作为主要的 @Configuration。

::: tip 提示

在互联网上发布了很多使用XML配置的Spring配置示例，如果可能，请尽量使用基于Java的等效配置。搜索 Enable* 注解是一个很多方法。

:::

6.3.1 导入其它配置类（Importing Additional Configuration Classes）

你不需要把全部的 @Configuration 放在一个类中。 @Import 注解可以用于导入其它配置类。或者，您可以使用 @ComponentScan 主动扫描注入全部的Spring组件，包括 @Configuration 。

6.3.2 导入XML配置（Importing XML Configuration）

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

6.4 自动配置（Auto-configuration）

Spring Boot 自动配置会尝试根据您添加的jar依赖关系自动配置您的 Spring 应用程序。例如，如果 HSQLDB 在类路径上，而您没有手动配置任何数据库连接nean，则 Spring Boot 会自动配置内存数据库。

你需要在其中一个 @Configuration 类中添加@EnableAutoConfiguration 或 @SpringBootApplication 注解，从而添加自动配置功能

::: tip 提示

你只能添加一个 @SpringBootApplication 或 @EnableAutoConfiguration 注解。我们通常建议你只在主要的 @Configuration 添加其中一个组件。

:::

6.4.1 逐步取代自动配置（Gradually Replacing Auto-configuration）

自动配置是非侵入性的。在任何时候，你都可以开始定义自己的配置，用来取代自动配置的特定部分。例如，如果您添加了自己的 DataSource bean，默认嵌入式数据库不在进行支持。

个你需要了解当前应用的自动配置及其原因，请使用 --debug 开关启动应用程序。这样做可以为选定的核心日志记录器启用debug日志，并将报告记录到控制台。

6.4.2 禁用特定的自动配置类（Disabling Specific Auto-configuration Classes）

如果你发现当前应用中您不需要的特定自动配置类，你可以使用 @SpringBootApplication 的exclude属性来禁用它们，如下所示：

java 复制代码 
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class MyApplication {

}

如果类不在classpath上，可以使用注解的 excludeName 属性来指定全限定类名。如果你更倾向于使用 @EnableAutoConfiguration 而不是 @SpringBootApplication，也可以使用exclude 和 excludeName，最后，你可以使用 spring.autoconfigure.exclude 属性来控制需要排除的自动配置类列表。

::: tip 提示

您可以在注解级别的和使用属性来定义排除项。

:::

::: tip 提示

尽管自动配置类是 public，但是该类唯一被认为公共API的部分是类名，该名称可用于禁用自动配置。这些类的实际内容（比如嵌套配置类或bean方法）仅供内部使用，我们不建议直接使用这些。

:::

6.4.3 自动配置包路径（Auto-configuration Packages）

自动配置包路径是各种自动配置功能扫描实体和Spring Data repositories默认查找的包路径。 @EnableAutoConfiguration 注解（或者直接通过@SpringBootApplication）来决定默认的自动配置包路径。可以使用@AutoConfigurationPackage注解配置其它软件包路径。

6.5 Spring Beans 和依赖注入（Spring Beans and Dependency Injection）

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

如果你按照上面的建议（将主程序类放到顶级包中）修改代码架构，你就可以添加 @ComponentScan （无需任何参数）或者使用 @SpringBootApplication （包含前者）。所有的应用程序组件（@Component, @Service, @Repository, @Controller等）都会自动注入成 Spring Bean。

下面的示例显示了一个使用构造器注入获取所需 RiskAssessor Bean 的 @Service Bean：

java 复制代码 
@Service
public class MyAccountService implements AccountService {

    private final RiskAssessor riskAssessor;

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

    // ...

}

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

java 复制代码 
@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;
    }

    // ...

}

::: tip 提示

请注意，使用构造器注入可以将 riskAssessor 字段标记为 final 字段，表示以后不能更改。

:::

6.6 使用@SpringBootApplication注解（Using the @SpringBootApplication Annotation）

许多 Spring Boot 开发人员都希望自己的应用程序能够使用自动配置、组件扫描，并能在 "application class"定义额外的配置。只需要使用 @SpringBootApplication 注解就可以启用这三个功能，即：

  • @EnableAutoConfiguration：启用 Spring Boot 的自动配置机制
  • @ComponentScan：在应用程序所在包路径上启动 @Component 扫描 (参阅 the best practices)
  • @SpringBootConfiguration：启用在上下文中注册额外的 Bean 或导入额外的配置类。她是Spring标准 @Configuration 的替代品，有助于集成测试红的 configuration detection 。
java 复制代码 
// Same as @SpringBootConfiguration @EnableAutoConfiguration @ComponentScan
@SpringBootApplication
public class MyApplication {

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

}

::: tip 提示

@SpringBootApplication 提供了别名来自定义 @EnableAutoConfiguration 和 @ComponentScan 的属性。

:::

::: tip 提示

这些功能都不是强制性的，你可以选择用它所启用的任何功能来替代这个单一注解。例如，您可能不想在应用程序中使用组件扫描或配置属性扫描：

java 复制代码 
@SpringBootConfiguration(proxyBeanMethods = false)
@EnableAutoConfiguration
@Import({ SomeConfiguration.class, AnotherConfiguration.class })
public class MyApplication {

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

}

在上述示例中， MyApplication 和其它 Spring Boot 应用程序一样，只是 @Component-annotated 类和 @ConfigurationProperties-annotated 类不会被自动扫描到，而用户定义Bean的会被显式导入 (参阅 @Import)。

:::

6.7 运行应用程序（Running Your Application）

One of the biggest advantages of packaging your application as a jar and using an embedded HTTP server is that you can run your application as you would any other. The sample applies to debugging Spring Boot applications. You do not need any special IDE plugins or extensions.

::: tip 备注

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

:::

6.7.1. Running From an IDE

You can run a Spring Boot application from your IDE as a Java application. However, you first need to import your project. Import steps vary depending on your IDE and build system. Most IDEs can import Maven projects directly. For example, Eclipse users can select Import... → Existing Maven Projects from the File menu.

If you cannot directly import your project into your IDE, you may be able to generate IDE metadata by using a build plugin. Maven includes plugins for Eclipse and IDEA. Gradle offers plugins for various IDEs.

::: tip 提示

更多操作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.

:::

6.7.2. Running as a Packaged Application

If you use the Spring Boot Maven or Gradle plugins to create an executable jar, you can run your application using java -jar, as shown in the following example:

shell 复制代码 
$ java -jar target/myapplication-0.0.1-SNAPSHOT.jar

It is also possible to run a packaged application with remote debugging support enabled. Doing so lets you attach a debugger to your packaged application, as shown in the following example:

shell 复制代码 
$ java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n \
       -jar target/myapplication-0.0.1-SNAPSHOT.jar
6.7.3. Using the Maven Plugin

The Spring Boot Maven plugin includes a run goal that can be used to quickly compile and run your application. Applications run in an exploded form, as they do in your IDE. The following example shows a typical Maven command to run a Spring Boot application:

shell 复制代码 
$ mvn spring-boot:run

You might also want to use the MAVEN_OPTS operating system environment variable, as shown in the following example:

shell 复制代码 
$ export MAVEN_OPTS=-Xmx1024m
6.7.4. Using the Gradle Plugin

The Spring Boot Gradle plugin also includes a bootRun task that can be used to run your application in an exploded form. The bootRun task is added whenever you apply the org.springframework.boot and java plugins and is shown in the following example:

$ gradle bootRun

You might also want to use the JAVA_OPTS operating system environment variable, as shown in the following example:

$ export JAVA_OPTS=-Xmx1024m
6.7.5. Hot Swapping

Since Spring Boot applications are plain Java applications, JVM hot-swapping should work out of the box. JVM hot swapping is somewhat limited with the bytecode that it can replace. For a more complete solution, JRebel can be used.

The spring-boot-devtools module also includes support for quick application restarts. See the Hot swapping "How-to" for details.

6.8. Developer Tools

Spring Boot includes an additional set of tools that can make the application development experience a little more pleasant. The spring-boot-devtools module can be included in any project to provide additional development-time features. To include devtools support, add the module dependency to your build, as shown in the following listings for Maven and Gradle:

Maven

xml 复制代码 
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

Gradle

gradle 复制代码 
dependencies {
    developmentOnly("org.springframework.boot:spring-boot-devtools")
}

::: tip 注意事项

Devtools might cause classloading issues, in particular in multi-module projects. Diagnosing Classloading Issues explains how to diagnose and solve them.

:::

::: tip 提示

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.

:::

::: tip 提示

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.

:::

::: tip 提示

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.

:::

6.8.1. Diagnosing Classloading Issues

As described in the Restart vs Reload section, restart functionality is implemented by using two classloaders. For most applications, this approach works well. However, it can sometimes cause classloading issues, in particular in multi-module projects.

To diagnose whether the classloading issues are indeed caused by devtools and its two classloaders, try disabling restart. If this solves your problems, customize the restart classloader to include your entire project.

6.8.2. Property Defaults

Several of the libraries supported by Spring Boot use caches to improve performance. For example, template engines cache compiled templates to avoid repeatedly parsing template files. Also, Spring MVC can add HTTP caching headers to responses when serving static resources.

While caching is very beneficial in production, it can be counter-productive during development, preventing you from seeing the changes you just made in your application. For this reason, spring-boot-devtools disables the caching options by default.

Cache options are usually configured by settings in your application.properties file. For example, Thymeleaf offers the spring.thymeleaf.cache property. Rather than needing to set these properties manually, the spring-boot-devtools module automatically applies sensible development-time configuration.

The following table lists all the properties that are applied:

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.graphql.graphiql.enabled true
spring.groovy.template.cache false
spring.h2.console.enabled true
spring.mustache.servlet.cache false
spring.mvc.log-resolved-exception true
spring.reactor.netty.shutdown-quiet-period 0s
spring.template.provider.cache false
spring.thymeleaf.cache false
spring.web.resources.cache.period 0
spring.web.resources.chain.cache false

::: tip 备注

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

:::

Because you need more information about web requests while developing Spring MVC and Spring WebFlux applications, developer tools suggests you to enable DEBUG logging for the web logging group. This will give you information about the incoming request, which handler is processing it, the response outcome, and other details. If you wish to log all request details (including potentially sensitive information), you can turn on the spring.mvc.log-request-details

or spring.codec.log-request-details configuration properties.

6.8.3. Automatic Restart

Applications that use spring-boot-devtools automatically restart whenever files on the classpath change. This can be a useful feature when working in an IDE, as it gives a very fast feedback loop for code changes. By default, any entry on the classpath that points to a directory is monitored for changes. Note that certain resources, such as static assets and view

templates, do not need to restart the application.

::: tip Triggering a restart

As DevTools monitors classpath resources, the only way to trigger a restart is to update the classpath. Whether you're using an IDE or one of the build plugins, the modified files have to be recompiled to trigger a restart. The way in which you cause the classpath to be updated depends on the tool that you are using:

  • In Eclipse, saving a modified file causes the classpath to be updated and triggers a restart.
  • In IntelliJ IDEA, building the project (Build +→+ Build Project) has the same effect.
  • If using a build plugin, running mvn compile for Maven or gradle build for Gradle will trigger a restart.

:::

::: tip 备注

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.

:::

::: tip 提示

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.

:::

::: tip 备注

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

:::

::: tip 备注

更多操作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.

:::

::: tip 注意事项

Automatic restart is not supported when using AspectJ weaving.

:::

::: tip Restart vs Reload

The restart technology provided by Spring Boot works by using two classloaders. Classes that do not change (for example, those from third-party jars) are loaded into a base classloader. Classes that you are actively developing are loaded into a restart classloader. When the application is restarted, the restart classloader is thrown away and a new one is created. This approach means that application restarts are typically much faster than "cold starts", since the base classloader is

already available and populated.

If you find that restarts are not quick enough for your applications or you encounter classloading issues, you could consider reloading technologies such as JRebel from ZeroTurnaround. These work by rewriting classes as they are loaded to make them more amenable to reloading.

:::

Logging Changes in Condition Evaluation

By default, each time your application restarts, a report showing the condition evaluation delta is logged. The report shows the changes to your application's auto-configuration as you make changes such as adding or removing beans and setting configuration properties.

To disable the logging of the report, set the following property:

Properties

Yaml

yaml 复制代码 
spring:
  devtools:
    restart:
      log-condition-evaluation-delta: false
Excluding Resources

Certain resources do not necessarily need to trigger a restart when they are changed. For example, Thymeleaf templates can be edited in-place. By default, changing resources in /META-INF/maven, /META-INF/resources, /resources, /static, /public, or /templates does not trigger a restart but does trigger a live reload. If you want to customize these exclusions, you can use

the spring.devtools.restart.exclude property. For example, to exclude only /static and /public you would set the following property:

Properties

Yaml

yaml 复制代码 
spring:
  devtools:
    restart:
      exclude: "static/**,public/**"

::: tip 提示

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

:::

Watching Additional Paths

You may want your application to be restarted or reloaded when you make changes to files that are not on the classpath. To do so, use the spring.devtools.restart.additional-paths property to configure additional paths to watch for changes. You can use the spring.devtools.restart.exclude property described earlier to control whether changes beneath the additional paths

trigger a full restart or a live reload.

Disabling Restart

If you do not want to use the restart feature, you can disable it by using the spring.devtools.restart.enabled property. In most cases, you can set this property in your application.properties (doing so still initializes the restart classloader, but it does not watch for file changes).

If you need to completely disable restart support (for example, because it does not work with a specific library), you need to set the spring.devtools.restart.enabled System property to false before calling SpringApplication.run(...), as shown in the following example:

Java

Kotlin

java 复制代码 
@SpringBootApplication
public class MyApplication {

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

}
Using a Trigger File

If you work with an IDE that continuously compiles changed files, you might prefer to trigger restarts only at specific times. To do so, you can use a "trigger file", which is a special file that must be modified when you want to actually trigger a restart check.

::: tip 备注

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

:::

To use a trigger file, set the spring.devtools.restart.trigger-file property to the name (excluding any path) of your trigger file. The trigger file must appear somewhere on your classpath.

For example, if you have a project with the following structure:

src
+- main
   +- resources
      +- .reloadtrigger

Then your trigger-file property would be:

Properties

Yaml

yaml 复制代码 
spring:
  devtools:
    restart:
      trigger-file: ".reloadtrigger"

Restarts will now only happen when the src/main/resources/.reloadtrigger is updated.

::: tip 提示

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

:::

Some IDEs have features that save you from needing to update your trigger file manually. Spring Tools for Eclipse and IntelliJ IDEA (Ultimate Edition) both have such support. With Spring Tools, you can use the "reload" button from the console view (as long as your trigger-file is named .reloadtrigger). For IntelliJ IDEA, you can follow

the instructions in their documentation.

Customizing the Restart Classloader

As described earlier in the Restart vs Reload section, restart functionality is implemented by using two classloaders. If this causes issues, you might need to customize what gets loaded by which classloader.

By default, any open project in your IDE is loaded with the "restart" classloader, and any regular .jar file is loaded with the "base" classloader. The same is true if you use mvn spring-boot:run or gradle bootRun: the project containing your @SpringBootApplication is loaded with the "restart" classloader, and everything else with the "base" classloader.

You can instruct Spring Boot to load parts of your project with a different classloader by creating a META-INF/spring-devtools.properties file. The spring-devtools.properties file can contain properties prefixed with restart.exclude and restart.include. The include elements are items that should be pulled up into the "restart" classloader, and the exclude elements are items that should be pushed down into the "base" classloader. The value of the property is a regex pattern that is

applied to the classpath, as shown in the following example:

Properties

Yaml

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

::: tip 备注

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

:::

::: tip 提示

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.

:::

Known Limitations

Restart functionality does not work well with objects that are deserialized by using a standard ObjectInputStream. If you need to deserialize data, you may need to use Spring's ConfigurableObjectInputStream in combination with Thread.currentThread().getContextClassLoader().

Unfortunately, several third-party libraries deserialize without considering the context classloader. If you find such a problem, you need to request a fix with the original authors.

6.8.4. LiveReload

The spring-boot-devtools module includes an embedded LiveReload server that can be used to trigger a browser refresh when a resource is changed. LiveReload browser extensions are freely available for Chrome, Firefox and Safari. You can find these extensions by searching 'LiveReload' in the marketplace or store of your chosen browser.

If you do not want to start the LiveReload server when your application runs, you can set the spring.devtools.livereload.enabled property to false.

::: tip 备注

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.

:::

::: warning 警告

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

:::

6.8.5. Global Settings

You can configure global devtools settings by adding any of the following files to the $HOME/.config/spring-boot directory:

  1. spring-boot-devtools.properties
  2. spring-boot-devtools.yaml
  3. spring-boot-devtools.yml

Any properties added to these files apply to all Spring Boot applications on your machine that use devtools. For example, to configure restart to always use a trigger file, you would add the following property to your spring-boot-devtools file:

Properties

Yaml

yaml 复制代码 
spring:
  devtools:
    restart:
      trigger-file: ".reloadtrigger"

By default, $HOME is the user's home directory. To customize this location, set the SPRING_DEVTOOLS_HOME environment variable or the spring.devtools.home system property.

::: tip 备注

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.

:::

::: tip 备注

Profiles are not supported in devtools properties/yaml files.Any profiles activated in .spring-boot-devtools.properties will not affect the loading of profile-specific configuration files. Profile specific filenames (of the form spring-boot-devtools-<profile>.properties) and spring.config.activate.on-profile documents in both YAML and Properties files are not

supported.

:::

Configuring File System Watcher

FileSystemWatcher works by polling the class changes with a certain time interval, and then waiting for a predefined quiet period to make sure there are no more changes. Since Spring Boot relies entirely on the IDE to compile and copy files into the location from where Spring Boot can read them, you might find that

there are times when certain changes are not reflected when devtools restarts the application. If you observe such problems constantly, try increasing the spring.devtools.restart.poll-interval and spring.devtools.restart.quiet-period parameters to the values that fit your development environment:

Properties

Yaml

yaml 复制代码 
spring:
  devtools:
    restart:
      poll-interval: "2s"
      quiet-period: "1s"

The monitored classpath directories are now polled every 2 seconds for changes, and a 1 second quiet period is maintained to make sure there are no additional class changes.

6.8.6. Remote Applications

The Spring Boot developer tools are not limited to local development. You can also use several features when running applications remotely. Remote support is opt-in as enabling it can be a security risk. It should only be enabled when running on a trusted network or when secured with SSL. If neither of these options is available to you, you should not use DevTools' remote support. You should never enable support on a production deployment.

To enable it, you need to make sure that devtools is included in the repackaged archive, as shown in the following listing:

xml 复制代码 
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludeDevtools>false</excludeDevtools>
            </configuration>
        </plugin>
    </plugins>
</build>

Then you need to set the spring.devtools.remote.secret property. Like any important password or secret, the value should be unique and strong such that it cannot be guessed or brute-forced.

Remote devtools support is provided in two parts: a server-side endpoint that accepts connections and a client application that you run in your IDE. The server component is automatically enabled when the spring.devtools.remote.secret property is set. The client component must be launched manually.

::: tip 备注

Remote devtools is not supported for Spring WebFlux applications.

:::

Running the Remote Client Application

The remote client application is designed to be run from within your IDE. You need to run org.springframework.boot.devtools.RemoteSpringApplication with the same classpath as the remote project that you connect to. The application's single required argument is the remote URL to which it connects.

For example, if you are using Eclipse or Spring Tools and you have a project named my-app that you have deployed to Cloud Foundry, you would do the following:

  • Select Run Configurations... from the Run menu.
  • Create a new Java Application "launch configuration".
  • Browse for the my-app project.
  • Use org.springframework.boot.devtools.RemoteSpringApplication as the main class.
  • Add https://myapp.cfapps.io to the Program arguments (or whatever your remote URL is).

A running remote client might resemble the following listing:

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

2023-11-22 15:38:10.397  INFO 916 --- [           main] o.s.b.devtools.RemoteSpringApplication   : Starting RemoteSpringApplication v2.7.18-SNAPSHOT using Java 1.8.0_392 on myhost with PID 916 (/Users/myuser/.m2/repository/org/springframework/boot/spring-boot-devtools/2.7.18-SNAPSHOT/spring-boot-devtools-2.7.18-SNAPSHOT.jar started by myuser in /opt/apps/)
2023-11-22 15:38:10.401  INFO 916 --- [           main] o.s.b.devtools.RemoteSpringApplication   : No active profile set, falling back to 1 default profile: "default"
2023-11-22 15:38:10.702  INFO 916 --- [           main] o.s.b.d.a.OptionalLiveReloadServer       : LiveReload server is running on port 35729
2023-11-22 15:38:10.724  INFO 916 --- [           main] o.s.b.devtools.RemoteSpringApplication   : Started RemoteSpringApplication in 0.736 seconds (JVM running for 1.14)

::: tip 备注

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.

:::

::: tip 提示

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

:::

::: tip 提示

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.

:::

Remote Update

The remote client monitors your application classpath for changes in the same way as the local restart. Any updated resource is pushed to the remote application and (if required ) triggers a restart. This can be helpful if you iterate on a feature that uses a cloud service that you do not have locally. Generally, remote updates and restarts are much quicker than a full rebuild and deploy

cycle.

On a slower development environment, it may happen that the quiet period is not enough, and the changes in the classes may be split into batches. The server is restarted after the first batch of class changes is uploaded. The next batch can't be sent to the application, since the server is restarting.

This is typically manifested by a warning in the RemoteSpringApplication logs about failing to upload some of the classes, and a consequent retry. But it may also lead to application code inconsistency and failure to restart after the first batch of changes is uploaded. If you observe such problems constantly, try increasing the spring.devtools.restart.poll-interval and spring.devtools.restart.quiet-period parameters to the values that fit your development environment. See

the Configuring File System Watcher section for configuring these properties.

::: tip 备注

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.

:::

6.9. Packaging Your Application for Production

Executable jars can be used for production deployment. As they are self-contained, they are also ideally suited for cloud-based deployment.

For additional "production ready" features, such as health, auditing, and metric REST or JMX end-points, consider adding spring-boot-actuator. See Production-ready Features for details.

6.10. What to Read Next

You should now understand how you can use Spring Boot and some best practices that you should follow. You can now go on to learn about specific Spring Boot features in depth, or you could skip ahead and read about the "production ready" aspects of Spring Boot.

相关推荐
一直学习永不止步4 分钟前
LeetCode题练习与总结：赎金信--383
java·数据结构·算法·leetcode·字符串·哈希表·计数
尘浮生6 分钟前
Java项目实战II基于Spring Boot的光影视频平台（开发文档+数据库+源码）
java·开发语言·数据库·spring boot·后端·maven·intellij-idea
尚学教辅学习资料14 分钟前
基于SpringBoot的医药管理系统+LW示例参考
java·spring boot·后端·java毕业设计·医药管理
雷神乐乐30 分钟前
File.separator与File.separatorChar的区别
java·路径分隔符
小刘|35 分钟前
《Java 实现希尔排序：原理剖析与代码详解》
java·算法·排序算法
逊嘘1 小时前
【Java语言】抽象类与接口
java·开发语言·jvm
morris1311 小时前
【SpringBoot】Xss的常见攻击方式与防御手段
java·spring boot·xss·csp
七星静香1 小时前
laravel chunkById 分块查询 使用时的问题
java·前端·laravel
Jacob程序员1 小时前
java导出word文件(手绘)
java·开发语言·word
热门推荐
01【HarmonyOS】HUAWEI DevEco Studio 下载地址汇总02(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明03组基轨迹建模 GBTM的介绍与实现（Stata 或 R）04【AIGC】重塑未来的科技巨轮05全面解析：构建基于深度学习的安全帽检测系统（UI界面+YOLO代码+数据集）06【经验分享】Ubuntu22.04安装微信(linux官方版)07基于YOLOv10深度学习的CT扫描图像肾结石智能检测系统【python源码+Pyqt5界面+数据集+训练代码】深度学习实战、目标检测08Ubuntu 20.04使用Livox mid 360 测试 FAST_LIO09RAG 实践- Ollama+RagFlow 部署本地知识库10红米手机使用google play