SpringBoot 2.0.5.RELEASE 中文翻译笔记Getting Started

Getting Started

如果你在开始使用SpringBoot或者是"Spring"时，请首先阅读本章节. 它回答了一些基本的问题，“它是什么？”，“能做什么”，“为什么选择它”. 本章介绍了SpringBoot,以及一些安装说明然后我们将构建第一个SpringBoot应用程序，并讨论一些核心的问题。

Introducing Spring Boot

SpringBoot可以轻松的构建独立运行的基于Spring的应用程序。我们对Spring平台与一些其他的第三方库依赖进行了一些整合. 因此大多数的应用程序仅仅只需要少量
的配置就可以运行。

你可以使用SpringBoot创建Java应用程序，它支持java -jar 或者是更为传统的war部署.我们将提供一个命令行工具卡来运行 “spring scripts”.

我们的主要目标是:

• 为所有Spring的开发提供快速且广泛的入门体验
• 开箱即用
• 提供一系列对大型项目通用的非功能性功能(例如嵌入式服务器，安全性，指标，运行状况检查和外部化配置).
• 绝对没有代码生成，也不需要XML配置。

System Requirements

Spring Boot 2.0.5.RELEASE 必须 Java 8 or 9 和Spring Framework 5.0.9.RELEASE或者以上版本.

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

Build Tool	Version
Maven	3.2+
Gradle	4.4+

---

Servlet Containers

Spring Boot 支持如下嵌入式容器:

Name	Servlet Version
Tomcat 9.0	3.1+
Jetty 9.4	3.1+
Undertow 1.4	3.1+

你可以部署你的Spring Boot到任意Servlet 3.1+兼容的容器.

Installing Spring Boot

Spring Boot 可以使用 “classic” JAVA开发工具安装为命令行工具. 无论哪种方式, 你需要Java SDK v1.8 或者更高版本. 在这之前,
你可以通过以下命令来检查你当前所安装的JAVA版本:

$ java -version

如果你是一名新的JAVA开发者，或者想体验一下Spring Boot, 你可以尝试使用Spring Boot CLI (Command
Line Interface) . 除此之外, 请继续阅读 “classic” 安装说明.

Installation Instructions for the Java Developer

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

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

Maven Installation

Spring Boot 兼容 Apache Maven 3.2+. 如果您还没有安装Maven, 你可以查看https://maven.apache.org/.

TIP: On many operating systems, Maven can be installed with a package manager. If you use
OSX Homebrew, try brew install maven. Ubuntu users can run
sudo apt-get install maven. Windows users with https://chocolatey.org/[Chocolatey] can
run choco install maven from an elevated (administrator) prompt.

Spring Boot 依赖使用 org.springframework.boot groupId. 通常, 你的
Maven POM 文件继承spring-boot-starter-parent 项目和声明对一个或多个“Starters”的依赖
Spring Boot也提供一个可选的Maven plugin来创建一个可执行的Jar。

The following listing shows a typical pom.xml file:

	<?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>myproject</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>{spring-boot-version}</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>
		<!-- Add Spring repositories -->
		<!-- (you don't need this if you are using a .RELEASE 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>

通过spring-boot-starter-parent 来使用Spring Boot时一个不错的选择, 但它可能并不适合所有的场景. 有时候你也许需要继承不同的parent POM, 或者你不想要默认的配置. 在这些情况下, 参见
Section 13.2.2,""Using Spring Boot without the Parent POM"使用导入范围的替代解决方案。.

Installing the Spring Boot CLI

Spring Boot CLI (Command Line Interface) 是一个命令行工具使用它你可以快速的构建Spring原型的工程.它允许你运行Groovy脚本,
这意味着您拥有熟悉的类似Java的语法，而没有太多的样板代码。
CLI不是构建Spring Boot的必要工具，但它绝对是让Spring应用程序开始运行的最快方法。

Manual Installation

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

• spring-boot-cli-2.0.5.RELEASE-bin.zip
• spring-boot-cli-2.0.5.RELEASE-bin.tar.gz

查看可用的历史版本snapshot distributions.

下载完成后，请按照解压缩的存档中的INSTALL.txt说明进行操作.
综上所述, 这是一个 spring script
(spring.bat for Windows) 在.zip 文件中的bin/目录下 . 另外, 你可以使用java -jar 和 .jar 文件 (该脚本可帮助您确保正确设置类路径).

Installation with SDKMAN!

SDKMAN! (软件开发包管理器) 可以管理多个版本的各种二进制的SDKs，包括Groovy和Spring Boot CLI.
获取SDKMAN!和安装Spring Boot 可以通过如下命令：
commands:

	$ sdk install springboot
	$ spring --version
	Spring Boot v{spring-boot-version}

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

	$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-{spring-boot-version}-bin/spring-{spring-boot-version}/
	$ sdk default springboot dev
	$ spring --version
	Spring CLI v{spring-boot-version}

前面的说明安装了一个名为dev的spring本地实例.它指向您的目标构建位置, 所以每次重建Spring Boot时，spring都是最新的。

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

	$ sdk ls springboot

	================================================================================
	Available Springboot Versions
	================================================================================
	> + dev
	* {spring-boot-version}

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

OSX Homebrew Installation

如果你是Mac系统，你可以使用Homebrew, 你可以通过下面的命令安装Spring Boot:

	$ brew tap pivotal/tap
	$ brew install springboot

Homebrew 安装 spring 到 /usr/local/bin.

NOTE:如果你没有看到公式, 你brew的版本可能过时了。在这种情况下, 可以运行 brew update更新版本.

MacPorts Installation

如果你是Mac系统，你可以使用MacPorts, 你可以通过下面的命令安装Spring Boot:

	$ sudo port install spring-boot-cli

Command-line Completion

Spring Boot CLI为BASH andzsh 提供命令完成的脚本.您可以在任何shell中获取脚本（也称为spring），或者将其放入个人或系统范围的bash完成初始化中.在Debian system, 系统范围的脚本位于/shell-completion/bash中，当新shell启动时，该目录中的所有脚本都会执行。

例如，如果已使用SDKMAN安装，则手动运行脚本,使用下面的命令：

	$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
	$ spring <HIT TAB HERE>
	  grab  help  jar  run  test  version

NOTE: 如果你使用Homebrew或者MacPorts安装Spring Boot CLI, 命令行完成脚本会自动在shell中注册。

Windows Scoop Installation

如果你是windows系统，请使用 Scoop,安装命令如下：

	> scoop bucket add extras
	> scoop install springboot

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

NOTE: 如果您没有看到应用清单,你安装的scoop也许过时了.在此情况下运行 scoop update 进行更新.

Quick-start Spring CLI Example

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

	@RestController
	class ThisWillActuallyRun {

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

	}

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

	$ spring run app.groovy

NOTE: 第一次运行程序会比较慢, 因为会下载依赖.随后运行就会较快。

打开浏览器输入http://localhost:8080`.你应该看到如下输出：

---

Hello World!

---

=== Upgrading from an Earlier Version of Spring Boot
如果要从早期版本的Spring Boot升级, 检查"migration guide"
打开wiki，提供详细的升级说明。另请查看“发行说明”，了解每个版本的“新的和值得注意的”功能列表。

升级到新版本时, 一些属性被重命名或者移除.
Spring Boot 一种分析应用程序环境和启动时打印诊断的方法, 还可以在运行时临时迁移属性。可以通过添加如下依赖，启用此功能:

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

WARNING: 延迟添加到环境的属性（例如使用@PropertySource时）将不会被考虑在内

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

要升级现有CLI安装，请使用相应的软件包管理器命令 (for example, brew upgrade) , 如果手动安装CLI，请参考standard instructions, 记住要更新PATH环境变量删除任何旧的引用.

Developing Your First Spring Boot Application

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

spring.io网站包含许多使用Spring Boot的“入门”指南guides. 如果您需要解决特定问题, 可以先查看那里.您可以通过转到start.spring.io并从依赖关系搜索器中选择“Web”启动器来快捷执行以下步骤。这样做会生成一个新的项目结构，以便您可以立即开始编码。 Check有关更多详细信息，请查看Spring Initializr documentation。

在开始之前，打开终端并运行以下命令以确保安装了有效的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.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T16:41:47+00:00)
	Maven home: /usr/local/Cellar/maven/3.3.9/libexec
	Java version: 1.8.0_102, vendor: Oracle Corporation

NOTE: 此示例需要在其自己的文件夹中创建。后续说明假定您已创建合适的文件夹，并且它是您当前的目录。

Creating the POM

我们需要创建一个 pom.xml 文件. 这个 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 http://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>{spring-boot-version}</version>
		</parent>

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


		<!-- (you don't need this if you are using a .RELEASE 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!" 的警告).

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

Adding Classpath Dependencies

Spring Boot提供了许多“Starters”，可以将jar添加到classpath.我们的示例应用程序已经在POM的父节中使用了spring-boot-starter-parent. spring-boot-starter-parent是一个特殊的启动器，提供有用的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并在父节下面添加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本身。

Writing the Code

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

	import org.springframework.boot.*;
	import org.springframework.boot.autoconfigure.*;
	import org.springframework.web.bind.annotation.*;

	@RestController
	@EnableAutoConfiguration
	public class Example {

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

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

	}

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

The @RestController and @RequestMapping Annotations

在 Example 类中的第一个注解是@RestController. 这被称为_构造型_注释. 它为阅读代码的人提供了提示，而对于Spring来说，该类扮演着特定的角色.
在这种情况下,我们的类是一个 web @Controller,所以Spring在处理传入的Web请求时会考虑它。

@RequestMapping 注解提供 “routing” 信息. 它告诉任意的HTTP request 使用/路径的请求应该映射到home方法。
@RestController 注解告诉Spring将结果字符串直接渲染回调用者。

TIP: The @RestController and @RequestMapping 注解是Spring MVC的注解.
(它们不属于Spring Boot.) 有关更多详细信息，请参阅Spring参考文档中的MVC部分。

The @EnableAutoConfiguration Annotation

第二个类级别的注解是 @EnableAutoConfiguration.这个注解告诉
Spring Boot 根据你添加的jar依赖关系“猜测”你想要如何配置Spring。由于spring-boot-starter-web添加了Tomcat和Spring MVC，因此自动配置假定您正在开发Web应用程序并相应地设置Spring。.Starters and Auto-configuration

自动配置旨在与“启动器”配合使用，但这两个概念并不直接相关。您可以自由选择并在首发之外选择jar依赖项。 Spring Boot仍然尽力自动配置您的应用程序。

The “main” Method

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

Running the Example

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

	$ mvn spring-boot:run

	  .   ____          _            __ _ _
	 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
	( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
	 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
	  '  |____| .__|_| |_|_| |_\__, | / / / /
	 =========|_|==============|___/=/_/_/_/
	 :: Spring Boot ::  (v{spring-boot-version})
	....... . . .
	....... . . . (log output here)
	....... . . .
	........ Started Example in 2.222 seconds (JVM running for 6.514)

打开浏览器输入http://localhost:8080, 你可以看到如下输出:

---

Hello World!

---

要正常退出应用程序，请按ctrl-c.

Creating an Executable Jar

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

Executable jars and Java

Java没有提供加载嵌套jar文件的标准方法 (jar文件本身包含在jar中). 如果您要发布自包含的应用程序，这可能会有问题。

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

Spring Boot采用different approach，让你直接嵌套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目标. 如果您不使用父POM，则需要自己声明此配置。有关详细信息，请参阅插件plugin documentation文档。

保存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:{spring-boot-version}: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

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

运行这个应用程序, 使用 java -jar 命令, 如下:

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

	  .   ____          _            __ _ _
	 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
	( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
	 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
	  '  |____| .__|_| |_|_| |_\__, | / / / /
	 =========|_|==============|___/=/_/_/_/
	 :: Spring Boot ::  (v{spring-boot-version})
	....... . . .
	....... . . . (log output here)
	....... . . .
	........ Started Example in 2.536 seconds (JVM running for 2.864)

要正常退出应用程序，请按ctrl-c.

What to Read Next

希望本节提供了一些Spring Boot基础知识，让您开始编写自己的应用程序. 如果您是面向任务的开发人员类型，您可能需要跳转到spring.io并查看一些入门指南，这些指南解决了具体的“如何使用Spring实现这一点？”问题。我们还有特定于Spring Boot的“操作方法”参考文档。

Spring Boot repository有一堆可以运行的示例. 样本独立于其余代码 (也就是说，您不需要构建其余的来运行或使用示例).