寫一個restful後臺你需要什麼

基礎知識

• HTTP 協議
• oauth2 協議
• 一定的資料庫設計使用能力
• json

協議設計

作為後臺服務，需要一個比較符合程式設計師直覺的設計感覺，最基本幾個要求：

1. url應該包含版本號，方便多個版本的前臺使用
2. 語義化url,url中不要包含動詞，前後url應該包含結構間應該包含明顯的包含關係
3. 語義化動作,目前的情形下只需要包含get(查詢),post(新增),put(修改),delete(刪除)即可
4. 輸入和輸出採用json
5. 使用http state code 表示結果狀態

url設計

• 包含版本號，方便迭代，多個版本api同時使用
• url中的名詞需要注意單複數形式，對單個資源的操作用單數，對多個資源的操作用複數
• 名詞化資源:url中的每個部分應該包含明比較明顯的從屬關係，設計上比較符合資料庫中er模型的實體，注意名詞的單複數對於ge
  • 獲取使用者 get /v1/user
  • 獲取所有使用者 get /v1/users
  • 獲取某個使用者 get /v1/user/1
  • 修改某個使用者資訊 put /v1/user/1
  • 獲取某個使用者的所有電話 get /v1/user/2/phone_nums
  • 有時可以省去指定某個特定 /1 ，作為當前使用者，返回當前使用者的電話 get /v1/user/phone_nums

語義化動作

使用http的幾個標準方法來操作資源
目前主流支援的http方法有:

• get 獲取資源
• post 建立資源
• put 、patch 更新資源
• delete 刪除資源

使用這些方法配合url定位資源基本可以完成大部分操作

實際使用過程中可能有很多請求不是這樣的動詞語義，但基本都可以對映到這幾種方法上來

鑑權Authentication

因為restful 的無狀態特點，鑑權提供瞭如何識別一個請求發出者

目前業界普遍使用的是oauth2.0協議，目前我們使用的是一個它的簡化版本，在http header 中增加一個欄位
Access_token 作為使用者鑑權標準。

需要注意的是，為了增加安全性，這個token應該增加自動過期，然而為了體驗，目前沒有設定

輸入和輸出

輸入和輸出根據方法的不同，正確結果不同有所差異。

查詢操作

get 中可以使用查詢字串作為輸入 比如 get /v1/user?username=a

而查詢需要傳送的引數的作用一般在於進行幾個後續操作，有分頁，過濾，搜尋，排序

*分頁:
目前採用的使用page引數作為頁碼進行操作

v1/users?page=1

但是新的標準中使用的是link header作為翻頁的標準，使用link header的API應該返回一系列組合好了的url而不是讓使用者自己再去拼。這點在基於遊標的分頁中尤為重要。例如下面，來自github的文件

Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next", 
<https://api.github.com/user/repos?page=50&per_page=100>; rel="last"

根據目前情況，仍然將使用一段時間page 作為分頁遊標

• 過濾 ，過濾結果。目前沒有這樣的操作
• 搜尋，使用?q=asd 查詢字元傳來查詢，所有的搜尋都是使用模糊搜尋
• 排序，使用?sort_by=asd 查詢字串來進行排序

輸出，根據文件而定，一般而言根據結果可以分為正確返回和錯誤返回

需要注意的是單複數返回結果的不一致
返回某個使用者資訊 get /v1/user/2

    {
        "id": 1,
        "username":"asd",
        "phone":"132xxxx2222"
    }

獲取全部使用者資訊 get /v1/users

    {
        "users":[
            {
                "id":1,
                "username":"asd",
                "phone":"132xxxx2222"
            },
            ...
        ]
    }

新增操作

post方法使用json object 獲取傳入引數

比如建立使用者 則可以向 /v1/user 傳送post 請求，請求body是json字串

{
    "username":"coco",
    "password":"test"
}

post,put 方法房返回 建立、修改的id，比如之前建立使用者的操作返回json

{
    "id":123
}

更新操作

put 方法使用json object 獲取傳入引數,傳入的資料大體相當於post方法。但是這邊為了方便使用，混淆了put和patch 方法，所有put 方法的引數都是可選的，只修改發來的引數部分

刪除操作## Heading

delete 方法不接受引數，對某個資源的操作需要包含在
delete 方法返回操作結果，一般是

    {
        "state":"ok"
    }

標準化過程

一般的restful操作基本可以分為這麼幾步

restful過程

其中出現了幾個錯誤，用幾個http狀態碼確定錯誤型別
所有錯誤返回體是
{ "state":"error", "code":123, "reason":"呵呵"}

下一篇將 python的tornado 框架具體實現一個這樣標準的模板~~~~

全文禁止轉載！！！！