Spring Boot 中文参考指南_springboot中文手册

Spring Boot 版本 2.7.8

原文：https://docs.spring.io/spring-boot/docs/2.7.8/reference/htmlsingle/
—
笔者注：
Spring Boot 3.x 第一个 GA 版本已于22年底发布，2.7.8 是2.x 的最后一个 GA版本，我觉得一段时间内依然会以2.x为主，该文大部分通过软件翻译，再加上自己的经验理解进行整理和注释，目的用来作为手册查找和知识扫盲，如对内容有不理解的地方欢迎交流。
这篇主要是Spring Boot 参考指南中的“Spring Boot 开发”和“Spring Boot 核心功能”

Spring Boot 中文参考指南(一)
Spring Boot 中文参考指南(二)-Web
Spring Boot 中文参考指南(三)-Data
Spring Boot 中文参考指南(四)-消息
Spring Boot 中文参考指南(五)-IO
Spring Boot 中文参考指南(六)-容器镜像
Spring Boot 中文参考指南(七)-生产就绪功能
Spring Boot 中文参考指南(八)-部署
Spring Boot 中文参考指南(九)-Spring Boot CLI
Spring Boot 中文参考指南(十)-构建工具
Spring Boot 中文参考指南(十一)-“How-to” 指南
Spring Boot 中文参考指南(十二)-附录

---

1. 文档预览

2. 开始

本节对Spring Boot进行介绍 以及如何安装，我们将引导您构建第一个Spring Boot 应用，同时讨论一些核心准则。

2.1 Spring Boot 介绍

Spring Boot 帮助您创建可以独立运行的，生产级的Spring 应用程序。

您创建的Spring Boot 应用程序，可以通过java -jar 或者 传统的war包方式启动，另外还提供了一个运行spring scripts的命令行工具。

2.2 系统要求

Spring Boot 2.7.8 需要Java8 ，兼容Java19，Spring 版本5.3.25或更高。

2.2.1 Servlet 容器

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

您也可以将Spring Boot部署到任何兼容servlet 3.1+的容器中。

2.3 Spring Boot 安装

安装之前使用java -version检查 Java 版本，Spring Boot 2.7.8 需要Java8 或更高的版本。

2.3.1 面向Java开发人员

Maven 安装

Spring Boot 依赖项使用org.springframework.boot groupId。通常，您的Maven POM文件继承自spring-boot-starter-parent ,并声明一个或多个“Starters”的依赖关系。

另外Spring Boot 还提供了可选的Maven 插件来创建可执行的jar,更多信息参考 Spring Boot Maven 插件文档。

Gradle 安装

同Maven，Spring Boot 也提供了一个 Gradle插件，用于创建可执行的jar，更多信息参考 Spring Boot Gradle 插件文档。

2.3.2 安装Spring Boot CLI

Spring Boot CLI是一个命令行工具，可用于快速创建Spring Boot 初始化应用程序，这在没有IDE的情况下非常有用。

手动安装

您可以从如下地址下载Spring CLI发行版本：

• spring-boot-cli-2.7.8-bin.zip
• spring-boot-cli-2.7.8-bin.tar.gz

另外提供了 快照列表

下载后，按照解压缩存档中的INSTALL.txt说明进行操作。.zip文件的bin/目录中有一个spring脚本（适用于Windows的spring.bat），或者可以使用jar -jar 运行 jar包。

使用SDKMAN安装

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

$ sdk install springboot
$ spring --version
Spring CLI v2.7.8
1
2
3

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

$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.7.8-bin/spring-2.7.8/
$ sdk default springboot dev
$ spring --version
Spring CLI v2.7.8
1
2
3
4

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

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

$ sdk ls springboot

================================================================================
Available Springboot Versions
================================================================================
> + dev
* 2.7.8

================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
1
2
3
4
5
6
7
8
9
10
11
12
13

使用OSX Homebrew安装

在Mac上可以使用Homebrew安装。

$ brew tap spring-io/tap
$ brew install spring-boot
1
2

Homebrew 安装 spring 到 /usr/local/bin.

如果找不到这个命令，尝试使用brew update更新后重试

使用MacPorts安装

在Mac上使用MacPorts 安装。

$ sudo port install spring-boot-cli
1

使用 Windows Scoop安装

在Window使用Scoop安装。

> scoop bucket add extras
> scoop install springboot
1
2

Scoop 安装 spring 到 ~/scoop/apps/springboot/current/bin

如果提示命令不存，请使用scoop update更新后再重试

Spring CLI 快速启动示例

首先创建一个名为app.groovy的文件。

@RestController
class ThisWillActuallyRun {

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

}
1
2
3
4
5
6
7
8
9

然后使用如下命令运行：

$ spring run app.groovy
1

第一次运行需要下载依赖，会比较慢，后面运行会快很多。

最后，使用浏览器打开localhost:8080，输出

Hello World!
1

2.4 开发第一个Spring Boot 应用程序

建议使用start.spring.io 创建Spring Boot 应用程序。

3. 升级Spring Boot

3.1 从1.x升级

从1.x升级，可以查看GitHub wiki上的升级指南

3.2 升级到最新的功能版本

Spring Boot提供了一种方法来分析应用程序的环境并在启动时打印诊断信息，还可以在运行时临时迁移属性，要启动该功能，在项目中添加以下依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>
1
2
3
4
5

完成升级后，删除该依赖。

4. Spring Boot开发

4.1 构建系统

可以使用Maven、Gradle、Ant 构建系统

4.1.1 Starters

所有官方启动器都遵循类似的命名模式：spring-boot-starter-*，其中*是特定类型的应用程序，如果是自己创建的启动器一般以项目名称开头，如thirdpartyproject-spring-boot-starter。

Spring Boot 提供了以下应用启动器org.springframework.boot：

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

最后，Spring Boot 还包括以下启动器:

其他社区贡献的starter列表，请参阅GitHub 上模块 中的自述文件。spring-boot-starters

4.2 构建代码

Spring Boot 没有固定的代码布局，但是有些实践提供参考。

4.2.1 "default"包

当一个类不包含package时，它被认为在“default package”中。通常不建议使用“default package”，它可能会导致@ComponentScan、@ConfigurationPropertiesScan、@EntityScan或@SpringBootApplication 注解出现问题，我们应该遵循推荐的包命名方式，比如com.example.project

4.2.2 主程序类

通常建议将主程序类放在其他类之上的根包中，@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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

MyApplication.java 定义了一个main方法以及@SpringBootApplication,如下所示：

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

@SpringBootApplication
public class MyApplication {

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

}
1
2
3
4
5
6
7
8
9
10
11

4.3 配置类

Spring Boot 支持使用Java进行配置，虽然SpringApplication 跟XML可以一起使用，但还是建议@Configuration是独立的类。

4.3.1 导入其他的配置类

你不需要把所有的@Configuration 放到一个类中，该@Import注解可用于导入其他的配置类，或者可以使用@ComponentScan自动获取所有的Spring 组件，包括@Configuration类。

4.3.2 导入XML配置

如果你还是要使用XML配置，依然建议使用@Configuration类，然后使用@ImportResource来加载XML配置。

4.4 自动配置

Spring Boot会尝试将starter自动配置到应用程序，比如引入了HSQLDB的starter，但是没有手动配置任何数据库连接bean，那么Spring Boot 会自动配置一个内存数据库。

开启自动配置，需要添加@EnableAutoConfiguration或者@SpringBootApplication。

4.4.1 替换自动配置

自动配置是非侵入式的，任何时候都可以使用自定义配置替换自动配置的指定部分，比如，添加了DataSource bean，默认的嵌入式数据库就会被替换。

使用--debug启动应用程序，可以打印出当前应用了哪些自动配置。

4.4.2 禁用指定的自动配置类

如果想要禁用指定的自动配置类，可以使用@SpringBootApplication的exclude属性，如：

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

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

}
1
2
3
4
5
6
7

如果排除的类不在类路径中，可以使用excludeName指定类的完全限定名，另外如果不用@SpringBootApplication，@EnableAutoConfiguration的exclude和excludeName也是可用的。

最后也能用spring.autoconfigure.exclude的配置来排除自动配置类。

4.5 Spring Beans和依赖注入

通常建议使用构造函数注入依赖项，和@ComponentScan查找bean。

如果是按照4.2的方式构建的代码，则可以使用@ComponentScan不带任何参数或者使用@SpringBootApplication其已经包含了@ComponentScan注解，这样所有的组件（@Component、@Service、@Repository、@Controller和其他）都会自动注册为Spring Beans。

如下示例表示一个@Service使用构造函数来注入RiskAssessor Bean。

import org.springframework.stereotype.Service;

@Service
public class MyAccountService implements AccountService {

    private final RiskAssessor riskAssessor;

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

    // ...

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

如果一个Bean有多个构造函数，需要使用@Autowired标记哪个需要Spring 注入：

import java.io.PrintStream;

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

@Service
public class MyAccountService implements AccountService {

    private final RiskAssessor riskAssessor;

    private final PrintStream out;

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

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

    // ...

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

使用构造函数注入应该使用 final标记，表示后面不能再被修改。

4.6 使用@SpringBootApplication 注解

使用@SpringBootApplication注解可以启用如下三个功能：

• @EnableAutoConfiguration: 启用Spring Boot 的自动配置机制

• @ComponentScan @Component：在应用程序所在的包上启用扫描

• @SpringBootConfiguration: 允许在上下文中注册额外的 beans 或导入额外的配置类。Spring 标准的替代方案@Configuration，有助于在集成测试中进行配置检测。

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

}
1
2
3
4
5
6
7
8
9
10
11
12

如果不想使用@SpringBootApplication，也可以单独使用注解，如下示例并未使用@ComponentScan 自动扫描功能，而使用显示导入(@Import)：

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

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

4.7 运行应用程序

4.7.1 从IDE运行

4.7.2 作为打包应用程序运行

使用java -jar运行：

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

也可以附加远程调式器：

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

4.7.3 使用Maven插件

Spring Boot Maven 插件包含一个run命令：

$ mvn spring-boot:run
1

另外还可以使用MAVEN_OPTS 设置环境变量：

$ export MAVEN_OPTS=-Xmx1024m
1

4.7.4 使用Gradle插件

Gradle插件包含一个bootRun命令：

$ gradle bootRun
1

使用JAVA_OPTS设置环境变量：

$ export JAVA_OPTS=-Xmx1024m
1

4.7.5 热插拨

Spring Boot 的热插拨基于JVM，JVM在某种程序上受限于可以替换的字节码，对于完整方案可以使用JRebel 。

spring-boot-devtools模块还包括对应用程序快速重启的支持，详细信息查看后面的热插拔“操作方法”。

4.8 开发者工具

Spring Boot 提供spring-boot-devtools 模块提供开发时的额外功能，要支持该功能，需要将依赖添加到项目中:

Maven

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>
1
2
3
4
5
6
7

Gradle

dependencies {
    developmentOnly("org.springframework.boot:spring-boot-devtools")
}
1
2
3

默认情况下，打包的应用程序不包含devtools，如果想要使用某个远程devtool特性，在Maven插件中配置，excludeDevtools为false，Gradle插件中配置task任务以包含developmentOnly，如

tasks.named("bootWar") {
	classpath configurations.developmentOnly
}
1
2
3

当打包生产应用程序时，开发者工具将被自动禁用。如果您的应用程序是从一个特殊的类加载器启动的或者 使用java -jar，那么会被认为是一个"生产的应用程序"。可以使用spring.devtools.restart.enabled来控制，要开启devtools，使用-Dspring.devtools.restart.enabled=true启动，要禁用devtools，排除依赖项或者使用-Dspring.devtools.restart.enabled=false启动。

Maven 中使用optional，Gradle 使用 developmentOnly，表示可以防止devtools被传递到项目的其他模块。

4.8.1 诊断类加载问题

开发者工具的重启功能是通过使用两个类加载器实现的，对于大不多应用程序效果很好，但是有时候会导致类加载问题，特别是在多模块项目中。

要判断是不是由于这个问题，可以尝试禁用重启，使用spring.devtools.restart.enabled=false属性禁用它。

另外可以 自定义重启类加载器，自定义由哪个类加载加载，详见[4.8.3自动重启](#4.8.3 自动重启)。

4.8.2 属性默认值

Spring Boot 的一些库使用缓存来提高性能，比如，模版引擎会缓存编译后的模版，以此避免重复解析，但这样在开发过程中我们就不能即时看到模版的变更。spring-boot-devtools 默认禁用了缓存。

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

如果不想应用属性默认值，可以在应用程序配置文件中配置spring.devtools.add-properties=false

在开发WEB应用的时候，可以开启DEBUG日志，这样会显示请求、正在处理的程序，响应结果和其他详细信息，如果希望显示所有的详细信息（比如潜在的敏感信息），可以打开spring.mvc.log-request-details或spring.codec.log-request-details。

⚠️笔者注：

开启spring.mvc.log-request-details 后的日志

关闭spring.mvc.log-request-details后的日志：

4.8.3 自动重启

只要类路径上的文件发生变更，使用了spring-boot-devtools的应用程序就会自动重启，但是某些资源（如静态资源和视图模版）不需要重启应用程序。

触发重启的方法：

由于DevTools 通过监听类路径上的资源来触发重启，所以不管使用哪个IDE都需要重新编译后才能触发重启：

Eclipse 中，保存修改后会更新类文件并触发重启

IDEA中，通过Build 触发或者编辑项目的Edit Configurations -> On Update action：Update classes and resources也可以触发重启

使用构建工具，mvn compile或者gradle build可以触发重启

⚠️笔者注：

官方文档提示：使用Maven或者Gradle时，需要将forking设置为enabled,才能触发重启。

实测，新版本的spring-boot-maven-plugin在项目引入spring-boot-devtools后会自动开启fork，如图：

并且插件的注释也标记为过期，将在3.0.0中彻底删除：

在重启期间 DevTools 依赖应用上下文的 shutdown hook 来关闭，如果设置为SpringApplication.setRegisterShutdownHook(false)，就会导致其无法正常工作。

⚠️笔者注：

在笔者按照这样设置后，发现自动重启并无失效

public static void main(String[] args) {
 SpringApplication application = new SpringApplication(SpringBootDemoApplication.class);
 application.setRegisterShutdownHook(false);
 application.run(args);
}
1
2
3
4
5

AspectJ 切面不支持自动重启

重新启动与重新加载

Spring Boot 的重启技术通过使用两个类加载器来工作的，不会更改的类（如：第三方jar的类）被加载到基类加载器中，频繁修改的类被加载到一个重启类加载器中。当应用程序重启时，旧的重启类加载器被丢弃并创建一个新的类加载器，这种方法会被“冷启动”快得多，因为基类加载器已经可用。

如果自动重启还是比较慢的，或者遇到类加载问题，可用尝试使用重新加载技术，如JRebel，他们通过加载类时重写类来获得更快的速度。

记录条件评估中的变化

默认每次自动重启应用程序的时候，都会显示一份对自动配置的变更报告（比如添加或删除bean或者设置配置属性）

禁用报告设置：

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

⚠️笔者注：

开启时候的报告示例：

排除资源

某些资源在更改时并不会触发自动重启，默认情况下更改 /META-INF/maven, /META-INF/resources, /resources, /static, /public, /templates目录下的资源不会触发重启但是会触发[实时加载](#4.8.4 实时加载)，如果要自定义这些排除项，可以使用spring.devtools.restart.exclude属性，比如仅排除/static和/public目录：

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

如果要保留默认的配置，并且添加新的排除项，使用spring.devtools.restart.additional-exclude。

监听其他路径文件

如果要监听不在类路径中的文件时，使用spring.devtools.restart.additional-paths属性。另外可以配合spring.devtools.restart.exclude来设置其他路径下的文件变更是触发重启还是实时加载。

禁用重启

使用spring.devtools.restart.enabled禁用重启，如果在application.properties配置，重启类加载器还是会初始化，只是不会监听文件的变更，要完全禁用需要设置系统变量spring.devtools.restart.enabled为false，如下：

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

@SpringBootApplication
public class MyApplication {

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

}
1
2
3
4
5
6
7
8
9
10
11
12

使用触发式文件

使用某个指定的文件变更来触发自动重启，使用spring.devtools.restart.trigger-file配置指定文件（不包括路径），该文件必须在类路径下。

比如：有这样一个结构的项目：

src 
+- main 
   +- resources 
      +- .reloadtrigger
1
2
3
4

那么trigger-file的配置是

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

自定义重启类加载器

默认情况下，IDE中打开的项目都使用重启类加载器，其他.jar文件使用基类加载器。使用mvn spring-boot:run或者gradle bootRun也是这样。

可以通过META-INF/spring-devtools.properties文件来自定义，spring-devtools.properties文件包含前缀为restart.exclude和restart.include的属性，include属性被重启类加载器加载，exclude属性被基类加载器排除，该属性适用类路径的正则表达式，如：

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

键必须是唯一的，只要是restart.exclude和restart.include开头的属性都会被考虑。

META-INF/spring-devtools.properties的内容可以打包中项目中，也可以打包到库中。

已知限制

对于使用标准ObjectInputStream反序列化的对象，重新启动功能不起作用。如果您需要反序列化数据，则可能需要将Spring的ConfigurableObjectInputStream与Thread.currentThread().getContextClassLoader()结合使用。

⚠️笔者注：

这个点我觉得略过即可

4.8.4 实时加载

spring-boot-devtools包含一个嵌入式的LiveReload服务器，可用于资源变更时实时触发浏览器刷新。LiveReload 浏览器扩展可从livereload.com免费获得 Chrome、Firefox 和 Safari 。如果您不想在应用程序运行时启动 LiveReload 服务器，您可以将该spring.devtools.livereload.enabled属性设置为false.

您一次只能运行一个 LiveReload 服务器。在启动您的应用程序之前，请确保没有其他 LiveReload 服务器正在运行。如果您从 IDE 启动多个应用程序，则只有第一个应用程序支持 LiveReload。

⚠️笔者注：

这个点我觉得略过即可，浏览器手动刷新一下也不费事

声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/盐析白兔/article/detail/243631?site