開發您的第一個 Spring Boot 應用程式

本節說明如何開發一個小的 “Hello World!” 網路應用程式，重點介紹 Spring Boot 的一些關鍵功能。您可以選擇 Maven 或 Gradle 作為建置系統。

spring.io 網站包含許多使用 Spring Boot 的 “開始使用” 指南。如果您需要解決特定問題，請先查看那裡。

您可以前往 start.spring.io 並從依賴搜尋器中選擇 “Web” starter 來縮短以下步驟。這樣做會產生一個新的專案結構，讓您可以立即開始編碼。請查看 start.spring.io 使用者指南以瞭解更多詳細資訊。

先決條件

在我們開始之前，請開啟終端機並執行以下命令，以確保您已安裝有效的 Java 版本

$ java -version
openjdk version "17.0.4.1" 2022-08-12 LTS
OpenJDK Runtime Environment (build 17.0.4.1+1-LTS)
OpenJDK 64-Bit Server VM (build 17.0.4.1+1-LTS, mixed mode, sharing)

此範例需要在其自己的目錄中建立。後續說明假設您已建立一個合適的目錄，並且它是您目前的目錄。

Maven

如果您想使用 Maven，請確保您已安裝 Maven

$ mvn -v
Apache Maven 3.8.5 (3599d3414f046de2324203b78ddcf9b5e4388aa0)
Maven home: usr/Users/developer/tools/maven/3.8.5
Java version: 17.0.4.1, vendor: BellSoft, runtime: /Users/developer/sdkman/candidates/java/17.0.4.1-librca

Gradle

如果您想使用 Gradle，請確保您已安裝 Gradle

$ gradle --version

------------------------------------------------------------
Gradle 8.1.1
------------------------------------------------------------

Build time:   2023-04-21 12:31:26 UTC
Revision:     1cf537a851c635c364a4214885f8b9798051175b

Kotlin:       1.8.10
Groovy:       3.0.15
Ant:          Apache Ant(TM) version 1.10.11 compiled on July 10 2021
JVM:          17.0.7 (BellSoft 17.0.7+7-LTS)
OS:           Linux 6.2.12-200.fc37.aarch64 aarch64

使用 Maven 設定專案

我們需要從建立一個 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 https://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>3.3.5</version>
	</parent>

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

</project>

前面的列表應該會給您一個可運作的建置。

您可以透過執行 mvn package 來測試它（目前，您可以忽略 “jar will be empty - no content was marked for inclusion!” 警告）。

在這一點上，您可以將專案匯入 IDE（大多數現代 Java IDE 都包含對 Maven 的內建支援）。為了簡化起見，我們在此範例中繼續使用純文字編輯器。

使用 Gradle 設定專案

我們需要從建立一個 Gradle build.gradle 檔案開始。build.gradle 是用於建置專案的建置腳本。開啟您最喜歡的文字編輯器並新增以下內容

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.3.5'
}

apply plugin: 'io.spring.dependency-management'

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
	mavenCentral()
}

dependencies {
}

前面的列表應該會給您一個可運作的建置。您可以透過執行 gradle classes 來測試它。

在這一點上，您可以將專案匯入 IDE（大多數現代 Java IDE 都包含對 Gradle 的內建支援）。為了簡化起見，我們在此範例中繼續使用純文字編輯器。

新增類別路徑依賴

Spring Boot 提供了許多 starter，讓您可以將 jar 新增到您的類別路徑中。Starter 提供了在開發特定類型應用程式時您可能需要的依賴。

Maven

大多數 Spring Boot 應用程式都在 POM 的 parent 區段中使用 spring-boot-starter-parent。spring-boot-starter-parent 是一個特殊的 starter，它提供了有用的 Maven 預設值。它還提供了一個 dependency-management 區段，以便您可以為 “blessed” 依賴省略 version 標籤。

由於我們正在開發一個網路應用程式，因此我們新增了 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 網路伺服器和 Spring Boot 本身。

Gradle

大多數 Spring Boot 應用程式都使用 org.springframework.boot Gradle 外掛程式。此外掛程式提供了有用的預設值和 Gradle 任務。io.spring.dependency-management Gradle 外掛程式提供了依賴管理，以便您可以為 “blessed” 依賴省略 version 標籤。

由於我們正在開發一個網路應用程式，因此我們新增了 spring-boot-starter-web 依賴。在此之前，我們可以透過執行以下命令來查看我們目前擁有的內容

$ gradle dependencies

> Task :dependencies

------------------------------------------------------------
Root project 'myproject'
------------------------------------------------------------

gradle dependencies 命令會列印您的專案依賴的樹狀結構表示。目前，專案沒有任何依賴。若要新增必要的依賴，請編輯您的 build.gradle 並在 dependencies 區段中新增 spring-boot-starter-web 依賴

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
}

如果您再次執行 gradle dependencies，您會看到現在有許多額外的依賴，包括 Tomcat 網路伺服器和 Spring Boot 本身。

編寫程式碼

為了完成我們的應用程式，我們需要建立一個 Java 檔案。預設情況下，Maven 和 Gradle 會從 src/main/java 編譯來源，因此您需要建立該目錄結構，然後新增一個名為 src/main/java/MyApplication.java 的檔案以包含以下程式碼

Java
Kotlin

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@SpringBootApplication
public class MyApplication {

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

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

}

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@SpringBootApplication
class MyApplication {

	@RequestMapping("/")
	fun home() = "Hello World!"

}

fun main(args: Array<String>) {
	runApplication<MyApplication>(*args)
}

雖然這裡沒有太多程式碼，但實際上有很多事情正在發生。我們將在接下來的幾節中逐步介紹重要的部分。

@RestController 和 @RequestMapping 註解

我們 MyApplication 類別上的第一個註解是 @RestController。這被稱為刻板印象註解。它為閱讀程式碼的人和 Spring 提供了提示，表明該類別扮演著特定的角色。在本例中，我們的類別是一個網路 @Controller，因此 Spring 在處理傳入的網路請求時會考慮它。

@RequestMapping 註解提供了 “路由” 資訊。它告訴 Spring，任何路徑為 / 的 HTTP 請求都應該映射到 home 方法。@RestController 註解告訴 Spring 將產生的字串直接渲染回呼叫者。

@RestController 和 @RequestMapping 註解是 Spring MVC 註解（它們不是 Spring Boot 特有的）。有關更多詳細資訊，請參閱 Spring 參考文件中的 MVC 區段。

@SpringBootApplication 註解

第二個類別層級註解是 @SpringBootApplication。此註解被稱為元註解，它結合了 @SpringBootConfiguration、@EnableAutoConfiguration 和 @ComponentScan。

在這些註解中，我們最感興趣的是 @EnableAutoConfiguration。@EnableAutoConfiguration 告訴 Spring Boot “猜測” 您希望如何組態 Spring，基於您已新增的 jar 依賴。由於 spring-boot-starter-web 新增了 Tomcat 和 Spring MVC，自動組態會假設您正在開發一個網路應用程式並相應地設定 Spring。

Starter 和自動組態

自動組態旨在與 starter 良好協同工作，但這兩個概念並非直接相關。您可以自由選擇 starter 之外的 jar 依賴。Spring Boot 仍然會盡力自動組態您的應用程式。

“main” 方法

我們應用程式的最後一部分是 main 方法。這是一個標準方法，它遵循 Java 應用程式進入點的慣例。我們的 main 方法透過呼叫 run 委派給 Spring Boot 的 SpringApplication 類別。SpringApplication 啟動我們的應用程式，啟動 Spring，進而啟動自動組態的 Tomcat 網路伺服器。我們需要將 MyApplication.class 作為參數傳遞給 run 方法，以告知 SpringApplication 哪個是主要的 Spring 組件。args 陣列也會被傳遞以公開任何命令列引數。

執行範例

Maven

在這一點上，您的應用程式應該可以運作了。由於您使用了 spring-boot-starter-parent POM，因此您有一個有用的 run 目標，可以用於啟動應用程式。從根專案目錄輸入 mvn spring-boot:run 以啟動應用程式。您應該會看到類似以下的輸出

$ mvn spring-boot:run

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.3.5)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.906 seconds (process running for 6.514)

如果您在網路瀏覽器中開啟 localhost:8080，您應該會看到以下輸出

Hello World!

若要優雅地退出應用程式，請按下 ctrl-c。

Gradle

在這一點上，您的應用程式應該可以運作了。由於您使用了 org.springframework.boot Gradle 外掛程式，因此您有一個有用的 bootRun 目標，可以用於啟動應用程式。從根專案目錄輸入 gradle bootRun 以啟動應用程式。您應該會看到類似以下的輸出

$ gradle bootRun

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.3.5)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.906 seconds (process running for 6.514)

如果您在網路瀏覽器中開啟 localhost:8080，您應該會看到以下輸出

Hello World!

若要優雅地退出應用程式，請按下 ctrl-c。

建立可執行 Jar

我們透過建立一個完全獨立的可執行 jar 檔案來完成我們的範例，我們可以在生產環境中執行它。可執行 jar（有時稱為 “uber jar” 或 “fat jar”）是包含您編譯的類別以及您的程式碼需要執行的所有 jar 依賴的封存檔。

可執行 jar 和 Java

Java 沒有提供載入巢狀 jar 檔案（jar 檔案本身包含在 jar 檔案中）的標準方法。如果您希望發布一個獨立的應用程式，這可能會造成問題。

為了解決這個問題，許多開發人員使用 “uber” jar。uber jar 將所有應用程式依賴中的所有類別封裝到一個封存檔中。這種方法的問題是，很難看到您的應用程式中有哪些函式庫。如果多個 jar 中使用相同的檔案名稱（但內容不同），也可能會造成問題。

Spring Boot 採取了不同的方法，讓您可以實際直接巢狀 jar。

Maven

若要建立可執行 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 目標。如果您不使用 parent 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:3.3.5:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

如果您查看 target 目錄，您應該會看到 myproject-0.0.1-SNAPSHOT.jar。檔案大小應約為 18 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 ::  (v3.3.5)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.999 seconds (process running for 1.253)

與之前一樣，若要退出應用程式，請按下 ctrl-c。

Gradle

若要建立可執行 jar，我們需要從命令列執行 gradle bootJar，如下所示

$ gradle bootJar

BUILD SUCCESSFUL in 639ms
3 actionable tasks: 3 executed

如果您查看 build/libs 目錄，您應該會看到 myproject-0.0.1-SNAPSHOT.jar。檔案大小應約為 18 MB。如果您想查看內部，可以使用 jar tvf，如下所示

$ jar tvf build/libs/myproject-0.0.1-SNAPSHOT.jar

若要執行該應用程式，請使用 java -jar 命令，如下所示

$ java -jar build/libs/myproject-0.0.1-SNAPSHOT.jar

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

與之前一樣，若要退出應用程式，請按下 ctrl-c。