spring boot參考文件——PartI和PartII
Part I. Spring Boot參考文件
本小節是對Spring Boot參考文件的概述. 是文件其餘部分的對映.
1. 關於本參考文件
本參考文件支援的檔案格式有：
HTML
PDF
EPUB
最新版本路徑：docs.spring.io/spring-boot/docs/current/reference.
本文件免費，並且沒有任何使用限制。
2. 獲取幫助
如果你在使用spring boot時遇到困難，可以通過以下方式獲取幫助：
參考How-to文件。它提供了大多數常見問題的解決方案。
學習Spring基礎文件。spring boot建立在其他spring專案之上。訪問spring.io網站可以獲取到大量參考文件。如果你是初學者，可以選擇其中一個作為入門引導。
問問題。有什麼問題可以在stackoverflow.com上提出，但是要加上spring-boot標籤。
可以在github.com/spring-projects/spring-boot/issues上報告spring boot的bug。
[注意]
spring boot及其文件都是開源的，如果你在文件中發現問題或你想要改進他們，請參與進來。
3. 第一步
如果你以正常的方式來開啟學習spring boot或spring，請從以下步驟開始：
從頭開始: 概述 | 要求 | 安裝
輔導教程: Part 1 | Part 2
執行你的示例: Part 1 | Part 2
4. 使用Spring Boot
準備好開始使用Spring Boot了嗎? 我們已經為你安排好了:
建立系統: Maven | Gradle | Ant | Starters
最佳實踐: Code Structure | @Configuration | @EnableAutoConfiguration | Beans and Dependency Injection
執行你的程式碼: IDE | Packaged | Maven | Gradle
打包你的應用: 生產jars
Spring Boot命令列介面: 使用命令列介面
5. 學習Spring Boot的特性
需要了解更多Spring Boot核心特性的細節? 請參考以下內容:
核心特性: SpringApplication | External Configuration | Profiles | Logging
Web應用: MVC | Embedded Containers
資料操作: SQL | NO-SQL
訊息機制: Overview | JMS
測試: Overview | Boot Applications | Utils
擴充套件: Auto-configuration | @Conditions
6. 生產
當你要將你的spring boot應用放到生產中，這裡有一些訣竅你或許喜歡：
管理終端: Overview | Customization
連線選項: HTTP | JMX
監控: Metrics | Auditing | Tracing | Process
7. 高階主題
最後，我們有一些話題是為高階使用者準備的:
Spring Boot應用部署: Cloud Deployment | OS Service
構建工具外掛: Maven | Gradle
附錄: Application Properties | Auto-configuration classes | Executable Jars
----------------------------------------------------------------------------------------------------------
Part II. 啟動
如果你打算用正常的方式開始spring boot或spring，從本節開始。本節解答 “什麼？”， “怎麼？” 和 “為什麼？” 這三個問題。包括對spring boot
的介紹，和安裝過程的描述。然後你就可以建立自己的第一個spring boot應用並和我們一起討論一些spring boot的核心原理了。
8. 介紹Spring Boot
spring boot使得你可以很容易的建立一個可執行的獨立的生產級的基於spring的應用。我們對於spring平臺和第三方庫有自己的規劃，這樣可以
使你輕鬆的啟動。大多數的spring boot應用只需要很少的spring配置。
你可以使用spring boot建立使用java -jar或更傳統的war部署啟動的java應用。我們也提供了命令列工具執行“spring 指令碼”。
我們的主要目標是：
我們為所有spring 開發提供了一個極端快速和易理解的開發體驗。開箱即用，但是當需求開始偏離預設時要及時退出。我們提供了一些大型別專案通用
的非功能特性（例如嵌入式伺服器，安全，metric監控，健康檢測，和外部化配置）。完全不需要生成程式碼也不需要任何XML配置。
9. 系統要求
要求Spring Boot 2.0.3.RELEASE，Java 8或9，以及Spring Framework 5.0.7.RELEASE或以上。Maven 3.2+和Gradle 4
9.1 Servlet容器
Spring Boot支援一下嵌入式servlet容器:
名稱 Servlet版本
Tomcat 8.5
Jetty 9.4
Undertow 1.4
你也可以將spring boot部署到任何相容Servlet 3.1+的容器中。
10. 安裝Spring Boot
spring boot可以使用經典的java工具安裝也可以通過命令列工具來安裝。無論哪種方式，都需要java SDK v1.8及以上。開始之前你需要使用以下
命令檢查java版本：
$ java -version
如果你是一個java開發的新手或者你想用spring boot做實驗，你可以首先嚐試一下spring boot命令列。不然，也可以繼續閱讀經典安裝方式
的介紹。
10.1 安裝指南
你可以像使用其他java標準庫一樣使用spring boot。這樣做，你的類路徑的會包含適當的spring-boot-*.jar檔案。spring boot不需要任何
特殊的整合工具，你可以使用任何的IDE或文字編輯器。同樣，spring boot應用也沒有任何特殊的地方，你可以像其他java程式一樣執行和
除錯spring boot應用。
相對於拷貝spring boot的jar包，我們強烈建議您使用支援依賴管理的構建工具來導包（例如maven或gradle）；
10.1.1 Maven安裝
spring boot需要Apache Maven 3.2或以上。如果你還沒有安裝maven，你可以參考maven.apache.org上的說明。
[小竅門]
在許多的作業系統中，maven可以通過包管理器來安裝。如果你使用OSX Homebrew，可以嘗試使用brew安裝maven。ubuntu使用者可以
執行sudo apt-get install maven。使用Chocolatey的windows使用者可以執行choco install maven。
spring boot依賴使用org.springframework.boot groupId。典型的，你的Maven POM檔案繼承spring-boot-starter-parent專案，
並且宣告一個或更多“Starters”。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>2.0.3.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節，13.2.2，“使用沒有父POM的Spring Boot”。通過匯入域來替代。
10.1.2 Gradle安裝
spring boot相容Gradle 4。如果你還沒有安裝Gradle，你可以在gradle.org檢視安裝說明。
可以使用org.springframework.boot group宣告spring boot依賴。你的專案可以宣告一個或多個“Starters”。spring boot提供了
一個有用的Gradle外掛可以去進行簡單的依賴宣告和建立可執行jar。
Gradle Wrapper
Gradle Wrapper在你需要建立專案時提供了一種很好的獲取Gradle的方式。你只需要在你的程式碼旁邊提交很小的指令碼和庫來輔助建立
過程。參考docs.gradle.org/4.2.1/userguide/gradle_wrapper.html檢視詳細內容。
以下展示了一個典型的build.gradle檔案的內容：
plugins {
id 'org.springframework.boot' version '2.0.3.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命令列介面
spring boot命令列介面是一個可以使你快速使用spring 原型的命令列工具。它可以使你執行groovy指令碼，意味著你可以使用一個沒有太多
樣本程式碼的熟悉的類java語法。
你不需要使用命令列介面操作spring boot，但是它確實是使spring應用執行的最快方式。
10.2.1 自定義安裝
你可以從spring軟體倉庫下載spring命令列介面。
spring-boot-cli-2.0.3.RELEASE-bin.zip
spring-boot-cli-2.0.3.RELEASE-bin.tar.gz
簡化版同樣可以.
下載下來以後，參考解壓包中檔案INSTALL.txt中的說明進行安裝。總之，在解壓包的bin/目錄下有一個spring指令碼。你可以對.jar檔案使用
java -jar命令（這個指令碼幫助你確保類路徑設定正確）。
10.2.2 使用SDKMAN安裝!
SDKMAN！（軟體開發工具管理器）可以用來管理多個版本的各種二進位制SDKs，包括Groovy和spring boot命令列介面。獲取SDKMAN!
從sdkman.io下載並且使用以下命令安裝spring boot：
$ sdk install springboot
$ spring --versions
如果你要發揮命令列的特性並且想要很容易的獲得你所建立的版本，使用以下命令：
$ sdk install springboot dev
/path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-2.0.3.RELEASE-bin/spring-2.0.3.RELEASE/
$ sdk default springboot dev
$ springboot --version
Spring CLI v2.0.3.RELEASE
以上呼叫dev例項安裝了一個本地的spring例項。它指出了你的目標路徑，所以每次重新建立spring boot，spring都是最新的。
你可以通過以下命令來檢視：
$ sdk ls springboot
================================================================================
Available Springboot Versions
================================================================================
> + dev
* 2.0.3.RELEASE
================================================================================
+ - local version
* - installed
> - currently in use
================================================================================
10.2.3 OSX Homebrew安裝
如果你在Mac環境並且使用Homebrew，你可以使用以下命令安裝spring boot命令列介面：
$ brew tap pivotal/tap
$ brew install springboot
Homebrew installs spring to /usr/local/bin.
[注意]
如果你沒有看到以上結果，你安裝的brew可能已經過時了。如果那樣，執行brew update並且重試。
10.2.4 MacPorts安裝
如果你在Mac環境中使用MacPorts，你可以通過以下命令安裝spring boot命令列介面：
$ sudo port install spring-boot-cli
10.2.5 命令列實現
spring boot命令列介面提供BASH和zsh shells命令實現指令碼。你可以從任何shell中提取指令碼並放在你個人或是系統的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命令列介面，命令列實現指令碼會自動註冊到你的shell中。
10.2.6 Windows Scoop安裝
如果你在windows環境使用Scoop，你可以使用以下命令安裝spring boot命令列介面：
> scoop bucket add extras
> scoop install springboot
Scoop installs spring to ~/scoop/apps/springboot/current/bin.
[注意]
如果沒有看到以上結果，你安裝的scoop可能已經過時。如果那樣，執行scoop update並且重試。
10.2.7 快速啟動spring命令列介面例項
你可以使用以下web應用測試你的安裝。首先，建立一個app.groovy檔案，如下：
@RestController
class ThisWillActuallyRun {
@RequestMapping("/")
String home() {
"Hello World!"
}
}
然後在shell中執行檔案，如下：
$ spring run app.groovy
[注意]
由於要下載依賴，第一次執行應用會很慢。以後執行會快很多。
在你的瀏覽器中訪問localhost:8080. 你會看到以下輸出：
Hello World!
10.3 從早期版本更新Spring Boot
如果你要更新早期的spring boot，參考專案wiki中的“migration guide”，裡面提供了詳細的更新說明。參考“release notes”中的
“new and noteworthy”，瞭解每個版本中的新特性。
更新一個已存在的命令列介面版本，使用適當的包管理器命令，如果你是手動安裝的命令列介面，參考標準說明書，記得更新環境變數
的路徑並移除舊的引用。
11. 開發你的第一個spring boot應用
本節描述瞭如何開發一個具有spring boot特性的簡單的“Hello World”Web應用。考慮到多數IDE的支援，我們使用maven構建這個專案。
[小竅門]
spring.io網站包含了許多使用spring boot的啟動引導，如果你有特殊的需求，可以參考那裡。你可以跳過以下步驟去start.spring.io在搜
索器中選擇Web依賴直接建立專案。這樣建立一個新專案後你就可以開始編程式碼了。可以參考spring初始化文件瞭解更多細節。
開始之前，開啟終端執行以下命令以保證你安裝的的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
[注意]
本樣例需要建立資料夾。隨後的介紹假設你在自己的目錄中已經建立好了合適的資料夾。
11.1 建立POM
開始時我們需要建立一個maven的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>2.0.3.RELEASE</version>
</parent>
<!-- Additional lines to be added here... -->
</project>
[注意]
在這一點上，你可以使用IDE（支援maven）匯入專案。為了簡單，本例我們繼續使用文字編輯器。
11.2 新增依賴
spring boot提供了一系列“Starters”來使你在類路徑中新增jar包。我們的應用樣例已經在pom的父本標籤部分使用了
spring-boot-starter-parent。spring-boot-starter-parent提供了非常有用的對maven的預設支援。它同樣提供了依賴管理功能使你在
新增“blessed”（spring boot的依賴）依賴時不需要再加版本標籤。
“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本身沒有提供任何的依賴。可以在父本標籤
下面新增spring-boot-starter-web依賴，如下：
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
如果你再次執行mvn dependency:tree，你會看到包括Tomcat伺服器和spring boot在內的一系列依賴。
11.3 編寫程式碼
為了完成我們的應用，我們需要建立一個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);
}
}
雖然程式碼不多，但是發生了好多事情。接下來我們逐步介紹。
11.3.1 @RestController和@RequestMapping註解
例項檔案中第一個註解是@RestController。這是一個很老的註解。他告訴spring本類的角色是一個[email protected]（控制器），因此
處理web請求時spring就會考慮呼叫這個類。
@RequestMapping註解提供路徑資訊。它告訴spring任何滿足“/”路徑的HTTP請求都會對映到home方法。@RestController註解告訴spring
將結果字串返回給請求者。
[小竅門]
@RestController和@RequestMapping註解是spring MVC註解. (並不是Spring Boot特有.) 在spring 參考文件中檢視MVC部分可以
瞭解更多細節。
11.3.2 @EnableAutoConfiguration註解
第二個類級註解是@EnableAutoConfiguration。這個註解告訴Spring Boot根據已新增的依賴猜測你將如何配置spring。由於
spring-boot-starter-web添加了Tomcat和Spring MVC，自動配置認為你在開發Web應用，所以對spring進行了相應的設定。
啟動器和自動配置：
自動配置被設計為可以很好的支援“Starters”，但是兩者並不是直接捆綁在一起的。你也可以選擇外部的依賴，spring boot
依然儘可能的將其自動配置到你的應用中。
11.3.3 “main”方法
應用的最後部分是main方法。它只是一個標準的遵循java約定的應用入口方法。我們的main方法通過呼叫run方法將入口委託給
spring boot的SpringApplication類。SpringApplication引導我們的應用開啟spring，反過來，通過spring開啟自動配置
Tomcat伺服器。我們需要將Example.class作為run方法的引數來告訴SpringApplication哪個是主要的spring元件。引數列表也會
用來顯示一些命令列引數。
11.4 執行例項
在本節，你的應用將會執行起來。由於你使用了spring-boot-starter-parent POM，你有一個的很好執行目標。在專案的根目錄執行
mvn spring-boot:run來開啟應用。你會看到類似以下內容的輸出：
$ mvn spring-boot:run
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.0.3.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.222 seconds (JVM running for 6.514)
If you open a web browser to localhost:8080, you should see the following output:
Hello World!
To gracefully exit the application, press ctrl-c.
11.5 建立一個可執行jar
我們通過建立一個可以執行在生產中的完全獨立的可執行jar檔案作為本例項的結束。可執行jars（有時也叫“fat jars”）中包含了你的編譯類
以及所有程式碼執行需要的依賴。
可執行jars和Java：
java不支援jar檔案間的嵌入。這樣出現的問題是你很難部署一個自己的獨立應用。
為了解決這個問題，許多開發者生使用“uber” jars. 一個uber jar將所有應用所需依賴的類檔案打包在了一起。這樣就很難看出
你的應用中都有哪些庫。並且有同樣檔名的屬於不同jar的不同檔案也不能一起放在uber jar中。
spring boot使用了一種不同的方式使得可以直接內嵌jar。
建立一個可執行jar，我們需要在pom.xml中新增spring-boot-maven-plugin。具體操作是在依賴標籤下面插入以下內容：
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
[注意]
spring-boot-starter-parent POM包含<executions>配置來繫結重新打包。如果你不是用父本（parent）POM，你需要自己宣告這個配置。
檢視外掛文件瞭解更多細節。
儲存你的pom.xml並且在命令列執行以下內容：
$ 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.0.3.RELEASE:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
如果你檢視目標目錄，你應該會看到myproject-0.0.1-SNAPSHOT.jar。這個檔案大約10M大小。如果你想要檢視檔案裡面的內容，你可以使用
jar tvf，如下：
$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar
你會在目標資料夾中看到一個更小的名為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.0.3.RELEASE)
....... . . .
....... . . . (log output here)
....... . . .
........ Started Example in 2.536 seconds (JVM running for 2.864)
ctrl-c退出應用。
12. 導讀
本節提供了一些spring boot的基本內容，並且指導你寫了自己的應用。如果你是一個以工作為導向的開發者，你可能想要跳到spring.io的啟動
指南來定製自己的spring啟動方式。我們同樣有spring boot的“How-to”參考文件。
spring boot倉庫也有很多你可以執行的樣例。這些樣例是獨立的。
另外，下一步是閱讀Part III, “Using Spring Boot”。如果你實在缺乏耐心，你可以直接跳到spring boot特性部分。