REST的6大指導(dǎo)原則

1. 前言

REST 全稱為 ：Resource Representational State Transfer. 是一種分布式超媒體系統(tǒng)（ distributed hypermedia systems ）架構(gòu)風(fēng)格。由Roy Fielding 提出。

REST API 也稱RESTful API， 其遵循REST架構(gòu)規(guī)范的應(yīng)用編程接口， 支持與RESTful WEB服務(wù)進(jìn)行交互。簡單來講就是：符合REST架構(gòu)風(fēng)格的 WEB API 或WEB 服務(wù)就是 REST API。

2. REST 的6大指導(dǎo)原則

REST 定義了6個(gè)原則，這些原則使得一個(gè)WEB API 成為真正的RESTful API。

• 統(tǒng)一接口（Uniform interface）
  開發(fā)者一旦熟悉了你的其中一個(gè)API，那么他就可以遵循類似的結(jié)構(gòu)去使用其他API.
• 客戶端服務(wù)器（Client-server）
  只要不改變他們之間的接口，服務(wù)端和客戶端可以相互替換或獨(dú)立開發(fā)。
• 無狀態(tài)（Stateless）
  客戶端上下文狀態(tài)不應(yīng)該存儲(chǔ)在服務(wù)端，而應(yīng)該有客戶端去管理程序的狀態(tài)
• 可緩存（Cacheable）
  優(yōu)秀的緩存可以部分或者完全消除客戶端和服務(wù)端的交互，最終提高應(yīng)用的伸縮性和性能。
• 分層系統(tǒng)（Layered System）
  REST可以允許你使用分層架構(gòu)，讓你在服務(wù)器A上部署API， 服務(wù)器B上存儲(chǔ)數(shù)據(jù)，服務(wù)器C上進(jìn)行權(quán)限驗(yàn)證，客戶端不知道它實(shí)際連接的是哪個(gè)服務(wù)器。
• 按需編碼（Code on demand （optional））
  這些規(guī)則可以幫組你構(gòu)建真正的RESTful API ，所以盡量遵循著些規(guī)則。如果因?yàn)槟承┰蜻`反這些規(guī)則，事實(shí)上你還是在構(gòu)建RESTful API ，只是不算真正的RESTful。

3. 最佳實(shí)踐

3.1 API名稱

API的名稱應(yīng)該出現(xiàn)在URL中，API的標(biāo)題也應(yīng)該和名稱一致，所以起名子也是比較重要的一點(diǎn)，這決定了你的API是否容易讓人讀懂！

3.2 API的版本

API的版本應(yīng)該遵循, MAJOR.MINOR.PATCH的結(jié)構(gòu)，即主要.次要.補(bǔ)丁 。

如果有重大的改動(dòng)，導(dǎo)致前后的版本不兼容應(yīng)該升級(jí)主要版本， 比如從1.0 升級(jí)到2.0。

如果只是增加了一些特性，前后的版本都是兼容話，可以升級(jí)次要版本， 比如從1.0 升級(jí)到1.1.

如果有一些小的bug修改的話，可以在補(bǔ)丁版本的上升級(jí)，比如從 1.0 升級(jí)到1.0.1

例如：

https://mysite.com/v1/...
https://mysite.com/v2/...

3.3提供準(zhǔn)確的API文檔

開發(fā)完成一個(gè)API之后，你需要讓API的使用者可以正確的使用它，那么就需要一份漂亮的API文檔了。

API文檔需要提供準(zhǔn)確的請(qǐng)求路徑， 請(qǐng)求示例， 以及各種error時(shí)的狀態(tài)碼等。 可以使用Swagger等工具。

3.4資源路徑命名

• 資源名稱使用名詞，而不要使用動(dòng)詞。
  比如 POST : /cars 表示創(chuàng)建cars , GET: /cars 表示查詢cars 而不應(yīng)該寫成/createCars ， /getCars 等等。
• 獲取集合資源與獲取特定資源,統(tǒng)一使用復(fù)數(shù)來表示資源。

  #獲取資源集合時(shí)使用復(fù)數(shù)名詞 
  例如 /schools
  
  
  #獲取特定資源
  例如 /schools/{school-id}  /schools/5
  
  
  #獲取特定資源的子資源 
  例如 /schools/{school-id}/grades  /schools/5/grades
  

3.5資源操作

RESTful API 使用HTTP 方法來對(duì)資源進(jìn)行操作，相對(duì)應(yīng)的一些常用操作如下：

• 創(chuàng)建資源 POST
  使用POST方法 創(chuàng)建資源，此處可以創(chuàng)建單個(gè)資源或者資源集合。創(chuàng)建成功應(yīng)該立馬返回HTTP 201， 二接受到resource并未立即添加資源則返回 HTTP 202 。

  例如： 使用POST: /schools 添加多個(gè)school資源，
           /schools/{school-id}/grades 添加某個(gè)school資源的grade，
  

• 查詢集合資源 及單個(gè)資源

  例如： 使用 GET: /schools?type=PRIMARY  查詢所有的小學(xué)
        使用 GET :/schools/{school-id}/grades 查詢某個(gè)學(xué)校的所有年級(jí)
            GET :/schools/{school-id}/grades/{grade-id}  查詢某個(gè)學(xué)校某個(gè)年級(jí)
  

• 更新及修改資源 PUT/PATCH
  更新個(gè)修改資源包含多種情況：
  一種是完全更新，使用新的資源完全替換舊的資源。

  例如：PUT: /schools/{school-id}/address  更新某個(gè)客戶學(xué)校的地址信息
  

  一種是修改局部更新，根據(jù)需求去更新修改原有的資源。

  例如：PATCH: /schools/{school-id}/teachers  調(diào)整某個(gè)學(xué)校的老師
  

  舉個(gè)例子

  原有的資源如下：

  {
      "a":"A",
      "b":{
          "c":"C",
          "d":"D"
      }
  }
  

  當(dāng)PATAH請(qǐng)求 如下：

  PATCH  HTTP/1.1
  Content-Type: application/merge-patch+json
  {
      "a":"Z",
      "b":{
          "d":null
      }
  }
  

  修改后的resource如下

  {
      "a":"Z",
      "b":{
          "c":"C"
      }
  }
  

• 刪除資源
  刪除資源使用DELETE方法，刪除的方法有直接刪除，或者使資源不可見。

3.6請(qǐng)求參數(shù)

• 其余不是資源的參數(shù)應(yīng)該出現(xiàn)在請(qǐng)求參數(shù)中。而且查詢參數(shù)應(yīng)該出現(xiàn)在GET請(qǐng)求中，不應(yīng)該出現(xiàn)在PUT，POST請(qǐng)求中。
• 請(qǐng)求參數(shù)應(yīng)該使用駝峰命名法。

  例如：GET /orders?startDate=2022-01-03&endDate=2022-02-03
      DELETE /orders?status=EXPIRED
  

• 使用唯一查詢參數(shù)進(jìn)行過濾

  GET /orders?orderType=PAID
  GET /orders?amount >100.00
  

• 分頁查詢

  API 使用offset={resultOffset}&limit={resultsPerPage} 進(jìn)行分頁查詢，
  并且以第0條數(shù)據(jù)為起始。
  
  另外也可以使用 page={pageNumber}&limit={resultPerPage} 此時(shí)起始頁為第1頁
  
  使用index={pageIndex}&limit={resultPerPage}, 每一頁可以返回上一頁或者下一頁的link
  
  可以看如下例子：
      GET /orders?page=1&limit=15 第一頁的15條數(shù)據(jù)
      GET /orders?offset=0&limit=15 第一頁的15條數(shù)據(jù)
      GET /orders?page=5&limit=10 第五頁的10條數(shù)據(jù) 第51-60條
      GET /orders?offset=50&limit=10 第51到60條數(shù)據(jù)
      GET /orders?index=xxxxxxx&limit=10  同樣也可以表示第51-60條數(shù)據(jù)，
    只不過對(duì)客戶端來說可能不知道第幾頁，response中應(yīng)該包含有上一頁和下一頁的index
  

• 排序
  API的排序功能是API非常重要的一個(gè)功能，可以使用sort，sort-by 即使沒有指出要排序，那么而應(yīng)該給一個(gè)默認(rèn)的排序。

  例如：
      GET /orders?sort=asc(date)  /orders?sort=desc(date) 
      GET /orders?sort=+date      /orders?sort=-date
      GET /orders?sort=date.asc      /orders?sort=date.desc
      GET /orders?sort=date&order-by=asc    /orders?sort=-date&order-by=desc 
  
   多字段排序示例：
      GET /orders?sort=desc(date),asc(amount)
      GET /orders?sort=-date,+amount
  

3.7使用HTTP狀態(tài)碼處理錯(cuò)誤

Http狀態(tài)碼有很多，這里列舉一些常見的。

總結(jié)

本篇介紹了一些REST API的一些食用方式，我們工作中可以根據(jù)一些各自的條件，作為參考。歡迎留言講講自己的一些實(shí)踐經(jīng)驗(yàn)！