4. 开始使用（Getting Started）

4. 开始使用（Getting Started）

如果您要开始学习 Spring Boot 或 Spring，请先阅读本节内容。它回答了 “是什么？”、"怎么做？"和 "为什么？"等基本问题。其中包括 Spring Boot 简介和安装说明。我们将引导您构建第一个 Spring Boot 应用程序，并讨论一些核心原则。

4.1 Spring Boot 介绍（Introducing Spring Boot）

Spring Boot 可帮助您创建可运行的基于 Spring 的独立生产级应用程序。我们对 Spring 平台和第三方库保持开放的态度，因此您可以轻松上手。大多数 Spring Boot 应用程序只需要很少的 Spring 配置。

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

我们的主要目标是：

• 为所有 Spring 开发人员提供更快、更广泛的入门体验。
• 开箱即用，但随着需求开始偏离默认值而迅速摆脱困境。
• 提供大型项目通用的一系列非功能性特效（例如嵌入式服务器，安全性，度量标准，运行状况检查和外部化配置）。
• 绝对没有代码生成，也不需要XML配置。

4.2 系统要求（System Requirements）

Spring Boot 2.7.18-SNAPSHOT 要求 Java 8 并兼容 Java 21。要求 Spring Framework 5.3.31 或以上版本。

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

Build Tool	Version
Maven	3.5+
Gradle	6.8.x, 6.9.x, 7.x, and 8.x

4.2.1 Servlet容器（Servlet Containers）

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

Name	Servlet Version
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 的容器。

4.3 安装Spring Boot

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

java -version

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

4.3.1 Java Developer安装说明（Installation Instructions for the Java Developer）

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

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

Maven安装（Maven Installation）

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

::: tip 提示

在许多操作系统上， Maven 可以作为一个安装包进行安装. 如果您使用 OSX Homebrew，请尝试使用brew install maven。 Ubuntu 用户可以运行sudo apt-get install maven。 使用Chocolatey的 Windows 用户可以使用管理员cmd窗口运行choco install maven。

:::

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

有关 Spring Boot 和 Maven 使用的更多详情，请参阅 Maven 插件参考指南的 “开始使用”部分。

<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>example-project</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <!-- Inherit defaults from Spring Boot -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.18-SNAPSHOT</version>
    </parent>

    <!-- Add typical dependencies for a web application -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

    <!-- Package as an executable jar -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

Gradle 安装（Gradle Installation）

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

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

::: tip Gradle Wrapper
当你需要构建项目时，Gradle Wrapper 提供了一种 “obtaining” Gradle 的方法。它是一个小脚本库，您可以 在提交代码的同时进行构建操作。有关详细信息，请参阅 docs.gradle.org/current/userguide/gradle_wrapper.html。
:::

有关 Spring Boot 和 Gradle 使用的更多详情，请参阅 Gradle 插件参考指南的 “开始使用”部分。

4.3.2 安装Spring Boot CLI（Installing the Spring Boot CLI）

Spring Boot CLI（命令行界面）是一个命令行公交，可以用于快速创建 Spring 原型。它运行你运行 Groovy 脚本，这意味着您可以使用一种类似Java的语法，而无需太多模板代码。

你可能并不需要使用 CLI 来使用 Spring Boot，但它是一种无需IDE即可快速启动 Spring 应用程序的方法。

手动安装（Manual Installation）

你可以从Spring 软件存储库 中下载 spring-boot-cli-*-bin.zip 文件或 spring-boot-cli-*-bin.tar.gz 文件。

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

使用SDKMAN安装（Installation with SDKMAN!）

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

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

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

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

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

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

$ sdk ls springboot

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

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

OSX Homebrew 安装（OSX Homebrew Installation）

如果您使用的是 Mac 并使用 Homebrew，你可以通过以下命令安装 Spring Boot CLI：

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

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

::: tip 提示
如果您没有看到formula，你的安装Homebrew 不是最新的，在这种情况下，请运行brew update 并重试。
:::

MacPorts 安装（MacPorts Installation）

如果您使用的是 Mac 并使用 MacPorts，你可以通过以下命令安装 Spring Boot CLI：

$ sudo port install spring-boot-cli

命令行（Command-line Completion）

Spring Boot CLI 包含 BASH 和 zsh shell 提供的命令行脚本。你可以在任意shell上运行 source 脚本（也称之为 spring）或者将它放到您个人或者 system-wide bash 完成初始化。在 Debian 系统上，system-wide 脚本位于 /shell-completion/bash ，启动一个新shell执行该文件下的所有脚本。例如，如果您使用 SDKMAN! 手动安装，要运行脚本，请使用以下命令：

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

Windows Scoop 安装（Windows Scoop Installation）

如果您使用的是 Windows 并使用 Scoop，你可以通过以下命令安装 Spring Boot CLI：

> scoop bucket add extras
> scoop install springboot

Scoop 会将spring 安装到 ~/scoop/apps/springboot/current/bin 文件夹下。

::: tip 提示
如果您没有看到应用清单，你的安装 Scoop 不是最新的，在这种情况下，请运行scoop update 并重试。
:::

快速启动Spring CLI实例（Quick-start Spring CLI Example）

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

@RestController
class ThisWillActuallyRun {

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

}

然后使用shell来运行她，如下所示：

$ spring run app.groovy

::: tip 提示
因为依赖项需要下载，应用程序的第一次运行速度很慢。后续启动则要快得多。
:::

在浏览器中打开 localhost:8080 。你可以看到以下输出：

Hello World!

4.4 开发第一个Spring Boot 应用程序（Developing Your First Spring Boot Application）

本节介绍如果开发一个简单的 “Hello World!” Web 应用程序，该应用程序突显了 Spring Boot 的一些主要功能。我们可以使用 Maven 来构建这个项目，大多数 IDE 都支持它。

::: tip 提示
spring.io 网站包含了许多使用 Spring Boot 的入门指南。如果您需要解决特定问题，请先检查一下。您可以跳转 start.spring.io 网站，从依赖管理搜索器中选择 “Web” starter，来快速的创建项目。这样操作会生成一个新的项目结构，以便于您可以 立即开始编码。
如果需要获取更多详细信息，参阅 start.spring.io user guide 。
:::

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

::: tip 提示
上述示例需要在您的文件夹中创建。后续说明中已经假定您已创建对应文件夹，并且它是您的当前目录。
:::

4.4.1 创建POM（Creating the 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>example</artifactId>
    <version>0.0.1-SNAPSHOT</version>

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

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

    <!-- (you only need this if you are using a milestone or snapshot version) -->
    <repositories>
        <repository>
            <id>spring-snapshots</id>
            <url>https://repo.spring.io/snapshot</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>spring-milestones</id>
            <url>https://repo.spring.io/milestone</url>
        </repository>
    </repositories>
    <pluginRepositories>
        <pluginRepository>
            <id>spring-snapshots</id>
            <url>https://repo.spring.io/snapshot</url>
        </pluginRepository>
        <pluginRepository>
            <id>spring-milestones</id>
            <url>https://repo.spring.io/milestone</url>
        </pluginRepository>
    </pluginRepositories>
</project>

上述内容为您提供一个有效的构建。你可以运行 mvn package 来测试它（现在，你可以忽略“jar will be empty - no content was marked for inclusion!” 的警告）。

::: tip 提示

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

:::

4.4.2 添加路径依赖（Adding Classpath Dependencies）

您可以将 Spring Boot 提供的一些 “Starters” 添加到您的 classpath。我们的业务应用已经在POM的parent 部分使用了 spring-boot-starter-parent 。spring-boot-starter-parent 是一个特殊的 starter，它提供了很多 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 并在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 Boot 本身。

4.4.3 写代码（Writing the Code）

如果要完成我们的应用程序，我们需要创建一个 Java 文件。默认情况下，Maven 会编译 src/main/java 下的文件，所以您需要创建该文件夹结构，然后添加一个名为 src/main/java/MyApplication.java 的文件，如下所示：

package com.example;

@RestController
@SpringBootApplication
public class MyApplication {

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

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

}

虽然这里代码不多，但是还有很多事情要做。在接下来的几个章节，我们将逐步介绍重要部分：

@RestController和@RequestMapping注解（The @RestController and @RequestMapping Annotations）

MyApplication 类的第一个注解是 @RestController。这就是 构造型 注解。它为阅读代码的人和Spring 提供标识，表明该类扮演着特定角色。在本示例中，我们的类是一个Web @Controller，因此 在处理传入的Web请求时，Spring会发现它。

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

::: tip 提示
@RestController 和@RequestMapping注解是Spring MVC注解（它们不是Spring Boot特有的）。有关详细信息，请参阅Spring文档中的MVC 部分。
:::

@SpringBootApplication 注解（The @SpringBootApplication Annotation）

第二个类上的注解是 @SpringBootApplication。这个注解被称之为 元组件，它将 @SpringBootConfiguration，@EnableAutoConfiguration 和 @ComponentScan组合在一起。

其中，我们最感兴趣的注解是 @EnableAutoConfiguration。@EnableAutoConfiguration 会让 Spring Boot 基于你添加的jar依赖关系“猜测”你想如何配置Spring。由于 spring-boot-starter-web 添加了 Tomcat 和 Spring MVC，因此自动配置会假定你正在开发Web应用程序并相应的配置Spring。

::: tip Starters and Auto-configuration
自动配置旨在与 “Starters” 配合使用，但是这两个概念并不直接相关。您可以自由选择jar依赖项。Spring Boot 仍然会尽力自动配置您的应用程序。
:::

main方法（The “main” Method）

我们应用程序的第一部分是 main 方法。这只是遵循应用程序入口点的Java约定的标准方法。我们的 main 方法的主要功能就是通过调用 Spring Boot 的 SpringApplication 类中的 run 方法. SpringApplication 引导应用程序，启动 Spring，然后启动自动配置的Tomcat Web服务器。我们需要将 MyApplication.class 作为一个参数传入 run 方法，来告诉 SpringApplication 哪个是 Spring 主组件。还可以通过命令行参数的形式传递 args 数组参数

4.4.4 运行示例（Running the Example）

至此，你的应用应该可以正常运行了。由于你使用了 spring-boot-starter-parent POM，因此你可以使用 run 命令来启动应用程序。在项目的根目录下，输入命令行 mvn spring-boot:run 用来启动应用程序。您会看到类似于以下内容的输出：

$ mvn spring-boot:run

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

如果你使用浏览器打开 localhost:8080，你可以看到如下输出：

Hello World!

如果想退出应用程序，请按 ctrl-c。

4.4.5 创建一个可执行的Jar（Creating an Executable Jar）

最后，我们将创建一个完全独立的可执行jar文件，以便于在生产环境中运行。可执行jars （有时称为 “fat jars”）是包含编译过的类以及代码运行所需要的全部jar依赖项。

::: tip Executable jars and Java

Java 未提供加载嵌套jar文件（本身包含在jar中的jar文件夹）的标准方法。如果你想发布一个独立的应用程序，这可以会造成问题。

为了解决这个问题，许多开发人员使用 "uber "jar。uber jar 将应用程序所有依赖项中的所有类都打包到一个压缩包中。 这种方法的问题是很难看出应用程序中包含哪些库。如果在多个 jar 中使用相同的文件名（但内容不同），也会造成问题。

Spring Boot 采用 不同的方法 让你可以直接嵌套 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>

::: tip 提示

spring-boot-starter-parent POM 的<executions> 标签中配置了 repackage goal. 如果你不适用父 POM，你需要自行声明该配置。详情请查看 plugin documentation。

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <executions>
            <execution>
                <goals>
                    <goal>repackage</goal>
                </goals>
            </execution>
        </executions>
    </plugins>
</build>

:::

保存你的 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.18-SNAPSHOT:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

如果你查看 target 文件夹，你可以看到 myproject-0.0.1-SNAPSHOT.jar。该文件大学应该在18 MB左右。如果需要查看jar里面，你可以使用 jar tvf，如下：

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

你应该在target目录中还可以看到名为 myproject-0.0.1-SNAPSHOT.jar.original 的小文件。这是Maven在Spring Boot重新打包之前创建的原始jar文件。

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

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

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

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

4.5 接下来要阅读的内容（What to Read Next）

本章节提供了一些 Spring Boot 的基础知识，让您开始编写自己的应用程序。如果您是以任务为导向的开发人员，你可能希望跳转到 spring.io 并查看一些 入门指南 ，这些指南解决了 “我如何使用 Spring？” 的问题。我们还有专门针对 Spring Boot “How-to” 的参考文档。

否则，下一步就是阅读 使用 Spring Boot 开发。如果您非常着急，你可以提前阅读 Spring Boot 功能.