前后端分離和restful開發規范


一.web開發的兩種模式

  1.前后端不分離

   在前后端不分離的應用模式中,前端頁面看到的效果都是由后端控制,由后端渲染頁面或重定向,也就是后端需要控制前端的展示,前端與后端的耦合度很高。

    這種應用模式比較適合純網頁應用,但是當后端對接App時,App可能並不需要后端返回一個HTML網頁,而僅僅是數據本身,所以后端原本返回網頁的接口不再
適用於前端App應用,為了對接App后端還需再開發一套接口。 請求的數據交互如下圖:
  

  2.前后端分離

  在前后端分離的應用模式中,后端僅返回前端所需的數據,不再渲染HTML頁面,不再控制前端的效果。

  至於前端用戶看到什么效果,從后端請求的數據如何加載到前端中,都由前端自己決定,網頁有網頁的處理
方式,App有App的處理方式,但無論哪種前端,所需的數據基本相同,后端僅需開發一套邏輯對外提供數據即可。   在前后端分離的應用模式中 ,前端與后端的耦合度相對較低。   在前后端分離的應用模式中,我們通常將后端開發的每個視圖都稱為一個接口,或者API,前端通過訪問接口
來對數據進行增刪改查。
對應的數據交互如下圖 :
  

 

二.API接口

  為了在團隊內部形成共識、防止個人習慣差異引起的混亂,我們需要找到一種大家都覺得很好的接口實現規范,
而且這種規范能夠讓后端寫的接口,用途一目了然,減少雙方之間的合作成本。 目前市面上大部分公司開發人員使用的接口服務架構主要有:restful、rpc。

 

三. RESTful API規范

  1.概念

  REST全稱是Representational State Transfer,中文意思是表述(編者注:通常譯為表征)性狀態轉移。
它首次出現在2000年Roy Fielding的博士論文中。   RESTful是一種定義Web API接口的設計風格,尤其適用於前后端分離的應用模式中。   這種風格的理念認為后端開發任務就是提供數據的,對外提供的是數據資源的訪問接口,所以在定義接口時,客戶端訪問的URL路徑就表示這種要操作的數據資源。   而對於數據資源分別使用POST、DELETE、GET、UPDATE等請求動作來表達對數據的增刪查改。
  
請求方法 請求地址 后端操作
GET /students 獲取所有學生
POST /students 增加學生
GET /students/1 獲取編號為1的學生
PUT /students/1 修改編號為1的學生
DELETE /students/1 刪除編號為1的學生
 

   

  2.域名

應該盡量將API部署在專用域名之下。

https://api.example.com


如果確定API很簡單,不會有進一步擴展,可以考慮放在主域名下。
https://example.org/api/

  3. 版本(Versioning)

應該將API的版本號放入URL。

http://www.example.com/app/1.0/foo
​
http://www.example.com/app/1.1/foo
​
http://www.example.com/app/2.0/foo

另一種做法是,將版本號放在HTTP頭信息中,
但不如放入URL方便和直觀。Github就采用了這種做法。

 因為不同的版本,可以理解成同一種資源的不同表現形式,所以應該采用同一個URL。版本號可以在HTTP請求頭信息的Accept字段中進行區分

 
 
Accept: vnd.example-com.foo+json; version=1.0

Accept: vnd.example-com.foo+json; version=1.1

 

  4.. 路徑(Endpoint)

路徑又稱"終點"(endpoint),表示API的具體網址,每個網址代表一種資源(resource)

(1) 資源作為網址,只能有名詞,不能有動詞,而且所用的名詞往往與數據庫的表名對應。

舉例來說,以下是不好的例子:

/getProducts
/listOrders
/retreiveClientByOrder?orderId=1
對於一個簡潔結構,你應該始終用名詞。 此外,利用的HTTP方法可以分離網址中的資源名稱的操作。

GET /products :將返回所有產品清單
POST /products :將產品新建到集合
GET /products/4 :將獲取產品 4
PATCH(或)PUT /products/4 :將更新產品 4

(2) API中的名詞應該使用復數。無論子資源或者所有資源。 舉例來說,獲取產品的API可以這樣定義 獲取單個產品:http://127.0.0.1:8080/AppName/rest/products/1 獲取所有產品: http://127.0.0.1:8080/AppName/rest/products

 

  5. HTTP動詞

對於資源的具體操作類型,由HTTP動詞表示。

常用的HTTP動詞有下面四個(括號里是對應的SQL命令)。

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

還有三個不常用的HTTP動詞。

- PATCH(UPDATE):在服務器更新(更新)資源(客戶端提供改變的屬性)。
- HEAD:獲取資源的元數據。
- OPTIONS:獲取信息,關於資源的哪些屬性是客戶端可以改變的。

下面是一些例子。

GET /zoos:列出所有動物園
POST /zoos:新建一個動物園(上傳文件)
GET /zoos/ID:獲取某個指定動物園的信息
PUT /zoos/ID:更新某個指定動物園的信息(提供該動物園的全部信息)
PATCH /zoos/ID:更新某個指定動物園的信息(提供該動物園的部分信息)
DELETE /zoos/ID:刪除某個動物園
GET /zoos/ID/animals:列出某個指定動物園的所有動物
DELETE /zoos/ID/animals/ID:刪除某個指定動物園的指定動物

  6.. 過濾信息(Filtering)

如果記錄數量很多,服務器不可能都將它們返回給用戶。API應該提供參數,過濾返回結果。

下面是一些常見的參數。query_string 查詢字符串,地址欄后面問號后面的數據,格式: name=xx&sss=xxx

?limit=10:指定返回記錄的數量
?offset=10:指定返回記錄的開始位置。
?page=2&per_page=100:指定第幾頁,以及每頁的記錄數。
?sortby=name&order=asc:指定返回結果按照哪個屬性排序,以及排序順序。
?animal_type_id=1:指定篩選條件
參數的設計允許存在冗余,即允許API路徑和URL參數偶爾有重復。比如,GET /zoos/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的

  7.. 狀態碼(Status Codes)

  服務器向用戶返回的狀態碼和提示信息,常見的有以下一些(方括號中是該狀態碼對應的HTTP動詞)。

200 OK - [GET]:服務器成功返回用戶請求的數據

201 CREATED - [POST/PUT/PATCH]:用戶新建或修改數據成功。

202 Accepted - [*]:表示一個請求已經進入后台排隊(異步任務)

204 NO CONTENT - [DELETE]:用戶刪除數據成功。

400 INVALID REQUEST - [POST/PUT/PATCH]:用戶發出的請求有錯誤,服務器沒有進行新建或修改數據的操作

401 Unauthorized - [*]:表示用戶沒有權限(令牌、用戶名、密碼錯誤)。

403 Forbidden - [*] 表示用戶得到授權(與401錯誤相對),但是訪問是被禁止的。

404 NOT FOUND - [*]:用戶發出的請求針對的是不存在的記錄,服務器沒有進行操作,該操作是冪等的。

406 Not Acceptable - [GET]:用戶請求的格式不可得(比如用戶請求JSON格式,但是只有XML格式)。

410 Gone -[GET]:用戶請求的資源被永久刪除,且不會再得到的。

422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時,發生一個驗證錯誤。

500 INTERNAL SERVER ERROR - [*]:服務器發生錯誤,用戶將無法判斷發出的請求是否成功。

  8.. 錯誤處理(Error handling)

  如果狀態碼是4xx,服務器就應該向用戶返回出錯信息。一般來說,返回的信息中將error作為鍵名,出錯信息作為鍵值即可。

{
    error: "Invalid API key"
}

  9. 返回結果

針對不同操作,服務器向用戶返回的結果應該符合以下規范。

GET /collection:返回資源對象的列表(數組)

GET /collection/ID:返回單個資源對象(json)

POST /collection:返回新生成的資源對象(json)

PUT /collection/ID:返回完整的資源對象(json)

DELETE /collection/ID:返回一個空文檔(空字符串)

  10. 超媒體(Hypermedia API)

RESTful API最好做到Hypermedia(即返回結果中提供鏈接,連向其他API方法),使得用戶不查文檔,也知道下一步應該做什么。

比如,Github的API就是這種設計,訪問api.github.com會得到一個所有可用API的網址列表。

{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}
從上面可以看到,如果想獲取當前用戶的信息,應該去訪問api.github.com/user,然后就得到了下面結果。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}
上面代碼表示,服務器給出了提示信息,以及文檔的網址。

  11. 其他

服務器返回的數據格式,應該盡量使用JSON,避免使用XML。

注意:上面的規范是一些約定的,並不是強制,可以不遵守,也可以只遵守幾條

四.序列化

  

  api接口開發,最核心最常見的一個過程就是序列化,所謂序列化就是把**數據轉換格式**,序列化可以分兩個階段:

  **序列化**: 把我們識別的數據轉換成指定的格式提供給別人。 
  例如:我們在django中獲取到的數據默認是模型對象,但是模型對象數據無法直接提供給前端或別的平台使用,所以我們需要把數據進行序列化,變成字符串或者json數據,提供給別人。
   **反序列化**:把別人提供的數據轉換/還原成我們需要的格式。

  例如:前端js提供過來的json數據,對於python而言就是字符串,我們需要進行反序列化換成模型類對象,這樣我們才能把數據保存到數據庫中。

 

五.django restful_framework

  核心思想: 縮減編寫api接口的代碼

  Django REST framework是一個建立在Django基礎之上的Web 應用開發框架,可以快速的開發REST API接口應用。
在REST framework中,提供了序列化器Serialzier的定義,可以幫助我們簡化序列化與反序列化的過程,不僅如此,還
提供豐富的類視圖、擴展類、視圖集來簡化視圖的編寫工作。REST framework還提供了認證、權限、限流、過濾、分頁、
接口文檔等功能支持。REST framework提供了一個API 的Web可視化界面來方便查看測試接口。

特點

  • 提供了定義序列化器Serializer的方法,可以快速根據 Django ORM 或者其它庫自動序列化/反序列化;

  • 提供了豐富的類視圖、Mixin擴展類,簡化視圖的編寫;

  • 豐富的定制層級:函數視圖、類視圖、視圖集合到自動生成 API,滿足各種需要;

  • 多種身份認證和權限認證方式的支持;[jwt]

  • 內置了限流系統;

  • 直觀的 API web 界面;

  • 可擴展性,插件豐富

 

六.drf安裝與環境配置

 DRF需要以下依賴:

  • Python (2.7, 3.2, 3.3, 3.4, 3.5, 3.6)

  • Django (1.10, 1.11, 2.0)

DRF是以Django擴展應用的方式提供的,所以我們可以直接利用已有的Django環境而無需從新創建。(若沒有Django環境,需要先創建環境安裝Django)

  1.安裝drf

pip install djangorestframework

 

 

 


注意!

本站转载的文章为个人学习借鉴使用,本站对版权不负任何法律责任。如果侵犯了您的隐私权益,请联系我们删除。



 
粤ICP备14056181号  © 2014-2020 ITdaan.com