Day 22 - RESTful API 實作 - @GetMapping、@PostMapping...

哈囉大家好，我是古古。

在上一篇文章中，我們有介紹了什麼是 RESTful API，以及在設計 RESTful API 時，需要滿足哪三個設計條件，先讓大家對 RESTful API 有基本的認識。

而在了解了 RESTful API 的概念之後，接著這篇文章，我們就會實際到 Spring Boot 上，練習要如何在 Spring Boot 中設計和實作出 RESTful API，所以我們就開始吧！

回顧：什麼是 RESTful API？ #

RESTful API 指的是「你所設計的 API 符合 REST 風格」，而 RESTful API 的目的，是為了「簡化工程師之間的溝通成本」，當每個工程師都安照共同的默契來設計 API 時，大家就可以設計出更一致的 API，因此就可以把溝通所花費的時間節省下來，進而提升開發的效率。

而要設計出 RESTful API 的話，需要符合以下三個條件：

1. 使用 Http method，表示要執行的資料庫操作
2. 使用 url 路徑，描述資源之間的階層關係
3. Response body 返回 JSON 或是 XML 格式

只要同時滿足這三個條件，就可以將你的 API 稱為是 RESTful API 了！

設計 RESTful API #

了解了 RESTful API 的概念之後，接著我們也可以試著去設計出一套 RESTful API 出來，並且了解要如何透過 Spring Boot 程式，去實作這套 RESTful API。

舉例來說，我們可以先設計出一個 Student class，並且在裡面新增 id 和 name 兩個變數，用來表示這個學生的 id 和名字，程式如下：

public class Student {
    Integer id;
    String name;
}

接著，我們可以為 Student 這個資源，去設計出一連串的 RESTful API：

• 像是我們需要一個「創建學生」的 API ，這樣子才能新增新同學的數據到資料庫
• 我們也需要一個「查詢學生」的 API，這樣子才能去查詢某一筆學生的數據
• …等等

所以針對 Student 這個「資源」，通常我們會設計四個最基本的 RESTful API 給他，也就是 CRUD（Create 新增、Read 查詢、Update 修改、Delete 刪除），具體設計方式如下圖所示：

所以透過這四個 RESTful API，就可以完成 Student 的「新增、查詢、修改、刪除」的四個基本操作了！

補充：「Create 新增、Read 查詢、Update 修改、Delete 刪除」這四個操作，又可以簡稱為 CRUD，幾乎每一種資源（ex: 商品、訂單、會員…等），都會需要這四個操作，因此 CRUD 也可以說是大家剛入門 Spring Boot 時，最常撰寫的程式。

在 Spring Boot 中實作 RESTful API #

指定 Http method 的方式：@GetMapping、@PostMapping…等 #

當我們設計好 Student 資源的四個基本 RESTful API 之後，因此前端到時候想要去新增一筆 Student 數據時，前端就要使用 POST，去請求 /students 這個 url 路徑，這樣子才能夠創建一筆新的 Student 數據到資料庫中。

而在 Spring Boot 中，有兩種方式可以「限制」前端只能用某個 Http method 來請求 url 路徑，分別是：

@RequestMapping(value = "/students", method = RequestMethod.POST)

以及

@PostMapping("/students")

上面這兩種寫法，都可以限制前端只能使用 POST，去請求 /students 的 url 路徑，他們的差別就只是一行寫起來比較長、一行寫起來比較短而已。

在之前的文章中，我們都是使用上面的 @RequestMapping 的寫法來設計 url 路徑，而他的缺點，就是寫起來比較冗長，不利於後續維護。

因此一般在實作上，通常會改成使用下方的 @PostMapping 的寫法，直接透過 @PostMapping 這個註解，去「限制」前端只能使用 POST 來請求，這樣子的寫法會更簡潔、更一目瞭然，所以一般在設計 RESTful API 時，通常就是會採用下方的 @PostMapping 來實作！

Spring Boot 中常用的 RESTful API 註解 #

在 Spring Boot 中，除了可以使用 @PostMapping，去限制前端只能使用 POST 來請求之外，Spring Boot 也是有提供其他好用的註解，讓我們去限制其他的 Http method 的。

像是 Spring Boot 就提供了以下四個註解給我們使用：

• @GetMapping：限制前端只能使用 GET 來請求該 url 路徑
• @PostMapping：限制前端只能使用 POST 來請求該 url 路徑
• @PutMapping：限制前端只能使用 PUT 來請求該 url 路徑
• @DeleteMapping：限制前端只能使用 DELETE 來請求該 url 路徑

不過這些註解大家不需要死背，因為大家如果觀察一下的話，可以發現「這些註解都是以 Http method 當作開頭」來設計，像是 @GetMapping 就是 Get + Mapping，而 @PostMapping 則是 Post + Mapping。

所以當大家以後看到這些註解時，只要直接觀察註解的名稱（XXX + Mapping），就可以知道他想要限制的是哪一種請求方法了！

具體實作 #

設計好 RESTful API，並且也了解了 Spring Boot 中的 @GetMapping、@PostMapping…等註解的用法之後，接下來我們就可以實際到 Spring Boot 中，去實作這四個 RESTful API 出來了！

前期準備 #

首先大家可以先刪除 MyController class，這個 class 後續不會再使用到了。刪好之後，接著在 Spring Boot 中創建一個新的 class 出來，並且命名為 Student class，然後在裡面寫上兩個變數 id 和 name，用來表示這個學生的 id 和名字，具體程式如下：

public class Student {

    private Integer id;
    private String name;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

接著我們再創建出一個新的 class，名字為 StudentController，並且在裡面寫上下方的程式：

@RestController
public class StudentController {

}

所以整個 Spring Boot 程式的結構，就會像是下方這個樣子：

實作 POST /students（創建 Student 數據） #

實作好前期準備的程式之後，接著我們就可以來實作第一個 RESTful API，也就是 POST /students 這個 API 了！

首先 POST /students 這個 API 所代表的意義，即是「創建一個新的 Student 數據」。

要實作 POST /students API 的話，我們可以先運用上面所介紹的 RESTful API 相關註解，即是使用 @PostMapping 這個註解，去限制這個 API 只能夠使用 POST 來請求。

而至於在實作 POST 請求的方法時，要如何去接住前端所傳遞過來的參數，這部分我們可以照著 Day 19 - 取得請求參數 (上) - @RequestParam、@RequestBody 的介紹，使用 @RequestBody 去接住前端所傳遞過來的 JSON 參數。

因此在我們使用 @RequestBody 之後，Spring Boot 到時候就會將前端所傳遞的 JSON 數據，自動地去轉換成 student 類型的參數了。

程式實作 #

@PostMapping("/students")
public String create(@RequestBody Student student) {
    return "執行資料庫的 Create 操作";
}

API Tester 中的請求寫法 #

實作 GET /students/123（查詢 Student 數據） #

實作完 POST /students 之後，接著我們可以來實作第二個 RESTful API，即是 GET /students/123。

GET /students/123 這個 API 所代表的意義，是去「查詢 student id 為 123 的 Student 數據」。

要實作 GET /students/123 這個 API 的話，則要運用 RESTful API 註解中的 @GetMapping，去指定這個 API 只能夠使用 GET 來請求。

另外在實作 GET /students/123 時，因為 RESTful API 會使用「url 路徑來表達階層關係」，所以我們想要取得到的 student id 的值，就會被放在 url 路徑 /students/123 裡面。

因此為了取得放在 url 路徑中的 student id 的值，我們就得使用到 Day 20 - 取得請求參數 (下) - @RequestHeader、@PathVariable 所介紹到的 @PathVariable 來實作，即是從 /students/123 這個 url 路徑中，取得到其中的 123 的數據。

補充：不知道大家有沒有發現，其實我們在前面所學的內容，在這篇文章中全部應用起來了👍。這就是為什麼我們前面要花許多篇幅介紹 Http 協議、GET 和 POST、以及 Spring Boot 取得前端參數的四種註解，因為這些知識可以幫助我們更好的設計和實作 RESTful API，所以這些技術可以說是必學的知識！

程式實作 #

@GetMapping("/students/{studentId}")
public String read(@PathVariable Integer studentId) {
    return "執行資料庫的 Read 操作";
}

API Tester 中的請求寫法 #

實作 PUT /students/123（更新 Student 數據） #

實作完 GET /students/123 之後，接著我們也可以來實作第三個 RESTful API，即是 PUT /students/123。

PUT /students/123 這個 API 所代表的意義，是去「更新 student id 為 123 的數據」。

更新的 API 算是實作上比較複雜的 API，首先我們一樣是要先運用 RESTful API 註解中的 @PutMapping，去限制這個 API 只能夠使用 PUT 來請求。

而在參數的部分，則會同時使用到 @PathVariable 和 @RequestBody 這兩個註解，去取得前端所傳過來的參數。

• @PathVariable 負責從 url 路徑中，取得「要更新的是哪一個 student id」的值（也就是從 /students/123 中，取得 student id 的值 123）
• @RequestBody 則是負責去接住前端傳過來的 JSON 數據，了解前端想要把這個 Student 數據更新成哪些值

如果不熟悉 @PathVariable 和 @RequestBody 的用法的話，一樣是可以參考前面的 Day 19 和 Day 20 的介紹，回頭複習一下他們的用法。

也建議大家可以先完成前面的 POST 和 GET 的實作之後，再來練習 PUT 實作，會比較好上手一點（因為 PUT 在實作上確實比較複雜）。

程式實作 #

@PutMapping("/students/{studentId}")
public String update(@PathVariable Integer studentId,
                     @RequestBody Student student) {
    return "執行資料庫的 Update 操作";
}

API Tester 中的請求寫法 #

實作 DELETE /students/123（刪除 Student 數據） #

實作完前面的 POST、GET、PUT API 之後，最後我們可以來介紹實作第四個 RESTful API，即是 DELETE /students/123。

DELETE /students/123 這個 API 所代表的意義，是去「刪除 student id 為 123 的數據」。

要實作 DELETE /students/123 這個 API 的話，就要運用 RESTful API 註解中的 @DeleteMapping，去指定這個 API 只能夠使用 DELETE 來請求。

另外也因為 RESTful API 會使用「url 路徑來表達階層關係」，所以這裡和 GET API 的實作很類似，都是去使用 @PathVariable，從 url 路徑 /students/123 裡面取得 student id 的值 123。

程式實作 #

@DeleteMapping("/students/{studentId}")
public String delete(@PathVariable Integer studentId) {
    return "執行資料庫的 Delete 操作";
}

API Tester 中的請求寫法 #

實作成果 #

所以透過上述的實作，最終我們就可以在 StudentController 裡面，將這四個 RESTful API 給實作出來了，結果如下：

因此後續我們就可以透過這四個 RESTful API，去對 Student 資源進行「Create 新增、Read 查詢、Update 修改、Delete 刪除」這四個 CRUD 的基本操作了！

總結 #

這篇文章我們先介紹了如何針對 Student 這個資源，去設計出一套 RESTful API 出來，並且也有實際到 Spring Boot 中，去使用 @GetMapping、@PostMapping…等註解，在 Spring Boot 中實作出 RESTful API。所以大家以後就可以透過同樣的方式，在你的 Spring Boot 程式裡面實作 RESTful API 了！

而在我們了解了最重要的 RESTful API 的設計和實作之後，在下一篇文章中，我們就會回頭來介紹一下 Http response 中也很重要的一個部分：Http status code，了解要如何透過 Http status code，讓前端快速的知道這一次請求的結果為何，那我們就下一篇文章見啦！

補充：本文是擷取自我開設的線上課程 Java 工程師必備！Spring Boot 零基礎入門 的內容，如果你想了解更多的 Spring Boot 的用法，歡迎參考課程簡介 （輸入折扣碼「HH202504KU」即可享 85 折優惠）。