距離上一篇關(guān)于Web API的文章(如何實(shí)現(xiàn)RESTful Web API的身份驗(yàn)證)有好些時(shí)間了，在那篇文章中提到的方法是非常簡單而有效的，我在實(shí)際的項(xiàng)目中就這么用了，代碼經(jīng)過一段時(shí)間的磨合，已經(jīng)很穩(wěn)定了，所以我打算寫篇總結(jié)，并在最近這段時(shí)間里提供一個(gè)ASP.net Web API的綜合例子。

對(duì)四個(gè)HTTP方法的理解

眾所周知，HTTP有四個(gè)方法，GET、POST、PUT和DELETE，分別對(duì)應(yīng)數(shù)據(jù)庫的SELECT、INSERT、UPDATE和DELETE，一般的教程說到這里也就Over了，其實(shí)光是知道這個(gè)還不夠，還不足以把各種業(yè)務(wù)操作轉(zhuǎn)變?yōu)檫@四個(gè)方法。下面我給出一些設(shè)計(jì)思路，這是我自行實(shí)踐的總結(jié)，如有謬誤，請(qǐng)不吝指正：

GET

沒錯(cuò)，就是SELECT，如果這個(gè)業(yè)務(wù)操作不會(huì)改變服務(wù)器的數(shù)據(jù)，那么就可以將它抽象成GET方法，但也不絕對(duì)，比如很多網(wǎng)站提供了文件下載，按理說下載應(yīng)該是不會(huì)改變服務(wù)器數(shù)據(jù)的，所以用GET，但很多時(shí)候服務(wù)器還提供了下載計(jì)數(shù)，你說這算不算改變了服務(wù)器的數(shù)據(jù)？——這種情況一般不算，所以依然用GET。下面是GET方法的舉例：

• 獲取所有員工列表
• 按條件分頁查詢某些員工信息
• 獲取一個(gè)員工的信息
• 下載一個(gè)文件
• 獲取當(dāng)前輸入的商品的價(jià)格

這么看來GET可是使用相當(dāng)多的方法。

PUT

UPDATE一條記錄就抽象成PUT方法，那這個(gè)動(dòng)作是不是也會(huì)用得很多呢？這個(gè)比你想像中的少得多，為什么？因?yàn)榇罅康男薷挠涗浀膭?dòng)作都不只是一個(gè)簡單的UPDATE動(dòng)作，比如用戶要撤銷一個(gè)訂單，這個(gè)操作表面上看起來是修改一條訂單記錄的狀態(tài)為“撤銷”，但實(shí)際上比這個(gè)要復(fù)雜得多，我們的訂貨是有流程的，用戶撤銷一個(gè)訂單其實(shí)只是向我們的服務(wù)器提出了一個(gè)撤銷訂單的請(qǐng)求，讓這個(gè)訂單轉(zhuǎn)入了撤銷流程，而不是簡單地修改訂單記錄的狀態(tài)，這里面有一連串的動(dòng)作，比如：等待管理員確認(rèn)，更新應(yīng)收款信息，將已出庫的貨物重新入庫，寫操作日志，發(fā)送系統(tǒng)通知等等，所以這個(gè)動(dòng)作應(yīng)該是POST，而不是PUT，大多數(shù)涉及業(yè)務(wù)流程的東西都是POST，這個(gè)我后面會(huì)再提到，而PUT則用于簡單的，不涉及業(yè)務(wù)流程的數(shù)據(jù)庫單條記錄UPDATE，例如：

• 用戶修改自己的個(gè)人信息(假設(shè)這個(gè)修改動(dòng)作不需要審批)
• 用戶編輯了一張暫存(未轉(zhuǎn)入執(zhí)行流程)的訂單

POST

表面上看起來對(duì)應(yīng)到數(shù)據(jù)庫的一次INSERT，但實(shí)際上對(duì)比PUT，POST的使用是廣泛很多的，可以說大多數(shù)業(yè)務(wù)操作都會(huì)被抽象成POST方法，例如：

• 新增一個(gè)用戶
• 提交一個(gè)訂單
• 撤銷一個(gè)訂單
• 付款
• 給員工發(fā)放工資
• 提交一個(gè)基礎(chǔ)資料的修改申請(qǐng)(需要審批)
• 激活一個(gè)產(chǎn)品
• 駁回一個(gè)員工的申請(qǐng)

想想看上述的這些動(dòng)作往往涉及到數(shù)據(jù)庫的若干張表的一系列的變化，這個(gè)時(shí)候就不能簡單地使用PUT，而是應(yīng)該使用POST，代表“提交了一個(gè)XX的請(qǐng)求”，理解這點(diǎn)很關(guān)鍵。

DELETE

對(duì)應(yīng)SQL語句的DELETE，表示刪除一個(gè)對(duì)象，是不是應(yīng)該使用也很多呢？其實(shí)跟PUT一樣，使用得比你想像的少，因?yàn)榇蠖鄶?shù)時(shí)候，我們的數(shù)據(jù)庫所執(zhí)行的“刪除”都不是簡單的DELETE，甚至大多數(shù)對(duì)象，我們都不會(huì)提供直接的刪除，例如用戶，為了保證數(shù)據(jù)的完整性，我們?cè)跀?shù)據(jù)庫中使用了許多的外鍵約束，要直接DELETE一條用戶記錄是不會(huì)成功的，我們只能“停用”一個(gè)用戶，表示此用戶不再生效。當(dāng)然了，話不是那么絕對(duì)，如果這是個(gè)剛剛增加的用戶并且沒有在其它表中引用到它，那么確實(shí)可以直接把它DELETE掉，這種情況出現(xiàn)在管理員剛剛添加了一個(gè)用戶，但發(fā)現(xiàn)用戶名輸錯(cuò)了，而用戶名卻是無法修改的，管理員只能嘗試刪除這個(gè)用戶然后重新添加，或者“停用”掉這個(gè)錯(cuò)誤的用戶，只是這么一來會(huì)產(chǎn)生一條完全沒意義的用戶記錄。DELETE用于你認(rèn)為需要提供DELETE方法的場(chǎng)合(很多時(shí)候其實(shí)不需要，這取決于你的設(shè)計(jì))，例如：

• 刪除一個(gè)用戶(很可能執(zhí)行失敗)
• 刪除一條暫存的訂單(此訂單尚未轉(zhuǎn)入處理流程)
• 刪除一條系統(tǒng)消息

更具體的動(dòng)作描述

為了表達(dá)得更具體些，我就把上面舉的這些例子轉(zhuǎn)變?yōu)榫唧w化的URI及動(dòng)作描述：

操作	URI	HTTP方法	說明
?獲取所有員工列表	?/api/emp/employees	?GET	?
?按條件分頁查詢某些員工信息	?/api/emp/employees?sex=m&page=1&numberperpage=20	?GET	?在URI中帶上參數(shù)
?獲取一個(gè)員工的信息	?/api/emp/employees/58	?GET	?58是員工的ID，當(dāng)然你也可以設(shè)計(jì)成用戶名
?下載一個(gè)文件	?/api/fileservice/files/2832	?GET	?2832是文件的ID，當(dāng)然你可以設(shè)計(jì)成文件名或者GUID
?獲取當(dāng)前輸入的商品的價(jià)格	?/api/sale/goods/32680	?GET	?32680是商品的ID
?用戶修改自己的個(gè)人信息(假設(shè)這個(gè)修改動(dòng)作不需要審批)	?/api/admin/users/8642	?PUT	?8642是用戶的ID，另外要帶上修改所需要的各種信息
?用戶編輯了一張暫存(未轉(zhuǎn)入執(zhí)行流程)的訂單	?/api/sale/orders/234892	?PUT	?234892是訂單的ID，另外要帶上修改訂單所需的各種信息
?新增一個(gè)用戶	?/api/admin/users	?POST	?帶上新增用戶所需要的信息
?提交一個(gè)訂單	?/api/sale/orders	?POST	?帶上訂單完整信息
?付款	?/api/sale/pay	?POST	?付款完整信息，將包含要支付的訂單的ID等信息
?給員工發(fā)放工資	?/api/emp/paysalary	?POST	?帶上發(fā)放工資的完整信息，將包括員工ID，發(fā)放工資的月份和金額等
?提交一個(gè)基礎(chǔ)資料的修改申請(qǐng)(需要審批)	?/api/basic/modifymanufacture	?POST	?帶上要修改的對(duì)象的完整信息，包括ID等
?激活一個(gè)產(chǎn)品	?/api/sale/activateproduct	?POST	?帶上要激活的產(chǎn)品的相關(guān)信息，包括ID等
?駁回一個(gè)員工的申請(qǐng)	?/api/admin/approve	?POST	?帶上申請(qǐng)ID、駁回原因等
?刪除一個(gè)用戶(很可能執(zhí)行失敗)	?/api/admin/users/567	?DELETE	?567為要?jiǎng)h除的用戶的ID
?刪除一條暫存的訂單(此訂單尚未轉(zhuǎn)入處理流程)	?/api/sale/orders/234892	?DELETE	?234892為訂單ID
?刪除一條系統(tǒng)消息	?/api/sys/messages/1008689021	?DELETE	?1008689021為系統(tǒng)消息的ID

URI中的“api”是固定的，用于區(qū)別于普通的網(wǎng)頁的URI，接下去的“emp”、“fileservice”、“sale”、“admin”、“basic”和“sys”等可看作是分類，例如“給員工發(fā)放工資”和“員工信息”這兩個(gè)“資源”都是放在“emp”這個(gè)分類中的，剩余的部分是對(duì)象名稱，或稱資源名稱，其實(shí)準(zhǔn)確地說，完整的URI地址才是真正的資源名稱，為什么叫資源？google一下RESTful Web API，看看RESTful的“R”就理解了，簡單地說，我們把各種操作都最終抽象為資源，一切業(yè)務(wù)操作(不管多復(fù)雜)都轉(zhuǎn)變?yōu)閷?duì)某個(gè)資源的增刪查改，也就是上面提到的四個(gè)HTTP的方法。

GET、PUT和DELETE方法都比較顯而易見，好理解，大多數(shù)時(shí)候，這幾個(gè)方法的資源都確確實(shí)實(shí)對(duì)應(yīng)著數(shù)據(jù)庫的某張表或某條記錄，例如“/api/admin/users”可能對(duì)應(yīng)著數(shù)據(jù)庫中的ADMIN_USER表，而“/api/admin/users/8642”則對(duì)應(yīng)著ADMIN_USER表中的ID為8642的這條用戶記錄。

POST方法則不是那么直截了當(dāng)，例如“/api/emp/paysalary”，也許數(shù)據(jù)庫中根本就沒有一個(gè)直接與之一一對(duì)應(yīng)的表，paysalary是一個(gè)抽象的業(yè)務(wù)操作對(duì)象，往這個(gè)對(duì)象執(zhí)行一下POST就相當(dāng)于給某個(gè)員工發(fā)放了一次工資，其實(shí)際的動(dòng)作可能涉及到多張表的聯(lián)動(dòng)，如員工表的工資發(fā)放標(biāo)志、工資發(fā)放記錄表插入一條記錄，公司財(cái)務(wù)表插入一條記錄，操作日志表插入一條記錄，系統(tǒng)消息表插入一條記錄等……

總結(jié)

以上是生活随笔為你收集整理的对RESTful Web API的理解与设计思路的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。