開發您的第一個 Spring Boot 應用

本節介紹如何開發一個小型“Hello World!” Web 應用，該應用突出顯示了 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.4.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.4.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 的支援）。為了簡單起見，本例中我們將繼續使用純文字編輯器。

新增 Classpath 依賴項

Spring Boot 提供了許多 starter，它們讓您可以將 jar 新增到 classpath 中。starter 提供您在開發特定型別的應用時可能需要的依賴項。

Maven

大多數 Spring Boot 應用在 POM 的 parent 部分使用 spring-boot-starter-parent。spring-boot-starter-parent 是一個特殊的 starter，提供了有用的 Maven 預設設定。它還提供了 dependency-management 部分，以便您可以省略“推薦”依賴項的 version 標籤。

由於我們正在開發一個 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 本身。

Gradle

大多數 Spring Boot 應用使用 org.springframework.boot Gradle 外掛。這個外掛提供了有用的預設設定和 Gradle 任務。io.spring.dependency-management Gradle 外掛提供了依賴管理，以便您可以省略“推薦”依賴項的 version 標籤。

由於我們正在開發一個 Web 應用，我們將新增 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 Web 伺服器和 Spring Boot 本身。

編寫程式碼

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

Java
Kotlin

package com.example;

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);
	}

}

package com.example

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。這被稱為一個 stereotype 註解。它為閱讀程式碼的人以及 Spring 提供了提示，表明該類扮演著特定的角色。在本例中，我們的類是一個 web @Controller，因此 Spring 在處理傳入的 web 請求時會考慮它。

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

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

@SpringBootApplication 註解

第二個類級別註解是 @SpringBootApplication。這個註解被稱為一個 meta-annotation，它結合了 @SpringBootConfiguration、@EnableAutoConfiguration 和 @ComponentScan。

其中，我們最感興趣的註解是 @EnableAutoConfiguration。@EnableAutoConfiguration 會根據您新增的 jar 依賴項，指示 Spring Boot“猜測”您希望如何配置 Spring。由於 spring-boot-starter-web 添加了 Tomcat 和 Spring MVC，自動配置會假定您正在開發一個 Web 應用並相應地設定 Spring。

Starters 與自動配置

自動配置旨在與 starter 很好地配合使用，但這兩個概念並非直接繫結。您可以自由選擇 starter 之外的 jar 依賴項。Spring Boot 仍然會盡力自動配置您的應用。

“main” 方法

我們應用的最後一部分是 main 方法。這是一個遵循 Java 應用入口點約定的標準方法。我們的 main 方法透過呼叫 run 方法，將職責委託給 Spring Boot 的 SpringApplication 類。SpringApplication 會引導我們的應用，啟動 Spring，進而啟動自動配置的 Tomcat web 伺服器。我們需要將 MyApplication.class 作為引數傳遞給 run 方法，以告訴 SpringApplication 哪個是主要的 Spring 元件。args 陣列也會被傳遞進去，以暴露任何命令列引數。

執行示例

Maven

此時，您的應用應該可以工作了。由於您使用了 spring-boot-starter-parent POM，您有一個很有用的 run 目標可以用來啟動應用。在專案根目錄下輸入 mvn spring-boot:run 來啟動應用。您應該會看到類似於以下的輸出

$ mvn spring-boot:run

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

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

Hello World!

要平滑退出應用，請按 ctrl-c。

Gradle

此時，您的應用應該可以工作了。由於您使用了 org.springframework.boot Gradle 外掛，您有一個很有用的 bootRun 目標可以用來啟動應用。在專案根目錄下輸入 gradle bootRun 來啟動應用。您應該會看到類似於以下的輸出

$ gradle bootRun

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

如果您在 Web 瀏覽器中開啟 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 目標。如果您不使用父 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.4.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 的小得多的檔案。這是 Spring Boot 重新打包之前 Maven 建立的原始 jar 檔案。

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

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

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.4.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。