RESTful介紹和最佳實踐

文章目錄

• 1、 RESTful概述
• • 1.1、 什麼是REST
  • 1.2、 什麼是RESTful
  • 1.3、 REST标準規範
  • • 1.3.1、 REST風格的WEB設計原則
    • 1.3.2、 如何統一接口規則
• 2、 REST最佳實踐
• • 2.1、 接口設計
  • 2.2、 響應設計
  • • 2.2.1、 響應規則
    • 2.2.2、 響應字段
    • 2.2.3、 響應狀态碼
• 3、 REST實作使用者CRUD
• • 3.1、 根據ID查詢使用者
  • 3.2、 查詢所有使用者
  • 3.3、 新增使用者
  • 3.4、 修改使用者
  • 3.5、 删除使用者

1、 RESTful概述

1.1、 什麼是REST

作者：

REST 僅僅是一種架構的風格，并不是真正的架構，也不是一個軟體，而是一種思想。

我們可以基于現有的HTTP、URI、XML、等現有技術來實作REST的風格。而不用去學習任何新的技術。

而學習REST的關鍵，不是任何的API或者實作方式，而是這種思想。

1. 全新的界面設計 ，将會帶來全新的寫作體驗；
2. 在創作中心設定你喜愛的代碼高亮樣式，Markdown 将代碼片顯示選擇的高亮樣式 進行展示；
3. 增加了 圖檔拖拽 功能，你可以将本地的圖檔直接拖拽到編輯區域直接展示；
4. 全新的 KaTeX數學公式 文法；
5. 增加了支援甘特圖的mermaid文法1 功能；
6. 增加了 多螢幕編輯 Markdown文章功能；
7. 增加了 焦點寫作模式、預覽模式、簡潔寫作模式、左右區域同步滾輪設定 等功能，功能按鈕位于編輯區域與預覽區域中間；
8. 增加了 檢查清單 功能。

1.2、 什麼是RESTful

1.3、 REST标準規範

在REST提出後，到了2008年，Java才具有了完善的官方REST式的WEB服務标準規範：JAX-RS标準：

Jersey是Java的JAX-RS标準的一種實作架構，就是一種RESTful 的架構，基于Jersey開發的WEB應用自然就是Restful的WEB服務

SpringMVC天生也是支援REST标準的。

1.3.1、 REST風格的WEB設計原則

從上面的定義中，我們可以發現REST其實是一種組織Web服務的架構風格，而并不是我們想象的那樣是實作Web服務的一種新的技術，更沒有要求一定要使用HTTP。其目标是為了建立具有良好擴充性的分布式系統。它提出了一系列架構級限制。這些限制有：

• 使用客戶/伺服器模型

  客戶和伺服器之間通過一個統一的接口來互相通訊。

• 階層化的系統

  在一個REST系統中，用戶端并不會固定地與一個伺服器打交道。

• 無狀态

  在一個REST系統中，服務端并不會儲存有關客戶的任何狀态。也就是說，用戶端自身負責使用者狀态的維持，并在每次發送請求時都需要提供足夠的資訊。

  Http協定本身就是無狀态的協定。

• 可緩存

  REST系統需要能夠恰當地緩存請求，以盡量減少服務端和用戶端之間的資訊傳輸，以提高性能。

• 統一接口

  一個REST系統需要使用一個統一的接口來完成子系統之間以及服務與使用者之間的互動。這使得REST系統中的各個子系統可以獨自完成演化。

  如果一個系統滿足了上面所列出的五條限制，那麼該系統就被稱為是RESTful的

1.3.2、 如何統一接口規則

要實作統一接口，必須滿足一下條件：

• 每個資源都擁有一個資源辨別。每個資源的資源辨別可以用來唯一地标明該資源REST是圍繞資源為核心的，任何接口的設計都是圍繞着資源進行，而不再是圍繞着業務功能

• 消息的自描性

  在REST系統中所傳遞的消息需要能夠提供自身如何被處理的足夠資訊。例如該消息所使用的MIME類型，是否可以被緩存，傳回結果包含哪些字段等

• 資源操作動作

  不使用動詞來描述要對資源進行的操作，那麼REST中該如何表示CRUD呢？

  一般我們會借助于HTTP協定中的請求方法來表明對資源的操作：

  

  舉例：

以前非REST時，我們的URI
查詢使用者： http://localhost/user/query?id=1		- GET
添加使用者： http://localhost/user/insert			- POST
修改使用者： http://localhost/user/update 			- POST
删除使用者： http://localhost/user/delete?id=1		- GET
遵循REST規範的URI定義：
查詢使用者： http://localhost/user/{id}		- GET
添加使用者： http://localhost/user		        - POST
修改使用者： http://localhost/user 		    - PUT
删除使用者： http://localhost/user/{id}		- DELETE
           

2、 REST最佳實踐

2.1、 接口設計

REST中的最佳實踐：

2.2、 響應設計

2.2.1、 響應規則

示例：

2.2.2、 響應字段

2.2.3、 響應狀态碼

3、 REST實作使用者CRUD

3.1、 根據ID查詢使用者

根據REST的原則，我們查詢後需要根據結果傳回不同的狀态碼： 資源存在：200

資源不存在：404

内部異常：500 這裡通過ResponseEntity來封裝響應的結果，包含兩部分内容：資料和狀态碼

1. 定義Service

@Service
@Transactional
public class UserService {

    @Resource
    private UserMapper userMapper;

    public User queryById(Long id){
        return this.userMapper.selectByPrimaryKey(id);
    }
 }  
           

1. 定義Controller

@RestController
@RequestMapping("/hello")
public class HelloController {

    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    public ResponseEntity<User> queryById(@PathVariable("id") Long id){
        try {
            User user = userService.queryById(id);
            return ResponseEntity.ok(user);
        } catch (Exception e) {
            e.printStackTrace();
            // 出現異常，傳回500
            return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
        }
    }
}   
           

1. 測試

3.2、 查詢所有使用者

1. 定義Service

public List<User> queryAll(){
        return this.userMapper.selectAll();
    }

           

1. 定義Controller

@GetMapping
public ResponseEntity<List<User>> queryAll(){
    try {
        List<User> userList = userService.queryAll();
        return ResponseEntity.ok(userList);
    } catch (Exception e) {
        e.printStackTrace();
        // 出現異常，傳回500
        return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

           

1. 測試

   

3.3、 新增使用者

在原來的新增使用者功能中，我們傳回的結果包含了status，也就是狀态，這不符合REST風格。響應狀态應該包含在header中

并且新增成功，應傳回201狀态碼

1. 定義Service中的方法

public void addUser(User user){
	this.userMapper.insert(user);
}

           

1. 定義Controller中的方法

@PostMapping
    public ResponseEntity<Void> addUser(@RequestBody User user){
        try {
            userService.addUser(user);
            return new ResponseEntity<Void>(HttpStatus.CREATED);
        } catch (Exception e) {
            e.printStackTrace();
            // 出現異常，傳回500
            return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
        }
    }
           

1. 測試

   

   

   

3.4、 修改使用者

修改成功，但是沒有結果傳回，根據REST原則，傳回204：

1. 定義Service中的方法

public void updateUser(User user){
	this.userMapper.updateByPrimaryKey(user);
}
           

1. 定義Controller中的方法

@PutMapping
public ResponseEntity<Void> modifyUser(User user){
    try {
        userService.updateUser(user);
        return new ResponseEntity<Void>(HttpStatus.NO_CONTENT);
    } catch (Exception e) {
        e.printStackTrace();
        // 出現異常，傳回500
        return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

           

1. 測試

   

   

3.5、 删除使用者

删除成功，但是沒有結果傳回，根據REST原則，傳回204

1. 定義Service中的方法

public void deleteById(Long id){
    this.userMapper.deleteByPrimaryKey(id);
}
           

1. 定義Controller中的方法

@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id){
    try {
        userService.deleteById(id);
        return new ResponseEntity<Void>(HttpStatus.NO_CONTENT);
    } catch (Exception e) {
        e.printStackTrace();
        // 出現異常，傳回500
        return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
    }
}
           

1. 測試：

   

   

1. mermaid文法說明 ↩︎