入門指南 | 建構 RESTful Web 服務

您將建構的內容

您將建構一個服務，該服務將接受位於 https://127.0.0.1:8080/greeting 的 HTTP GET 請求。

它將以 JSON 格式回應問候語，如下列清單所示

{"id":1,"content":"Hello, World!"}

您可以透過查詢字串中的選用 name 參數來自訂問候語，如下列清單所示

https://127.0.0.1:8080/greeting?name=User

name 參數值會覆寫預設值 World，並反映在回應中，如下列清單所示

{"id":1,"content":"Hello, User!"}

您需要的東西

約 15 分鐘
您慣用的文字編輯器或 IDE
Java 17 或更高版本
Gradle 7.5+ 或 Maven 3.5+
您也可以將程式碼直接匯入您的 IDE

如何完成本指南

如同大多數 Spring 入門指南，您可以從頭開始並完成每個步驟，或者您可以略過您已熟悉的基本設定步驟。無論哪種方式，您最終都會得到可運作的程式碼。

若要從頭開始，請繼續前往從 Spring Initializr 開始。

若要略過基本步驟，請執行下列操作

下載並解壓縮本指南的原始碼儲存庫，或使用 Git 複製它： git clone https://github.com/spring-guides/gs-rest-service.git
cd 進入 gs-rest-service/initial
跳到建立資源表示類別。

當您完成時，您可以對照 gs-rest-service/complete 中的程式碼檢查您的結果。

從 Spring Initializr 開始

您可以使用這個預先初始化的專案，然後按一下 Generate (產生) 下載 ZIP 檔案。此專案已設定為符合本教學課程中的範例。

若要手動初始化專案

導覽至 https://start.spring.io。此服務會提取應用程式所需的所有相依性，並為您完成大部分的設定。
選擇 Gradle 或 Maven 以及您想要使用的語言。本指南假設您選擇 Java。
按一下 Dependencies (相依性) 並選取 Spring Web。
按一下 Generate (產生)。
下載產生的 ZIP 檔案，這是使用您的選擇設定的 Web 應用程式的封存檔。

如果您的 IDE 具有 Spring Initializr 整合，您可以從您的 IDE 完成此程序。

您也可以從 Github 分叉專案，並在您的 IDE 或其他編輯器中開啟它。

建立資源表示類別

現在您已設定專案和建置系統，您可以建立您的 Web 服務。

從思考服務互動開始此過程。

此服務將處理針對 /greeting 的 GET 請求，選擇性地在查詢字串中帶有 name 參數。GET 請求應傳回 200 OK 回應，且主體中包含代表問候語的 JSON。它應類似於下列輸出

{
    "id": 1,
    "content": "Hello, World!"
}

id 欄位是問候語的唯一識別碼，而 content 是問候語的文字表示法。

若要為問候語表示法建模，請建立資源表示類別。若要執行此操作，請為 id 和 content 資料提供 Java 記錄類別，如下列清單 (來自 src/main/java/com/example/restservice/Greeting.java) 所示

package com.example.restservice;

public record Greeting(long id, String content) { }

此應用程式使用 Jackson JSON 程式庫自動將 Greeting 類型的執行個體封送處理為 JSON。Web starter 預設包含 Jackson。

建立資源控制器

在 Spring 的建構 RESTful Web 服務方法中，HTTP 請求由控制器處理。這些元件由 @RestController 註解識別，且下列清單 (來自 src/main/java/com/example/restservice/GreetingController.java) 中顯示的 GreetingController 處理針對 /greeting 的 GET 請求，方法是傳回 Greeting 類別的新執行個體

package com.example.restservice;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

	private static final String template = "Hello, %s!";
	private final AtomicLong counter = new AtomicLong();

	@GetMapping("/greeting")
	public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
		return new Greeting(counter.incrementAndGet(), String.format(template, name));
	}
}

此控制器簡潔且簡單，但在底層運作了很多功能。我們將逐步分解它。

@GetMapping 註解確保針對 /greeting 的 HTTP GET 請求會對應到 greeting() 方法。

其他 HTTP 動詞 (例如，POST 的 @PostMapping) 也有對應的註解。還有一個 @RequestMapping 註解，它們都衍生自該註解，並且可以作為同義詞 (例如，@RequestMapping(method=GET))。

@RequestParam 將查詢字串參數 name 的值繫結到 greeting() 方法的 name 參數。如果請求中缺少 name 參數，則會使用 World 的 defaultValue。

方法主體的實作會建立並傳回新的 Greeting 物件，其 id 和 content 屬性基於來自 counter 的下一個值，並透過使用問候語 template 來格式化給定的 name。

傳統 MVC 控制器與先前顯示的 RESTful Web 服務控制器之間的主要差異在於 HTTP 回應主體的建立方式。此 RESTful Web 服務控制器不是依賴檢視技術來執行問候語資料到 HTML 的伺服器端轉譯，而是填入並傳回 Greeting 物件。物件資料將以 JSON 格式直接寫入 HTTP 回應。

此程式碼使用 Spring @RestController 註解，該註解將類別標記為控制器，其中每個方法都會傳回網域物件而不是檢視。它是同時包含 @Controller 和 @ResponseBody 的簡寫。

Greeting 物件必須轉換為 JSON。由於 Spring 的 HTTP 訊息轉換器支援，您不需要手動執行此轉換。因為 Jackson 2 在類別路徑上，所以 Spring 的 MappingJackson2HttpMessageConverter 會自動選擇將 Greeting 執行個體轉換為 JSON。

執行服務

Spring Initializr 為您建立應用程式類別。在此案例中，您不需要進一步修改類別。下列清單 (來自 src/main/java/com/example/restservice/RestServiceApplication.java) 顯示應用程式類別

package com.example.restservice;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class RestServiceApplication {

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

}

@SpringBootApplication 是一個便利註解，新增了下列所有內容

@Configuration：將類別標記為應用程式內容的 Bean 定義來源。
@EnableAutoConfiguration：告知 Spring Boot 根據類別路徑設定、其他 Bean 和各種屬性設定開始新增 Bean。例如，如果 spring-webmvc 在類別路徑上，則此註解會將應用程式標記為 Web 應用程式，並啟動主要行為，例如設定 DispatcherServlet。
@ComponentScan：告知 Spring 在 com/example 套件中尋找其他元件、組態和服務，使其找到控制器。

main() 方法使用 Spring Boot 的 SpringApplication.run() 方法啟動應用程式。您是否注意到沒有單行 XML？也沒有 web.xml 檔案。此 Web 應用程式是 100% 純 Java，而且您不必處理設定任何管線或基礎結構。

建置可執行 JAR

您可以使用 Gradle 或 Maven 從命令列執行應用程式。您也可以建置包含所有必要相依性、類別和資源的單一可執行 JAR 檔案並執行該檔案。建置可執行 JAR 讓您可以輕鬆地在整個開發生命週期、跨不同環境等情況下，將服務作為應用程式發佈、版本控制和部署。

如果您使用 Gradle，您可以使用 ./gradlew bootRun 來執行應用程式。或者，您可以使用 ./gradlew build 來建置 JAR 檔案，然後執行 JAR 檔案，如下所示

java -jar build/libs/gs-rest-service-0.1.0.jar

如果您使用 Maven，您可以使用 ./mvnw spring-boot:run 來執行應用程式。或者，您可以使用 ./mvnw clean package 建置 JAR 檔案，然後執行 JAR 檔案，如下所示

java -jar target/gs-rest-service-0.1.0.jar

此處描述的步驟會建立可執行 JAR。您也可以建置傳統 WAR 檔案。

會顯示記錄輸出。服務應在幾秒鐘內啟動並執行。

測試服務

現在服務已啟動，請造訪 https://127.0.0.1:8080/greeting，您應該會看到

{"id":1,"content":"Hello, World!"}

透過造訪 https://127.0.0.1:8080/greeting?name=User 來提供 name 查詢字串參數。請注意 content 屬性的值如何從 Hello, World! 變更為 Hello, User!，如下列清單所示

{"id":2,"content":"Hello, User!"}

此變更示範了 GreetingController 中的 @RequestParam 配置如預期般運作。name 參數已給定預設值 World，但可以透過查詢字串明確覆寫。

另請注意 id 屬性如何從 1 變更為 2。這證明您正在針對多個請求中的相同 GreetingController 執行個體工作，並且其 counter 欄位正在如預期般在每次呼叫時遞增。

摘要

恭喜！您剛剛使用 Spring 開發了一個 RESTful Web 服務。

另請參閱

下列指南也可能有所幫助

想要撰寫新的指南或貢獻現有的指南嗎？請查看我們的貢獻指南。

所有指南均以 ASLv2 授權發布程式碼，並以姓名標示-禁止改作創用 CC 授權條款 3.0 發布寫作內容。

建構 RESTful Web 服務