word版可編輯-restfulapi設(shè)計(jì)規(guī)范精心整理(已修改)
2025-04-19 06:53 本頁面
【正文】 背景目前互聯(lián)網(wǎng)上充斥著大量的關(guān)于RESTful API（為方便，下文中“RESTful API ”簡寫為“API”）如何設(shè)計(jì)的文章，然而卻沒有一個(gè)”萬能“的設(shè)計(jì)標(biāo)準(zhǔn)：如何鑒權(quán)？API 格式如何？你的API是否應(yīng)該加入版本信息？當(dāng)你開始寫一個(gè)app的時(shí)候，特別是后端模型部分已經(jīng)寫完的時(shí)候，你不得不殫精竭慮的設(shè)計(jì)和實(shí)現(xiàn)自己app的public API部分。因?yàn)橐坏┌l(fā)布，對外發(fā)布的API將會很難改變。在給SupportedFu設(shè)計(jì)API的時(shí)候，我試圖以實(shí)用的角度來解決上面提到的問題。我希望可以設(shè)計(jì)出容易使用，容易部署，并且足夠靈活的API，本文因此而生。API設(shè)計(jì)的基本要求網(wǎng)上的很多關(guān)于API設(shè)計(jì)的觀點(diǎn)都十分”學(xué)院派“，它們也許更有理論基礎(chǔ)，但是有時(shí)卻和現(xiàn)實(shí)世界脫軌（因此我是自由派）。所以我這篇文章的目標(biāo)是從實(shí)踐的角度出發(fā)，給出當(dāng)前網(wǎng)絡(luò)應(yīng)用的API設(shè)計(jì)最佳實(shí)踐（當(dāng)然，是我認(rèn)為的最佳了~），如果覺得不合適，我不會遵從標(biāo)準(zhǔn)。當(dāng)然作為設(shè)計(jì)的基礎(chǔ)，幾個(gè)必須的原則還是要遵守的：1. 當(dāng)標(biāo)準(zhǔn)合理的時(shí)候遵守標(biāo)準(zhǔn)。2. API應(yīng)該對程序員友好，并且在瀏覽器地址欄容易輸入。3. API應(yīng)該簡單，直觀，容易使用的同時(shí)優(yōu)雅。4. API應(yīng)該具有足夠的靈活性來支持上層ui。5. API設(shè)計(jì)權(quán)衡上述幾個(gè)原則。需要強(qiáng)調(diào)的是：API的就是程序員的UI，和其他UI一樣，你必須仔細(xì)考慮它的用戶體驗(yàn)！使用RESTful URLs 和action.雖然前面我說沒有一個(gè)萬能的API設(shè)計(jì)標(biāo)準(zhǔn)。但確實(shí)有一個(gè)被普遍承認(rèn)和遵守：RESTfu設(shè)計(jì)原則。它被Roy Felding提出（在他的”基于網(wǎng)絡(luò)的軟件架構(gòu)“論文中第五章）。而REST的核心原則是將你的API拆分為邏輯上的資源。這些資源通過被操作（GET ,POST,PUT,DELETE）。那么我應(yīng)該如何拆分出這些資源呢？顯然從API用戶的角度來看，”資源“應(yīng)該是個(gè)名詞。即使你的內(nèi)部數(shù)據(jù)模型和資源已經(jīng)有了很好的對應(yīng)，API設(shè)計(jì)的時(shí)候你仍然不需要把它們一對一的都暴露出來。這里的關(guān)鍵是隱藏內(nèi)部資源，暴露必需的外部資源。在SupportFu里，資源是 ticket、user、group。一旦定義好了要暴露的資源，你可以定義資源上允許的操作，以及這些操作和你的API的對應(yīng)關(guān)系： GET /tickets 獲取ticket列表 GET /tickets/12 查看某個(gè)具體的ticket POST /tickets 新建一個(gè)ticket PUT /tickets/12 更新ticket 12. DELETE /tickets/12 刪除ticekt 12可以看出使用REST的好處在于可以充分利用的強(qiáng)大實(shí)現(xiàn)對資源的CURD功能。而這里你只需要一個(gè)endpoint：/tickets,再沒有其他什么命名規(guī)則和url規(guī)則了，cool！這個(gè)endpoint的單數(shù)復(fù)數(shù)一個(gè)可以遵從的規(guī)則是：雖然看起來使用復(fù)數(shù)來描述某一個(gè)資源實(shí)例看起來別扭，但是統(tǒng)一所有的endpoint，使用復(fù)數(shù)使得你的URL更加規(guī)整。這讓API使用者更加容易理解，對開發(fā)者來說也更容易實(shí)現(xiàn)。如何處理關(guān)聯(lián)？關(guān)于如何處理資源之間的管理REST原則也有相關(guān)的描述： GET /tickets/12/messages Retrieves list of messages for ticket 12 GET /tickets/12/messages/5 Retrieves message 5 for ticket 12 POST /tickets/12/messages Creates a new message in ticket 12 PUT /tickets/12/messages/5 Updates message 5 for ticket 12 PATCH /tickets/12/messages/5 Partially updates message 5 for ticket 12 DELETE /tickets/12/messages/5 Deletes message 5 for ticket 12其中，如果這種關(guān)聯(lián)和資源獨(dú)立，那么我們可以在資源的輸出表示中保存相應(yīng)資源的endpoint。然后API的使用者就可以通過點(diǎn)擊鏈接找到相關(guān)的資源。如果關(guān)聯(lián)和資源聯(lián)系緊密。資源的輸出表示就應(yīng)該直接保存相應(yīng)資源信息。（例如這里如果message資源是獨(dú)立存在的，那么上面 GET /tickets/12/messa
公司管理相關(guān)推薦
鄂ICP備17016276號-1