[點晴永久免費OA]Restful API接口規范
當前位置：點晴教程→點晴OA辦公管理信息系統
→『 經驗分享&問題答疑 』
REST：英文representational state transfer直譯為表現層狀態轉移，或者表述性狀態轉移；Rest是web服務的一種架構風格，一種設計風格，是一種思想；同時Rest不是針對某一種編程語言的。 以webService為例通俗解釋。 非Rest設計，以往我們都會這么寫： http://localhost:8080/admin/getUser （查詢用戶） http://localhost:8080/admin/addUser （新增用戶） http://localhost:8080/admin/updateUser （更新用戶） http://localhost:8080/admin/deleteUser （刪除用戶） 總結：以不同的URL（主要為使用動詞）進行不同的操作。 Rest架構： GET http://localhost:8080/admin/user （查詢用戶） POST http://localhost:8080/admin/user （新增用戶） PUT http://localhost:8080/admin/user （更新用戶） delete http://localhost:8080/admin/user （刪除用戶） 總結：URL只指定資源，以HTTP方法動詞進行不同的操作。用HTTP STATUS/CODE定義操作結果。 Restful：遵守了rest風格的web服務便可稱為Restful。 為什么需要Restful？ URL具有很強可讀性的，具有自描述性 規范化請求過程和返回結果 資源描述與視圖的松耦合 可提供OpenAPI，便于第三方系統集成，提高互操作性 提供無狀態的服務接口，降低復雜度，可提高應用的水平擴展性 /版本號/資源路徑 /v1/tags/{tag_id} /v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20] 1、版本號命名版本號可以解決版本不兼容問題，在設計 RESTful API 的一種實用的做法是使用版本號。一般情況下，我們會在 url 中保留舊版本號，并同時兼容多個版本 【GET】 /v1/users/{user_id} // 版本 v1 的查詢用戶列表的 API 接口 【GET】 /v2/users/{user_id} // 版本 v2 的查詢用戶列表的 API 接口 2、資源路徑URI 不能包含動詞，只能是名詞（命名名詞的時候，要使用小寫、數字及下劃線來區分多個單詞）。 資源的路徑應該從根到子依次如下: /{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property} 【POST】 /v1/users/{user_id}/roles/{role_id} // 添加用戶的角色 有的時候，當一個資源變化難以使用標準的 RESTful API 來命名，可以考慮使用一些特殊的 actions 命名。 /{resources}/{resource_id}/actions/{action} 【PUT】 /v1/users/{user_id}/password/actions/modify // 密碼修改 3、請求方式【GET】 /users # 查詢用戶信息列表 【GET】 /users/1001 # 查看某個用戶信息 【POST】 /users # 新建用戶信息 【PUT】 /users/1001 # 更新用戶信息(全部字段) 【PATCH】 /users/1001 # 更新用戶信息(部分字段) 【delete】 /users/1001 # 刪除用戶信息 【PATCH】一般不用，用【PUT】 4、查詢參數RESTful API 接口應該提供參數，過濾返回結果。 【GET】 /{version}/{resources}/{resource_id}?offset=0&limit=20 5、響應參數JSON格式（code、data、msg） 6、狀態碼使用適合的狀態碼很重要，而不應該全部都返回狀態碼 200 狀態碼，可根據以下標準按照項目擴展自身狀態碼： 200~299段 表示操作成功： 200 操作成功，正常返回 201 操作成功，已經正在處理該請求 300~399段 表示參數方面的異常 300 參數類型錯誤 301 參數格式錯誤 302 參數超出正常取值范圍 303 token過期 304 token無效 400~499段 表示請求地址方面的異常： 400 找不到地址 500~599段 表示內部代碼異常： 500 服務器代碼異常 7、完整事例UserController.java @RestController(/v1) @API(tag=”用戶相關接口”) public class UserController { @Autowired private UserJPARepository userJPARepository; /** * 查詢用戶列表 * @return */ @GetMapping(value = "/user") public List<User> findUserList(){ return userJPARepository.findAll(); } /** * 根據Id查詢一個用戶 * @param id * @return */ @GetMapping(value = "/user/query/{id}") public User findUserOne(@PathVariable("id") Integer id){ return userJPARepository.findOne(id); } /** * 添加用戶 * @param name * @param age * @param country * @return */ @PostMapping(value = "/user") public User addUser(@RequestParam("name") String name, @RequestParam("age") int age, @RequestParam("country") String country){ User user = new User(); user.setName(name); user.setAge(age); user.setCountry(country); return userJPARepository.save(user); } /** * 刪除用戶 * @param id 用戶編號 * @return */ @deleteMapping(value = "/user/{id}") public List<User> deleteUser(@PathVariable("id") Integer id){ userJPARepository.delete(id); return userJPARepository.findAll(); } /** * 更新用戶 * @param id * @param name * @param age * @param country * @return */ @PutMapping(value = "/user/{id}") public User updateUser(@PathVariable("id") Integer id, @RequestParam("name") String name, @RequestParam("age") int age, @RequestParam("country") String country){ User user = userJPARepository.findById(id); user.setName(name); user.setAge(age); user.setCountry(country); return userJPARepository.save(user); } /** * 根據國家查詢用戶 * @param country * @return */ @GetMapping(value = "/user/{country}") public List<User> findByCountry(@PathVariable("country") String country){ return userJPARepository.findByCountry(country); } }
該文章在 2022/4/18 16:06:58 編輯過 |
關鍵字查詢
相關文章
正在查詢... 
|
400 186 1886
