# 开始 如果你要开始使用 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 都可以安装一个包管理器。
如果你使用 OSX Homebrew，请尝试`brew install maven`。
Ubuntu 用户可以运行`sudo apt-get install maven`。
具有[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 可能已经过期。
在这种情况下，运行`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 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 安装可能已经过期。
在这种情况下，运行`scoop update`，然后再试一次。| |---|----------------------------------------------------------------------------------------------------------------------------------------| #### 3.2.7.快速启动 Spring CLI 示例 你可以使用下面的 Web 应用程序来测试你的安装。首先，创建一个名为`app.groovy`的文件，如下所示： ``` @RestController class ThisWillActuallyRun { @RequestMapping("/") String home() { "Hello World!" } } ``` 然后从一个 shell 中运行它，如下所示： ``` $ spring run app.groovy ``` | |应用程序的第一次运行很慢，因为依赖项是下载的。
后续运行要快得多。| |---|----------------------------------------------------------------------------------------------------------------| 在你最喜欢的 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)，
如果你需要解决特定的问题，首先检查那里。

你可以通过转到[start.spring.io](https://start.spring.io)并从依赖项搜索器中选择“web”启动器来快捷下面的步骤。
这样做会生成一个新的项目结构，这样你就可以[立即开始编码](#getting-started.first-application.code)。
检查[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 ``` | |这个示例需要在它自己的目录中创建。
后续的说明假设你已经创建了一个合适的目录，并且它是你当前的目录。| |---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ### 4.1.创建 POM 我们需要从创建一个 Maven `pom.xml`文件开始。`pom.xml`是用于构建项目的配方。打开你最喜欢的文本编辑器，并添加以下内容： ``` 4.0.0 com.example myproject 0.0.1-SNAPSHOT org.springframework.boot spring-boot-starter-parent 2.6.4 ``` 前面的列表应该为你提供一个可工作的构建。你可以通过运行`mvn package`来测试它（目前，你可以忽略“ jar 将为空-没有内容被标记为包含！”警告）。 | |此时，你可以将项目导入到 IDE 中（大多数现代 Java IDE 都包含对 Maven 的内置支持）。
为了简单起见，我们在这个示例中继续使用纯文本编辑器。| |---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ### 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`依赖项： ``` org.springframework.boot spring-boot-starter-web ``` 如果再次运行`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 引导）。
有关更多详细信息，请参见 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`部分下方插入以下行： ``` org.springframework.boot spring-boot-maven-plugin ``` | |`spring-boot-starter-parent` POM 包括``配置，以绑定`repackage`目标。
如果不使用父 POM，则需要自己声明此配置。
有关详细信息，请参见[插件文档](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)* 的文章。