RESTful架構及實踐

rest：（representational state transfer）即表現層狀態轉換，定義了資源的通用訪問格式，是一種網路應用程式的設計風格和開發方式。

在概念中，需要理解以下幾個名稱：

資源（resource）

即伺服器上獲取到的東西任何資源，一條使用者記錄，乙個使用者的密碼，一張等等都是。

資源的表述（representation）

即資源格式，是 html、xml、json、純文字、等等，可以用各種各樣的格式來表述你獲取到的資源。

狀態轉移（state transfer）

即url定位資源，用 http 動詞（get,post,delete,detc）描述操作。操作是動詞，資源是名詞。

統一介面（uniform inte***ce）

即通過統一的介面對資源進行操作。

rest 通常基於使用http，uri，和xml以及html這些現有的廣泛流行的協議和標準，每一種 uri 代表一種資源。

rest 通常使用json資料格式。

rest 基本架構的四個方法：

下面會通過乙個場景介紹。

rest 定義了資源的通用訪問格式，接下來乙個消費者為例項，介紹 restful api 定義：

獲取所有 users

get /api/users

獲取指定 id 的 users

get /api/users/100

新建一條 users 記錄

post /api/users

更新一條 users 記錄

put /api/users/100

刪除一條 users 記錄

delete /api/users/100

獲取乙個 users 的所有消費賬單

get  /api/users/100/bill

獲取乙個 user 指定時間的消費賬單

get  /api/users/100/bill?from=201910&to=201911

以上其中 restful 風格 api 幾乎包含常見業務情況。

本案例使用 mock 資料來演示，如下：

,
"user2" : ,
"user3" : 
}

我們將實現以下 restful api ：

這一步我們會建立 restful api 中的/users，使用 get 來讀取使用者的資訊列表：

// index.js
const express = require('express');
const fs = require("fs");
// 定義 讀取使用者的資訊列表 的介面
})

這一步我們會建立 restful api 中的/users，使用 post 來新增使用者記錄：

// index.js
// 省略之前檔案 只展示需要實現的介面
// mock 一條要新增的資料
const user = 
}// 定義 新增使用者記錄 的介面
// 讀取已存在的資料
fs.readfile( __dirname + "/" + "users.json", 'utf8', (err, data) => );
})

這一步我們在 restful api 中的 uri 後面加上/users/:id，使用 get 來獲取指定使用者詳情：

// index.js
// 省略之前檔案 只展示需要實現的介面
// 定義 獲取指定使用者詳情 的介面
// 首先我們讀取已存在的使用者
fs.readfile( __dirname + "/" + "users.json", 'utf8', (err, data) => );
})

這一步我們會建立 restful api 中的/users，使用 delete 來刪除指定使用者：

// index.js
// 省略之前檔案 只展示需要實現的介面
// mock 一條要刪除的使用者id
const id = 2;
fs.readfile( __dirname + "/" + "users.json", 'utf8', (err, data) => );
})

1.1 "動詞 + 賓語"的操作指令結構

客戶端發出的資料操作指令都是"動詞 + 賓語"的結構。

如上面提到的，get /user這個命令，get是動詞，/user是賓語。根據 http 規範，動詞一律大寫。

動詞通常有以下五種 http 方法：

get：讀取（read）

post：新建（create）

put：更新（update）

patch：更新（update），通常是部分更新

delete：刪除（delete）

1.2 賓語必須是名詞

賓語就是 api 的 url，是 http 動詞作用的物件。它應該是名詞，不能是動詞。

比如，/users是正確的，因為 url 是名詞，而下面就都是錯誤的了：

/getusers /createusers

/deleteusers

1.3 建議複數 url

因為 url 是名詞，沒有單複數的限制，但是還是建議如果是乙個集合，就使用複數形式。如get /users來讀取所有使用者列表。

1.4 避免多級 url

避免在多層級資源時，使用多級 url。常見案例如獲取某位使用者的購買過的某一類商品:

get /users/100/product/120

這種 url 語意不明，也不利拓展，建議只有第一級，其他級別用查詢字串來表達：

get /users/100?product=120

http 五大類狀態碼有100多種，每一種狀態碼都有標準的（或者約定的）解釋，客戶端只需檢視狀態碼，就可以判斷出發生了什麼情況，所以伺服器應該返回盡可能精確的狀態碼。

這邊列舉幾個經常使用的狀態碼介紹：

400 bad request：伺服器不理解客戶端的請求，未做任何處理。

401 unauthorized：使用者未提供身份驗證憑據，或者沒有通過身份驗證。

403 forbidden：使用者通過了身份驗證，但是不具有訪問資源所需的許可權。

404 not found：所請求的資源不存在，或不可用。

405 method not allowed：使用者已經通過身份驗證，但是所用的 http 方法不在他的許可權之內。

415 unsupported media type：客戶端要求的返回格式不支援。比如，api 只能返回 json 格式，但是客戶端要求返回 xml 格式。

422 unprocessable entity：客戶端上傳的附件無法處理，導致請求失敗。

429 too many requests：客戶端的請求次數超過限額。

500 internal server error：客戶端請求有效，伺服器處理時發生了意外。

3.1 應該返回 json 物件

api 返回的資料格式應該是 json 乙個物件。

3.2 發生錯誤時，不要返回 200 狀態碼

在發生錯誤時，如果還返回 200 狀態碼，前端需要解析返回資料才知道錯誤資訊，這樣實際上取消了狀態碼，是不恰當的。

正確的做法應該是在錯誤時，返回對應錯誤狀態碼，並將錯誤資訊返回：

Restful最佳實踐

restful 是目前最流行的 api 設計規範，用於 web 資料介面的設計。它的大原則容易把握，但是細節不容易做對。本文總結 restful 的設計細節，介紹如何設計出易於理解和使用的 api。restful 的核心思想就是，客戶端發出的資料操作指令都是動詞賓語的結構。比如，get art...

RESTful 最佳實踐

restful是目前最流行的 api 規範，適用於 web 介面規範的設計。讓介面易讀，且含義清晰。本文將介紹如何設計易於理解和使用的 api，並且借助 docker api 的實踐說明。它的核心思想就是客戶端發出的資料操作指令都是動詞賓語的結構，比如 get articles這個命令，get...

理解RESTful架構

理解restful架構 restful的精闢理解看url就知道要什麼看http method就知道幹什麼看http status code就知道結果如何 rest不是 rest 這個單詞，而是幾個單詞縮寫。但即使那幾個單詞說出來，也無法理解在說什麼不是要貶低人，是我自己也理解困難 rest描...

RESTful架構及實踐

Restful最佳實踐

RESTful 最佳實踐

理解RESTful架構

相關推薦