這篇文章主要介紹“Restful架構(gòu)風(fēng)格下，API接口設(shè)計(jì)正確的寫法是什么”，在日常操作中，相信很多人在Restful架構(gòu)風(fēng)格下，API接口設(shè)計(jì)正確的寫法是什么問題上存在疑惑，小編查閱了各式資料，整理出簡單好用的操作方法，希望對大家解答”Restful架構(gòu)風(fēng)格下，API接口設(shè)計(jì)正確的寫法是什么”的疑惑有所幫助！接下來，請跟著小編一起來學(xué)習(xí)吧！

創(chuàng)新互聯(lián)建站專注于安定企業(yè)網(wǎng)站建設(shè),響應(yīng)式網(wǎng)站開發(fā),商城系統(tǒng)網(wǎng)站開發(fā)。安定網(wǎng)站建設(shè)公司,為安定等地區(qū)提供建站服務(wù)。全流程按需求定制設(shè)計(jì)，專業(yè)設(shè)計(jì)，全程項(xiàng)目跟蹤，創(chuàng)新互聯(lián)建站專業(yè)和態(tài)度為您提供的服務(wù)

1、查詢某個對象接口：GET /app/getImportantApp

@GetMapping(path = "/getImportantApp")  public R getImportionApp(@RequestHeader("pid") String pid

2、查詢列表接口：GET /app/list

@RequestMapping("/list")  public R list(String deptId)

3、保存對象接口：POST /app/save

@PostMapping("/save")  public R add(CmsAppLicationEntity appLication, String deptId)

4、刪除對象接口：POST /app/delete

@DeleteMapping("/delete/{applicationId}")  public R delete(@PathVariable("applicationId") long applicationId)

5、更新對象接口：POST /app/batchUpdate

@PostMapping("/batchUpdate") public R batchUpdate(@RequestBody List<CmsAppLicationEntity> list)

是不是感覺很熟悉的代碼，難道寫的不對?看著挺直觀易懂的。如果采用 Restful 架構(gòu)風(fēng)格，上面這五種寫法當(dāng)然不對，這是對 Restful  架構(gòu)風(fēng)格不了解所致。

微信搜公眾號「猿芯」，后臺私信回復(fù) 1024 免費(fèi)領(lǐng)取  SpringCloud、SpringBoot，微信小程序、Java面試、數(shù)據(jù)結(jié)構(gòu)、算法等全套視頻資料。

Restful 架構(gòu)風(fēng)格定義

• “Restful  是一種軟件架構(gòu)風(fēng)格、設(shè)計(jì)風(fēng)格，而不是標(biāo)準(zhǔn)，只是提供了一組設(shè)計(jì)原則和約束條件。它主要用于客戶端和服務(wù)器交互類的軟件?；谶@個風(fēng)格設(shè)計(jì)的軟件可以更簡潔，更有層次，更易于實(shí)現(xiàn)緩存等機(jī)制。

由于對 Restful 架構(gòu)風(fēng)格理解的不夠透徹，一般會產(chǎn)生三種爭議的設(shè)計(jì)誤區(qū)。

• 誤區(qū)一 請求路徑 URI 是動詞，而不是名詞問題

• 誤區(qū)二 URI中帶版本號問題

• 誤區(qū)三 URI 中路徑大小寫問題

誤區(qū)一 請求路徑 URI 是動詞，而不是名詞問題

按照對 Restful 架構(gòu)風(fēng)格理解，每個業(yè)務(wù)實(shí)體代表一種資源，代表一個名詞。

比方說，設(shè)計(jì)產(chǎn)品列表接口時：

錯誤寫法

/getProductList

請求路徑 /getProductList 路徑出現(xiàn)動詞 get，這種寫法是不對的。

推薦寫法

/products

另外 URL 出現(xiàn) /addProduct、/deleteProduct、/updateProduct 等寫法也是不對的。

如果某些動作是 HTTP 動詞表示不了的，你應(yīng)該把該動作變成一種資源。

比方說，我們獲取用戶下的產(chǎn)品列表，錯誤接口設(shè)計(jì)是：

POST /users/1/getProducts

或者

POST /users/1/getProductList

正確的寫法是把動詞 getProducts 改成名詞 products

POST /users/1/products

誤區(qū)二 URI 中帶版本號問題

業(yè)界對 URI 中是否帶版本號存在三種說法。

第一種說法是，在請求路徑中加入版本號，比方說：

POST /products/v1 GET /users/v1 POST /orders/v1 POST /items/v1

這種說法認(rèn)為，在 URI 中加入版本避免了向后兼容，另外通過過期提示，重定向，文檔等手段也能降低用戶遷移到新的接口上的成本。

當(dāng)然有人贊成在請求路徑中加入版本號，也有人反對這種加版本號的做法，他們認(rèn)為:

• 加入版本號會讓服務(wù)接口變得混亂，經(jīng)常碰到的情況是，一些低版本的API接口調(diào)用一些高版本的API接口，導(dǎo)致數(shù)據(jù)解析錯誤，這無疑加大了用戶遷移的成本。

• 版本和資源的概念沒有任何關(guān)系，因此在 URI 中加入版本會讓用戶混淆。

還有一種說法是，在路徑中加版本號是錯誤的設(shè)計(jì)方式，在老外寫的 Versioning REST Services 這篇文章指出，你應(yīng)該在請求頭的  Accept 指定你的版本號，而不是請求路徑中。

例如：

For example, for versions 1.0, 1.1, and 2.0 of the foo data type as JSON set the Accept/Content-Type header as follows: 1.0: vnd.example-com.foo+json; version=1.0 1.1: vnd.example-com.foo+json; version=1.1 2.0: vnd.example-com.foo+json; version=2.0

前端 js 在請求頭 Accept 指定 vnd.example-com.foo+json; version=1.1 的版本  version=1.1。

$.ajax({     beforeSend: function (req) {         req.setRequestHeader("Accept", "vnd.example-com.foo+json; version=1.1");          },     type: "GET",     url: "http://http://www.example.com/foo/12",     success: function (data) {         /* code elided */     },     dataType: "json" });

我個人是比較傾向請求路徑中加版本號的，因?yàn)槲艺J(rèn)為加版本號是站在程序角度來考慮新老版本的接口移植問題，特別是現(xiàn)在流行微服務(wù)架構(gòu)，業(yè)務(wù)粒度很細(xì)的情況下，接口的升級，原有版本是否保留呢?

那什么時候該加版本號呢?

• “如果你開發(fā)的 restful 接口是開放的，你也不知道都有誰調(diào)用過，那么這個時候版本號就是必須的了。以百度地圖接口為例，百度發(fā)布了 restful  風(fēng)格的地圖接口在網(wǎng)上，全國甚至全世界各行各業(yè)都可以調(diào)用這些接口，百度要對接口進(jìn)行升級，該怎么辦?如果百度直接在原有的url上進(jìn)行升級，會產(chǎn)生什么樣的結(jié)果呢?不可預(yù)估。程序員：老板，咱們的產(chǎn)品崩潰了!老板：為啥?程序員：百度升級了接口!哪怕僅僅是多返回了一個字段，都可能導(dǎo)致調(diào)用者原有的代碼出現(xiàn)問題，畢竟百度無法知道所有人都是怎么解析返回值的。這個時候最好的做法就是加版本號，保持原有版本，發(fā)布新的版本，所有問題迎刃而解。老用戶也不用因?yàn)榘俣鹊纳?，進(jìn)行代碼的更新，新用戶又能享受最新的接口，完美。

判斷是否要加版本號的方法：

• 是否明確的知道都有誰調(diào)用了你的接口，并且能通知到，如果能，那可以不加版本號;

• restful接口升級的時候，原有版本是否保留，如果不保留，可以不加版本號;

當(dāng)然，加版本號是有一定技巧的，版本號應(yīng)該放在一個功能模塊的后面，甚至一個 url就應(yīng)該自己獨(dú)立的版本，如  api/user/v2，這樣調(diào)用者就不會有整套接口都升級到 v2的錯覺。

誤區(qū)三 URI 中路徑大小寫問題

URL 中路徑最好是小寫，不要有駝峰式寫法，比如下面接口錯誤寫法

POST /orderItems/v1/1001

推薦寫法

POST /orders/v1/items/1001

或者

/order-items/v1/1001

總結(jié)

我見過很多采用基于微服務(wù)架構(gòu)編寫的微服務(wù)代碼，大多數(shù)接口看似 restful 風(fēng)格，然而仔細(xì)辨識才發(fā)現(xiàn)，原來是一堆的偽 restful  接口，要么動詞名詞不分，要么路徑版本各種混亂。

實(shí)際上的場景是，restful 風(fēng)格基本上停留在口口相傳上，看起來逼格很高的東西也只能高高供起。大部分的程序員為了趕進(jìn)度，完成  KPI，那還顧得上這種規(guī)范，一直在瘋狂的打碼中。

附錄1 API 設(shè)計(jì)風(fēng)格基本規(guī)則

1、使用名詞而不是動詞

不要使用：

/getAllUsers /createNewUser /deleteAllUser

2、Get 方法和查詢參數(shù)不應(yīng)該涉及狀態(tài)改變

使用 PUT, POST 和 DELETE 方法 而不是 GET 方法來改變狀態(tài)，不要使用 GET 進(jìn)行狀態(tài)改變:

3、使用復(fù)數(shù)名詞

不要混淆名詞單數(shù)和復(fù)數(shù)，為了保持簡單，只對所有資源使用復(fù)數(shù)。

/cars 而不是 /car /users 而不是 /user /products 而不是 /product /settings 而部署 /setting

4、使用子資源表達(dá)關(guān)系 如果一個資源與另外一個資源有關(guān)系，使用子資源：

GET /cars/711/drivers/ 返回 car 711的所有司機(jī)  GET /cars/711/drivers/4 返回 car 711的4號司機(jī)

5、使用 Http 頭聲明序列化格式

在客戶端和服務(wù)端，雙方都要知道通訊的格式，格式在 HTTP-Header 中指定

• Content-Type 定義請求格式

• Accept 定義系列可接受的響應(yīng)格式

6、為集合提供過濾 排序 選擇和分頁等功能

Filtering 過濾: 使用唯一的查詢參數(shù)進(jìn)行過濾：

GET /cars?color=red 返回紅色的cars  GET /cars?seats<=2 返回小于兩座位的cars集合

Sorting 排序:允許針對多個字段排序

GET /cars?sort=-manufactorer,+model

這是返回根據(jù)生產(chǎn)者降序和模型升序排列的 car 集合。

移動端能夠顯示其中一些字段，它們其實(shí)不需要一個資源的所有字段，給 API 消費(fèi)者一個選擇字段的能力，這會降低網(wǎng)絡(luò)流量，提高 API 可用性。

GET /cars?fields=manufacturer,model,id,color

Paging 分頁，使用 limit 和 offset.實(shí)現(xiàn)分頁，缺省 limit=20 和 offset=0;

GET /cars?offset=10&limit=5

為了將總數(shù)發(fā)給客戶端，使用訂制的 HTTP 頭：X-Total-Count。鏈接到下一頁或上一頁可以在 HTTP 頭的 link 規(guī)定，遵循 Link  規(guī)定:

Link: <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>; rel="next", <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>; rel="last", <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>; rel="first", <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>; rel="prev",

7、版本化你的 API

使得 API 版本變得強(qiáng)制性，不要發(fā)布無版本的 API，使用簡單數(shù)字，避免小數(shù)點(diǎn)如 2.5

一般在 Url 后面使用 ?v

/blog/api/v1

8、使用 Http 狀態(tài)碼處理錯誤

如果你的API沒有錯誤處理是很難的，只是返回 500 和出錯堆棧不一定有用，Http 狀態(tài)碼提供 70 個出錯，我們只要使用 10 個左右：

200 – OK – 一切正常 201 – OK – 新的資源已經(jīng)成功創(chuàng)建 204 – OK – 資源已經(jīng)成功擅長 304 – Not Modified – 客戶端使用緩存數(shù)據(jù) 400 – Bad Request – 請求無效，需要附加細(xì)節(jié)解釋如 "JSON無效" 401 – Unauthorized – 請求需要用戶驗(yàn)證 403 – Forbidden – 服務(wù)器已經(jīng)理解了請求，但是拒絕服務(wù)或這種請求的訪問是不允許的。 404 – Not found – 沒有發(fā)現(xiàn)該資源 422 – Unprocessable Entity – 只有服務(wù)器不能處理實(shí)體時使用，比如圖像不能被格式化，或者重要字段丟失。 500 – Internal Server Error – API開發(fā)者應(yīng)該避免這種錯誤。

使用詳細(xì)的錯誤包裝錯誤：

{   "errors": [    {     "userMessage": "Sorry, the requested resource does not exist",     "internalMessage": "No car found in the database"     "code": 34,     "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"    }   ] }

允許覆蓋http方法

一些代理只支持 POST 和 GET 方法， 為了使用這些有限方法支持 RESTful API，需要一種辦法覆蓋 http 原來的方法。使用訂制的  HTTP 頭 X-HTTP-Method-Override 來覆蓋 POST 方法.

到此，關(guān)于“Restful架構(gòu)風(fēng)格下，API接口設(shè)計(jì)正確的寫法是什么”的學(xué)習(xí)就結(jié)束了，希望能夠解決大家的疑惑。理論與實(shí)踐的搭配能更好的幫助大家學(xué)習(xí)，快去試試吧！若想繼續(xù)學(xué)習(xí)更多相關(guān)知識，請繼續(xù)關(guān)注創(chuàng)新互聯(lián)網(wǎng)站，小編會繼續(xù)努力為大家?guī)砀鄬?shí)用的文章！

網(wǎng)頁題目：Restful架構(gòu)風(fēng)格下，API接口設(shè)計(jì)正確的寫法是什么
網(wǎng)站網(wǎng)址：http://chinadenli.net/article16/gigogg.html

成都網(wǎng)站建設(shè)公司_創(chuàng)新互聯(lián)，為您提供標(biāo)簽優(yōu)化、面包屑導(dǎo)航、虛擬主機(jī)、品牌網(wǎng)站設(shè)計(jì)、自適應(yīng)網(wǎng)站、手機(jī)網(wǎng)站建設(shè)

廣告

聲明：本網(wǎng)站發(fā)布的內(nèi)容（圖片、視頻和文字）以用戶投稿、用戶轉(zhuǎn)載內(nèi)容為主，如果涉及侵權(quán)請盡快告知，我們將會在第一時間刪除。文章觀點(diǎn)不代表本網(wǎng)站立場，如需處理請聯(lián)系客服。電話：028-86922220；郵箱：631063699@qq.com。內(nèi)容未經(jīng)允許不得轉(zhuǎn)載，或轉(zhuǎn)載時需注明來源： 創(chuàng)新互聯(lián)