微服務接口設計(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:不冪等,多次請求會在數據庫表中生成多條記錄


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM