重新思考我們的 REST API：建立黃金 API

在某個時刻，每家公司都會到達一個十字路口，他們需要停下來重新評估他們一直在使用的工具。對我們來說，那一刻到來了，我們意識到為 Web 儀表板提供支援的 API 變得難以管理、難以測試，並且不符合我們為程式碼庫設定的標準。

Arcjet 主要是安全即程式碼 SDK，可協助開發人員實現機器人偵測、電子郵件驗證和 PII 偵測等安全功能。這與我們的高效能、低延遲決策 gRPC API 進行通訊。

我們的網頁儀表板使用單獨的REST API 主要用於管理網站連接和審查已處理的請求分析，但這也包括註冊新用戶和管理他們的帳戶，這意味著它仍然是產品的重要組成部分。

Arcjet 儀表板的請求分析頁面的螢幕截圖。

因此，我們決定接受從頭開始重建 API 的挑戰，這次將重點放在可維護性、效能和可擴充性。然而，我們不想開始一個巨大的重寫專案 - 永遠不會成功 - 相反，我們決定建立一個新的基礎，然後從單一 API 端點開始。

在這篇文章中，我將討論我們如何解決這個問題。

之前在 Arcjet 上

當速度是我們的首要任務時，Next.js 提供了最方便的解決方案來建立我們的前端可以使用的 API 端點。它為我們提供了在單一程式碼庫中進行無縫全端開發的能力，而且我們不必太擔心基礎設施，因為我們部署在 Vercel 上。

我們的重點是程式碼 SDK 的安全性和低延遲決策 API，因此對於前端儀表板，該堆疊使我們能夠輕鬆快速地製作功能原型。

我們的堆疊：Next.js、DrizzleORM、useSWR、NextAuth

然而，隨著我們產品的發展，我們發現將所有 API 端點和前端程式碼組合在同一個專案中會導致混亂。

測試我們的API 變得很麻煩（並且無論如何使用Next.js 都很難），並且我們需要一個能夠處理內部和外部消費。隨著我們與更多平台（如 Vercel、Fly.io 和 Netlify）集成，我們意識到僅靠開發速度是不夠的。我們需要一個更強大的解決方案。

作為此專案的一部分，我們還希望解決一個揮之不去的安全問題，即 Vercel 如何要求您公開公開資料庫。除非您為他們的企業「安全計算」付費，否則連接到遠端資料庫需要它具有公共端點。我們更喜歡鎖定我們的資料庫，以便只能透過專用網路存取它。縱深防禦很重要，這將是另一層保護。

這導致我們決定將前端 UI 與後端 API 分開。

介紹“黃金 API”

什麼是「黃金 API」？它不是特定的技術或框架，而是定義建構良好的 API 的一組理想原則。雖然開發人員可能對語言和框架有自己的偏好，但在建立高品質 API 時，大多數人都同意某些跨技術堆疊有效的概念。

1. 效能和可擴充性

我們已經擁有交付高效能 API 的經驗。 我們的 Decision API 部署在靠近客戶的位置，使用 Kubernetes 進行動態擴展，並針對低延遲響應進行了優化.

我們考慮了無伺服器環境和其他供應商，但由於我們現有的k8s 叢集已經在運行，因此重用現有的基礎設施是最有意義的：透過Octopus Deploy 進行部署，透過Grafana Jaeger、Loki 、Prometheus 等進行監控

經過短暫的內部Rust 與Go 對比後，我們選擇了Go，因為它的簡單性、速度以及它實現其最初目標 對構建可擴展網絡服務的出色支援的效果。我們也已經將它用於 Decision API 並了解如何操作 Go API，這為我們最終確定了決策。

2. 全面、清晰的文檔

由於 Go 的簡單性和強大工具的可用性，將後端 API 切換到 Go 非常簡單。但有一個問題：我們保留了 Next.js 前端，並且不想手動編寫 TypeScript 類型或為我們的新 API 維護單獨的文件。

引入 OpenAPI——它非常適合我們的需求。 OpenAPI 允許我們定義前端和後端之間的契約，同時也充當我們的文件。這解決了維護應用程式兩側架構的問題。

3. 安全與認證

在 Go 中整合身分驗證並不太困難，這要歸功於 NextAuth 在後端的模仿相對簡單。 NextAuth（現在的 Auth.js）具有可用於驗證會話的 API。

這意味著我們可以在前端有一個根據 OpenAPI 規範產生的 TypeScript 用戶端，對後端 API 進行提取呼叫。憑證會自動包含在取得呼叫中，後端可以使用 NextAuth 驗證會話。

4. 可測試性

在 Go 中編寫任何類型的測試都非常簡單，並且有很多範例，涵蓋了測試 HTTP 處理程序的主題。

與 Next.js API 相比，為新的 Go API 端點編寫測試也容易得多，特別是因為我們想要測試經過身份驗證的狀態和真實的資料庫呼叫。我們能夠輕鬆地為 Gin 路由器 編寫測試，並使用 Testcontainers 針對我們的 Postgres 資料庫啟動真正的整合測試。

把它們放在一起

編寫 OpenAPI 規範

我們先為我們的 API 寫 OpenAPI 3.0 規格。 OpenAPI 優先的方法提倡在實施之前設計 API 契約，確保所有利害關係人（開發人員、產品經理和客戶）在編寫任何程式碼之前就 API 的行為和結構達成一致。它鼓勵仔細規劃並產生經過深思熟慮的 API 設計，該設計是一致的並遵守既定的最佳實踐。這就是為什麼我們選擇先編寫規範並從中產生程式碼，而不是相反的原因。

我選擇的工具是API Fiddle，它可以幫助您快速起草和測試 OpenAPI 規格。然而，API Fiddle 僅支援 OpenAPI 3.1（我們無法使用它，因為許多程式庫尚未採用它），因此我們堅持使用 3.0 版本並手動編寫規格。

以下是我們 API 規格的範例：

OpenAPI 規格就位後，我們使用了 OAPI-codegen，這是一個根據 OpenAPI 規格自動產生 Go 程式碼的工具。它產生所有必要的類型、處理程序和錯誤處理結構，使開發過程更加順利。

輸出是一組 Go 文件，一個包含伺服器框架，另一個包含處理程序實作。以下是為 Site 物件產生的 Go 類型的範例：

使用產生的程式碼，我們能夠實作 API 處理程序邏輯，如下所示：

資料庫：遠離 DrizzleORM

Drizzle 對於 JS 專案來說是一個很棒的 ORM，我們會再次使用它，但是將資料庫程式碼移出 Next.js 意味著我們需要類似的 Go 程式碼。

我們選擇 GORM 作為我們的 ORM，並使用 儲存庫模式 來抽象資料庫互動。這使我們能夠編寫乾淨、可測試的資料庫查詢。

測試。一切

測試對我們來說至關重要。我們希望確保所有資料庫呼叫都得到正確測試，因此我們使用 Testcontainers 為我們的測試啟動一個真實的資料庫，密切反映我們的生產設定。

設定測試環境後，我們像在生產中一樣測試了所有 CRUD 操作，確保我們的程式碼行為正確。

為了測試我們的 API 處理程序，我們使用了 Go 的 httptest 套件並使用 Mockery 模擬了資料庫互動。這使我們能夠專注於測試 API 邏輯，而不必擔心資料庫問題。

前端消耗：OpenAPI 驅動的前端

我們的 API 經過測試和部署後，我們就把注意力轉向了前端。

我們之前的 API 呼叫是使用 Next.js 推薦的 fetch API 進行的，內建快取。對於更多動態視圖，一些元件在 fetch 之上使用 SWR，因此我們可以獲得類型安全、自動重新載入資料獲取呼叫。

為了在前端使用 API，我們使用了 openapi-typescript 函式庫，它根據我們的 OpenAPI 架構產生 TypeScript 類型。這使得我們可以輕鬆地將後端與前端集成，而無需手動同步資料模型。它內建了 Tanstack Query，它在底層使用 fetch，但也同步到我們的架構。

我們正在逐步將 API 端點遷移到新的 Go 伺服器，並在過程中進行一些小的改進。如果您開啟瀏覽器檢查器，您將看到這些新請求發送至 api.arcjet.com

瀏覽器檢查器螢幕截圖，顯示對新 Go 後端的 API 呼叫。

黃金清單

那麼，我們實作了難以捉摸的 Golden API 了嗎？讓我們選中該框：

• ✅ 效能和可擴充性 – API 部署在我們現有的 k8s 叢集上，這些叢集已經針對效能進行了調整。我們有詳細的指標，並可根據需要進行擴展。
• ✅ 全面且清晰的文件 – OpenAPI 規範提供了單一的事實來源，因為程式碼是從它產生的，而不是相反。使用產生的客戶端意味著我們的團隊可以輕鬆使用 API。
• ✅ 安全性和身份驗證 – 我們已經在生產中部署了 Go，因此我們可以複製我們的安全實踐。身份驗證由 NextAuth 處理。
• ✅ 可測試性 – 我們使用 Testcontainers 實現了處理程序的單元測試和整合測試，這是對我們的 Next.js API 的重大改進。

我們更進一步：

• ✅ 監控 – 部署到現有的 k8s 叢集意味著我們繼承了已經設定的追蹤、日誌記錄和指標功能。在 Gin 上加入 OpenTelemetry 儀器非常簡單。
• ✅ 簡單性 – Go 最初是為 API 設計的，這一點也體現出來了。我們的程式碼更乾淨、更易於維護。

最後，我們對結果感到滿意。我們的 API 更快、更安全且經過更好的測試。向 Go 的過渡是值得的，隨著我們產品的成長，我們現在可以更好地擴展和維護我們的 API。

以上是重新思考我們的 REST API：建立黃金 API的詳細內容。更多資訊請關注PHP中文網其他相關文章！