前言

說到restful，其實我們並不完全遵循restful規範。我們會參考restful的設計理念，並且結合我們自己的一些實踐來對web api進行設計。

我們一起來看看RESTFul API有哪些特點：

1. 基於“資源”，資料也好、服務也好，在RESTFul設計裡一切都是資源。GET：查詢，POST：新增，PUT：更新，DELETE：刪除
2. 無狀態。一次呼叫一般就會返回結果，不存在類似於“開啟連線-訪問資料-關閉連線”這種依賴於上一次呼叫的情況。
3. URL中通常不出現動詞，只有名詞
4. URL語義清晰、明確，使用HTTP的GET、POST、DELETE、PUT來表示對於資源的增刪改查

5. 返回結果使用JSON不使用XML

   網站：/get_user?id=100
   RESTFul: GET /user/100 (GET是HTTP型別)

我們通常的GET和POST同RESTFul中的GET、POST是不一樣的。通常使用GET、POST的選擇點在於，簡單的用GET、複雜物件用POST，並沒有動作的含義，例如我也可以使用get來執行新增的動作，如果引數很多，我也可以使用POST來執行查詢操作；但在REST裡，GET對應的是查詢一個資源，而POST對應的是新增一個資源，意義是決然不同的。理解這一點非常重要。

規範

1. api 介面必須加版本號，初始版本 【v1】
2. 不使用rest的PUT和DELETE，因為很多瀏覽器不支援，很多框架也不支援
3. POST在需要傳輸大量資料的時候使用，其餘使用GET就可以了；
   

   這裡GET和POST沒有明確的含義，GET也可以新增

4. 我們返回一般統一使用json格式返回
5. 在url上必須包含行為
6. 使用Token令牌來做使用者身份的校驗與許可權分級，而不是Cookie
7. 暴露外部請求一定使用SSL

Path具體的實現

path = /{版本}/{具體的業務功能}/{表名}/{行為}

1. {版本}：開始時全部為V1，
2. {具體的業務功能}：
   

App的setting，資料庫命名為 app_setting
那麼，具體的業務功能=setting
架構組的wechat，資料庫命名為arch_wechat
那麼，具體的業務功能=wechat

{表名}:就是資料的表名

{行為}：一般就是方法名

?limit=10：指定返回記錄的數量

?offset=10：指定返回記錄的開始位置。

?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。

?sort_by=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。

http協議	方法	行為path	說明
POST	add(POJO)	/add	新增一個物件，接收json資訊
GET	insert(param …)	/insert?param1=?&param1=?	插入一個物件，多個引數的方式，作用和add一樣，只是傳引數方式不同
GET	deleteById(long)	/delete_by_id?id=?	資料庫不刪除，但是業務上有刪除的語意
POST	update(POJO)	/update
GET	updateById(long)	/update_by_id?id=?	{表名}中已經具體指明瞭實體，所有這裡可以不用update_pojo_by_id
GET	getById(long)	/get_by_id?id=?	{表名}中已經具體指明瞭實體，所有這裡可以不用get_pojo_by_id
GET	listByParam(Object)	/list_by_param?param=?&page=2&per_page=100	list查詢多個，預設全部,可以帶上limit，offset，page，sort_by，order等引數

參考資料庫設計 
【推薦】表的命名最好是加上“業務名稱_表的作用”。       
正例: user / trade_config
【推薦】庫名與應用名稱儘量一致，{業務專案}_{功能},業務專案和功能怎麼寫參考

Response

1. 採用JSON，不要使用XML
2. 預設情況下要支援gzip
3. 格式統一：

{
      "code" : 0,
      "msg" : "Something bad happened",
      "data" : {

      }
    }

• code: 0為成功，非0為失敗。可以自定義code，代表不同的錯誤碼
• msg: 當code為非0時，獲取錯誤資訊。當code為0時，msg一般為”success”。如果有需要也可以另外作規定
• data: 當code為0時，獲取結果，全部以json方式表示。當code為非0時，data沒有資料

錯誤處理

不要直接將異常拋給客戶端處理，一般需要一個統一的異常處理類，並且以統一格式將異常資訊返回前端，統一格式參照“# Response”