# 开始

如果你要开始使用 Spring boot，或者一般的“ Spring”，那么请阅读这一部分。它回答了基本的“什么？”、“怎么做？”和“为什么？”的问题。它包括对 Spring 启动的介绍，以及安装说明。然后，我们将带领你构建你的第一个 Spring 启动应用程序，并在此讨论一些核心原则。

## 1. 引入 Spring 引导

Spring 引导帮助你创建可以运行的独立的、基于生产级别 Spring 的应用程序。我们对 Spring 平台和第三方库持有一种固执己见的观点，这样你就可以在开始时尽量减少麻烦。大多数 Spring 启动应用程序只需要很少的 Spring 配置。

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

我们的主要目标是：

* 为所有 Spring 开发提供一种从根本上更快且广泛获得的入门体验。

* 在需求开始偏离默认值时，不要拘泥于常规，但要尽快摆脱。

* 提供一系列非功能特性，这些特性是大型项目类所共有的（例如嵌入式服务器、安全性、度量、健康检查和外部化配置）。

* 绝对不需要代码生成，也不需要 XML 配置。

## 2. 系统要求

Spring Boot2.6.4 要求[Java 8](https://www.java.com)并且兼容到并包括 Java17。[Spring Framework 5.3.16](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/)或以上也是必需的。

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

|Build Tool|版本|
|----------|---------------------|
|  Maven   |3.5+|
|  Gradle  |6.8.x、6.9.x 和 7.x|

### 2.1. Servlet 集装箱

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

|    Name    |Servlet 版本|
|------------|---------------|
| Tomcat 9.0 |      4.0      |
| Jetty 9.4  |      3.1      |
| Jetty 10.0 |      4.0      |
|Undertow 2.0|      4.0      |

你还可以将 Spring 引导应用程序部署到任何 Servlet 3.1+ 兼容容器。

## 3. 安装 Spring 启动

Spring 启动可以与“经典”Java 开发工具一起使用，也可以作为命令行工具安装。无论哪种方式，你都需要[Java SDK v1.8](https://www.java.com)或更高的值。在开始之前，你应该使用以下命令检查当前的 Java 安装：

```
$ java -version
```

如果你是 Java 开发的新手，或者你想要尝试 Spring 引导，那么你可能想要首先尝试[Spring Boot CLI](#getting-started.installing.cli)（命令行接口）。否则，请继续阅读“经典”安装说明。

### 3.1.Java 开发人员的安装说明

你可以以与任何标准 Java 库相同的方式使用 Spring boot。要做到这一点，在你的 Classpath 中包含适当的`spring-boot-*.jar`文件。 Spring 启动不需要任何特殊的工具集成，因此可以使用任何 IDE 或文本编辑器。此外， Spring 引导应用程序没有什么特别之处，因此你可以像运行任何其他 Java 程序一样运行和调试 Spring 引导应用程序。

尽管你*Coul*复制了 Spring 引导 JAR，但我们通常建议你使用支持依赖管理的构建工具（例如 Maven 或 Gradle）。

#### 3.1.1. Maven 安装

Spring 引导与 Apache Maven 3.3 或更高版本兼容。如果尚未安装 Maven，则可以按照[maven.apache.org](https://maven.apache.org)中的说明进行操作。

|   |在许多操作系统上， Maven 都可以安装一个包管理器。<br/>如果你使用 OSX Homebrew，请尝试`brew install maven`。<br/>Ubuntu 用户可以运行`sudo apt-get install maven`。<br/>具有[Chocolatey](https://chocolatey.org/)的 Windows 用户可以从提升的（管理员）提示符中运行`choco install maven`。|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

Spring 引导依赖项使用`org.springframework.boot``groupId`。通常，你的 Maven  POM 文件从`spring-boot-starter-parent`项目继承，并声明一个或多个[“Starters”](using.html#using.build-systems.starters)的依赖关系。 Spring 引导还提供了一个可选的[Maven plugin](build-tool-plugins.html#build-tool-plugins.maven)来创建可执行 JAR。

关于开始使用 Spring boot 和 Maven 的更多详细信息，可以在 Maven 插件的参考指南[入门部分](https://docs.spring.io/spring-boot/docs/2.6.4/maven-plugin/reference/htmlsingle/#getting-started)中找到。

#### 3.1.2. Gradle 安装

Spring 引导与 Gradle 6.8、6.9 和 7.x 兼容。如果尚未安装 Gradle，则可以按照[gradle.org](https://gradle.org)中的说明进行操作。

Spring 启动依赖项可以通过使用`org.springframework.boot``group`来声明。通常，你的项目声明依赖于一个或多个[“Starters”](using.html#using.build-systems.starters)。 Spring Boot 提供了一个有用的[Gradle plugin](build-tool-plugins.html#build-tool-plugins.gradle)，可用于简化依赖项声明并创建可执行 JAR。

Gradle 包装纸

当你需要构建一个项目时， Gradle 包装器提供了一种很好的“获取” Gradle 方式。它是一个小的脚本和库，你可以在代码旁边提交它来引导构建过程。详见[docs.gradle.org/current/userguide/gradle\_wrapper.html](https://docs.gradle.org/current/userguide/gradle_wrapper.html)。

关于开始使用 Spring boot 和 Gradle 的更多详细信息，可以在 Gradle 插件的参考指南[入门部分](https://docs.spring.io/spring-boot/docs/2.6.4/gradle-plugin/reference/htmlsingle/#getting-started)中找到。

### 3.2.安装 Spring boot cli

Spring 引导 CLI（命令行界面）是一种命令行工具，你可以使用它来快速地使用 Spring 进行原型设计。它允许你运行[Groovy](https://groovy-lang.org/)脚本，这意味着你有一个熟悉的类似 Java 的语法，而不需要那么多样板代码。

你不需要使用 CLI 来处理 Spring 引导，但是这是一种在没有 IDE 的情况下使 Spring 应用程序脱离地面的快速方法。

#### 3.2.1.手动安装

你可以从 Spring 软件库下载 Spring CLI 发行版：

* [spring-boot-cli-2.6.4-bin.zip](https://repo.spring.io/release/org/springframework/boot/spring-boot-cli/2.6.4/spring-boot-cli-2.6.4-bin.zip)

* [spring-boot-cli-2.6.4-bin.tar.gz](https://repo.spring.io/release/org/springframework/boot/spring-boot-cli/2.6.4/spring-boot-cli-2.6.4-bin.tar.gz)

尖端[快照分布](https://repo.spring.io/snapshot/org/springframework/boot/spring-boot-cli/)也是可用的。

一旦下载，请按照解压缩归档文件中的[安装.TXT](https://raw.githubusercontent.com/spring-projects/spring-boot/v2.6.4/spring-boot-project/spring-boot-cli/src/main/content/INSTALL.txt)说明进行操作。总之，在`.zip`文件中的`bin/`目录中有一个`spring`脚本（`spring.bat`用于 Windows）。或者，你可以在`.jar`文件中使用`java -jar`（该脚本可以帮助你确保 Classpath 设置正确）。

#### 3.2.2.用 SDKMAN 安装！

SDKMAN!（软件开发工具包管理器）可以用于管理各种二进制 SDK 的多个版本，包括 Groovy 和 Spring Boot CLI。得到 SDKMAN！从[sdkman.io](https://sdkman.io)开始，使用以下命令安装 Spring boot:

```
$ sdk install springboot
$ spring --version
Spring CLI v2.6.4
```

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

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

前面的指令安装一个`spring`的本地实例，称为`dev`实例。它指向你的目标构建位置，因此每次重新生成 Spring 引导时，`spring`都是最新的。

你可以通过运行以下命令看到它：

```
$ sdk ls springboot

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

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

#### 3.2.3.OSX Homebrew 安装

如果你在 Mac 上使用[Homebrew](https://brew.sh/)，则可以使用以下命令安装 Spring boot cli:

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

Homebrew 将`spring`安装到`/usr/local/bin`。

|   |如果你没有看到公式，那么你安装的 BREW 可能已经过期。<br/>在这种情况下，运行`brew update`，然后再试一次。|
|---|---------------------------------------------------------------------------------------------------------------------------------|

#### 3.2.4. MacPorts 安装

如果你在 Mac 上使用[MacPorts](https://www.macports.org/)，则可以使用以下命令安装 Spring boot cli:

```
$ sudo port install spring-boot-cli
```

#### 3.2.5.命令行完成

Spring 引导 CLI 包括为[BASH](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29)和[zsh](https://en.wikipedia.org/wiki/Z_shell)shell 提供命令完成的脚本。你可以在任何 shell 中`source`该脚本（也称为`spring`），或者将其放入你的个人或系统范围的 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 启动 CLI，那么命令行完成脚本将自动注册到你的 shell 中。|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------|

#### 3.2.6.Windows Scoop 安装

如果你在 Windows 上并使用[Scoop](https://scoop.sh/)，则可以使用以下命令安装 Spring boot cli:

```
> scoop bucket add extras
> scoop install springboot
```

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

|   |如果你没有看到应用程序清单，那么你的 Scoop 安装可能已经过期。<br/>在这种情况下，运行`scoop update`，然后再试一次。|
|---|----------------------------------------------------------------------------------------------------------------------------------------|

#### 3.2.7.快速启动 Spring CLI 示例

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

```
@RestController
class ThisWillActuallyRun {

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

}

```

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

```
$ spring run app.groovy
```

|   |应用程序的第一次运行很慢，因为依赖项是下载的。<br/>后续运行要快得多。|
|---|----------------------------------------------------------------------------------------------------------------|

在你最喜欢的 Web 浏览器中打开`[localhost:8080](http://localhost:8080)`。你应该会看到以下输出：

```
Hello World!
```

## 4. 开发你的第一个 Spring 启动应用程序

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

|   |[spring.io](https://spring.io)网站包含许多使用 Spring 引导的“入门”[guides](https://spring.io/guides)，<br/>如果你需要解决特定的问题，首先检查那里。<br/><br/>你可以通过转到[start.spring.io](https://start.spring.io)并从依赖项搜索器中选择“web”启动器来快捷下面的步骤。<br/>这样做会生成一个新的项目结构，这样你就可以[立即开始编码](#getting-started.first-application.code)。<br/>检查[start.spring.io user guide](https://github.com/spring-io/start.spring.io/blob/main/USING.adoc)以获取更多详细信息。|
|---| |

在开始之前，打开一个终端并运行以下命令，以确保安装了有效的 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
```

|   |这个示例需要在它自己的目录中创建。<br/>后续的说明假设你已经创建了一个合适的目录，并且它是你当前的目录。|
|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

### 4.1.创建 POM

我们需要从创建一个 Maven `pom.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.6.4</version>
    </parent>

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

</project>
```

前面的列表应该为你提供一个可工作的构建。你可以通过运行`mvn package`来测试它（目前，你可以忽略“ jar 将为空-没有内容被标记为包含！”警告）。

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

### 4.2.添加 Classpath 依赖项

Spring Boot 提供了许多“启动器”，允许你将罐子添加到你的 Classpath。我们的烟雾测试应用程序使用 POM 中`parent`部分中的`spring-boot-starter-parent`。`spring-boot-starter-parent`是一种特殊的启动器，它提供了有用的 Maven 默认值。它还提供了一个[`dependency-management`]（使用.html#using.build-systems.dependency-management）部分，这样你就可以省略`version`标记来表示“有福的”依赖关系。

其他“启动器”提供了在开发特定类型的应用程序时可能需要的依赖关系。因为我们正在开发一个 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`，并在`parent`部分下面添加`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 引导本身。

### 4.3.编写代码

为了完成我们的应用程序，我们需要创建一个单独的 Java 文件。默认情况下， Maven 从`src/main/java`编译源代码，因此你需要创建该目录结构，然后添加一个名为`src/main/java/MyApplication.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);
    }

}

```

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

#### 4.3.1.restcontroller 和 @requestmapping 注释 ###

我们的`MyApplication`类的第一个注释是`@RestController`。这被称为*刻板印象*注释。它为阅读代码的人提供了提示，并为 Spring 提供了类扮演特定角色的提示。在这种情况下，我们的类是一个 Web`@Controller`，因此 Spring 在处理传入的 Web 请求时考虑它。

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

|   |`@RestController`和`@RequestMapping`注释是 Spring MVC 注释（它们不特定于 Spring 引导）。<br/>有关更多详细信息，请参见 Spring 参考文档中的[MVC 部分](https://docs.spring.io/spring-framework/docs/5.3.16/reference/html/web.html#mvc)。|
|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

#### 4.3.2.@enableAutoConfiguration 注释 ###

第二个类级注释是`@EnableAutoConfiguration`。这个注释告诉 Spring 引导“猜测”你想要如何配置 Spring，基于你添加的 jar 依赖关系。由于`spring-boot-starter-web`添加了 Tomcat 和 Spring MVC，因此自动配置假定你正在开发一个 Web 应用程序，并相应地设置 Spring。

起动器和自动配置

自动配置的设计是为了与“启动器”很好地配合，但这两个概念并没有直接联系在一起。你可以自由地选择 jar 启动器之外的依赖项。 Spring 启动仍然会尽力自动配置你的应用程序。

#### 4.3.3.“主”法

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

### 4.4.运行示例

在这一点上，你的应用程序应该可以工作。因为你使用了`spring-boot-starter-parent` POM，所以你有了一个有用的`run`目标，你可以使用它来启动应用程序。从根项目目录中键入`mvn spring-boot:run`以启动应用程序。你应该会看到类似于以下内容的输出：

```
$ mvn spring-boot:run

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

如果将 Web 浏览器打开到`[localhost:8080](http://localhost:8080)`，应该会看到以下输出：

```
Hello World!
```

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

### 4.5.创建可执行文件 jar

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

可执行 JAR 和 Java

Java 没有提供一种标准的方式来加载嵌套的 jar 文件（ jar 文件本身包含在 jar 中）。如果你希望分发一个自包含的应用程序，这可能会有问题。

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

Spring boot 需要[不同的方法](executable-jar.html#appendix.executable-jar)，并让你实际上直接嵌套罐子。

要创建可执行文件 jar，我们需要将`spring-boot-maven-plugin`添加到我们的`pom.xml`中。要做到这一点，请在`dependencies`部分下方插入以下行：

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

|   |`spring-boot-starter-parent` POM 包括`<executions>`配置，以绑定`repackage`目标。<br/>如果不使用父 POM，则需要自己声明此配置。<br/>有关详细信息，请参见[插件文档](https://docs.spring.io/spring-boot/docs/2.6.4/maven-plugin/reference/htmlsingle/#getting-started)。|
|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

保存`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.6.4:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
```

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

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

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

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

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

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

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

## 5. 接下来要读什么？

希望这一部分提供了一些 Spring 引导基础知识，并帮助你编写自己的应用程序。如果你是一位面向任务类型的开发人员，你可能希望跳到[spring.io](https://spring.io)，并遵循一些[开始](https://spring.io/guides/)指南，这些指南解决了特定的“如何使用 Spring？”问题。我们还有 Spring 特定于引导的“[How-to](howto.html#howto)”参考文档。

否则，下一个逻辑步骤是读取 *[using.html](using.html#using)*。如果你真的不耐烦了，你也可以跳到前面去读关于 *[Spring Boot features](features.html#features)* 的文章。
