Getting Started

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

1. Introducing Spring Boot

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

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

我们的主要目标是：

为所有的Spring开发提供极快且可广泛访问的入门体验。
要坚持自己的观点，但当需求开始偏离默认设置时，请迅速离开。
提供大类项目常见的一系列非功能性功能(如嵌入式服务器、安全性、指标、运行状况检查和外部化配置)。
绝对不需要代码生成，也不需要配置XML。

2. System Requirements

Spring Boot 3.0.0需要Java 17，并且与Java 19(包括Java 19)兼容。还需要Spring Framework6.0.2或更高版本。

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

Build Tool	Version
Maven	3.5+
抱篮	7.x(7.5或更高版本)

Build Tool

Version

Maven

3.5+

抱篮

7.x(7.5或更高版本)

2.1. Servlet Containers

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

Name	Servlet Version
Tomcat 10.0	5.0
Jetty 11.0	5.1
Undertow 2.2(雅加达EE 9变种)	5.0

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

2.2. GraalVM Native Images

可以使用GraalVM22.3或更高版本将Spring Boot应用程序转换为本机映像。

可以使用GraalVM提供的原生构建工具Gradle/Maven插件或原生映像工具创建镜像。您还可以使用本机映像Paketo构建包创建本机映像。

支持以下版本：

Name	Version
GraalVM社区	22.3
本机构建工具	0.9.18

Name

Version

GraalVM社区

22.3

本机构建工具

0.9.18

3. Installing Spring Boot

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

$ java -version

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

3.1. Installation Instructions for the Java Developer

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

尽管您可以复制Spring Boot Jars，但我们通常建议您使用支持依赖项管理的构建工具(如Maven或Gradle)。

3.1.1. Maven Installation

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

On many operating systems, Maven can be installed with a package manager. If you use OSX Homebrew, try brew install maven. Ubuntu users can run sudo apt-get install maven. Windows users with Chocolatey can run choco install maven from an elevated (administrator) prompt.

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

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

3.1.2. Gradle Installation

Spring Boot与Gradle 7.x(7.5或更高版本)兼容。如果您尚未安装Gradle，可以按照gradle.org上的说明进行操作。

Spring Boot依赖项可以通过使用org.springFrawork.Boot组声明。通常，您的项目声明对一个或多个“starters”的依赖项。Spring Boot提供了一个有用的Gradle插件，可用于简化依赖项声明和创建可执行JAR。

Gradle Wrapper

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

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

3.2. Installing the Spring Boot CLI

Spring Boot CLI(命令行界面)是一个命令行工具，您可以使用它来快速构建Spring的原型。它允许您运行Groovy脚本，这意味着您不必编写太多样板代码，就可以使用熟悉的类似Java的语法。

您不需要使用CLI来使用Spring Boot，但这是在没有IDE的情况下启动Spring应用程序的一种快速方法。

3.2.1. Manual Installation

您可以从Spring软件资源库下载Spring CLI发行版：

还可以使用最先进的快照分发。

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

3.2.2. Installation with SDKMAN!

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

$ sdk install springboot
$ spring --version
Spring CLI v3.0.0

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

$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-3.0.0-bin/spring-3.0.0/
$ sdk default springboot dev
$ spring --version
Spring CLI v3.0.0

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

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

$ sdk ls springboot

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

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

3.2.3. OSX Homebrew Installation

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

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

HomeBrew将Spring安装到/usr/local/bin。

If you do not see the formula, your installation of brew might be out-of-date. In that case, run brew update and try again.

3.2.4. MacPorts Installation

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

$ sudo port install spring-boot-cli

3.2.5. Command-line Completion

Spring Boot CLI包括为Bash和zsh外壳提供命令完成的脚本。您可以在任何外壳中源代码脚本(也称为Spring)，或者将其放入您的个人或系统范围的bash完成初始化中。在Debian系统上，系统范围内的脚本位于/ellerComplete/bash中，该目录中的所有脚本都会在新的外壳启动时执行。例如，如果已使用SDKMAN！安装，要手动运行脚本，请使用以下命令：

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

If you install the Spring Boot CLI by using Homebrew or MacPorts, the command-line completion scripts are automatically registered with your shell.

3.2.6. Windows Scoop Installation

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

> scoop bucket add extras
> scoop install springboot

《独家新闻》将Spring安装到~/scoop/apps/springboot/current/bin.

If you do not see the app manifest, your installation of scoop might be out-of-date. In that case, run scoop update and try again.

3.2.7. Quick-start Spring CLI Example

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

@RestController
class ThisWillActuallyRun {

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

}

然后从一个外壳运行它，如下所示：

$ spring run app.groovy

The first run of your application is slow, as dependencies are downloaded. Subsequent runs are much quicker.

在您喜欢的Web浏览器中打开Localhost：8080。您应该会看到以下输出：

Hello World!

4. Developing Your First Spring Boot Application

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

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

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

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

$ java -version
openjdk version "17.0.4.1" 2022-08-12 LTS
OpenJDK Runtime Environment (build 17.0.4.1+1-LTS)
OpenJDK 64-Bit Server VM (build 17.0.4.1+1-LTS, mixed mode, sharing)

$ mvn -v
Apache Maven 3.8.5 (3599d3414f046de2324203b78ddcf9b5e4388aa0)
Maven home: usr/Users/developer/tools/maven/3.8.5
Java version: 17.0.4.1, vendor: BellSoft, runtime: /Users/developer/sdkman/candidates/java/17.0.4.1-librca

This sample needs to be created in its own directory. Subsequent instructions assume that you have created a suitable directory and that it is your current directory.

4.1. Creating the 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>3.0.0</version>
    </parent>

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

</project>

前面的清单应该会为您提供一个有效的构建。您可以通过运行MVN Package来测试它(目前，您可以忽略“JAR将为空-没有内容被标记为包含！”警告)。

At this point, you could import the project into an IDE (most modern Java IDEs include built-in support for Maven). For simplicity, we continue to use a plain text editor for this example.

4.2. Adding Classpath Dependencies

Spring Boot提供了许多“启动器”，允许您将JAR添加到类路径中。我们的冒烟测试应用程序使用POM的父部分中的Spring-boot-starter-parent。SpringBoot-starter-parent是一个特殊的启动器，它提供了有用的Maven缺省值。它还提供了一个 dependency-management部分，以便您可以省略“幸福的”依赖项的 版本标记。

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

$ mvn dependency:tree

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

MVN Dependency：tree命令打印项目依赖项的树形表示形式。您可以看到，SpringBoot-starter-Parent本身没有提供依赖项。要添加必要的依赖项，请编辑您的pom.xml，并在父部分下面添加Spring-boot-starter-web依赖项：

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

如果您再次运行MVN Dependency：Tree，您会看到现在有许多额外的依赖项，包括Tomcat web服务器和Spring Boot本身。

4.3. Writing the Code

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

Java

Kotlin

import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @SpringBootApplication 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.SpringBootApplication import org.springframework.boot.runApplication import org.springframework.web.bind.annotation.RequestMapping import org.springframework.web.bind.annotation.RestController @RestController @SpringBootApplication class MyApplication { @RequestMapping("/") fun home() = "Hello World!" } fun main(args: Array<String>) { runApplication<MyApplication>(*args) }

虽然这里没有太多代码，但有相当多的代码在运行。在接下来的几个部分中，我们将逐步介绍重要的部分。

4.3.1. The @RestController and @RequestMapping Annotations

MyApplication类上的第一个批注是@RestController。这称为构造型注释。它为阅读代码的人提供了提示，并为Spring提供了该类扮演特定角色的提示。在本例中，我们的类是一个Web@Controller，因此Spring在处理传入的Web请求时会考虑它。

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

The @RestController and @RequestMapping annotations are Spring MVC annotations (they are not specific to Spring Boot). See the MVC section in the Spring Reference Documentation for more details.

4.3.2. The @SpringBootApplication Annotation

第二个类级注释是@SpringBootApplication。这个批注称为元批注，它结合了@SpringBootConfiguration、@EnableAutoConfiguration和@ComponentScan。

其中，我们在这里最感兴趣的批注是@EnableAutoConfiguration。@EnableAutoConfiguration告诉Spring Boot根据您添加的JAR依赖项“猜测”您希望如何配置Spring。由于Spring-ot-starter-web添加了Tomcat和Spring MVC，因此自动配置假定您正在开发Web应用程序并相应地设置Spring。

Starters and Auto-configuration

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

4.3.3. The “main” Method

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

4.4. Running the Example

此时，您的应用程序应该可以工作了。由于您使用了Spring-ot-starter-parentPOM，因此您有一个有用的run目标，您可以使用它来启动应用程序。在根项目目录中输入MVN Spring-ot：run以启动应用程序。您应该会看到类似于以下内容的输出：

$ mvn spring-boot:run

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

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

Hello World!

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

4.5. Creating an Executable Jar

我们通过创建一个可以在生产中运行的完全自包含的可执行JAR文件来结束我们的示例。可执行JAR(有时称为“胖JAR”)是包含已编译类以及代码运行所需的所有JAR依赖项的归档。

Executable jars and Java

Java不提供加载嵌套JAR文件(本身包含在JAR中的JAR文件)的标准方法。如果您希望分发一个自包含的应用程序，这可能会有问题。

为了解决这个问题，许多开发人员使用“Uber”JAR。Uber JAR将应用程序的所有依赖项中的所有类打包到单个归档中。这种方法的问题是，很难看到您的应用程序中有哪些库。如果在多个JAR中使用相同的文件名(但具有不同的内容)，也可能会出现问题。

Spring Boot采用了一种不同的方法，让您可以直接嵌套JAR。

要创建可执行JAR，我们需要将Spring-ot-maven-plugin添加到pom.xml。为此，请在依赖项部分的正下方插入以下行：

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

The spring-boot-starter-parent POM includes <executions> configuration to bind the repackage goal. If you do not use the parent POM, you need to declare this configuration yourself. See the plugin documentation for details.

保存pom.xml并从命令行运行MVN包，如下所示：

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

如果查看目标目录，您应该看到myproject-0.0.1-SNAPSHOT.jar。该文件的大小应该在10MB左右。如果您想要窥探内部，可以使用jar TVF，如下所示：

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

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

要运行该应用程序，请使用Java-jar命令，如下所示：

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

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

如前所述，要退出应用程序，请按ctrl-c。

5. What to Read Next

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

否则，下一个合乎逻辑的步骤是使用.html读取。如果您真的很不耐烦，您也可以跳过头来阅读Spring Boot特性。