對RESTful Web API的理解與設計思路

標籤：blog   http   os   ar   使用   sp   檔案   資料   div   

距離上一篇關於Web API的文章（如何?RESTful Web API的身分識別驗證）有好些時間了，在那篇文章中提到的方法是非常簡單而有效，我在實際的項目中就這麼用了，代碼經過一段時間的磨合，已經很穩定了，所以我打算寫篇總結，並在最近這段時間裡提供一個ASP.net Web API的綜合例子。

對四個HTTP方法的理解

眾所周知，HTTP有四個方法，GET、POST、PUT和DELETE，分別對應資料庫的SELECT、INSERT、UPDATE和DELETE，一般的教程說到這裡也就Over了，其實光是知道這個還不夠，還不足以把各種業務操作轉變為這四個方法。下面我給出一些設計思路，這是我自行實踐的總結，如有謬誤，請不吝指正：

GET

沒錯，就是SELECT，如果這個業務操作不會改變伺服器的資料，那麼就可以將它抽象成GET方法，但也不絕對，比如很多網站提供了檔案下載，按理說下載應該是不會改變伺服器資料的，所以用GET，但很多時候伺服器還提供了下載計數，你說這算不算改變了伺服器的資料？——這種情況一般不算，所以依然用GET。下面是GET方法的舉例：

• 擷取所有員工列表
• 按條件分頁查詢某些員工資訊
• 擷取一個員工的資訊
• 下載一個檔案
• 擷取當前輸入的商品的價格

這麼看來GET可是使用相當多的方法。

PUT

UPDATE一條記錄就抽象成PUT方法，那這個動作是不是也會用得很多呢？這個比你想像中的少得多，為什嗎？因為大量的修改記錄的動作都不只是一個簡單的UPDATE動作，比如使用者要撤銷一個訂單，這個動作表面上看起來是修改一條訂單記錄的狀態為“撤銷”，但實際上比這個要複雜得多，我們的訂貨是有流程的，使用者撤銷一個訂單其實只是向我們的伺服器提出了一個撤銷訂單的請求，讓這個訂單轉入了撤銷流程，而不是簡單地修改訂單記錄的狀態，這裡面有一連串的動作，比如：等待管理員確認，更新應收款資訊，將已出庫的貨物重新入庫，寫動作記錄，發送系統通知等等，所以這個動作應該是POST，而不是PUT，大多數涉及商務程序的東西都是POST，這個我後面會再提到，而PUT則用於簡單的，不涉及商務程序的資料庫單條記錄UPDATE，例如：

• 使用者修改自己的個人資訊（假設這個修改動作不需要審批）
• 使用者編輯了一張暫存（未轉入執行流程）的訂單

POST

表面上看起來對應到資料庫的一次INSERT，但實際上對比PUT，POST的使用是廣泛很多的，可以說大多數業務操作都會被抽象成POST方法，例如：

• 新增一個使用者
• 提交一個訂單
• 撤銷一個訂單
• 付款
• 給員工發放工資
• 提交一個基礎資料的修改申請（需要審批）
• 啟用一個產品
• 駁回一個員工的申請

想想看上述的這些動作往往涉及到資料庫的若干張表的一系列的變化，這個時候就不能簡單地使用PUT，而是應該使用POST，代表“提交了一個XX的請求”，理解這點很關鍵。

DELETE

對應SQL語句的DELETE，表示刪除一個對象，是不是應該使用也很多呢？其實跟PUT一樣，使用得比你想像的少，因為大多數時候，我們的資料庫所執行的“刪除”都不是簡單的DELETE，甚至大多數對象，我們都不會提供直接的刪除，例如使用者，為了保證資料的完整性，我們在資料庫中使用了許多的外鍵約束，要直接DELETE一條使用者記錄是不會成功的，我們只能“停用”一個使用者，表示此使用者不再生效。當然了，話不是那麼絕對，如果這是個剛剛增加的使用者並且沒有在其它表中引用到它，那麼確實可以直接把它DELETE掉，這種情況出現在管理員剛剛添加了一個使用者，但發現使用者名稱輸錯了，而使用者名稱卻是無法修改的，管理員只能嘗試刪除這個使用者然後重新添加，或者“停用”掉這個錯誤的使用者，只是這麼一來會產生一條完全沒意義的使用者記錄。DELETE用於你認為需要提供DELETE方法的場合（很多時候其實不需要，這取決於你的設計），例如：

• 刪除一個使用者（很可能執行失敗）
• 刪除一條暫存的訂單（此訂單尚未轉入處理流程）
• 刪除一條系統訊息

更具體的動作描述

為了表達得更具體些，我就把上面舉的這些例子轉變為具體化的URI及動作描述：

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

URI中的“api”是固定的，用於區別於普通的網頁的URI，接下去的“emp”、“fileservice”、“sale”、“admin”、“basic”和“sys”等可看作是分類，例如“給員工發放工資”和“員工資訊”這兩個“資源”都是放在“emp”這個分類中的，剩餘的部分是對象名稱，或稱資源名稱，其實準確地說，完整的URI地址才是真正的資源名稱，為什麼叫資源？google一下RESTful Web API，看看RESTful的“R”就理解了，簡單地說，我們把各種操作都最終抽象為資源，一切業務操作（不管多複雜）都轉變為對某個資源的增刪查改，也就是上面提到的四個HTTP的方法。

GET、PUT和DELETE方法都比較顯而易見，好理解，大多數時候，這幾個方法的資源都確確實實對應著資料庫的某張表或某條記錄，例如“/api/admin/users”可能對應著資料庫中的ADMIN_USER表，而“/api/admin/users/8642”則對應著ADMIN_USER表中的ID為8642的這條使用者記錄。

POST方法則不是那麼直截了當，例如“/api/emp/paysalary”，也許資料庫中根本就沒有一個直接與之一一對應的表，paysalary是一個抽象的業務操作對象，往這個對象執行一下POST就相當於給某個員工發放了一次工資，其實際的動作可能涉及到多張表的聯動，如員工表的工資發放標誌、工資發放記錄表插入一條記錄，公司財務表插入一條記錄，動作記錄表插入一條記錄，系統訊息表插入一條記錄等……

對RESTful Web API的理解與設計思路