Spring Boot：入门指南

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

1. 介绍 Spring Boot

Spring Boot 帮助您创建独立的、生产级别的 Spring 应用程序。我们对 Spring 平台和第三方库持有一定的观点，以便您能以最少的麻烦开始使用。大多数 Spring Boot 应用程序几乎不需要任何 Spring 配置。

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

我们的主要目标是：

提供一个极大地加快和广泛可访问的 Spring 开发入门体验；
在默认情况下有自己的观点，但在需求开始偏离默认值时迅速退出；
提供一系列非功能性特性，这些特性在大类项目中是常见的（例如嵌入式服务器、安全性、度量、健康检查和外部化配置）；
绝对没有代码生成，也没有 XML 配置的要求；

2. 系统要求

Spring Boot 2.7.18 需要 Java 8，并且兼容到 Java 21。还需要 Spring Framework 5.3.31 或更高版本。

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

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

2.1. Servlet 容器

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

名称	Servlet 版本
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 的容器中。

3. 安装 Spring Boot

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

Bash

$ 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 上的说明进行安装。

Note：在许多操作系统上，Maven 可以通过软件包管理器安装。如果您使用的是 OSX Homebrew，请尝试 brew install maven。Ubuntu 用户可以运行 sudo apt-get install maven。Windows 用户可以使用 Chocolatey 运行 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 和 8.x。如果您尚未安装 Gradle，可以按照 gradle.org 上的说明进行安装。

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

Note Gradle Wrapper
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，但它是一种快速启动 Spring 应用程序而不需要 IDE 的方法。

3.2.1. 手动安装

您可以从以下位置之一下载 Spring CLI 发行版：

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

3.2.2. 使用 SDKMAN! 安装

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

Bash

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

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

Bash

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

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

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

Bash

$ sdk ls springboot

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

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

3.2.3. OSX Homebrew 安装

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

Bash

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

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

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

3.2.4. MacPorts 安装

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

Bash

$ sudo port install spring-boot-cli

3.2.5. 命令行补全

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

Bash

$ . ~/.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 注册。

3.2.6. Windows Scoop 安装

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

Bash

> scoop bucket add extras
> scoop install springboot

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

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

3.2.7. 快速启动 Spring CLI 示例

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

Java

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

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

Bash

$ spring run app.groovy

Tip：应用程序的第一次运行速度较慢，因为需要下载依赖项。后续运行速度会快得多。

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

Text

Hello World!

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

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

Note
spring.io 网站包含许多 “入门” 指南，这些指南使用 Spring Boot。如果您需要解决特定问题，请先查看那里。
您可以通过访问 start.spring.io 并从依赖项搜索器中选择 “Web” Starter 来跳过以下步骤，从而生成一个新的项目结构，以便您可以立即开始编码。查看 start.spring.io 用户指南以获取更多详细信息。

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

Bash

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

Bash

$ 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.1. 创建 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>myproject</artifactId>
    <version>0.0.1-SNAPSHOT</version>

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

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

</project>

上述列表应该为您提供一个可工作的构建。您可以通过运行 mvn package 进行测试（目前，您可以忽略 “jar 将为空 - 未标记任何内容包含在内！” 警告）。

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

4.2. 添加类路径依赖

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

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

Bash

$ 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.3. 编写代码

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

Java

package com.example;

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

}

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

4.3.1. `@RestController` 和 `@RequestMapping` 注解

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

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

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

4.3.2. @SpringBootApplication 注解

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

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

Note Starters 和自动配置
自动配置设计为与 “Starters” 一起工作，但这两个概念并不直接绑定。您可以自由地在 starters 之外选择和选择 jar 依赖项。Spring Boot 仍然会尽力自动配置您的应用程序。

4.3.3. “main” 方法

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

4.4. 运行示例

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

Bash

$ mvn spring-boot:run

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

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

Text

Hello World!

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

4.5. 创建可执行的 jar

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

Note 可执行 jars 和 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 目标。如果您不使用父 POM，则需要自己声明此配置。有关详细信息，请参阅插件文档。

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

Bash

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

如果您查看 target 目录，您应该看到 myproject-0.0.1-SNAPSHOT.jar。该文件的大小应该约为 18 MB。如果您想查看内部，可以使用 jar tvf，如下所示：

Bash

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

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

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

Bash

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

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

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

5. 接下来阅读什么

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

否则，下一步自然是阅读 使用 Spring Boot 进行开发。如果您非常急切，还可以跳到阅读 Spring Boot 功能。

Spring Boot：入门指南 ​

1. 介绍 Spring Boot ​

2. 系统要求 ​

2.1. Servlet 容器 ​

3. 安装 Spring Boot ​

3.1. 面向 Java 开发人员的安装说明 ​

3.1.1. Maven 安装 ​

3.1.2. Gradle 安装 ​

3.2. 安装 Spring Boot CLI ​

3.2.1. 手动安装 ​

3.2.2. 使用 SDKMAN! 安装 ​

3.2.3. OSX Homebrew 安装 ​

3.2.4. MacPorts 安装 ​

3.2.5. 命令行补全 ​

3.2.6. Windows Scoop 安装 ​

3.2.7. 快速启动 Spring CLI 示例 ​

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

4.1. 创建 POM ​

4.2. 添加类路径依赖 ​

4.3. 编写代码 ​

4.3.1. @RestController 和 @RequestMapping 注解 ​

4.3.2. @SpringBootApplication 注解 ​

4.3.3. “main” 方法 ​

4.4. 运行示例 ​

4.5. 创建可执行的 jar ​

5. 接下来阅读什么 ​

Spring Boot：入门指南

1. 介绍 Spring Boot

2. 系统要求

2.1. Servlet 容器

3. 安装 Spring Boot

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

3.1.1. Maven 安装

3.1.2. Gradle 安装

3.2. 安装 Spring Boot CLI

3.2.1. 手动安装

3.2.2. 使用 SDKMAN! 安装

3.2.3. OSX Homebrew 安装

3.2.4. MacPorts 安装

3.2.5. 命令行补全

3.2.6. Windows Scoop 安装

3.2.7. 快速启动 Spring CLI 示例

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

4.1. 创建 POM

4.2. 添加类路径依赖

4.3. 编写代码

4.3.1. `@RestController` 和 `@RequestMapping` 注解

4.3.2. @SpringBootApplication 注解

4.3.3. “main” 方法

4.4. 运行示例

4.5. 创建可执行的 jar

5. 接下来阅读什么