SpringBoot-2.1.1.RELEASE官方参考指南(翻译)——002

Part II.开始使用（GettingStarted）

如果您正开始使用SpringBoot，或者一般的Spring，请先阅读本部分。它回答了基本的“是什么?””、“如何?”和“为什么?”的问题。它包括对SpringBoot的介绍，以及安装说明。然后，我们将带您构建您的第一个SpringBoot应用程序，同时介绍一些核心概念。

8.SpringBoot简介（IntroducingSpringBoot）

SpringBoot使创建可以运行的独立的、基于spring的产品级应用程序变得很容易。我们对Spring平台和第三方库有自己的集成方式，这样您就可以以最少的配置开始构建Spring应用。大多数SpringBoot应用程序只需要很少的Spring配置。

您可以使用SpringBoot创建可以通过使用Java-jar或更传统的war部署启动的Java应用程序。我们还提供了一个运行springscripts的命令行工具。

我们有如下主要目标:

为所有Spring开发工作提供一个非常快的、广泛可访问的初始体验。
Beopinionatedoutoftheboxbutgetoutofthewayquicklyasrequirementsstarttodivergefromthedefaults.
提供对大型项目类(如嵌入式服务器、安全性、度量、健康检查和外部化配置)常见的一系列非功能性特性。
不需要代码生成硬编码配置，也不需要XML配置。

9.系统环境要求（SystemRequirements）

SpringBoot2.1.1.RELEASE要求Java8以上版本，并且兼容Java11(包括在内)，兼容SpringFramework5.1.3.RELEASE以上版本

以下是构建工具版本要求:

构建工具	版本号
Maven	3.3+
Gradle	4.4+

9.1Servlet容器（ServletContainers）

SpringBoot支持以下嵌入式Servlet容器：

容器	Servlet版本号
Tomcat9.0	4.0
Jetty9.4	3.1
Undertow2.0	4.0

你也可以将SpringBoot应用程序发不到Servlet3.1+的容器中运行。

10.安装SpringBoot（InstallingSpringBoot）

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

$java-version

如果您是Java开发新手，或者您想尝试使用SpringBoot，您可能想先尝试SpringBootCLI（命令行接口）。否则，请继续阅读“经典”安装说明。

10.1 安装介绍（InstallationInstructionsfortheJavaDeveloper）

您可以像使用任何标准Java库一样使用SpringBoot。请引入适当版本的spring-boot-* 到classpash。SpringBoot不需要任何特殊的工具集成，所以您可以使用任何IDE或文本编辑器。此外，SpringBoot应用程序没有什么特别之处，所以您可以像运行其他任何Java程序一样运行和调试SpringBoot应用程序。

尽管您可以复制SpringBootjar包，但我们还是建议您使用依赖管理工具(例如Maven或Gradle)。

10.1.1 通过Maven安装（MavenInstallation）

SpringBoot需要ApacheMaven3.3或更高版本。如果您还没有安装Maven，可以按照maven.apache.org上的说明先安装maven。

在许多操作系统上，Maven可以与包管理器一起安装。如果您使用OSX系统Homebrew，请尝试使用brewinstallmaven。Ubuntu用户可以运行sudoapt-getinstallmaven安装maven。在Windows上可以使用Chocolatey以管理员运行chocoinstallmaven安装Maven。

SpringBoot依赖项使用org.springframework.boot``groupId引入。通常，Maven文件继承自spring-boot-start-parent项目，并声明一个或多个“启动者”的依赖。SpringBoot还提供了一个可选的Maven插件来创建可执行jar。

下面的程序清单给出了一个典型的.xml文件:

<?xmlversion="1.0"encoding="UTF-8"?>
<projectxmlns="http://maven.apache.org//4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org//4.0.0http://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>

	<!--InheritdefaultsfromSpringBoot-->
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.1.1.RELEASE</version>
	</parent>

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

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

</project>

10.1.2 通过Gradle安装（GradleInstallation）

SpringBoot与Gradle4.4以上版本兼容。如果您还没有安装Gradle，可以按照gradle.org说明安装。

可以使用org.springframework.boot``group声明SpringBoot依赖项，通常一个SpringBoot项目会依赖一个或多个“Starter”，SpringBoot提供了一个有用的Gradle插件，可以用来简化依赖声明和创建可执行jar包。

Gradle包装
Gradle包装器提供了一种很好的“获取”Gradle的方法用于构建一个项目。它本质上是一个小脚本和库，您可以将其与代码一起提交，以引导构建过程。详情请参考[docs.gradle.org/4.2.1/userguide/gradle_wrapper.html`(https://docs.gradle.org/4.2.1/userguide/gradle_wrapper.html)。

更多关于使用Gradle构建SpringBoot项目的细节可以在Gradle的“插件向导”找到

10.2 安装使用SpringBootCLI（InstallingtheSpringBootCLI）

SpringBootCLI(命令行接口)是一个命令行工具，您可以使用它快速地用构建Spring原型。可以用它执行Groovy脚本，这意味着您可以在不需要了解太多样板代码的情况下就可以使用熟悉的类java的语法构建SpringBoot。

您不需要使用CLI来与SpringBoot一起工作，但是它绝对是启动Spring应用程序的最快方法。

10.2.1 手动安装（ManualInstallation）

你可以通过以下方式安装SpringCLI二进制发行包：

你也可以使用最新的快照版本。

下载完成之后，按照解压包中的INSTALL.txt说明进行操作。总之，在.zip包中的的bin/目录下有一个spring脚本(针对Windows有一个spring.bat脚本)，这个脚本可以帮助你检查classpath是否安装正确。

10.2.2 通过SDKMAN安装

SDKMAN!(TheSoftwareDevelopmentKitManager)可以用来管理多个二进制SDK发行包。包括Groovy和SpringBootCLI。可以通过sdkman.io获取SDKMAN!，并按以下步骤安装SpringBoot：

$sdkinstallspringboot
$spring--version
SpringBootv2.1.1.RELEASE

如果您为CLI开发特性，并希望轻松访问构建的版本，请使用以下命令:

$sdkinstallspringbootdev/path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.1.1.RELEASE-bin/spring-2.1.1.RELEASE/
$sdkdefaultspringbootdev
$spring--version
SpringCLIv2.1.1.RELEASE

前面的说明用于安装一个名为spring的dev本地实例。用于指向您的项目构建位置，因此每次重新构建SpringBoot时，Spring都是最新的。

你可以使用如下命令查看它们：

$sdklsspringboot

================================================================================
AvailableSpringbootVersions
================================================================================
>+dev
* 2.1.1.RELEASE

================================================================================
+-localversion
* -installed
>-currentlyinuse
================================================================================

10.2.3 OSXHomebrew安装流程（OSXHomebrewInstallation）

如果你使用的是Mac并且安装了Homebrew包管理工具，你可以使用如下命令安装SpringCLI:

$brewtappivotal/tap
$brewinstallspringboot

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

brew的安装可能出现过时。在这种情况下，运行brewupdate并重试。

10.2.4 MacPorts安装流程（MacPortsInstallation）

如果您在Mac上使用MacPorts，可以使用以下命令安装SpringBootCLI:

$sudoportinstallspring-boot-cli

10.2.5 命令行使用SpringBootCLI（Command-lineCompletion）

SpringBootCLI包含为BASH和zshshell提供命令初始化的脚本。您可以在任何shell中获取脚本，或者将其放入您的个人或系统范围的bash完成初始化。在Debian系统上，系统范围的脚本位于/shell-completion/bash中，该目录中的所有脚本都在新的shell启动时执行。例如，如果您已经使用SDKMAN安装了该脚本，可以手动运行该脚本!，使用以下命令:

$.~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$spring<HITTABHERE>
grabhelpjarruntestversion

如果你使用的是Brew或者MacPorts安装的SpringBootCLI，那么该命令会自动加入到你的环境变量中（你可以直接运行StringBootCLI的相关命令）

10.2.6 WindowsScoop安装（WindowsScoopInstallation）

如果您在Windows上并使用Scoop，可以使用以下命令安装SpringBootCLI:

>scoopbucketaddextras
>scoopinstallspringboot

Scoop将Spring安装到~/scoop/apps/springboot/current/bin目录.

如果你使用Scoop安装时发现超时情况，可以尝试先执行scoopupdate，然后在安装

10.2.7 SpringCLI快速开始例子（Quick-startSpringCLIExample）

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

@RestController
classThisWillActuallyRun{
	@RequestMapping("/")
	Stringhome(){
		"HelloWorld!"
	}
}

使用以下命令运行：

$springrunapp.groovy

由于要下载很多依赖，应用程序的第一次运行很慢。后续运行要快得多。

使用浏览器打开Openlocalhost:8080，你将看见如下内容：

HelloWorld!

10.3 升级早期SpringBoot版本（UpgradingfromanEarlierVersionofSpringBoot）

如果你想从早期版本升级SpringBoot，你可以查看“migrationguide”ontheprojectwiki，这里系统了详细的安装流程，查看“releasenotes”浏览新特性。

当升级到新特性版本时，一些属性可能已经被重命名或删除。SpringBoot提供了一种方法来分析应用程序的环境，并在启动时打印诊断信息，还可以在运行时临时迁移属性。要启用该特性，请向项目添加以下依赖项:

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-properties-migrator</artifactId>
	<scope>runtime</scope>
</dependency>

最新版本添加到环境中的属性(例如@PropertySource)将不被考虑。

迁移完成之后，请确保将此模块从项目的依赖项中删除。

如果是更新SpringCLI，可以使用包管理工具，例如brewupgrade,如果是新安装CLI，安装这个流程。记得最后要更新PATH环境变量去除原来旧的引用。

###11.开发你的第一个SpringBoot应用（DevelopingYourFirstSpringBootApplication）
本章节将介绍如何开发一个简易的SpringBootHelloWorld，它包含了许多SpringBoot的关键特性。我们将使用Maven作为构建工具（Maven被大多数IDE支持）

spring.io给出了许多SpringBoot的“GettingStarted”指南，如果你需要解决特殊的问题，请访问这里。
您可以通过点击start.spring.io选择“Web”启动项来缩短开发步骤，这样可以生成一个新的项目结构，你可以立即开始编写代码。查看SpringInitializrdocumentation了解更多细节。

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

$java-version
javaversion"1.8.0_102"
Java(TM)SERuntimeEnvironment(build1.8.0_102-b14)
JavaHotSpot(TM)64-BitServerVM(build25.102-b14,mixedmode)

$mvn-v
ApacheMaven3.5.4(1edded0938998edf8bf061f1ceb3cfdeccf443fe;2018-06-17T14:33:14-04:00)
Mavenhome:/usr/local/Cellar/maven/3.3.9/libexec
Javaversion:1.8.0_102,vendor:OracleCorporation

这个例子在一个文件目录下创建，我们假设你已经创建了一个目录并将它作为你的当前目录。

11.1 创建文件（Creatingthe）

我们需要创建一个Maven.xml文件，该.xml文件将作为你项目的环境依赖配置。打开编辑器，输入如下内容：

<?xmlversion="1.0"encoding="UTF-8"?>
<projectxmlns="http://maven.apache.org//4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org//4.0.0http://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.1.1.RELEASE</version>
	</parent>
	<!--Additionallinestobeaddedhere...-->

</project>

上面的文件是可以被运行的，你可以运行mvnpackage进行测试.

此时，您可以将项目导入IDE(大多数现代JavaIDE都包含对Maven的内置支持)。为了简单起见，我们在本例中继续使用纯文本编辑器。

11.2 增加环境依赖（AddingClasspathDependencies）

SpringBoot提供了许多“starter”，可以将jar添加到类路径中。我们的例子使用了spring-boot-starter-parent作为父项目，spring-boot-starter-parent定义了许多Maven默认值。它还提供了一个dependency-management，以便您可以省略版本号就能获得“blessed”依赖。

其他一些“starter”可以在开发特定类型的应用程序时提供你需要的依赖项。因为我们正在开发一个web应用程序，所以我们添加了一个spring-boot-starter-web依赖项。在此之前，我们可以通过运行以下命令查看当前的情况:

$mvndependency:tree

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

mvndependency:tree命令用于打印出你项目的依赖树，你会发现spring-boot-starter-parent并没有提供任何依赖，要添加必要的依赖项，请编辑.xml在在<dependencies>内添加spring-boot-start-web依赖项:

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

如果再次运行mvn命令dependency:tree，您会看到现在有许多附加的依赖项，包括Tomcatweb服务器和SpringBoot本身。

11.3 编写实现代码（WritingtheCode）

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

importorg.springframework.boot.* ;
importorg.springframework.boot.autoconfigure.* ;
importorg.springframework.web.bind.annotation.* ;

@RestController
@EnableAutoConfiguration
publicclassExample{

	@RequestMapping("/")
	Stringhome(){
		return"HelloWorld!";
	}

	publicstaticvoidmain(String[]args)throwsException{
		SpringApplication.run(Example.class,args);
	}

}

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

11.3.1 `@RestController`和`@RequestMapping`注解（The@RestControllerand@RequestMappingAnnotations）

我们实例项目的第一个注解为@RestController，它被称为构造型注释。它为阅读代码的人和Spring提供了提示，说明类扮演了特定的角色。在本例中，我们的类是Web@Controller，因此Spring在处理传入的web请求时会使用它处理。

@RequestMapping提供了路由信息。它告诉Spring任何带有/的HTTP请求都应该映射到home方法处理。@RestController告诉Spring将结果字符串直接呈现回调用方。

@RequestMapping和@RestController都是SpringMVC的注解。查看SpringMVC相关章节获取更多细节。

11.3.2 @EnableAutoConfiguration注解（The@EnableAutoConfigurationAnnotation）

第二个类级别的注释是@EnableAutoConfiguration。这个注释告诉SpringBoot根据您添加的jar依赖关系“猜测”您希望如何配置Spring。由于spring-boot-starter-web添加了Tomcat和SpringMVC，因此自动配置假定您正在开发web应用程序，并设置相应的Spring默认值。

Starters和自动化配置

自动配置被设计成可以很好地与“Starters”一起工作，但是这两个概念没有直接联系。您可以在启动程序之外自由选择jar依赖项。SpringBoot仍然尽力自动配置你的应用程序。

11.3.3 main方法（The“main”Method）

应用程序的最后一部分是main方法。Java程序约定main方法为应用程序入口点。我们的main方法通过调用SpringApplication类的run执行SpringBoot。SpringApplication引导我们的应用程序，启动Spring，然后启动自动配置的Tomcatweb服务器。将Example.class作为参数传递给run方法，以告诉SpringApplication哪个是主Spring组件。args数组也被传递个SpringBoot，以此来传递启动参数。

11.4 运行这个Example（RunningtheExample）

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

$ mvnspring-boot:run
._________
/\\/___'_____(_)______\\\\
(()\___ | '_ | '_ |  | '_\/_` | \\\\
\\/___) | | _) | |  |  |  |  |  | (_ |  | ))))
' | ____ | .__ | _ |  | _ | _ |  | _\__, | 
========= | _ | ============== | ___/=/_/_/_/
::SpringBoot::(v2.1.1.RELEASE)
..........
..........(logoutputhere)
..........
........StartedExamplein2.222seconds(JVMrunningfor6.514)

如果您打开一个web浏览器输入localhost:8080，您应该会看到以下输出:

HelloWorld!

如果你想终止程序运行，可以使用ctrl-c.

11.5 创建一个外部运行的Jar（CreatinganExecutableJar）

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

可执行jar和Java

Java不提供加载嵌套jar文件的标准方法。如果希望分发自包含的应用程序，这可能会存在问题。
为了解决这个问题，许多开发者使用“uber”jar。uberjar将来自应用程序所有依赖项的所有类打包到一个归档文件中。这种方法的问题是很难看到应用程序中有哪些库。如果在多个jar中使用相同的文件名(但使用不同的内容)，也会有问题。

SpringBoot采用了一种不同的方法，可以直接嵌套jar。

要创建可执行jar，我们需要将spring-boot-maven-plugin添加到我们的.xml中。为此，请在dependencies部分下面插入以下几行:

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

spring-boot-starter-parent包含绑定重新打包目标的<executions>配置。如果不使用父，则需要自己声明此配置。有关详细信息，请参阅插件文档。

按如下保存你的.xml文件，并运行mvnpackage命令：

$mvnpackage

[INFO]Scanningforprojects...
[INFO]
[INFO]------------------------------------------------------------------------
[INFO]Buildingmyproject0.0.1-SNAPSHOT
[INFO]------------------------------------------------------------------------
[INFO]......
[INFO]---maven-jar-plugin:2.4:jar(default-jar)@myproject---
[INFO]Buildingjar:/Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
[INFO]
[INFO]---spring-boot-maven-plugin:2.1.1.RELEASE:repackage(default)@myproject---
[INFO]------------------------------------------------------------------------
[INFO]BUILDSUCCESS
[INFO]------------------------------------------------------------------------

你可以查看target目录下的myproject-0.0.1-SNAPSHOT.jar文件，大概在10MB左右，如果你想查看里面的内容，请使用命令jartvf，如下：

$jartvftarget/myproject-0.0.1-SNAPSHOT.jar

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

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

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

._________
/\\/___'_____(_)______\\\\
(()\___ | '_ | '_ |  | '_\/_` | \\\\
\\/___) | | _) | |  |  |  |  |  | (_ |  | ))))
' | ____ | .__ | _ |  | _ | _ |  | _\__, | 
========= | _ | ============== | ___/=/_/_/_/
::SpringBoot::(v2.1.1.RELEASE)
..........
..........(logoutputhere)
..........
........StartedExamplein2.536seconds(JVMrunningfor2.864)

通过ctrl-c结束运行。

12. 接下来涉及的内容（WhattoReadNext）

希望本节提供了一些SpringBoot基础知识，帮助您编写自己的应用程序。如果您是一名面向任务的开发人员，您可能希望跳到spring.io，并查看一些解决具体问题的入门指南，我们也提供了“How-to”的相关文档。

SpringBootrepository还提供了一些可以运行的示例。示例独立于代码的其余部分

否则，下一个合乎逻辑的步骤是阅读第三部分“使用SpringBoot”。如果您实在没有耐心，您还可以跳到前面，阅读有关SpringBoot特性的文章。