資訊專欄INFORMATION COLUMN
摘要：此文已由作者鄭華斌授權(quán)網(wǎng)易云社區(qū)發(fā)布。結(jié)合最近的項(xiàng)目，總結(jié)下常見的違背設(shè)計(jì)的一些做法。其實(shí)有個(gè)原則叫統(tǒng)一接口，統(tǒng)一接口原則建議了各方法的使用場合，獲取資源，返回消息頭和消息表示，即和。參考文獻(xiàn)文章來源網(wǎng)易云社區(qū)
此文已由作者鄭華斌授權(quán)網(wǎng)易云社區(qū)發(fā)布。
REST這詞我們常常掛在嘴邊，比如“開發(fā)一個(gè)rest接口”，又比如Spring項(xiàng)目的代碼：
@RestControllerpublic class CommonController { @RequestMapping("/") public String index() { return "Welcome to Yanxuan DMS!";
}
CommonController使用了@RestController注解，顧名思義，告訴讀者這是一個(gè)Rest接口的實(shí)現(xiàn)。然而以@RestController注解的接口卻不一定符合Rest原則。結(jié)合最近的項(xiàng)目，總結(jié)下常見的違背Rest設(shè)計(jì)的一些做法。
一、一律使用POST或者GET方法
典型的錯(cuò)誤做法：無論什么請(qǐng)求，一律用POST，或者‘增刪改’用POST，‘查’用GET。
其實(shí)REST有個(gè)原則叫統(tǒng)一接口（uniform interface），統(tǒng)一接口原則建議了各http方法的使用場合，
GET：獲取資源，返回消息頭和消息表示，即header和body。
HEAD：獲取資源元數(shù)據(jù)，返回消息頭
DELETE：刪除資源
POST：REST設(shè)計(jì)中，POST通常用來為一個(gè)已有資源創(chuàng)建一個(gè)從屬資源（subordinate resource），如AWS S3的POST Object(或者稱web post)接口。
PUT：創(chuàng)建或修改一個(gè)資源
PUT和POST的區(qū)別比較微妙，這里拿AWS S3（或者參考網(wǎng)易對(duì)象存儲(chǔ)NOS）的接口設(shè)計(jì)來舉例。其中AWS S3的詳細(xì)API文檔參見：http://docs.aws.amazon.com/Am...。 S3有兩種資源，桶（bucket）和對(duì)象（object），對(duì)象從屬于某個(gè)桶。
創(chuàng)建一個(gè)桶的接口為：
PUT /BucketName HTTP/1.1
Host: s3.amazonaws.com
創(chuàng)建/修改一個(gè)對(duì)象的PUT Object接口為：
PUT /BucketName/ObjectName HTTP/1.1
Host: s3.amazonaws.com[對(duì)象數(shù)據(jù)]
AWS S3同時(shí)提供了POST Object接口，同樣可以創(chuàng)建/修改一個(gè)對(duì)象，如下
POST /BucketName HTTP/1.1Host: s3.amazonaws.comContent-Type: multipart/form-data; boundary=9431149156168[包含對(duì)象數(shù)據(jù)的body]
獲取對(duì)象的GET Object接口為：
GET /BucketName/ObjectName HTTP/1.1
Host: s3.amazonaws.com
同樣的創(chuàng)建/修改一個(gè)對(duì)象，一個(gè)用PUT方法，另一個(gè)用POST方法，為什么？關(guān)鍵在于URL，PUT請(qǐng)求的目標(biāo)URL（這里為/BucketName/ObjectName），就是將來用于獲取該對(duì)象的URL，即PUT Object和GET Object的URL是一致的。但是POST Object的URL與GET ObjectURL不一樣，POST 請(qǐng)求只知道父資源的URL（即/BucketName），表示在該父資源下創(chuàng)建新資源，至于新資源的確切URL，是由服務(wù)器決定的，一般來說是POST請(qǐng)求的響應(yīng)應(yīng)該包含一個(gè)Location消息頭，其包含新建從屬資源的URL。
安全性safe和冪等性idempotent
REST設(shè)計(jì)還應(yīng)該遵循安全性和冪等性約束，如下：
GET和HEAD應(yīng)當(dāng)是安全的：GET和HEAD請(qǐng)求不應(yīng)該導(dǎo)致服務(wù)器狀態(tài)發(fā)生改變
GET、HEAD、PUT和DELETE應(yīng)當(dāng)是冪等的：向一個(gè)URL發(fā)送多次PUT和DELETE請(qǐng)求，跟只做過一次請(qǐng)求一樣。比如PUT不能是append語義，否則不冪等。GET和HEAD也是冪等。
統(tǒng)一接口原則的好處：
給一個(gè)資源URI，不用看文檔就知道可以有GET、DELETE等操作及其意義，世界通用。
安全性和冪等性增加了http的可靠性：如果請(qǐng)求沒成功（但也許已成功了），只需重新發(fā)一次即可，不用擔(dān)心副作用。
二、HTTP Code一律返回200
典型的錯(cuò)誤做法：無論成功失敗，HTTP Code一律返回200，具體錯(cuò)誤信息交由json body里的內(nèi)容來判斷，舉例如下，
某甲服務(wù)xxx接口的響應(yīng)如下
HTTP/1.1 200 OK{ "status":1, //1: 成功 0: 參數(shù)異常 -1: 失敗
"message":"" //返回的消息 成功時(shí)返回的數(shù)據(jù)
}
某乙服務(wù)xxx接口的響應(yīng)如下
HTTP/1.1 200 OK{ "code":200, //1: 成功 0: 參數(shù)異常 -1: 失敗
"msg":"" //code非200時(shí)返回的錯(cuò)誤信息
"data":{成功時(shí)返回的數(shù)據(jù)內(nèi)容}
}
其實(shí)RESTful的設(shè)計(jì)的一個(gè)標(biāo)志特征是充分并正確利用HTTP響應(yīng)碼，典型的如：
200 -- OK，成功
301 -- Moved Permanently，重定向
400 -- Bad Request，錯(cuò)誤的請(qǐng)求，比如缺少參數(shù)或者參數(shù)值不對(duì)
403 -- Forbidden，無權(quán)限訪問
404 -- Not Found，url不存在
500 -- Internal Server Error，系統(tǒng)錯(cuò)誤，如數(shù)據(jù)庫訪問失敗或者bug導(dǎo)致的錯(cuò)誤
設(shè)計(jì)REST接口應(yīng)該遵循上面的響應(yīng)碼，語義明確并通用。如果像上面例子那樣，任何情況都一律返回200，而具體成功與否需要到http響應(yīng)消息體里去解析，而且不同的服務(wù)或開發(fā)者自定義消息體的格式，那么服務(wù)調(diào)用方就需要針對(duì)不同的服務(wù)寫不同的判斷邏輯，增加系統(tǒng)交互復(fù)雜性。
有些通用的客戶端，會(huì)針對(duì)301自動(dòng)處理重定向，針對(duì)500以上的響應(yīng)自動(dòng)重試，而一律返回200的設(shè)計(jì)是沒法使用這些特性的，只能調(diào)用方一一自個(gè)處理。
三、 面向操作而不是面向資源的url設(shè)計(jì)
典型的錯(cuò)誤做法：設(shè)計(jì)的URI是面向操作而不是面向資源的，舉例如下，
某系統(tǒng) 設(shè)計(jì)的渠道相關(guān)的URI是這樣的：
新增渠道
POST /xhr/thirdparty/admin/channel/add.json?{渠道信息參數(shù)}
編輯渠道
POST /xhr/thirdparty/admin/channel/update.json?{渠道信息參數(shù)}
刪除渠道
POST /xhr/thirdparty/admin/channel/delete.json?channelId=id
這里的接口設(shè)計(jì)有三個(gè)特點(diǎn)：
http方法都是POST；
URI里攜帶操作信息，如URI里出現(xiàn)“add”，“update”，“delete”等字眼；
同一個(gè)資源由于操作不一樣而URI不一樣。
其實(shí)REST式的設(shè)計(jì)中，URI即是資源的名稱，也是資源的地址，因?yàn)椴煌牟僮鞫Y源地址不一樣是不合適的。資源的操作（方法信息）應(yīng)該由統(tǒng)一接口來表示，即http 方法PUT、POST、GET、DELETE等，而不應(yīng)該放到URI中。
對(duì)照統(tǒng)一接口和面向資源這兩個(gè)特征來設(shè)計(jì)，上面的接口RESTful化可以是這樣的：
新增渠道
POST /xhr/thirdparty/admin/channel
[渠道具體信息]
修改渠道
PUT /xhr/thirdparty/admin/channel?channelId=id 或者PUT /xhr/thirdparty/admin/channel/${id}
[渠道具體信息]
刪除渠道
DELETE /xhr/thirdparty/admin/channel?channelId=id或者DELETE /xhr/thirdparty/admin/channel/${id}
渠道的地址為/xhr/thirdparty/admin/channel?channelId=id或者/xhr/thirdparty/admin/channel/${id}，重在url唯一。
參考文獻(xiàn)
《RESTful Web Services》
文章來源： 網(wǎng)易云社區(qū)
文章版權(quán)歸作者所有，未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請(qǐng)注明本文地址：http://systransis.cn/yun/25333.html
摘要：前言關(guān)于設(shè)計(jì)模式，想必大家的第一感覺就是過于高深，有點(diǎn)虛吧。為什么要學(xué)習(xí)設(shè)計(jì)模式因?yàn)橐b逼啊咳咳，大家請(qǐng)忽略前面那句話。處處都是設(shè)計(jì)模式的體現(xiàn)，所以若想攻下，設(shè)計(jì)模式是必學(xué)的。下節(jié)預(yù)告單例模式 前言 關(guān)于設(shè)計(jì)模式，想必大家的第一感覺就是過于高深，有點(diǎn)虛吧。相對(duì)來說，我們還是更熟悉ssh或者ssm之類的開發(fā)框架，一個(gè)工具用久了就會(huì)熟能生巧，就像刷漆工，時(shí)間長了也知道如何刷的一手漂亮的好墻...
摘要：飛機(jī)就是一種交通工具，可飛行的能力是是飛機(jī)的屬性，通過繼承接口來獲取語言可沒有接口功能，但是它可以多重繼承。說是，因?yàn)閺恼Z法上看，的確是通過多重繼承實(shí)現(xiàn)的。所以從含義上理解，只是一個(gè)，不是一個(gè)。比如飛機(jī)照樣可以載客，就是不能飛了 REST API設(shè)計(jì)理念 showImg(https://segmentfault.com/img/remote/1460000019923606);sho...
摘要：飛機(jī)就是一種交通工具，可飛行的能力是是飛機(jī)的屬性，通過繼承接口來獲取語言可沒有接口功能，但是它可以多重繼承。說是，因?yàn)閺恼Z法上看，的確是通過多重繼承實(shí)現(xiàn)的。所以從含義上理解，只是一個(gè)，不是一個(gè)。比如飛機(jī)照樣可以載客，就是不能飛了 REST API設(shè)計(jì)理念 showImg(https://segmentfault.com/img/remote/1460000019923606);sho...
摘要：策略模式又稱政策模式，其定義一系列的算法，把它們一個(gè)個(gè)封裝起來，并且使它們可以互相替換。的表單具有表單驗(yàn)證功能，用來校驗(yàn)用戶輸入的表單內(nèi)容。實(shí)際需求中表單驗(yàn)證項(xiàng)一般會(huì)比較復(fù)雜，所以需要給每個(gè)表單項(xiàng)增加自定義校驗(yàn)方法。 showImg(https://segmentfault.com/img/remote/1460000020135990); 策略模式 （Strategy Pattern...
摘要：如何快速搭建一個(gè)微服務(wù)架構(gòu)上圖異步通信方式通常異步的生產(chǎn)者消費(fèi)者模式，通過等異步消息通訊協(xié)議規(guī)范。數(shù)據(jù)的去中心化，進(jìn)一步降低了微服務(wù)之間的耦合度，不同服務(wù)可以采用不同的數(shù)據(jù)庫技術(shù)等。 什么是微服務(wù)？ 微服務(wù)(Microservices Architecture)是一種架構(gòu)風(fēng)格，一個(gè)大型復(fù)雜軟件應(yīng)用由一個(gè)或多個(gè)微服務(wù)組成。系統(tǒng)中的各個(gè)微服務(wù)可被獨(dú)立部署，各個(gè)微服務(wù)之間是松耦合的。每個(gè)微服...
閱讀 1484·2019-08-30 15:55
閱讀 1189·2019-08-30 15:52
閱讀 1306·2019-08-29 13:53
閱讀 1479·2019-08-29 11:19
閱讀 2991·2019-08-26 13:29
閱讀 540·2019-08-26 11:33
閱讀 2609·2019-08-23 17:20
閱讀 1036·2019-08-23 14:14
