[[333102]]

【51CTO.com快譯】本文將從SDK與文檔的使用，向后兼容性的保持，處置升級，有效地開展測試這五個方面，與您討論REST API設(shè)計的各項(xiàng)實(shí)踐。

毋庸置疑，API已成為了當(dāng)前在不同系統(tǒng)之間交換信息的實(shí)際標(biāo)準(zhǔn)。它往往能夠有助于更好地集成某個系統(tǒng)內(nèi)部各種組件。那么怎樣才能設(shè)計出更好的API呢?在本文中，我將和您討論在進(jìn)行多種REST API設(shè)計和實(shí)現(xiàn)時，那些值得遵循的良好實(shí)踐原則。

1.善用各種客戶端SDK，而無需自行編寫代碼

如果服務(wù)提供商或創(chuàng)建者已經(jīng)給出了一套開發(fā)工具包(SDK)，那么我們就應(yīng)該在API調(diào)用中使用它們，而無需在本機(jī)REST調(diào)用之上，去重新編寫自己的客戶端庫。此方面的一個最好例子便是與Amazon Web Services交互的AWS SDK。選擇使用AWS SDK，不但有助于減緩的團(tuán)隊(duì)學(xué)習(xí)曲線、快速上手，而且能夠節(jié)省編寫有關(guān)安全性、網(wǎng)絡(luò)超時、重試、回退等邏輯事務(wù)處理的時間。

此外，由于這些SDK由提供商所維護(hù)，因此開發(fā)人員無需進(jìn)行繁瑣的測試、修復(fù)和更改，即可支持各種新的API節(jié)點(diǎn)。如今，大多數(shù)SDK不但開源，并且能夠支持和快速集成包括REST、WebSocket、以及gRPC在內(nèi)的各種標(biāo)準(zhǔn)協(xié)議。

不過，API SDK的主要缺點(diǎn)是：可用性，以及對您所選編程語言的支持程度。針對此類狀況，開發(fā)人員有時需要開發(fā)自定義的REST客戶端。在此，我的經(jīng)驗(yàn)是：開發(fā)人員應(yīng)將其設(shè)計和實(shí)現(xiàn)作為一個單獨(dú)的Maven項(xiàng)目，托管到企業(yè)Git存儲庫中，并配上充分的文檔記錄，以供組織中的所有內(nèi)部團(tuán)隊(duì)共享使用。

2.巧用文檔

上文提到的配套文檔，不但對API開發(fā)人員，尤其是那些沒有任何開發(fā)背景的人員而言，是著手開發(fā)的基本要素，而且文檔往往也是絕大多數(shù)現(xiàn)代化開發(fā)框架的一個不可或缺的部分。作為開發(fā)人員的我，經(jīng)常可以根據(jù)現(xiàn)有的文檔，來輕松地執(zhí)行與API相關(guān)的各項(xiàng)測試，而不必臨時到浩如煙海的社區(qū)或論壇上，去搜索相關(guān)資料。通常，API的相關(guān)文檔能夠向使用者介紹API的基本功能、各種參數(shù)、以及預(yù)期的負(fù)載(payload)模型。

當(dāng)然，我在參與各種項(xiàng)目中也發(fā)現(xiàn)，有些文檔雖然包含了詳盡的內(nèi)容(包括負(fù)載模型的范例)，但是其中有些已經(jīng)滯后于API的當(dāng)前版本。因此，我在項(xiàng)目中往往會使用Swagger將文件的方法、參數(shù)和模型緊密地集成到服務(wù)器端的代碼之中，讓客戶端和文件系統(tǒng)的服務(wù)器以同樣的速度來更新與同步。

3.遵循標(biāo)準(zhǔn)的端點(diǎn)方法

在設(shè)計API時，許多開發(fā)人員不但容易忽略端點(diǎn)的標(biāo)準(zhǔn)命名法則，而且并未按照HTTP的各種動詞定義進(jìn)行操作。關(guān)于此方面的資料，網(wǎng)上有許多，只要你愿意花時間搜，一定能找到不少。下面，我分享一下自己一直嚴(yán)格遵守，同時也要求部門內(nèi)開發(fā)人員持續(xù)遵循的幾種方法：

• 不要在端點(diǎn)中混合使用大、小寫字母。例如：請將“/users/userId”更改為“/users/{id}”。請把POST“/deleteUser/userId”代替為DELETE“users/{id}”。
• 始終在URL中使用版本控制，例如：我會將“/api/v1/”作為URL的必要組成部分。
• 將“https”作為客戶端連接的默認(rèn)選項(xiàng)。
• 請將負(fù)載驗(yàn)證組件作為代碼處置的第一步。千萬不可將其留到后期處理，甚至是留給異常捕獲程序去處理。

4.處置升級

我曾經(jīng)遇到過這樣的一個案例：我們的某項(xiàng)服務(wù)一直使用著某個API來傳遞一些數(shù)據(jù)，但是某天它突然不工作了。在經(jīng)過了多輪電子郵件和電話會議的討論與研究后，我們最終才發(fā)現(xiàn)是因?yàn)樵揂PI的負(fù)載發(fā)生了變化--增加了一個必填字段。然而，我們在對該API的升級過程中，沒有考慮到向后兼容這個問題!

為了避免此類錯誤，我們應(yīng)當(dāng)使用現(xiàn)有的CI(持續(xù)集成)流程，以盡早地檢測出來。而作為一名API開發(fā)人員，您在更改目標(biāo)API的時候，應(yīng)該充分考慮現(xiàn)有的客戶端。例如：在請求的正文中，那些新的字段，是應(yīng)該使用默認(rèn)值呢?還是應(yīng)該定義一個諸如“/api/v2”之類的新版本端點(diǎn)?

5.測試

此處說所的測試，不只是功能性測試，也包括負(fù)載測試。您應(yīng)該能夠獲悉目標(biāo)服務(wù)器每分鐘通常可以處理多少個API調(diào)用，以及在網(wǎng)絡(luò)延遲增加時，響應(yīng)時間會產(chǎn)生何種變化。如今，更多的企業(yè)會在全球范圍內(nèi)部署不同規(guī)模的數(shù)據(jù)中心，或是采用多區(qū)域的云端環(huán)境。例如：我們有必要了解到，您在美國西部托管的API服務(wù)器，是否能夠給那些來自美國東部、歐洲、澳洲、甚至是亞洲的客戶端實(shí)例請求，提供足夠的帶寬和連接數(shù)。

就我的個人經(jīng)驗(yàn)而言，我更喜歡使用諸如：Postman或Apache JMeter之類的API測試工具，而不是從零開始編寫工具與用例。它們不僅能夠?yàn)槲夜?jié)省時間，還能夠方便我輕松地check-in到git，并且導(dǎo)出各種模板。

總結(jié)

上述五點(diǎn)經(jīng)驗(yàn)，便是我在實(shí)際項(xiàng)目中有關(guān)設(shè)計REST API的個人總結(jié)。希望它們能夠?yàn)槟腁PI開發(fā)，以及軟件工程的其他方面，帶來一些啟發(fā)，讓你少走一些彎路。

【原標(biāo)題】5 Tips for Better REST API Design

 作者: Preetdeep Kumar

【51CTO譯稿，合作站點(diǎn)轉(zhuǎn)載請注明原文譯者和出處為51CTO.com】