restful介面規範與postman調試工具介紹

作者：Eve Cole 更新時間：2023-04-04 09:51:58

最近學習了RESTful介面規範，並用Postman作了介紹，在這裡記錄一下有關RESTful介面規範： 1.什麼是RESTful？

REST：是web服務的一種架構風格;使用HTTP,URI,XML,JSON,HTML等廣泛流行的標準和協定;輕量級,跨平台,跨語言的架構設計;它是一種設計風格,不是一種標準,是一種思想。

RESTful：對應的中文是rest式的;Restful web service是一種常見的rest的應用,是遵守了rest風格的web服務;rest式的web服務是一種ROA(The Resource-Oriented Architecture)(面向資源的架構)【建議：web前端】

RESTful的本質是一種軟體架構風格，核心是面向資源，解決的問題：

降低開發的複雜性
提高系統的可擴展性

2.SOAP和REST的差別：
SOAP （Simple Object Access Protocol）：交換資料一種協定規範,是一種輕量的、簡單的、基於XML的協定。
REST （Representational State Transfer）：一種軟體架構風格,可以降低開發的複雜性,提高系統的可擴展性。

效率和易用性：
SOAP ：由於各種需求不斷擴充其本身協議的內容,導致在SOAP處理方面的性能下降。同時在易用性方面以及學習成本上也有所增加。
RESTful ：由於其面向資源介面設計以及操作抽象簡化了開發者的不良設計,同時也最大限度的利用了Http最初的應用協定設計理念。

安全性：
RESTful對於資源型服務介面來說很合適,同時特別適合對於效率要求很高，但是對於安全要求不高的場景。
SOAP的成熟性可以為需要提供給多開發語言的,對於安全性要求較高的介面設計帶來便利。
總之：
安全性： SOAP會比REST好；
效率與易用性: REST更勝一籌；
成熟度:總的來說SOAP在成熟度上優於REST。

3.如何設計RESTful API ：
資源路徑：在RESTful架構中,每個網址代表一種資源,所以網址中不能有動詞,只能有名詞。一般來說API中的名詞要使用複數。

HTTP動詞：對於資源的操作( CURD ) ,由HTTP動詞(謂詞)表示。

GET :從伺服器取出資源(一項或多項)。
POST:在伺服器新建一個資源。
PUT:在伺服器更新資源(客戶端提供改變後的完整資源)。
DELETE :從伺服器刪除資源。

我們以動物園（zoo）舉個例子（包括各種動物和員工的資料）：

 https://api.example.com/v1/zoos //動物園資源https://api.example.com/v1/animals //動物資源https://api.example.com/v1/employees //僱員資源

POST /zoos :新建一座動物園
GET /zoos/ID :取得某個指定動物園的信息
PUT /zoos/ID:更新某介指定動物園的信息
DELETE /zoos/D:刪除某個動物園

過濾訊息：

?limit=10：指定回傳記錄的數量
?offset=10：指定傳回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
?sortby=name&order=asc：指定傳回結果依照哪個屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件

狀態碼：

200 (OK)-如果現有資源已被更改
201 ( created )-如果新資源被創建
202 ( accepted )-已接受處理請求但尚未完成(非同步處理)
301 (Moved Permanently )-資源的URI被更新
303 ( 參見 Other )-其他(如,負載平衡)
400 ( bad request )-指壞請求
404 (not found )-資源不存在
406 (not acceptable )-服務端不支援所需表示
409 (conflict)-通用衝突
412 (Precondition Failed )-前置條件失敗(如執行條件更新時的衝突)
415 (unsupported media type )-接受到的表示不受支持
500 (internal server error )-通用錯誤回應
503 (Service Unavailable )-服務目前無法處理請求

錯誤處理：
在傳回的訊息中將error作為鍵名，出錯訊息作為鍵值。

 {
error: “Invalid API key”
}

回傳結果：

GET /collection：傳回資源物件的清單（陣列）
GET /collection/resource：傳回單一資源對象
POST /collection：傳回新產生的資源對象
PUT /collection/resource：傳回完整的資源對象
PATCH /collection/resource：傳回完整的資源對象
DELETE /collection/resource：傳回一個空文檔

4.REST風格的介面測試流程：
我們直接用一張圖來介紹吧

在這裡插入圖片描述

5.程式碼編寫和Postman測試：
工具：idea，mysql資料庫，Postman
資料庫表格資料：

在這裡插入圖片描述

實體類別：

前端（vue）入門到精通課程：進入學習

@Data
@ApiModel("使用者實體類別")
public class User extends Model<User> implements Serializable {
@ApiModelProperty("用戶id")
@NotNull(message = "用戶id不能為空")
private Integer id;

@NotBlank(message = "使用者名稱不能為空")
@ApiModelProperty("使用者名稱")
private String name;

@Min(1)
@Max(100)
@ApiModelProperty("用戶年齡")
private Integer age;

@NotEmpty(message = "郵箱不能為空")
@ApiModelProperty("使用者信箱")
@Email
private String email;

@ApiModelProperty("0:未刪除 1：已刪除")
@TableLogic
private Integer deleted;

@NotBlank(message = "密碼不能為空")
@ApiModelProperty("使用者密碼")
private String password;
}

controller層的程式碼（service層省略）：

 @Api(tags = "使用者管理")
@RestController
@RequestMapping("/MyWebsite/user")
public class UserController {
@Autowired
private UserServiceImpl userServiceimpl;

@ApiOperation(value = "新增使用者")
@PostMapping
public int insertUser(User user) {

System.out.println("新增成功");

return userServiceimpl.insertUser(user);
}

@ApiOperation(value = "修改使用者資訊")
@PutMapping
public void updateUser(@RequestBody @Valid User user) {

userServiceimpl.updateUser(user);

System.out.println("修改成功");
}

@ApiOperation(value = "刪除使用者", notes = "根據id刪除使用者")
@DeleteMapping("/{id}")
public int deleteUser(@ApiParam("用戶id") @PathVariable @Valid Integer id) {

System.out.println("刪除成功");

return userServiceimpl.deleteUser(id);
}

@ApiOperation(value = "查詢所有使用者")
@GetMapping
public List<User> allUser() {

System.out.println("查詢成功");

return userServiceimpl.allUser();
}

@ApiOperation(value = "id查詢使用者")
@GetMapping("/{id}")
public User selectById(@PathVariable("id") String id) {
return userServiceimpl.selectById(id);
}
}

利用Postman測試（url路徑要對應上）：
查詢所有使用者：http://localhost:8081/MyWebsite/user
Header：Content-Type=application/json
Body：空

在這裡插入圖片描述