微服務接口設計（RESTful規范）

微服務的接口設計（RESTful規范）

基本知識

• URI：在RESTful架構中，每個URI代表一種資源
• URI規范：
  1. 不用大寫
  2. 用中杠-，不用下划線_
  3. 路徑中不能有動詞，只能有名詞
  4. 名詞表示資源集合，要使用復數形式
• 通過標准HTTP方法對資源進行CRUD（將服務行為映射到標准HTTP動詞）
  1. CRUD：增加(Create)、檢索(Retrieve)、更新(Update)和刪除(Delete)幾個單詞的首字母簡寫
  2. GET（SELECT）：從服務器取出/請求資源
  3. POST（CREATE）：在服務器新建資源
  4. PUT（UPDATE）：在服務器更新資源
  5. DELETE：從服務器刪除資源
• 使用JSON作為微服務提交和返回數據的通用語言
• 使用HTTP狀態碼來傳達服務調用的狀態

示例：

服務器維護資源如下(使用一張表存用戶信息)
一般每種資源都會設計字段id來做唯一標識，便於請求資源
User {
    int id;
    int age;
    bool sex;
    String phone;
    role String;
    ...
}

該資源的URI設計為
ip:port/service-name/users

獲取全部用戶的信息
GET ip:port/service-name/users

創建一個用戶
POST ip:port/service-name/users

獲取某個用戶的信息
GET ip:port/service-name/users/id

修改某個用戶的信息
PUT ip:port/service-name/users

刪除某個用戶的信息
DEL ip:port/service-name/users/id

錯誤設計如下：

創建一個用戶
POST ip:port/service-name/users/add

獲取某個用戶的信息
GET ip:port/service-name/users/id/get

修改某個用戶的信息
PUT ip:port/service-name/users/change

有時請求中需要帶有很多條件，這些條件可以放在RequestParam（query）里。

比如用戶管理B端，做分頁展示時，如果每頁展示20個用戶，接口的設計可能為
GET ip:port/service-name/users?offset=xxx&limit=20

比如返回所有管理員權限的用戶，接口的設計可能為
GET ip:port/service-name/users?role=admin

當然，上述只是規范，實際開發中可能會有很多api的設計會突破RESTful規范。

注意保證冪等

冪等：請求一次和請求多次的效果是一樣的。

GET：由於GET請求僅僅是獲取資源 並不修改資源，所以能保證冪等
PUT：同樣的請求，修改一次和修改多次是一樣的，能保證冪等
DEL：同理，能保證冪等。但是多次請求，只有第一次能返回200，其他都應該是404
POST：不冪等，多次請求會在數據庫表中生成多條記錄