www.久久久久|狼友网站av天堂|精品国产无码a片|一级av色欲av|91在线播放视频|亚洲无码主播在线|国产精品草久在线|明星AV网站在线|污污内射久久一区|婷婷综合视频网站

當(dāng)前位置：首頁(yè) > 公眾號(hào)精選 > 架構(gòu)師社區(qū)

一文詳解?API?設(shè)計(jì)最佳實(shí)踐

時(shí)間：2021-10-27 13:54:18
關(guān)鍵字： API   
手機(jī)看文章

掃描二維碼
隨時(shí)隨地手機(jī)看文章

[導(dǎo)讀]-???前言???-良好設(shè)計(jì)的API=快樂(lè)的程序員。應(yīng)用程序接口（API）是一種接口，它讓?xiě)?yīng)用程序可以輕松地使用另一個(gè)應(yīng)用程序的數(shù)據(jù)和資源，API對(duì)于一個(gè)產(chǎn)品或公司的成功至關(guān)重要。如果沒(méi)有API，你大部分喜歡的軟件今天就不會(huì)存在。例如，GoogleMapsAPI可以讓你在app或...


-     前言 -



良好設(shè)計(jì)的API = 快樂(lè)的程序員 。

應(yīng)用程序接口（API）是一種接口，它讓?xiě)?yīng)用程序可以輕松地使用另一個(gè)應(yīng)用程序的數(shù)據(jù)和資源，API 對(duì)于一個(gè)產(chǎn)品或公司的成功至關(guān)重要。
如果沒(méi)有 API，你大部分喜歡的軟件今天就不會(huì)存在。例如，Google Maps API 可以讓你在 app 或 Web 應(yīng)用中使用 Google Maps。如果沒(méi)有它，你將不得不設(shè)計(jì)和開(kāi)發(fā)自己的地圖數(shù)據(jù)庫(kù)。這樣的話，在地圖上顯示一個(gè)位置需要花費(fèi)多少時(shí)間？
-     為什么要使用 API？ -



為什么要使用 API？
  1. API 可以讓外部應(yīng)用訪問(wèn)您的資源
  2. API 擴(kuò)展了應(yīng)用程序的功能
  3. API 允許開(kāi)發(fā)者重用應(yīng)用邏輯
  4. API 是獨(dú)立于平臺(tái)的，它們傳遞數(shù)據(jù)不受請(qǐng)求平臺(tái)的影響

一文詳解?API?設(shè)計(jì)最佳實(shí)踐
在大多數(shù)實(shí)際場(chǎng)景中，數(shù)據(jù)模型 已經(jīng)存在，但由于我們將討論 API 設(shè)計(jì)最佳實(shí)踐，我將從頭開(kāi)始說(shuō)起。


-     數(shù)據(jù)建模與結(jié)構(gòu)化 -



以 API 為中心對(duì)您的數(shù)據(jù)進(jìn)行建模，是設(shè)計(jì)易于創(chuàng)建、維護(hù)和更新 API 的第一步
在設(shè)計(jì) API 時(shí)，盡量考慮使用通用的術(shù)語(yǔ)，而不是使用內(nèi)部的復(fù)雜業(yè)務(wù)術(shù)語(yǔ)，因?yàn)檫@些術(shù)語(yǔ)在公司外可能不為人所知。你的 API 可能會(huì)對(duì)外開(kāi)放，以允許外部開(kāi)發(fā)人員使用你的 API 開(kāi)發(fā)他們自己的應(yīng)用。通過(guò)使用通用術(shù)語(yǔ)，你可以確保使用 API 的開(kāi)發(fā)人員易于了解你的 API，并能快速上手。
假設(shè)到你正在建立一個(gè)門(mén)戶網(wǎng)站，讓用戶點(diǎn)評(píng)不同作者的書(shū)籍。你的公司可能會(huì)使用特定的術(shù)語(yǔ)，如創(chuàng)作者、創(chuàng)作、系列等來(lái)指代圖書(shū)作者、書(shū)籍和系列。但為了簡(jiǎn)單起見(jiàn)，并方便外部應(yīng)用開(kāi)發(fā)者使用你的 API，使用通用的概念而不是公司特定的術(shù)語(yǔ)來(lái)創(chuàng)建 API 路徑。
https://api.domain.com/authors https://api.domain.com/authors/{id}/books


這有助于新的開(kāi)發(fā)人員快速了解你的 API 是什么，以及如何遍歷你的數(shù)據(jù)模型。


-     編寫(xiě)面向資源的 API -



應(yīng)用程序需要訪問(wèn)你的資源。維護(hù)一個(gè)資源層次結(jié)構(gòu)可以幫助你更好地構(gòu)建 API。資源層次結(jié)構(gòu)是指路徑中的每個(gè)節(jié)點(diǎn)，它由一個(gè)集合或一個(gè)資源組成。
資源可以是一個(gè)單一的數(shù)據(jù)，例如，上面例子中的作者簡(jiǎn)介。
集合是指一個(gè)資源的集合，在我們的例子中，它可以是一個(gè)作者所寫(xiě)的書(shū)的列表。
合適的資源層次結(jié)構(gòu)可以是：
Base Path -> 作者 (集合) -> profile (資源)Base Path -> 作者 (集合) -> 書(shū) (集合) -> 書(shū) (資源)


層次結(jié)構(gòu)需要保持一致，以確保開(kāi)發(fā)人員在將其應(yīng)用程序接入 API 時(shí)遇到的問(wèn)題最少。

為了保持簡(jiǎn)單性和一致性，這里有一些指導(dǎo)原則可以幫助你：
  1. 命名集合和資源時(shí)使用美式英語(yǔ)（例如：color 而不是 colour）
  2. 避免拼寫(xiě)錯(cuò)誤
  3. 使用更簡(jiǎn)單、更常用的詞來(lái)保持清晰，例如 delete 而不是 remove
  4. 如果你使用的資源與其他 API 使用的資源相同，請(qǐng)使用相同的術(shù)語(yǔ)以保持一致。
  5. 對(duì)集合使用復(fù)數(shù)形式（例如：authors、books 等）。


-     RESTful 接口 -



HTTP 形式的 API 最廣泛接受的標(biāo)準(zhǔn)是 REST(Representational State Transfer)。它基本上意味著每個(gè) URL 代表一個(gè)對(duì)象。
API 目的可以是以下之一：
  1. 創(chuàng)建數(shù)據(jù) Create
  2. 讀取數(shù)據(jù) Read
  3. 更新數(shù)據(jù) Update
  4. 刪除數(shù)據(jù) Delete

CRUD！猜對(duì)了!
API 通過(guò)使用一組 HTTP 命令來(lái)處理，這些命令定義了請(qǐng)求的性質(zhì)和它應(yīng)該做什么。
GET 從 API 中檢索數(shù)據(jù)。它要求從 API 中獲取數(shù)據(jù)的表示。GET請(qǐng)求可以包含查詢參數(shù)，以過(guò)濾從API接收的結(jié)果。
POST 向 API 提交一條記錄，該記錄將在數(shù)據(jù)庫(kù)中創(chuàng)建一個(gè)資源。
PUT 一般用于更新服務(wù)器上的現(xiàn)有資源。
DELETE 從服務(wù)器上刪除一個(gè)資源。


-     API 版本控制 -



應(yīng)用程序和 API 的生命周期越長(zhǎng)，應(yīng)用和 API 對(duì)用戶的承諾就越大。在某個(gè)時(shí)間點(diǎn)上，你的 API 將需要修改，因?yàn)槟銦o(wú)法預(yù)見(jiàn)隨著需求和業(yè)務(wù)政策而發(fā)生的變化。
因此需要對(duì) API 進(jìn)行更改。但是 API 可能已經(jīng)有一個(gè)或多個(gè)開(kāi)發(fā)者在使用了，所以，重要的是，你所做的更改不會(huì)破壞你的合作伙伴開(kāi)發(fā)者的應(yīng)用。


-     了解主要和次要更新 -



小版本升級(jí)（Minor）：當(dāng)變更不會(huì)破壞客戶端應(yīng)用程序的運(yùn)行時(shí)，可以使用小版本升級(jí)，例如添加可選字段或支持附加參數(shù)。這時(shí)候你可以為你的 API 增設(shè)小版本。
大版本升級(jí)（Major）：是那些肯定會(huì)破壞現(xiàn)有客戶端應(yīng)用的版本，比如在請(qǐng)求參數(shù)中添加一個(gè)新的必需參數(shù)，或改變返回結(jié)果中的字段。
可以通過(guò)多種方式來(lái)對(duì) API 進(jìn)行版本控制。
最常見(jiàn)的方法是將版本包含在 URI 中。
https://api.domain.com/v1.0/authors


另外一種方法是使用基于日期的版本控制。URI 中包括將版本發(fā)布日期。應(yīng)用程序開(kāi)發(fā)人員可以很方便了解 API 更改的頻率。

https://api.domain.com/2020-06-15/authors


另一種方法是在請(qǐng)求標(biāo)頭中包含 API 版本。

https://api.domain.com/authors x-api-version：v1


最推薦和接受的版本控制方式是，在URI 中使用版本名稱。


-     分頁(yè) -



在數(shù)據(jù)量越來(lái)越大的世界里，不可能在一個(gè)屏幕上同時(shí)顯示所有的數(shù)據(jù)。所以，讓用戶在再次請(qǐng)求數(shù)據(jù)之前，先取到一定數(shù)量的結(jié)果，這一點(diǎn)很重要。這就是所謂的分頁(yè)，返回的數(shù)據(jù)集叫做頁(yè)面。
建議你在請(qǐng)求和返回結(jié)果中使用特定的術(shù)語(yǔ)來(lái)啟用 API 中的分頁(yè)功能。這些術(shù)語(yǔ)有
  1. STRING page_token（在請(qǐng)求中發(fā)送）
  2. STRING next_page_token（由 API 返回）
  3. INT page_size（在請(qǐng)求中發(fā)送）

page_token 請(qǐng)求 API 需要返回哪個(gè)頁(yè)面。這通常是一個(gè)字符串。對(duì)于第一次API調(diào)用，page_token = "1"
page_size 定義了返回結(jié)果中應(yīng)該返回多少條記錄。例如page_size = 100，在API調(diào)用中最多返回100條記錄。
next_page_token 定義了翻頁(yè)的下一個(gè) token。如果在page_token = "1" 之后有額外的數(shù)據(jù)，返回的值是應(yīng)當(dāng)是  next_page_token="2"
如果沒(méi)有更多的數(shù)據(jù)可用，而且用戶已經(jīng)到達(dá)數(shù)據(jù)的終點(diǎn)，則返回一個(gè)空白值 next_page_token="" 。
這些就是設(shè)計(jì) API 的最佳實(shí)踐。它讓你的 API 更健壯、簡(jiǎn)潔并易于與其他應(yīng)用程序集成。
請(qǐng)記住。
良好設(shè)計(jì)的API = 快樂(lè)的程序員 。



本站聲明： 本文章由作者或相關(guān)機(jī)構(gòu)授權(quán)發(fā)布，目的在于傳遞更多信息，并不代表本站贊同其觀點(diǎn)，本站亦不保證或承諾內(nèi)容真實(shí)性等。需要轉(zhuǎn)載請(qǐng)聯(lián)系該專欄作者，如若文章內(nèi)容侵犯您的權(quán)益，請(qǐng)及時(shí)聯(lián)系本站刪除。
換一批
延伸閱讀

9月2日消息，不造車的華為或?qū)⒋呱龈蟮莫?dú)角獸公司，隨著阿維塔和賽力斯的入局，華為引望愈發(fā)顯得引人矚目。

關(guān)鍵字： 阿維塔 塞力斯 華為

倫敦2024年8月29日 /美通社/ -- 英國(guó)汽車技術(shù)公司SODA.Auto推出其旗艦產(chǎn)品SODA V，這是全球首款涵蓋汽車工程師從創(chuàng)意到認(rèn)證的所有需求的工具，可用于創(chuàng)建軟件定義汽車。 SODA V工具的開(kāi)發(fā)耗時(shí)1.5...

關(guān)鍵字： 汽車 人工智能 智能驅(qū)動(dòng) BSP

北京2024年8月28日 /美通社/ -- 越來(lái)越多用戶希望企業(yè)業(yè)務(wù)能7×24不間斷運(yùn)行，同時(shí)企業(yè)卻面臨越來(lái)越多業(yè)務(wù)中斷的風(fēng)險(xiǎn)，如企業(yè)系統(tǒng)復(fù)雜性的增加，頻繁的功能更新和發(fā)布等。如何確保業(yè)務(wù)連續(xù)性，提升韌性，成...

關(guān)鍵字： 亞馬遜 解密 控制平面 BSP

8月30日消息，據(jù)媒體報(bào)道，騰訊和網(wǎng)易近期正在縮減他們對(duì)日本游戲市場(chǎng)的投資。

關(guān)鍵字： 騰訊 編碼器 CPU

8月28日消息，今天上午，2024中國(guó)國(guó)際大數(shù)據(jù)產(chǎn)業(yè)博覽會(huì)開(kāi)幕式在貴陽(yáng)舉行，華為董事、質(zhì)量流程IT總裁陶景文發(fā)表了演講。

關(guān)鍵字： 華為 12nm EDA 半導(dǎo)體

8月28日消息，在2024中國(guó)國(guó)際大數(shù)據(jù)產(chǎn)業(yè)博覽會(huì)上，華為常務(wù)董事、華為云CEO張平安發(fā)表演講稱，數(shù)字世界的話語(yǔ)權(quán)最終是由生態(tài)的繁榮決定的。

關(guān)鍵字： 華為 12nm 手機(jī) 衛(wèi)星通信

要點(diǎn)： 有效應(yīng)對(duì)環(huán)境變化，經(jīng)營(yíng)業(yè)績(jī)穩(wěn)中有升 落實(shí)提質(zhì)增效舉措，毛利潤(rùn)率延續(xù)升勢(shì) 戰(zhàn)略布局成效顯著，戰(zhàn)新業(yè)務(wù)引領(lǐng)增長(zhǎng) 以科技創(chuàng)新為引領(lǐng)，提升企業(yè)核心競(jìng)爭(zhēng)力 堅(jiān)持高質(zhì)量發(fā)展策略，塑強(qiáng)核心競(jìng)爭(zhēng)優(yōu)勢(shì)...

關(guān)鍵字： 通信 BSP 電信運(yùn)營(yíng)商 數(shù)字經(jīng)濟(jì)

北京2024年8月27日 /美通社/ -- 8月21日，由中央廣播電視總臺(tái)與中國(guó)電影電視技術(shù)學(xué)會(huì)聯(lián)合牽頭組建的NVI技術(shù)創(chuàng)新聯(lián)盟在BIRTV2024超高清全產(chǎn)業(yè)鏈發(fā)展研討會(huì)上宣布正式成立。 活動(dòng)現(xiàn)場(chǎng) NVI技術(shù)創(chuàng)新聯(lián)...

關(guān)鍵字： VI 傳輸協(xié)議 音頻 BSP

北京2024年8月27日 /美通社/ -- 在8月23日舉辦的2024年長(zhǎng)三角生態(tài)綠色一體化發(fā)展示范區(qū)聯(lián)合招商會(huì)上，軟通動(dòng)力信息技術(shù)（集團(tuán)）股份有限公司（以下簡(jiǎn)稱"軟通動(dòng)力"）與長(zhǎng)三角投資（上海）有限...

關(guān)鍵字： BSP 信息技術(shù)
關(guān)閉
關(guān)閉