入门_Spring Boot 参考文档

如果您开始使用 Spring Boot 或一般的“Spring”，请从阅读本节开始。它回答了基本的“什么？”，“如何？” “为什么？” 问题。它包括对 Spring Boot 的介绍以及安装说明。然后，我们将引导您构建您的第一个 Spring Boot 应用程序，同时讨论一些核心原则。

1. Spring Boot 介绍

Spring Boot 可帮助您创建可以运行的独立的、生产级的基于 Spring 的应用程序。我们对 Spring 平台和第三方库持固执己见的看法，以便您可以轻松上手。大多数 Spring Boot 应用程序只需要很少的 Spring 配置。

您可以使用 Spring Boot 创建可以通过使用java -jar或更传统的战争部署启动的 Java 应用程序。我们还提供了一个运行“spring 脚本”的命令行工具。

我们的主要目标是：

为所有 Spring 开发提供从根本上更快且可广泛访问的入门体验。
开箱即用，但随着需求开始偏离默认值，请迅速摆脱困境。
提供大类项目（例如嵌入式服务器、安全性、指标、健康检查和外部化配置）通用的一系列非功能性特性。
绝对没有代码生成，也不需要 XML 配置。

2.系统要求

Spring Boot 2.7.1 需要Java 8，并且兼容 Java 18（包括 Java 18 ）。还需要Spring Framework 5.3.21或更高版本。

为以下构建工具提供了显式构建支持：

构建工具	版本
Maven	3.5+
Gradle	6.8.x、6.9.x 和 7.x

构建工具

版本

Maven

3.5+

Gradle

6.8.x、6.9.x 和 7.x

2.1。Servlet 容器

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

姓名	小服务程序版本
雄猫 9.0	4.0
码头 9.4	3.1
码头 10.0	4.0
暗潮 2.0	4.0

您还可以将 Spring Boot 应用程序部署到任何 servlet 3.1+ 兼容容器。

3.安装Spring Boot

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

$ java -version

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

3.1。Java 开发人员安装说明

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

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

3.1.1。Maven 安装

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

在许多操作系统上，可以使用包管理器安装 Maven。如果您使用 OSX Homebrew，请尝试brew install maven. Ubuntu 用户可以运行sudo apt-get install maven. 使用Chocolatey的Windows 用户可以choco install maven从提升的（管理员）提示符下运行。

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

有关 Spring Boot 和 Maven 入门的更多详细信息，请参阅 Maven 插件参考指南的入门部分。

3.1.2。Gradle安装

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

Spring Boot 依赖项可以使用org.springframework.boot group. 通常，您的项目会声明对一个或多个“Starters”的依赖关系。Spring Boot 提供了一个有用的Gradle 插件，可用于简化依赖声明和创建可执行 jar。

Gradle 包装器

当您需要构建项目时，Gradle Wrapper 提供了一种“获取” Gradle 的好方法。它是一个小脚本和库，您可以将其与代码一起提交以引导构建过程。有关详细信息，请参阅docs.gradle.org/current/userguide/gradle_wrapper.html。

有关 Spring Boot 和 Gradle 入门的更多详细信息，请参阅 Gradle 插件参考指南的入门部分。

3.2. 安装 Spring Boot CLI

Spring Boot CLI（命令行界面）是一个命令行工具，您可以使用它来快速使用 Spring 进行原型设计。它允许您运行Groovy脚本，这意味着您拥有熟悉的类似 Java 的语法，而无需太多样板代码。

您无需使用 CLI 即可使用 Spring Boot，但它是一种无需 IDE 即可快速启动 Spring 应用程序的方法。

3.2.1。手动安装

您可以从 Spring 软件存储库下载 Spring CLI 发行版：

还提供最先进的快照分发。

下载后，按照解压缩存档中的INSTALL.txt说明进行操作。总之，文件中的目录中有一个spring脚本（spring.bat适用于 Windows）。或者，您可以使用该文件（该脚本可帮助您确保类路径设置正确）。bin/.zipjava -jar.jar

3.2.2. 使用 SDKMAN 安装！

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

$ sdk install springboot
$ spring --version
Spring CLI v2.7.1

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

$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.7.1-bin/spring-2.7.1/
$ sdk default springboot dev
$ spring --version
Spring CLI v2.7.1

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

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

$ sdk ls springboot

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

================================================================================
+ - local version
* - installed
> - currently in use
================================================================================

3.2.3。OSX Homebrew 安装

如果您在 Mac 上使用Homebrew，则可以使用以下命令安装 Spring Boot CLI：

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

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

如果您没有看到公式，则您的 brew 安装可能已过时。在这种情况下，运行brew update并重试。

3.2.4。MacPorts 安装

如果您在 Mac 上并使用MacPorts，则可以使用以下命令安装 Spring Boot CLI：

$ sudo port install spring-boot-cli

3.2.5。命令行完成

Spring Boot CLI 包括为BASH和zsh shell提供命令完成的脚本。您可以source将脚本（也称为spring）放在任何 shell 中，或者将其放入您的个人或系统范围的 bash 完成初始化中。在 Debian 系统上，系统范围的脚本在其中，/shell-completion/bash并且该目录中的所有脚本都会在新的 shell 启动时执行。例如，如果您已使用 SDKMAN! 安装，要手动运行脚本，请使用以下命令：

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

如果您使用 Homebrew 或 MacPorts 安装 Spring Boot CLI，命令行完成脚本会自动注册到您的 shell。

3.2.6。Windows 独家新闻安装

如果您在 Windows 上并使用Scoop，则可以使用以下命令安装 Spring Boot CLI：

> 铲斗添加额外功能
>> 舀安装 springboot

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

如果您没有看到应用清单，则您安装的 scoop 可能已过期。在这种情况下，运行scoop update并重试。

3.2.7。快速入门 Spring CLI 示例

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

@RestController
class ThisWillActuallyRun {

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

}

然后从 shell 运行它，如下所示：

$ spring run app.groovy

您的应用程序的第一次运行很慢，因为下载了依赖项。随后的运行要快得多。

localhost:8080在您喜欢的网络浏览器中打开。您应该看到以下输出：

你好世界！

4. 开发你的第一个 Spring Boot 应用程序

本节介绍如何开发一个小的“Hello World！” 突出 Spring Boot 的一些关键特性的 web 应用程序。我们使用 Maven 来构建这个项目，因为大多数 IDE 都支持它。

spring.io网站包含许多使用 Spring Boot 的“入门”指南。如果您需要解决特定问题，请先检查那里。

您可以通过转到start.spring.io并从依赖项搜索器中选择“Web”启动器来简化以下步骤。这样做会生成一个新的项目结构，以便您可以立即开始编码。查看start.spring.io 用户指南了解更多详情。

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

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

$ 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

此示例需要在其自己的目录中创建。后续说明假定您已经创建了一个合适的目录并且它是您的当前目录。

4.1。创建 POM

我们需要从创建一个 Mavenpom.xml文件开始。这pom.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>myproject</artifactId>
    <version>0.0.1-SNAPSHOT</version>

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

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

</project>

前面的清单应该给你一个工作构建。您可以通过运行对其进行测试mvn package（现在，您可以忽略“jar 将为空 - 没有内容被标记为包含！”警告）。

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

4.2. 添加类路径依赖项

Spring Boot 提供了许多“启动器”，可让您将 jars 添加到类路径中。我们的烟雾测试应用程序使用POM 部分中的spring-boot-starter-parent。parent这spring-boot-starter-parent是一个特殊的启动器，提供有用的 Maven 默认值。它还提供了一个dependency-management部分，以便您可以省略version“祝福”依赖项的标签。

其他“Starters”提供了您在开发特定类型的应用程序时可能需要的依赖项。由于我们正在开发 Web 应用程序，因此我们添加了一个spring-boot-starter-web依赖项。在此之前，我们可以通过运行以下命令查看我们当前拥有的内容：

$ mvn dependency:tree

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

该mvn dependency:tree命令打印项目依赖项的树表示。您可以看到它spring-boot-starter-parent本身不提供任何依赖项。要添加必要的依赖项，请编辑您的并在该部分的正下方pom.xml添加依赖项：spring-boot-starter-webparent

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

如果mvn dependency:tree再次运行，您会看到现在有许多额外的依赖项，包括 Tomcat Web 服务器和 Spring Boot 本身。

4.3. 编写代码

为了完成我们的应用程序，我们需要创建一个 Java 文件。默认情况下，Maven 从编译源代码src/main/java，因此您需要创建该目录结构，然后添加一个名为src/main/java/MyApplication.java包含以下代码的文件：

java

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@EnableAutoConfiguration
public class MyApplication {

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

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

}

科特林

import org.springframework.boot.autoconfigure.EnableAutoConfiguration
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@EnableAutoConfiguration
class MyApplication {

    @RequestMapping("/")
    fun home() = "Hello World!"

}

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args)
}

虽然这里没有太多代码，但有很多事情正在发生。我们将在接下来的几节中逐步介绍重要部分。

4.3.1。@RestController 和 @RequestMapping 注解

MyApplication我们类的第一个注释是@RestController. 这称为构造型注释。它为阅读代码的人和 Spring 提供了类扮演特定角色的提示。在这种情况下，我们的类是一个 web @Controller，因此 Spring 在处理传入的 Web 请求时会考虑它。

@RequestMapping注释提供“路由”信息。它告诉 Spring 任何带有该/路径的 HTTP 请求都应该映射到该home方法。注释告诉 Spring将@RestController结果字符串直接呈现给调用者。

和注释是 Spring MVC 注释@RestController（@RequestMapping它们不是特定于 Spring Boot）。有关更多详细信息，请参阅 Spring 参考文档中的MVC 部分。

4.3.2. @EnableAutoConfiguration 注解

第二个类级别的注释是@EnableAutoConfiguration. 这个注解告诉 Spring Boot 根据你添加的 jar 依赖来“猜测”你想如何配置 Spring。由于spring-boot-starter-web添加了 Tomcat 和 Spring MVC，自动配置假定您正在开发 Web 应用程序并相应地设置 Spring。

启动器和自动配置

自动配置旨在与“启动器”很好地配合使用，但这两个概念没有直接联系。您可以自由选择启动器之外的 jar 依赖项。Spring Boot 仍然尽力自动配置您的应用程序。

4.3.3. “主要”方法

我们应用程序的最后一部分是main方法。这是一种遵循应用程序入口点的 Java 约定的标准方法。我们的 main 方法通过调用委托给 Spring Boot 的SpringApplication类run。 SpringApplication引导我们的应用程序，启动 Spring，然后启动自动配置的 Tomcat Web 服务器。我们需要将MyApplication.class作为参数传递给该run方法，以判断SpringApplication哪个是主要的 Spring 组件。该args数组也被传递以公开任何命令行参数。

4.4. 运行示例

此时，您的应用程序应该可以工作了。由于您使用了spring-boot-starter-parentPOM，因此您有一个run可以用来启动应用程序的有用目标。mvn spring-boot:run从根项目目录键入以启动应用程序。您应该会看到类似于以下内容的输出：

$ mvn spring-boot:run

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

如果您打开 Web 浏览器localhost:8080，您应该会看到以下输出：

你好世界！

要优雅地退出应用程序，请按ctrl-c。

4.5. 创建可执行 Jar

我们通过创建一个可以在生产环境中运行的完全独立的可执行 jar 文件来完成我们的示例。可执行 jars（有时称为“fat jars”）是包含已编译类以及代码需要运行的所有 jar 依赖项的存档。

可执行 jar 和 Java

Java 不提供加载嵌套 jar 文件（本身包含在 jar 中的 jar 文件）的标准方法。如果您希望分发一个独立的应用程序，这可能会出现问题。

为了解决这个问题，许多开发人员使用“超级”罐子。一个 uber jar 将所有应用程序依赖项中的所有类打包到一个存档中。这种方法的问题是很难看到应用程序中有哪些库。如果在多个 jar 中使用相同的文件名（但内容不同），也可能会出现问题。

Spring Boot 采用了不同的方法，让您实际上可以直接嵌套 jar。

spring-boot-maven-plugin要创建一个可执行的 jar，我们需要将pom.xml. 为此，请在该dependencies部分下方插入以下行：

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

spring-boot-starter-parentPOM 包含<executions>绑定repackage目标的配置。如果不使用父 POM，则需要自己声明此配置。有关详细信息，请参阅插件文档。

保存pom.xml并从命令行运行mvn package，如下：

$ 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.1:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

如果您查看target目录，您应该会看到myproject-0.0.1-SNAPSHOT.jar. 该文件的大小应约为 10 MB。如果你想偷看里面，你可以使用jar tvf，如下：

$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar

myproject-0.0.1-SNAPSHOT.jar.original您还应该在目录中看到一个小得多的文件target。这是Maven在被Spring Boot重新打包之前创建的原始jar文件。

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

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

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

和以前一样，要退出应用程序，请按ctrl-c。

5.接下来要读什么

希望本节提供了一些 Spring Boot 基础知识，并帮助您编写自己的应用程序。如果您是面向任务的开发人员类型，您可能想跳转到spring.io并遵循一些入门指南来解决特定的“我如何使用 Spring 做到这一点？” 问题。我们还有 Spring Boot 特定的“ How-to ”参考文档。

否则，下一个合乎逻辑的步骤是阅读using.html。如果你真的不耐烦，你也可以继续阅读Spring Boot features。