創(chuàng)建一個(gè) API（應(yīng)用程序接口），我們所要做的遠(yuǎn)遠(yuǎn)不止是讓它能“正常工作”。
如果你正在構(gòu)建基于 C/S 模型的應(yīng)用程序，那么你需要一個(gè)應(yīng)用程序接口（API）。API 就是一種非常清晰而又明確的定義，它是一個(gè)進(jìn)程process與另一個(gè)進(jìn)程之間明確定義的邊界。Web 應(yīng)用中我們常見的邊界定義就是 REST/JSON API。
雖然很多開發(fā)者可能主要關(guān)注在如何讓 API 正常工作（或功能正常），但卻還有一些“非功能性”的要求也是需要他們注意的。所有的 API 必須具備的 4 個(gè)非功能性的要求是：
- 安全
- 文檔
- 驗(yàn)證
- 測(cè)試
安全
在軟件開發(fā)中，安全是最基本的要求。對(duì)于 API 開發(fā)者來說，API 的安全性主要包含以下 4 個(gè)方面：
- HTTPS/SSL 證書
- 跨域資源共享
- 身份認(rèn)證與 JSON Web 令牌
- 授權(quán)與作用域
1、HTTPS/SSL 證書
Web 應(yīng)用的黃金標(biāo)準(zhǔn)是使用 SSL 證書的 HTTPS 協(xié)議。Let's Encrypt可以幫你達(dá)到這一目的。Let's Encrypt 來自于非營(yíng)利性的互聯(lián)網(wǎng)安全研究小組（ISRG），它是一個(gè)免費(fèi)的、自動(dòng)化的、開放的證書頒發(fā)機(jī)構(gòu)。
Let's Encrypt 的軟件會(huì)為你的域（LCTT 譯注：包含域名、IP 等信息）生成中央授權(quán)證書。而正是這些證書確保了從你的 API 到客戶端的數(shù)據(jù)載荷是點(diǎn)對(duì)點(diǎn)加密的。
Let's Encrypt 支持證書管理的多種部署方案。我們可以通過查看 文檔來找出最適合自己需要的方案。
2、跨域資源共享
跨域資源共享Cross-origin resource sharing（CORS）是一個(gè)針對(duì)瀏覽器的安全策略預(yù)檢。如果你的 API 服務(wù)器與發(fā)出請(qǐng)求的客戶端不在同一個(gè)域中，那么你就要處理 CORS。例如，如果你的服務(wù)器運(yùn)行在 api.domain-a.com并且接到一個(gè)來自domain-b.com的客戶端的請(qǐng)求，那么 CORS 就會(huì)（讓瀏覽器）發(fā)送一個(gè) HTTP 預(yù)檢請(qǐng)求，以便查看你的 API 服務(wù)是否會(huì)接受來自此客戶域的客戶端請(qǐng)求。
來自 MDN 的定義：
“跨域資源共享（CORS）是一種基于 HTTP 頭的機(jī)制，這種機(jī)制允許服務(wù)器標(biāo)記除自身源外的其他任何來源（域、方案或端口）。而對(duì)于這些被服務(wù)器標(biāo)識(shí)的源，瀏覽器應(yīng)該允許我們從它們加載資源。”
(MDN文檔，CC-BY-SA 2.5)
另外，有很多用于 Node.js的輔助庫來幫助 API 開發(fā)者處理 CORS。
3、身份認(rèn)證與 JSON Web 令牌
有多種方法可以驗(yàn)證你的 API 中的認(rèn)證用戶，但最好的方法之一是使用 JSON Web 令牌（JWT），而這些令牌使用各種知名的加密庫進(jìn)行簽名。
當(dāng)客戶端登錄時(shí)，身份管理服務(wù)會(huì)向客戶端提供一個(gè) JWT。然后，客戶端可以使用這個(gè)令牌向 API 發(fā)出請(qǐng)求，API 收到請(qǐng)求后，從服務(wù)器讀取公鑰或私密信息來驗(yàn)證這個(gè)令牌。
有一些現(xiàn)有的庫，可以幫助我們對(duì)令牌進(jìn)行驗(yàn)證，包括 jsonwebtoken。關(guān)于 JWT 的更多信息，以及各種語言中對(duì)其的支持庫，請(qǐng)查看JWT.io。
import jwt from 'jsonwebtoken'
export default function (req, res, next) {
// req.headers.authorization Bearer token
const token = extractToken(req)
jwt.verify(token, SECRET, { algorithms: ['HS256'] }, (err, decoded) => {
if (err) { next(err) }
req.session = decoded
next
})
}
4、授權(quán)與作用域
認(rèn)證（或身份驗(yàn)證）很重要，但授權(quán)同樣很重要。也就是說，經(jīng)過驗(yàn)證的客戶端是否有權(quán)限讓服務(wù)器執(zhí)行某個(gè)請(qǐng)求呢？這就是作用域的價(jià)值所在。當(dāng)身份管理服務(wù)器對(duì)客戶端進(jìn)行身份認(rèn)證，且創(chuàng)建 JWT 令牌時(shí)，身份管理服務(wù)會(huì)給當(dāng)前客戶提供一個(gè)作用域，這個(gè)作用域?qū)?huì)決定當(dāng)前經(jīng)過驗(yàn)證的客戶的 API 請(qǐng)求能否被服務(wù)器執(zhí)行。這樣也就免去了服務(wù)器對(duì)訪問控制列表的一些不必要的查詢。
作用域是一個(gè)文本塊（通常以空格分隔），用于描述一個(gè) API 端點(diǎn)的訪問能力。一般來說，作用域被分為資源與動(dòng)作。這種模式對(duì) REST/JSON API 很有效，因?yàn)樗鼈冇邢嗨频?nbsp;RESOURCE:ACTION結(jié)構(gòu)。（例如，ARTICLE:WRITE或ARTICLE:READ，其中ARTICLE是資源，READ和WRITE是動(dòng)作）。
作用域的劃分讓我們的 API 能夠?qū)Ｗ⒂诠δ艿膶?shí)現(xiàn)，而不是去考慮各種角色和用戶。身份訪問管理服務(wù)可以將不同的角色和用戶分配不同的權(quán)限范圍，然后再將這些不同的作用域提供給不同的 JWT 驗(yàn)證中的客戶。
總結(jié)
當(dāng)我們開發(fā)和部署 API 時(shí)，安全應(yīng)該一直是最重要的要求之一。雖然安全性是一個(gè)比較寬泛的話題，但如果能解決上面四個(gè)方面的問題，這對(duì)于你的 API 來說，在生產(chǎn)環(huán)境中將會(huì)表現(xiàn)得更好。
文檔
有什么能比沒有文檔更糟糕？過期的文檔。
開發(fā)者對(duì)文檔真的是又愛又恨。盡管如此，文檔仍然是 API 定義是否完善的一個(gè)關(guān)鍵部分。開發(fā)者需要從文檔中知道如何使用這些 API，且你創(chuàng)建的文檔對(duì)于開發(fā)者如何更好地使用 API 也有著非常巨大的作用。
創(chuàng)建 API 文檔，我們需要關(guān)注下面三個(gè)方面：
- 開發(fā)者入門文檔（自述文件/基本介紹）
- 技術(shù)參考（規(guī)范/說明書）
- 使用方法（入門和其他指南）
1、入門文檔
在構(gòu)建 API 服務(wù)的時(shí)候，你需要明確一些事情，比如：這個(gè) API 是做什么的？如何建立開發(fā)者環(huán)境？如何測(cè)試該服務(wù)？如何提交問題？如何部署它？
通常我們可以通過自述（README）文件來回答上面的這些問題，自述文件一般放在你的代碼庫中，用于為開發(fā)者提供使用你項(xiàng)目的最基本的起點(diǎn)和說明。
自述文件應(yīng)該包含：
- API 的描述
- 技術(shù)參考與指南的鏈接
- 如何以開發(fā)者的身份設(shè)置你的項(xiàng)目
- 如何測(cè)試這個(gè)項(xiàng)目
- 如何部署這個(gè)項(xiàng)目
- 依賴管理
- 代碼貢獻(xiàn)指南
- 行為準(zhǔn)則
- 許可證
- 致謝
你的自述文件應(yīng)該簡(jiǎn)明扼要；你不必解釋每一個(gè)方面，但要提供足夠的信息，以便開發(fā)者在熟悉你的項(xiàng)目后可以進(jìn)一步深入研究。
2、技術(shù)參考
在 REST/JSON API 中, 每一個(gè)具體的端點(diǎn)endpoint都對(duì)應(yīng)一個(gè)特定的功能，都需要一個(gè)具體的說明文檔，這非常重要。文檔中會(huì)定義 API 的描述，輸入和可能的輸出，并為各種客戶端提供使用示例。
OpenAPI是一個(gè)創(chuàng)建 REST/JSON 文檔的標(biāo)準(zhǔn), 它可以指導(dǎo)你完成編寫 API 文檔所需的各種細(xì)節(jié)。OpenAPI 還可以為你的 API 生成演示文檔。
3、使用方法
對(duì)于 API 的用戶來說，僅僅只有技術(shù)說明是不夠的。他們還需要知道如何在一些特定的情況和場(chǎng)景下來使用這些 API，而大多數(shù)的潛在用戶可能希望通過你的 API 來解決他們所遇到的問題。
向用戶介紹 API 的一個(gè)好的方法是利用一個(gè)“開始”頁面。“開始”頁面可以通過一個(gè)簡(jiǎn)單的用例引導(dǎo)用戶，讓他們迅速了解你的 API 能給他們能帶來的益處。
總結(jié)
對(duì)于任何完善的 API，文檔都是一個(gè)很關(guān)鍵的組成部分。當(dāng)你在創(chuàng)建文檔時(shí)，你需要關(guān)注 API 文檔中的如何入門、技術(shù)參考以及如何快速開始等三個(gè)方面，這樣你的 API 才算是一個(gè)完善的 API。
驗(yàn)證
API 開發(fā)過程中經(jīng)常被忽視的一個(gè)點(diǎn)就是驗(yàn)證。它是一個(gè)驗(yàn)證來自外部來源的輸入的過程。這些來源可以是客戶端發(fā)送過來的 JSON 數(shù)據(jù)，或者是你請(qǐng)求別人的服務(wù)收到的響應(yīng)數(shù)據(jù)。我們不僅僅要檢查這些數(shù)據(jù)的類型，還要確保這些數(shù)據(jù)確實(shí)是我們要的數(shù)據(jù)，這樣可以消除很多潛在的問題。了解你的邊界以及你能控制的和不能控制的東西，對(duì)于 API 的數(shù)據(jù)驗(yàn)證來說是一個(gè)很重要的方面。
最好的策略是在進(jìn)入數(shù)據(jù)邏輯處理之前，在你能控制的邊界的邊緣處進(jìn)行數(shù)據(jù)的驗(yàn)證。當(dāng)客戶端向你的 API 發(fā)送數(shù)據(jù)時(shí)，你需要對(duì)該數(shù)據(jù)做出任何處理之前應(yīng)用你的驗(yàn)證，比如：確保 Email 是真實(shí)的郵件地址、日期數(shù)據(jù)有正確的格式、字符串符合長(zhǎng)度要求。
這種簡(jiǎn)單的檢查可以為你的應(yīng)用增加安全性和一致性。還有，當(dāng)你從某個(gè)服務(wù)接收數(shù)據(jù)時(shí)，比如數(shù)據(jù)庫或緩存，你需要重新驗(yàn)證這些數(shù)據(jù)，以確保返回的結(jié)果符合你的數(shù)據(jù)檢查。
你可以自己手寫這些校驗(yàn)邏輯，當(dāng)然也可以用像 Lodash或Ramda這樣的函數(shù)庫，它們對(duì)于一些小的數(shù)據(jù)對(duì)象非常有用。像Joi、Yup或Zod這樣的驗(yàn)證庫效果會(huì)更好，因?yàn)樗鼈儼艘恍┏Ｒ姷尿?yàn)證方法，可以節(jié)省你的時(shí)間和精力。除此，它們還能創(chuàng)建一個(gè)可讀性強(qiáng)的模式。如果你需要看看與語言無關(guān)的東西，請(qǐng)看JSON Schema。
總結(jié)
數(shù)據(jù)驗(yàn)證雖然并不顯眼和突出（LCTT 譯注：跟 API 的功能實(shí)現(xiàn)以及其他幾個(gè)方面比），但它可以幫你節(jié)省大量的時(shí)間。如果不做驗(yàn)證，這些時(shí)間將可能被用于故障排除和編寫數(shù)據(jù)遷移腳本。真的不要相信你的客戶端會(huì)發(fā)送干凈的數(shù)據(jù)給你，也不要讓驗(yàn)證不通過的數(shù)據(jù)滲入到你的業(yè)務(wù)邏輯或持久數(shù)據(jù)存儲(chǔ)中去?；c(diǎn)時(shí)間驗(yàn)證你的 API 收到的數(shù)據(jù)和請(qǐng)求到的響應(yīng)數(shù)據(jù)，雖然在前期你可能會(huì)感到一些挫折和不適，但這總比你在后期花大量時(shí)間去做各種數(shù)據(jù)收緊管制、故障排除等要容易得多。
測(cè)試
測(cè)試是軟件開發(fā)中的最佳實(shí)踐，它應(yīng)該是最主要的非功能性的要求。對(duì)于包括 API 在內(nèi)的任何項(xiàng)目，確定測(cè)試策略都是一個(gè)挑戰(zhàn)，因?yàn)槟阕允贾两K都要掌握各種約束，以便相應(yīng)的來制定你的測(cè)試策略。
集成測(cè)試Integration testing是測(cè)試 API 的最有效的方法之一。在集成測(cè)試模式中，開發(fā)團(tuán)隊(duì)會(huì)創(chuàng)建一個(gè)測(cè)試集用來覆蓋應(yīng)用流程中的某些部分，從一個(gè)點(diǎn)到另一個(gè)點(diǎn)。一個(gè)好的集成測(cè)試流程包括測(cè)試 API 的入口點(diǎn)以及模擬請(qǐng)求到服務(wù)端的響應(yīng)。搞定這兩點(diǎn)，你就覆蓋了整個(gè)邏輯，包括從 API 請(qǐng)求的開始到模擬服務(wù)器的響應(yīng)，并返回?cái)?shù)據(jù)給 API。
雖然使用的是模擬，但這種方法讓能我們專注于代碼邏輯層，而不需要去依賴后端服務(wù)和展示邏輯來進(jìn)行測(cè)試。沒有依賴的測(cè)試會(huì)更加可靠、更容易實(shí)現(xiàn)自動(dòng)化，且更容易被接入持續(xù)集成管道流。
集成測(cè)試的實(shí)施中，我會(huì)用 Tape、Test-server和Fetch-mock。這些庫讓我們能夠從 API 的請(qǐng)求到數(shù)據(jù)的響應(yīng)進(jìn)行隔離測(cè)試，使用 Fetch-mock 還可以將出站請(qǐng)求捕獲到持久層。
總結(jié)
雖然其他的各種測(cè)試和類型檢查對(duì) API 也都有很好的益處，但集成測(cè)試在流程效率、構(gòu)建和管理時(shí)間方面卻有著更大的優(yōu)勢(shì)。使用 Fetch-mock 這樣的工具，可以在服務(wù)邊界提供一個(gè)干凈的模擬場(chǎng)景。
專注于基礎(chǔ)
不管是設(shè)計(jì)和構(gòu)建應(yīng)用程序還是 API，都要確保包含上面的四個(gè)基本要素。它們并不是我們唯一需要考慮的非功能性需求，其他的還包括應(yīng)用監(jiān)控、日志和 API 管理等。即便如此，安全、文檔、驗(yàn)證和測(cè)試這四個(gè)基本點(diǎn)，對(duì)于構(gòu)建任何使用場(chǎng)景下的完善 API 都是至關(guān)重要的關(guān)注點(diǎn)。
via: https://opensource.com/article/21/5/successful-apis
作者：Tom Wilson選題：lujun9972譯者：ywxgod校對(duì)：wxy
本文由 LCTT原創(chuàng)編譯，linux中國(guó)榮譽(yù)推出
