微服務的接口設計(RESTful規范)
基本知識
- URI:在RESTful架構中,每個URI代表一種資源
- URI規范:
- 不用大寫
- 用中杠-,不用下划線_
- 路徑中不能有動詞,只能有名詞
- 名詞表示資源集合,要使用復數形式
- 通過標准HTTP方法對資源進行CRUD(將服務行為映射到標准HTTP動詞)
- CRUD:增加(Create)、檢索(Retrieve)、更新(Update)和刪除(Delete)幾個單詞的首字母簡寫
- GET(SELECT):從服務器取出/請求資源
- POST(CREATE):在服務器新建資源
- PUT(UPDATE):在服務器更新資源
- 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:不冪等,多次請求會在數據庫表中生成多條記錄