[[405720]]

創(chuàng)建一個 API（應(yīng)用程序接口），我們所要做的遠(yuǎn)遠(yuǎn)不止是讓它能“正常工作”。

如果你正在構(gòu)建基于 C/S 模型的應(yīng)用程序，那么你需要一個應(yīng)用程序接口（API）。API 就是一種非常清晰而又明確的定義，它是一個進(jìn)程process與另一個進(jìn)程之間明確定義的邊界。Web 應(yīng)用中我們常見的邊界定義就是 REST/JSON API。

雖然很多開發(fā)者可能主要關(guān)注在如何讓 API 正常工作（或功能正常），但卻還有一些“非功能性”的要求也是需要他們注意的。所有的 API 必須具備 的 4 個非功能性的要求是：

• 安全
• 文檔
• 驗證
• 測試

安全

在軟件開發(fā)中，安全是最基本的要求。對于 API 開發(fā)者來說，API 的安全性主要包含以下 4 個方面：

1. HTTPS/SSL 證書
2. 跨域資源共享
3. 身份認(rèn)證與 JSON Web 令牌
4. 授權(quán)與作用域

1、HTTPS/SSL 證書

Web 應(yīng)用的黃金標(biāo)準(zhǔn)是使用 SSL 證書的 HTTPS 協(xié)議。Let's Encrypt 可以幫你達(dá)到這一目的。Let's Encrypt 來自于非營利性的互聯(lián)網(wǎng)安全研究小組（ISRG），它是一個免費的、自動化的、開放的證書頒發(fā)機(jī)構(gòu)。

Let's Encrypt 的軟件會為你的域（LCTT 譯注：包含域名、IP 等信息）生成中央授權(quán)證書。而正是這些證書確保了從你的 API 到客戶端的數(shù)據(jù)載荷是點對點加密的。

Let's Encrypt 支持證書管理的多種部署方案。我們可以通過查看 文檔 來找出最適合自己需要的方案。

2、跨域資源共享

跨域資源共享Cross-origin resource sharing（CORS）是一個針對瀏覽器的安全策略預(yù)檢。如果你的 API 服務(wù)器與發(fā)出請求的客戶端不在同一個域中，那么你就要處理 CORS。例如，如果你的服務(wù)器運行在 api.domain-a.com 并且接到一個來自 domain-b.com 的客戶端的請求，那么 CORS 就會（讓瀏覽器）發(fā)送一個 HTTP 預(yù)檢請求，以便查看你的 API 服務(wù)是否會接受來自此客戶域的客戶端請求。

來自 MDN 的定義：

“跨域資源共享（CORS）是一種基于 HTTP 頭的機(jī)制，這種機(jī)制允許服務(wù)器標(biāo)記除自身源外的其他任何來源（域、方案或端口）。而對于這些被服務(wù)器標(biāo)識的源，瀏覽器應(yīng)該允許我們從它們加載資源。”

(MDN文檔， CC-BY-SA 2.5)

另外，有很多用于 Node.js 的輔助庫來 幫助 API 開發(fā)者處理 CORS。

3、身份認(rèn)證與 JSON Web 令牌

有多種方法可以驗證你的 API 中的認(rèn)證用戶，但最好的方法之一是使用 JSON Web 令牌（JWT），而這些令牌使用各種知名的加密庫進(jìn)行簽名。

當(dāng)客戶端登錄時，身份管理服務(wù)會向客戶端提供一個 JWT。然后，客戶端可以使用這個令牌向 API 發(fā)出請求，API 收到請求后，從服務(wù)器讀取公鑰或私密信息來驗證這個令牌。

有一些現(xiàn)有的庫，可以幫助我們對令牌進(jìn)行驗證，包括 jsonwebtoken。關(guān)于 JWT 的更多信息，以及各種語言中對其的支持庫，請查看 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)證（或身份驗證）很重要，但授權(quán)同樣很重要。也就是說，經(jīng)過驗證的客戶端是否有權(quán)限讓服務(wù)器執(zhí)行某個請求呢？這就是作用域的價值所在。當(dāng)身份管理服務(wù)器對客戶端進(jìn)行身份認(rèn)證，且創(chuàng)建 JWT 令牌時，身份管理服務(wù)會給當(dāng)前客戶提供一個作用域，這個作用域?qū)Q定當(dāng)前經(jīng)過驗證的客戶的 API 請求能否被服務(wù)器執(zhí)行。這樣也就免去了服務(wù)器對訪問控制列表的一些不必要的查詢。

作用域是一個文本塊（通常以空格分隔），用于描述一個 API 端點的訪問能力。一般來說，作用域被分為資源與動作。這種模式對 REST/JSON API 很有效，因為它們有相似的 RESOURCE:ACTION 結(jié)構(gòu)。（例如，ARTICLE:WRITE 或 ARTICLE:READ，其中 ARTICLE 是資源，READ 和 WRITE 是動作）。

作用域的劃分讓我們的 API 能夠?qū)Ｗ⒂诠δ艿膶崿F(xiàn)，而不是去考慮各種角色和用戶。身份訪問管理服務(wù)可以將不同的角色和用戶分配不同的權(quán)限范圍，然后再將這些不同的作用域提供給不同的 JWT 驗證中的客戶。

總結(jié)

當(dāng)我們開發(fā)和部署 API 時，安全應(yīng)該一直是最重要的要求之一。雖然安全性是一個比較寬泛的話題，但如果能解決上面四個方面的問題，這對于你的 API 來說，在生產(chǎn)環(huán)境中將會表現(xiàn)得更好。

文檔

有什么能比沒有文檔更糟糕？過期的文檔。

開發(fā)者對文檔真的是又愛又恨。盡管如此，文檔仍然是 API 定義是否完善的一個關(guān)鍵部分。開發(fā)者需要從文檔中知道如何使用這些 API，且你創(chuàng)建的文檔對于開發(fā)者如何更好地使用 API 也有著非常巨大的作用。

創(chuàng)建 API 文檔，我們需要關(guān)注下面三個方面：

1. 開發(fā)者入門文檔（自述文件/基本介紹）
2. 技術(shù)參考（規(guī)范/說明書）
3. 使用方法（入門和其他指南）

1、入門文檔

在構(gòu)建 API 服務(wù)的時候，你需要明確一些事情，比如：這個 API 是做什么的？如何建立開發(fā)者環(huán)境？如何測試該服務(wù)？如何提交問題？如何部署它？

通常我們可以通過自述（README）文件來回答上面的這些問題，自述文件一般放在你的代碼庫中，用于為開發(fā)者提供使用你項目的最基本的起點和說明。

自述文件應(yīng)該包含：

• API 的描述
• 技術(shù)參考與指南的鏈接
• 如何以開發(fā)者的身份設(shè)置你的項目
• 如何測試這個項目
• 如何部署這個項目
• 依賴管理
• 代碼貢獻(xiàn)指南
• 行為準(zhǔn)則
• 許可證
• 致謝

你的自述文件應(yīng)該簡明扼要；你不必解釋每一個方面，但要提供足夠的信息，以便開發(fā)者在熟悉你的項目后可以進(jìn)一步深入研究。

2、技術(shù)參考

在 REST/JSON API 中, 每一個具體的端點endpoint都對應(yīng)一個特定的功能，都需要一個具體的說明文檔，這非常重要。文檔中會定義 API 的描述，輸入和可能的輸出，并為各種客戶端提供使用示例。

OpenAPI 是一個創(chuàng)建 REST/JSON 文檔的標(biāo)準(zhǔn), 它可以指導(dǎo)你完成編寫 API 文檔所需的各種細(xì)節(jié)。OpenAPI 還可以為你的 API 生成演示文檔。

3、使用方法

對于 API 的用戶來說，僅僅只有技術(shù)說明是不夠的。他們還需要知道如何在一些特定的情況和場景下來使用這些 API，而大多數(shù)的潛在用戶可能希望通過你的 API 來解決他們所遇到的問題。

向用戶介紹 API 的一個好的方法是利用一個“開始”頁面。“開始”頁面可以通過一個簡單的用例引導(dǎo)用戶，讓他們迅速了解你的 API 能給他們能帶來的益處。

總結(jié)

對于任何完善的 API，文檔都是一個很關(guān)鍵的組成部分。當(dāng)你在創(chuàng)建文檔時，你需要關(guān)注 API 文檔中的如何入門、技術(shù)參考以及如何快速開始等三個方面，這樣你的 API 才算是一個完善的 API。

驗證

API 開發(fā)過程中經(jīng)常被忽視的一個點就是驗證。它是一個驗證來自外部來源的輸入的過程。這些來源可以是客戶端發(fā)送過來的 JSON 數(shù)據(jù)，或者是你請求別人的服務(wù)收到的響應(yīng)數(shù)據(jù)。我們不僅僅要檢查這些數(shù)據(jù)的類型，還要確保這些數(shù)據(jù)確實是我們要的數(shù)據(jù)，這樣可以消除很多潛在的問題。了解你的邊界以及你能控制的和不能控制的東西，對于 API 的數(shù)據(jù)驗證來說是一個很重要的方面。

最好的策略是在進(jìn)入數(shù)據(jù)邏輯處理之前，在你能控制的邊界的邊緣處進(jìn)行數(shù)據(jù)的驗證。當(dāng)客戶端向你的 API 發(fā)送數(shù)據(jù)時，你需要對該數(shù)據(jù)做出任何處理之前應(yīng)用你的驗證，比如：確保 Email 是真實的郵件地址、日期數(shù)據(jù)有正確的格式、字符串符合長度要求。

這種簡單的檢查可以為你的應(yīng)用增加安全性和一致性。還有，當(dāng)你從某個服務(wù)接收數(shù)據(jù)時，比如數(shù)據(jù)庫或緩存，你需要重新驗證這些數(shù)據(jù)，以確保返回的結(jié)果符合你的數(shù)據(jù)檢查。

你可以自己手寫這些校驗邏輯，當(dāng)然也可以用像 Lodash 或 Ramda 這樣的函數(shù)庫，它們對于一些小的數(shù)據(jù)對象非常有用。像 Joi、Yup 或 Zod 這樣的驗證庫效果會更好，因為它們包含了一些常見的驗證方法，可以節(jié)省你的時間和精力。除此，它們還能創(chuàng)建一個可讀性強(qiáng)的模式。如果你需要看看與語言無關(guān)的東西，請看 JSON Schema。

總結(jié)

數(shù)據(jù)驗證雖然并不顯眼和突出（LCTT 譯注：跟 API 的功能實現(xiàn)以及其他幾個方面比），但它可以幫你節(jié)省大量的時間。如果不做驗證，這些時間將可能被用于故障排除和編寫數(shù)據(jù)遷移腳本。真的不要相信你的客戶端會發(fā)送干凈的數(shù)據(jù)給你，也不要讓驗證不通過的數(shù)據(jù)滲入到你的業(yè)務(wù)邏輯或持久數(shù)據(jù)存儲中去?；c時間驗證你的 API 收到的數(shù)據(jù)和請求到的響應(yīng)數(shù)據(jù)，雖然在前期你可能會感到一些挫折和不適，但這總比你在后期花大量時間去做各種數(shù)據(jù)收緊管制、故障排除等要容易得多。

測試

測試是軟件開發(fā)中的最佳實踐，它應(yīng)該是最主要的非功能性的要求。對于包括 API 在內(nèi)的任何項目，確定測試策略都是一個挑戰(zhàn)，因為你自始至終都要掌握各種約束，以便相應(yīng)的來制定你的測試策略。

集成測試Integration testing是測試 API 的最有效的方法之一。在集成測試模式中，開發(fā)團(tuán)隊會創(chuàng)建一個測試集用來覆蓋應(yīng)用流程中的某些部分，從一個點到另一個點。一個好的集成測試流程包括測試 API 的入口點以及模擬請求到服務(wù)端的響應(yīng)。搞定這兩點，你就覆蓋了整個邏輯，包括從 API 請求的開始到模擬服務(wù)器的響應(yīng)，并返回數(shù)據(jù)給 API。

雖然使用的是模擬，但這種方法讓能我們專注于代碼邏輯層，而不需要去依賴后端服務(wù)和展示邏輯來進(jìn)行測試。沒有依賴的測試會更加可靠、更容易實現(xiàn)自動化，且更容易被接入持續(xù)集成管道流。

集成測試的實施中，我會用 Tape、Test-server 和 Fetch-mock。這些庫讓我們能夠從 API 的請求到數(shù)據(jù)的響應(yīng)進(jìn)行隔離測試，使用 Fetch-mock 還可以將出站請求捕獲到持久層。

總結(jié)

雖然其他的各種測試和類型檢查對 API 也都有很好的益處，但集成測試在流程效率、構(gòu)建和管理時間方面卻有著更大的優(yōu)勢。使用 Fetch-mock 這樣的工具，可以在服務(wù)邊界提供一個干凈的模擬場景。

專注于基礎(chǔ)

不管是設(shè)計和構(gòu)建應(yīng)用程序還是 API，都要確保包含上面的四個基本要素。它們并不是我們唯一需要考慮的非功能性需求，其他的還包括應(yīng)用監(jiān)控、日志和 API 管理等。即便如此，安全、文檔、驗證和測試這四個基本點，對于構(gòu)建任何使用場景下的完善 API 都是至關(guān)重要的關(guān)注點。