Spring Boot入門系列(二十)快速打造Restful API 介面

章為忠發表於2020-10-10

spring boot入門系列文章已經寫到第二十篇,前面我們講了spring boot的基礎入門的內容,也介紹了spring boot 整合mybatis,整合redis、整合Thymeleaf 模板引擎 等各種框架,同時也介紹了使用jdbcTemplate 運算元據庫,配置多資料來源 等系列內容。應該說spring boot 常用的功能基本上都覆蓋到了。接下來說一說spring boot 比較實用的專案級的功能。首先會介紹spring boot 如何快速打造Restful API介面。

隨著網際網路化等逐漸深入,應用系統也變得越來越複雜,系統架構正在朝著微服務化,中臺化的方向發展。這就需要各個系統、各個廠家之間的資料頻繁互動。所以,使用 Restful 風格構建的應用介面適用於移動網際網路廠商的業務場景,正在被越來越多的企業推薦使用。那麼什麼是 RESTful 呢?

 

一、什麼是 RESTful

RESTful 是目前最流行的網際網路軟體架構。 REST(Representational State Transfer,表述性狀態轉移)一詞是由 Roy Thomas Fielding 在他 2000 年博士論文中提出的,定義了他對網際網路軟體的架構原則,如果一個架構符合 REST 原則,則稱它為 RESTful 架構。

RESTful 把伺服器端,所有的應用程式狀態和功能定義為“資源”(Resource)。從 RESTful 的⻆度看,網路上的任何東西都是資源,它可以是一段文字、一張圖片、一個服務等,每個資源都對應一個特定的 URI(統一資源定位符),並把它進行標示,訪問這個 URI 就可以獲得這個資源 。

資源可以有多種表現形式,也就是資源的“表述”(Representation),比如一張圖片可以使用 JPEG 格式也可以使用 PNG 格式。 URI 只是代表了資源的實體,並不能代表它的表現形式。網際網路中,客戶端和服務端之間的互動傳遞的就是資源的表述,我們上網的過程,就是呼叫資源的 URI,獲取它不同表現形式的過程。這種互動只能使用無狀態協議 HTTP,也就是說,服務端必須儲存所有的狀態,客戶端可以使用 HTTP 的幾個基本操作,包括 GET(獲取)、 POST(建立)、 PUT(更新)與DELETE(刪除),使得服務端上的資源發“狀態轉化”(State Transfer),也就是所謂的“表述性狀態轉移” 。

Restful 相比於 SOAP 更加簡單明瞭,它並沒有一個明確的標準,而更像是一種設計的風格。

Restful 特點包括:
  1、每一個URI代表1種資源;
  2、客戶端使用GET、POST、PUT、DELETE4個表示操作方式的動詞對服務端資源進行操作:GET用來獲取資源,POST用來新建資源(也可以用於更新資源),PUT用來更新資源,DELETE用來刪除資源;
  3、通過操作資源的表現形式來操作資源;
  4、資源的表現形式是XML或者HTML;
  5、客戶端與服務端之間的互動在請求之間是無狀態的,從客戶端到服務端的每個請求都必須包含理解請求所必需的資訊。
 

二、Spring Boot 實現Restful 方案

Spring Boot 開發Restful j介面非常簡單,通過不同的註解來支援前端的請求,除了經常使用的@RestController 註解外,Spring Boot 還提了一些組合註解。這些註解來幫助簡化常用的 HTTP 方法的對映,並更好地表達被註解方法的語義 。

Srping Boot 提供了與Rest 操作方式(GET、POST、PUT、DELETE)對應的註解:

  1、@GetMapping,處理 Get 請求
  2、@PostMapping,處理 Post 請求
  3、@PutMapping,用於更新資源
  4、@DeleteMapping,處理刪除請求
  5、@PatchMapping,用於更新部分資源

@PutMapping 主要是用來更新整個資源的,@PatchMapping 主要表示更新部分欄位

之前我們也介紹過,Spring Boot 提供了專門做資料處理的控制器:@RestController ,其實這些註解就是我們使用的 @RequestMapping 的簡寫版本:@GetMapping 其實就等於@RequestMapping(value = "/xxx",method = RequestMethod.DELETE) 。

 

三、Spring Boot 快速實現Restful

如何建立Spring Boot 專案之前的文章裡面都有,這裡不在重複了。可以看我之前的系列文章:https://www.cnblogs.com/zhangweizhong/category/1657780.html

1、設計介面

根據之前介紹的Restful 設計風格設計一組對使用者操作的 RESTful API

  • /user         POST         建立使用者
  • /user/id     GET            根據 id 獲取使用者資訊
  • /user         PUT            更新使用者
  • /user/id     DELETE     根據 id刪除對應的使用者

以上,就是對user操作的介面定義,在實際專案的Restful API 介面文件還會定義全部請求的資料結構體。

 

2、實現介面

首先建立UserController 控制器,定義之前設計的相關介面。

package com.weiz.controller;

import com.weiz.pojo.SysUser;
import com.weiz.service.UserService;
import com.weiz.utils.JSONResult;
import org.n3r.idworker.Sid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.Date;

@RestController
@RequestMapping("/")
public class UserController {

@Autowired
private UserService userService;

@Autowired
private Sid sid;

@PostMapping(value = "user")
public JSONResult create() throws Exception {

String userId = sid.nextShort();
SysUser user = new SysUser();
user.setId(userId);
user.setUsername("spring boot" + new Date());
user.setNickname("spring boot" + new Date());
user.setPassword("abc123");
user.setIsDelete(0);
user.setRegistTime(new Date());

userService.saveUser(user);
return JSONResult.ok("儲存成功");
}

@PutMapping(value = "user")
public JSONResult update() {
SysUser user = new SysUser();
user.setId("10011001");
user.setUsername("10011001-updated" + new Date());
user.setNickname("10011001-updated" + new Date());
user.setPassword("10011001-updated");
user.setIsDelete(0);
user.setRegistTime(new Date());
userService.updateUser(user);

return JSONResult.ok("儲存成功");
}


@DeleteMapping("user/{userId}")
public JSONResult delete(@PathVariable String userId) {
userService.deleteUser(userId);
return JSONResult.ok("刪除成功");
}

@GetMapping("user/{userId}")
public JSONResult queryUserById(@PathVariable String userId) {
return JSONResult.ok(userService.queryUserById(userId));
}

}

說明:

  1、@PathVariable 註解,用於引數對映。

  2、Rest需要注意請求的方式,可以看到PUT和POST的URL是相同的,但是後端處理邏輯不同,所以使用的時候千萬別搞混了

 

3、測試
實際開發測試的過程中,一般使用postman測試相關的介面。當然,也可以用單元測試來實現。這裡簡單起見,直接用postman來測試剛剛定義的人員操作介面。

建立人員:/user

 

 

 

根據 id 獲取人員資訊:/user/id 

以上,測試了人員的建立和查詢介面,其他介面的測試也是一樣。 

 

最後

以上,就把Spring Boot 實現Restful API 介面介紹完了。 Restful 是一種非常優雅的設計,採用RESTful 設計API之後 /user/api一個URL地址解決,前端一看就能明白。

這個系列課程的完整原始碼,也會提供給大家。大家關注我的微信公眾號(架構師精進),回覆:springboot原始碼。獲取這個系列課程的完整原始碼。

 

相關文章