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
為以下構建工具提供了顯式構建支援:
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, 你可以嘗試使用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 runsudo apt-get install maven
. Windows users with https://chocolatey.org/[Chocolatey] can runchoco 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發行版:
下載完成後,請按照解壓縮的存檔中的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: 第一次執行程式會比較慢, 因為會下載依賴.隨後執行就會較快。
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)
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中使用相同的檔名(但具有不同的內容),也可能會有問題。
要建立可執行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有一堆可以執行的示例. 樣本獨立於其餘程式碼 (也就是說,您不需要構建其餘的來執行或使用示例).