好看的言情小说,豆豆小说阅读网,玄幻小说完本

新聞中心

這里有您想知道的互聯(lián)網(wǎng)營(yíng)銷(xiāo)解決方案

RESTfulAPI優(yōu)秀實(shí)踐，你會(huì)了嗎？

RESTful 風(fēng)格的HTTP 方法有POST,GET ,PUT ,DELETE,PATCH 等等。那么我們?cè)陂_(kāi)發(fā)時(shí)應(yīng)該如何寫(xiě)出優(yōu)雅的RESTful接口呢。本篇就為大家?guī)?lái)一期RESTful API 實(shí)踐。

1. 前言

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

REST API 也稱(chēng)RESTful API，其遵循REST架構(gòu)規(guī)范的應(yīng)用編程接口，支持與RESTful WEB服務(wù)進(jìn)行交互。簡(jiǎn)單來(lái)講就是：符合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)

開(kāi)發(fā)者一旦熟悉了你的其中一個(gè)API，那么他就可以遵循類(lèi)似的結(jié)構(gòu)去使用其他API.

客戶(hù)端服務(wù)器(Client-server)

只要不改變他們之間的接口，服務(wù)端和客戶(hù)端可以相互替換或獨(dú)立開(kāi)發(fā)。

無(wú)狀態(tài)(Stateless)

客戶(hù)端上下文狀態(tài)不應(yīng)該存儲(chǔ)在服務(wù)端，而應(yīng)該有客戶(hù)端去管理程序的狀態(tài)

可緩存(Cacheable)

優(yōu)秀的緩存可以部分或者完全消除客戶(hù)端和服務(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)證，客戶(hù)端不知道它實(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名稱(chēng)

API的名稱(chēng)應(yīng)該出現(xiàn)在URL中，API的標(biāo)題也應(yīng)該和名稱(chē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文檔

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

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

3.4資源路徑命名

資源名稱(chēng)使用名詞，而不要使用動(dòng)詞。

比如 POST : /cars 表示創(chuàng)建cars , GET: /cars 表示查詢(xún)cars 而不應(yīng)該寫(xiě)成/createCars ， /getCars 等等。

獲取集合資源與獲取特定資源,統(tǒng)一使用復(fù)數(shù)來(lái)表示資源。

#獲取資源集合時(shí)使用復(fù)數(shù)名詞 
例如 /schools


#獲取特定資源
例如 /schools/{school-id}  /schools/5


#獲取特定資源的子資源 
例如 /schools/{school-id}/grades  /schools/5/grades

3.5資源操作

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

HTTP method	資源操作類(lèi)型
GET	查詢(xún)集合，查詢(xún)單個(gè)資源
POST	Create 創(chuàng)建某個(gè)資源
PUT	update 更新資源
PATCH	局部更新資源
DELETE	刪除資源

創(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，

查詢(xún)集合資源及單個(gè)資源

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

更新及修改資源 PUT/PATCH

更新個(gè)修改資源包含多種情況：

一種是完全更新，使用新的資源完全替換舊的資源。

例如：PUT: /schools/{school-id}/address  更新某個(gè)客戶(hù)學(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方法，刪除的方法有直接刪除，或者使資源不可見(jiàn)。

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

其余不是資源的參數(shù)應(yīng)該出現(xiàn)在請(qǐng)求參數(shù)中。而且查詢(xún)參數(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

使用唯一查詢(xún)參數(shù)進(jìn)行過(guò)濾。

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

分頁(yè)查詢(xún)

API 使用offset={resultOffset}&limit={resultsPerPage} 進(jìn)行分頁(yè)查詢(xún)，
并且以第0條數(shù)據(jù)為起始。
 
另外也可以使用 page={pageNumber}&limit={resultPerPage} 此時(shí)起始頁(yè)為第1頁(yè)

使用index={pageIndex}&limit={resultPerPage}, 每一頁(yè)可以返回上一頁(yè)或者下一頁(yè)的link
 
可以看如下例子：
    GET /orders?page=1&limit=15 第一頁(yè)的15條數(shù)據(jù)
    GET /orders?offset=0&limit=15 第一頁(yè)的15條數(shù)據(jù)
    GET /orders?page=5&limit=10 第五頁(yè)的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ù)，
  只不過(guò)對(duì)客戶(hù)端來(lái)說(shuō)可能不知道第幾頁(yè)，response中應(yīng)該包含有上一頁(yè)和下一頁(yè)的index

排序

API的排序功能是API非常重要的一個(gè)功能，可以使用sort，sort-by 即使沒(méi)有指出要排序，那么而應(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 status	描述
2XX	SUCCESS
200	OK
201	Create
202	Accepted
204	No Content
4XX	Client Error
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Too Many Request
5xx	Server Errors
500	Internal Server Error

總結(jié)

本篇介紹了一些REST API的一些食用方式，我們工作中可以根據(jù)一些各自的條件，作為參考。

文章名稱(chēng)：RESTfulAPI優(yōu)秀實(shí)踐，你會(huì)了嗎？
鏈接URL：http://fisionsoft.com.cn/article/cosegpc.html