第3章 Spring Boot 入門指南

Part II. 入門指南

如果你剛剛開始使用Spring Boot，這是你的一部分內容！ 在這里我們將會回答一些基本的“what?”, “how?” 和 “why?”的問題。 在這里你會找到一個詳細的Spring Boot介紹和安裝說明。 然后，我們將構建我們的第一個Spring Boot應用程序，並討論一些核心原則。

8. Spring Boot 介紹

Spring Boot可以基於Spring輕松創建可以“運行”的、獨立的、生產級的應用程序。 對Spring平台和第三方類庫我們有自己看法和意見（約定大於配置），所以你最開始的時候不要感到奇怪。大多數Spring Boot應用程序需要很少的Spring配置。

您可以使用Spring Boot創建可以使用java -jar或傳統 war 包部署啟動的Java應用程序。 我們還提供一個運行“spring scripts”的命令行工具。

我們的主要目標是：

• 為所有的Spring開發者提供一個更快，更廣泛接受的入門體驗。
• 開始使用開箱即用的配置（極少配置甚至不用配置），但隨着需求開始配置自己所需要的值（即所有配置都有默認值，同時也可以根據自己的需求進行配置）。
• 提供大量項目中常見的一系列非功能特征（例如嵌入式服務器，安全性，指標，運行狀況檢查，外部化配置）。
• 絕對沒有代碼生成，也不需要XML配置。

9. 系統要求

默認情況下，Spring Boot 1.5.2.RELEASE需要Java 7和Spring Framework 4.3.7.RELEASE或更高版本。 您可以進行一些其他配置在Java 6上使用Spring Boot。 有關詳細信息，請參見第84.11節“如何使用Java 6”。 為Maven（3.2+）、Gradle 2（2.9或更高版本）和3提供了顯式構建支持。

雖然您可以在Java 6或7上使用 Spring Boot，但我們通常推薦Java 8。

9.1 Servlet容器

以下嵌入式servlet容器可以直接使用：

名稱	Servlet 版本	Java 版本
Tomcat 8	3.1	Java 7+
Tomcat 7	3.0	Java 6+
Jetty 9.3	3.1	Java 8+
Jetty 9.2	3.1	Java 7+
Jetty 8	3.0	Java 6+
Undertow 1.3	3.1	Java 7+

您還可以將Spring Boot應用程序部署到任何兼容Servlet 3.0+ 的容器中。

10. 安裝 Spring Boot

Spring Boot可以與“經典(classic)”Java開發工具一起使用或作為命令行工具安裝。 無論如何，您將需要Java SDK v1.6或更高版本。 在開始之前檢查當前的Java安裝：

$ java -version

如果您是Java開發的新手，或者您只想嘗試一下 Spring Boot，您可能需要首先嘗試使用 Spring Boot CLI，如果想正式使用Spring Boot，請閱讀“經典(classic)”安裝說明。

雖然Spring Boot 與Java 1.6兼容，但我們建議使用最新版本的Java。

10.1 針對Java開發程序員安裝說明

Spring Boot的使用方式與標准Java庫的使用相同，只需在類路徑中包含適當的spring-boot-*.jar文件。Spring Boot不需要任何特殊的集成工具，所以可以使用任何IDE或文本編輯器進行開發；並且Spring Boot 應用程序沒有什么特殊的地方，因此您可以像其他Java程序一樣運行和調試。雖然您可以直接復制Spring Boot 的jar包，但我們通常建議您使用依賴關系管理的構建工具（如Maven或Gradle）。

10.1.1 Maven安裝

Spring Boot 兼容 Apache Maven 3.2。 如果您還沒有安裝Maven，可以按照 https://maven.apache.org/ 上的說明進行安裝。

在許多操作系統上，Maven可以通過軟件包管理器進行安裝。 如果您是OSX Homebrew用戶，請嘗試使用命令：brew install maven。 Ubuntu用戶可以運行命令：sudo apt-get install maven。

Spring Boot 依賴 org.springframework.boot groupId。通常，您的Maven POM文件將從 spring-boot-starter-parent 項目繼承，並聲明一個或多個“啟動器(啟動器)”的依賴關系。Spring Boot還提供了一個可選的Maven插件來創建可執行的jar包。

典型的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>

 <!-- Inherit defaults from Spring Boot -->
 <parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>1.5.2.RELEASE</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>

spring-boot-starter-parent是使用Spring Boot的一個很好的方式，但它並不是所有的時候都適合。有時您可能需要從不同的父POM繼承，或者您可能不喜歡我們的默認設置。 請參見第13.2.2節“使用不帶父POM的Spring Boot”作為使用導入作用域(import scope)的替代解決方案。

10.1.2 Gradle 安裝

Spring Boot 兼容 Gradle 2（2.9或更高版本）和Gradle 3。如果您尚未安裝Gradle，您可以按照 http://www.gradle.org/ 上的說明進行操作。

可以使用org.springframework.boot 組(group)聲明Spring Boot 的依賴項。 通常，您的項目將聲明一個或多個“啟動器(Starters)”的依賴。Spring Boot提供了一個有用的Gradle插件，可用於簡化依賴關系聲明和創建可執行 jar包。

Gradle Wrapper

當您需要構建項目時，Gradle Wrapper提供了一種“獲取(obtaining)”Gradle的更好的方式。 它是一個小腳本和庫，它與代碼一起引導構建過程。 有關詳細信息，請參閱 https://docs.gradle.org/2.14.1/userguide/gradle_wrapper.html 。

典型的 build.gradle 文件：

plugins {
 id 'org.springframework.boot' version '1.5.2.RELEASE'
 id 'java'
}


jar {
 baseName = 'myproject'
 version = '0.0.1-SNAPSHOT'
}

repositories {
 jcenter()
}

dependencies {
 compile("org.springframework.boot:spring-boot-starter-web")
 testCompile("org.springframework.boot:spring-boot-starter-test")
}

10.2 安裝Spring Boot CLI

Spring Boot CLI是一個命令行工具，如果要使用Spring快速原型(quickly prototype)，可以使用它。 它允許您運行Groovy腳本，這意味着會有您熟悉的類似Java的語法，沒有太多的樣板代碼(boilerplate code)。

您也不必要通過CLI來使用Spring Boot，但它絕對是開始Spring應用程序最快方法。

10.2.1 手動安裝

您可以從Spring軟件版本庫下載Spring CLI發行版：

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

各發布版本的快照。

下載完成后，請按照解壓縮后文件中的INSTALL.txt的說明進行操作。 總而言之：在.zip文件的bin/目錄中有一個spring腳本（Windows的spring.bat），或者你可以使用java -jar（腳本可以幫助您確保類路徑設置正確）。

10.2.2 使用SDKMAN!安裝

SDKMAN!（軟件開發套件管理器）可用於管理各種二進制SDK的多個版本，包括Groovy和Spring Boot CLI。從http://sdkman.io/ 獲取SDKMAN！並安裝Spring Boot。

$ sdk install springboot
$ spring --version
Spring Boot v1.5.2.RELEASE

如果您正在開發CLI的功能，並希望輕松訪問剛創建的版本，請遵循以下額外說明。

$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-1.5.2.RELEASE-bin/spring-1.5.2.RELEASE/
$ sdk default springboot dev
$ spring --version
Spring CLI v1.5.2.RELEASE

這將安裝一個稱為dev的spring的本地實例(instance)。 它指向您構建位置的target，所以每次重建(rebuild)Spring Boot時，Spring 將是最新的。

你可以看到：

$ sdk ls springboot

================================================================================
Available Springboot Versions
================================================================================
> + dev
* 1.5.2.RELEASE

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

10.2.3 OSX Homebrew 安裝

如果您在Mac上使用 Homebrew，安裝Spring Boot CLI 只需要下面命令：

$ brew tap pivotal/tap
$ brew install springboot

Homebrew會將Spring 安裝到 /usr/local/bin。

如果您沒有看到公式(formula)，您的安裝可能會過期。 只需執行brew更新，然后重試。

10.2.4 MacPorts安裝

如果您在Mac上使用 MacPorts，安裝Spring Boot CLI 只需要下面命令：

$ sudo port install spring-boot-cli

10.2.5 命令行提示

Spring Boot CLI為BASH和zsh shell提供命令提示的功能。 您可以在任何shell中引用腳本（也稱為spring），或將其放在您的個人或系統范圍的bash完成初始化中。 在Debian系統上，系統范圍的腳本位於 /shell-completion/bash 中，當新的shell啟動時，該目錄中的所有腳本將被執行。 手動運行腳本，例如 如果您使用SDKMAN安裝了！

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

如果使用Homebrew或MacPorts安裝Spring Boot CLI，則命令行補全腳本將自動注冊到您的shell。

10.2.6 快速啟動Spring CLI示例

這是一個非常簡單的Web應用程序，可用於測試您的安裝是否正確。 創建一個名為app.groovy的文件：

@RestController
class ThisWillActuallyRun {

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

}

然后從shell運行它：

$ spring run app.groovy

因為下載依賴的庫，首次運行應用程序需要一些時間，。 后續運行將會更快。

在瀏覽器中打開 http://localhost:8080 ，您應該會看到以下輸出：

Hello World!

10.3 從早期版本的Spring Boot升級

如果您從早期版本的 Spring Boot 升級，請檢查項目wiki上托管的“發行說明”。 您將找到升級說明以及每個版本的“新的和值得注意的”功能的列表。

要升級現有的CLI安裝，請使用包管理工具相應的package manager命令（例如brew upgrade），如果您手動安裝了CLI，請按照標准說明記住更新PATH環境變量以刪除任何舊的引用。

11. 開發您的第一個Spring Boot應用程序

讓我們在Java中開發一個簡單的“Hello World！”Web應用程序，突顯Spring Boot一些主要的功能。 我們將使用Maven構建該項目，因為大多數IDE支持它。

https://spring.io/ 包含許多使用Spring Boot的“入門指南”。 如果您正在尋求解決一些具體問題; 可以先看一下那里。

您可以在 https://start.spring.io/ 的依賴關系搜索器中選擇Web啟動器來快速完成以下步驟。
這會自動生成一個新的項目結構，方便您立即開始編碼。 查看文檔了解更多詳細信息。

在開始之前，打開終端來檢查您是否安裝了有效的Java和Maven版本。

$ java -version
java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)


$ mvn -v
Apache Maven 3.2.3 (33f8c3e1027c3ddde99d3cdebad2656a31e8fdf4; 2014-08-11T13:58:10-07:00)
Maven home: /Users/user/tools/apache-maven-3.1.1
Java version: 1.7.0_51, vendor: Oracle Corporation

這個示例需要在其自己的文件夾中創建。 后面我們假設您在當前目錄已經創建了一個正確的文件夾。

11.1 創建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 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>1.5.2.RELEASE</version>
 </parent>

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

</project>

這應該給你一個工作構建(working build)，你可以通過運行 mvn package 進行測試（你可以暫時忽略警告：“jar will be empty - no content was marked for inclusion!”）。

現在，您可以將項目導入到IDE中（最新的Java IDE內置對Maven的支持）。 為了簡單起見，這個示例我們繼續使用純文本編輯器。

11.2 添加類路徑依賴關系

Spring Boot提供了一些“啟動器(Starters)”，可以方便地將jar添加到類路徑中。我們的示例應用程序已經在POM的父部分使用了spring-boot-starter-parent。spring-boot-starter-parent是一個特殊啟動器，提供一些Maven的默認值。它還提供依賴管理 dependency-management 標簽，以便您可以省略子模塊依賴關系的版本標簽。

其他“啟動器(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本身。

11.3 編寫代碼

要完成我們的應用程序，我們需要創建一個的Java文件。 默認情況下，Maven將從src/main/java編譯源代碼，因此您需要創建該文件夾結構，然后添加一個名為src/main/java/Example.java的文件：

import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.stereotype.*;
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);
 }

}

雖然這里沒有太多的代碼，但是有一些重要的部分。

11.3.1 @RestController和@RequestMapping 注解

我們的Example類的第一個注解是@RestController。 這被稱為 stereotype annotation。它為人們閱讀代碼提供了一些提示，對於Spring來說，這個類具有特定的作用。在這里，我們的類是一個web @Controller，所以Spring在處理傳入的Web請求時會考慮這個類。

@RequestMapping注解提供“路由”信息。 告訴Spring，任何具有路徑“/”的HTTP請求都應映射到home方法。 @RestController注解告訴Spring將生成的字符串直接返回給調用者。

@RestController和@RequestMapping注解是Spring MVC 的注解（它們不是Spring Boot特有的）。 有關更多詳細信息，請參閱Spring參考文檔中的MVC部分。

11.3.2 @EnableAutoConfiguration注解

第二個類級別的注釋是@EnableAutoConfiguration。 這個注解告訴 Spring Boot 根據您添加的jar依賴關系來“猜(guess)”你將如何配置Spring。由於spring-boot-starter-web添加了Tomcat和Spring MVC，自動配置將假定您正在開發Web應用程序並相應地配置Spring。

啟動器和自動配置

自動配置旨在與“起動器”配合使用，但兩個概念並不直接相關。 您可以自由選擇啟動器之外的jar依賴項，Spring Boot仍然會自動配置您的應用程序。

11.3.3 “main”方法

我們的應用程序的最后一部分是main()方法。 這只是一個遵循Java慣例的應用程序入口點的標准方法。 我們的main()方法通過調用run()委托(delegates)給Spring Boot的SpringApplication類。 SpringApplication將引導我們的應用程序，啟動Spring，然后啟動自動配置的Tomcat Web服務器。 我們需要將Example.class作為一個參數傳遞給run方法來告訴SpringApplication，它是主要的Spring組件。 還傳遞了args數組以傳遞命令行參數。

11.4 運行示例

由於我們使用了spring-boot-starter-parent POM，所以我們有一個可用的運行目標，我們可以使用它來啟動應用程序。 鍵入mvn spring-boot：從根目錄運行以啟動應用程序：

$ mvn spring-boot:run

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

如果你用瀏覽器打開 http://localhost:8080 你應該看到以下輸出：

Hello World!

ctrl-c 正常(gracefully)退出應用程序。

11.5 創建可執行的jar

讓我們完成我們的例子，創建一個完全自包含的可執行jar文件，我們可以在生產環境中運行。 可執行的jar（有時稱為“fat jars”）是包含編譯的類以及代碼運行所需要的所有jar包依賴的歸檔(archives)。

可執行jar和Java

Java不提供任何標准的方法來加載嵌套的jar文件（即本身包含在jar中的jar文件）。 如果您正在尋找可以發布自包含的應用程序，這可能是有問題的。
為了解決這個問題，許多開發人員使用“uber” jars。 一個uber jar簡單地將所有類、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>

spring-boot-starter-parent POM 包括重新打包目標的 executions標簽 配置。 如果您不使用該父POM，您將需要自己聲明此配置。 有關詳細信息，請參閱插件文檔。

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

如果你看看target目錄，你應該看到myproject-0.0.1-SNAPSHOT.jar。 該文件的大小約為10 MB。 如果你想查看里面，可以使用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 :: (v1.5.2.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)

像之前一樣，ctrl+c正常退出應用程序。

12. 接下來應該讀什么

希望本節能為您提供一些Spring Boot基礎知識，並讓您准備編寫自己的應用程序。 如果你是一個面向具體任務的開發人員，你可能想跳過 https://spring.io/ ，看看一些解決具體的“如何用Spring”問題的入門指南; 我們還有Spring Boot-specific How-to參考文檔。

Spring Boot庫還有一大堆可以運行的示例。 示例與代碼的其余部分是獨立的（這樣您不需要構建多余的代碼來運行或使用示例）。

下一個是第三部分“使用 Spring Boot”。 如果你真的沒有這個耐心，也可以跳過去閱讀Spring Boot功能。