設計及開發 API Proxy 的最佳做法

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本文旨在提供一套標準和最佳做法，協助您使用 Apigee Edge 進行開發。本課程涵蓋的主題包括設計、程式設計、政策使用、監控和偵錯。這些資訊是透過與 Apigee 合作的開發人員在導入成功 API 計畫時所累積的經驗所彙整而成。此文件會不斷修訂，與時俱進。

除了本指南外，您可能也會發現 Apigee Edge 反模式社群文章很實用。

開發標準

註解和文件

  • 在 ProxyEndpoint 和 TargetEndpoint 設定中提供內嵌註解。註解可提升流程的可讀性，尤其是在政策檔案名稱無法充分描述流程的基礎功能時。
  • 發布實用的評論。避免使用明顯的註解。
  • 使用一致的縮排、間距、垂直對齊等。

架構式程式碼

架構式程式碼會將 API 代理資源儲存在您自己的版本管控系統中，以便在各個本機開發環境中重複使用。舉例來說，如要重複使用政策，請將政策儲存在來源控管中，方便開發人員同步處理並在自己的 Proxy 開發環境中使用。

  • 為啟用 DRY (「不要重複自己」)，政策設定和指令碼應盡可能實作專屬的可重複使用函式。舉例來說，您可以呼叫 ExtractVariables.ExtractRequestParameters，以便從要求訊息中擷取查詢參數。用於插入 CORS 標頭的專屬政策可稱為 AssignMessage.SetCORSHeaders。這些政策隨後可儲存在您的來源控管系統中，並新增至需要擷取參數或設定 CORS 標頭的每個 API Proxy，而不需要您建立冗餘 (因此較難管理) 的設定。
  • 清除 API 代理程式中未使用的政策和資源 (JavaScript、Java、XSLT 等)，特別是可能會減緩匯入和部署程序的大型資源。

命名慣例

  • 政策 name 屬性和 XML 政策檔案名稱必須相同。
  • Script 和 ServiceCallout 政策 name 屬性和資源檔案的名稱應相同。
  • DisplayName 應向從未使用過該 API 代理程式的使用者，準確說明政策的功能。
  • 請根據政策的用途命名。Apigee 建議您為政策建立一致的命名慣例。例如，使用簡短的前置字串，後面接著一系列以破折號分隔的描述性字詞。例如，AssignMessage 政策的 AM-xxx。另請參閱 apigeelint 工具。
  • 請為資源檔案使用適當的副檔名，.js 適用於 JavaScript、.py 適用於 Python，而 .jar 適用於 Java JAR 檔案。
  • 變數名稱應保持一致。如果您選擇了 camelCase 或 under_score 等樣式，請在整個 API 代理程式中使用該樣式。
  • 盡可能使用變數前置字元，依據變數用途進行分類，例如 Consumer.username 和 Consumer.password。

API Proxy 開發

初步設計考量

  • 如需符合 REST 標準的 API 設計指南，請下載電子書《 Web API Design: The Missing Link》。
  • 盡可能利用 Apigee Edge 政策和功能建構 API Proxy。請勿在 JavaScript、Java 或 Python 資源中編寫所有 Proxy 邏輯。
  • 有條理地建構流程。建議使用多個流程 (每個流程各有一個條件)，而非在同一個預流程和後置流程中加入多個條件式附件。
  • 做為「安全防護機制」，請建立預設 API Proxy，其 ProxyEndpoint BasePath 為 /。這可用於將基本 API 要求重新導向至開發人員網站，以便傳回自訂回應，或執行比傳回預設 messaging.adaptors.http.flow.ApplicationNotFound 更實用的其他動作。
  • 使用 TargetServer 資源，將 TargetEndpoint 設定與具體網址分離，以便在各環境中進行宣傳。
    請參閱「跨後端伺服器負載平衡」。
  • 如果您有多個 RouteRule，請建立一個「預設」RouteRule，也就是沒有條件的 RouteRule。請確認預設 RouteRule 是在條件式路由清單的最後定義。ProxyEndpoint 會由上往下評估 RouteRules。
    請參閱 API Proxy 設定參考資料。
  • API 代理程式套件大小：API 代理程式套件的大小不得超過 15 MB。在 Apigee Edge for Private Cloud 中，您可以變更大小限制，方法是在下列位置修改 thrift_framed_transport_size_in_mb 屬性：cassandra.yaml (在 Cassandra 中) 和 conf/apigee/management-server/repository.properties。
  • API 版本管理：如要瞭解 Apigee 對 API 版本管理的想法和建議，請參閱《Web API Design: The Missing Link》電子書中的「版本管理」一節。

啟用 CORS

在發布 API 前，您必須在 API 代理程式上啟用 CORS，以便支援用戶端跨來源要求。

CORS (跨來源資源共享) 是一種標準機制，可讓您在網頁中執行 JavaScript XMLHttpRequest (XHR) 呼叫，以便與非來源網域的資源互動。CORS 是所有瀏覽器強制執行的同源政策常見的實作解決方案。舉例來說，如果您透過在瀏覽器中執行的 JavaScript 程式碼，對 Twitter API 發出 XHR 呼叫，該呼叫將會失敗。這是因為向瀏覽器提供網頁的網域與提供 Twitter API 的網域不同。CORS 為此問題提供解決方案，允許伺服器在需要提供跨來源資源共用功能時「選擇加入」。

如要瞭解如何在發布 API 前，在 API Proxy 中啟用 CORS，請參閱「為 API Proxy 新增 CORS 支援」。

郵件酬載大小

為避免 Edge 發生記憶體問題，訊息酬載大小上限為 10 MB。超過這些大小時，就會產生 protocol.http.TooBigBody 錯誤。

這篇 Apigee 社群文章也討論了這個問題。

以下是 Edge 處理大型訊息大小的建議策略：

  • 串流要求和回應。請注意，在您進行串流時，政策就無法再存取訊息內容。請參閱「串流要求和回應」。
  • 在 Edge for Private Cloud 4.15.07 以下版本中，請編輯訊息處理器 http.properties 檔案，以提高 HTTPResponse.body.buffer.limit 參數的限制。請務必先進行測試，再將變更部署至正式環境。
  • 在 Edge for Private Cloud 4.16.01 以上版本中，含有酬載的要求必須包含 Content-Length 標頭，如果是串流，則必須包含「Transfer-Encoding: chunked」標頭。如要將 POST 傳送至 API 代理程式，且酬載為空白，則必須傳遞 Content-Length 為 0 的值。
  • 在 Edge for Private Cloud 4.16.01 以上版本中，請在 /opt/apigee/router.properties 或 message-processor.properties 中設定下列屬性，以變更限制。詳情請參閱「在 Router 或 Message Processor 上設定郵件大小上限」。

    兩個屬性的預設值都是「10m」，對應於 10MB：
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

錯誤處理

  • 請利用 FaultRules 處理所有錯誤。(RaiseFault 政策用於停止訊息流程，並將處理作業傳送至 FaultRules 流程)。
  • 在 FaultRules 流程中，請使用 AssignMessage 政策建構錯誤回應，而非 RaiseFault 政策。根據發生的錯誤類型，有條件地執行 AssignMessage 政策。
  • 一律包含預設的「萬用」錯誤處理程序，以便將系統產生的錯誤對應至客戶定義的錯誤回應格式。
  • 盡可能讓錯誤回應符合貴公司或專案中可用的任何標準格式。
  • 使用有意義且人類可讀的錯誤訊息，建議錯誤情況的解決方案。

請參閱「處理錯誤」。

如需業界最佳做法，請參閱「RESTful 錯誤回應設計」。

持續性

鍵/值對應

  • 請只針對有限的資料集使用鍵/值對應。這些資料並非長期儲存資料的用途。
  • 使用鍵/值對應時，請考量效能，因為這類資訊會儲存在 Cassandra 資料庫中。

請參閱「鍵值對應作業政策」。

回應快取

  • 如果回應失敗，或要求不是 GET，請勿填入回應快取。請勿快取建立、更新和刪除作業。<SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • 使用單一一致的內容類型 (例如 XML 或 JSON) 填入快取。擷取 responseCache 項目後，請使用 JSONtoXML 或 XMLToJSON 轉換為所需的內容類型。這樣一來，系統就不會儲存兩組、三組或更多資料。
  • 請確認快取鍵符合快取需求。在許多情況下，request.querystring 可做為專屬 ID。
  • 除非明確要求，否則請勿在快取索引鍵中加入 API 金鑰 (client_id)。大多數情況下，僅透過金鑰加以保護的 API 會針對特定要求，向所有用戶端傳回相同的資料。根據 API 金鑰為多個項目儲存相同值的做法效率不高。
  • 設定適當的快取到期時間間隔，避免髒讀。
  • 盡可能讓回應快取政策在 ProxyEndpoint 回應 PostFlow 中盡可能晚執行，以便填入快取。也就是說，請在轉譯和中介服務步驟後執行，包括以 JavaScript 為基礎的中介服務，以及 JSON 和 XML 之間的轉換。快取經仲介的資料，可避免每次擷取快取資料時執行仲介步驟而產生的效能成本。

    請注意，如果中介服務導致每個請求的回應不同，您可能會想改為快取未經中介服務的資料。

  • 用於查詢快取項目的回應快取政策應在 ProxyEndpoint 要求的 PreFlow 中執行。在傳回快取項目之前，請避免實作太多邏輯 (除了快取鍵產生)。否則，快取的效益將降到最低。
  • 一般來說，您應盡可能讓回應快取查詢與用戶端要求保持一致。相反地，您應盡可能讓回應快取填入作業與用戶端回應保持一致。
  • 在 Proxy 中使用多個不同的回應快取政策時，請遵循下列指南，確保每個政策的行為皆不重複：
    • 根據互斥條件執行各項政策。這有助於確保只有一個回應快取政策執行。
    • 為每項回應快取政策定義不同的快取資源。您可以在政策的 <CacheResource> 元素中指定快取資源。

請參閱回應快取政策。

政策和自訂程式碼

政策或自訂程式碼？

  • 請盡可能優先使用內建政策。Apigee 政策經過強化、最佳化，並提供支援。舉例來說，請使用標準的 AssignMessage 和 ExtractVariables 政策，而非 JavaScript (盡可能) 來建立酬載、從酬載中擷取資訊 (XPath、JSONPath) 等。
  • 建議使用 JavaScript 而非 Python 和 Java。不過，如果效能是主要需求，建議您使用 Java 而非 JavaScript。

JavaScript

  • 如果 JavaScript 比 Apigee 政策更直覺 (例如為許多不同的 URI 組合設定 target.url)，請使用 JavaScript。
  • 複雜的酬載剖析作業，例如透過 JSON 物件和 Base64 編碼/解碼進行疊代。
  • JavaScript 政策設有時間限制，因此會封鎖無限迴圈。
  • 請一律使用 JavaScript 步驟，並將檔案放在 jsc 資源資料夾中。JavaScript 政策類型會在部署時預先編譯程式碼。

請參閱「使用 JavaScript 編寫 API 代理程式」。

Java

  • 如果效能是優先考量，或是邏輯無法在 JavaScript 中實作，請使用 Java。
  • 在原始碼追蹤中加入 Java 來源檔案。

如要瞭解如何在 API 代理程式中使用 Java，請參閱「使用 Java 說明文字將回應轉換為大寫」和「Java 說明文字政策」。

Python

  • 除非絕對必要，否則請勿使用 Python。Python 指令碼會在執行階段進行解譯，因此可能會導致簡單執行作業的效能瓶頸。

指令碼呼叫 (Java、JavaScript、Python)

  • 使用全域 try/catch 或等效方法。
  • 擲回有意義的例外狀況，並妥善擷取這些例外狀況，以便在錯誤回應中使用。
  • 提早擲回及擷取例外狀況。請勿使用全域 try/catch 來處理所有例外狀況。
  • 視需要執行空值和未定義的檢查。例如擷取選用的工作流程變數時。
  • 請勿在指派的程式碼中發出 HTTP/S 要求。請改用 Apigee ServiceCallout 政策，因為該政策可妥善處理連線。

JavaScript

  • API 平台上的 JavaScript 會透過 E4X 支援 XML。

請參閱「JavaScript 物件模型」。

Java

  • 存取訊息酬載時，請盡量使用 context.getMessage()，而非 context.getResponseMessage 或 context.getRequestMessage。這可確保程式碼能在要求和回應流程中擷取酬載。
  • 將程式庫匯入 Apigee Edge 機構或環境，且不要將這些程式庫納入 JAR 檔案。這麼做可縮減套件大小，並讓其他 JAR 檔案存取相同的程式庫存放區。
  • 請使用 Apigee 資源 API 匯入 JAR 檔案，而非將這些檔案納入 API 代理資源資料夾中。這麼做可縮短部署時間，並讓相同的 JAR 檔案可供多個 API 代理程式參照。另一個優點是類別載入器隔離。
  • 請勿使用 Java 處理資源 (例如建立及管理執行緒集區)。

請參閱「使用 Java 說明文字將回應轉換為大寫」。

Python

  • 擲回有意義的例外狀況，並妥善擷取這些例外狀況，以便在 Apigee 錯誤回應中使用

請參閱 Python 指令碼政策。

ServiceCallouts

  • 使用 Proxy 鏈結的有效用途有很多，例如在一個 API Proxy 中使用服務呼叫來呼叫另一個 API Proxy。如果您使用 Proxy 鏈結，請務必避免「無限迴圈」的遞迴呼叫回傳至相同的 API Proxy。

    如果您要連線至同一個機構和環境中的 Proxy，請務必參閱「將 API Proxy 連結在一起」一文，進一步瞭解如何實作本地連線，以避免不必要的網路開銷。

  • 使用 AssignMessage 政策建構 ServiceCallout 要求訊息，並在訊息變數中填入要求物件。(包括設定要求酬載、路徑和方法)。
  • 政策中設定的網址需要通訊協定規格，也就是說，網址的通訊協定部分 (例如 https://) 無法由變數指定。此外，您必須為網址的網域部分和其餘部分使用不同的變數。例如：https://{domain}/{path}
  • 請將 ServiceCallout 的回應物件儲存在個別訊息變數中。接著，您可以剖析訊息變數，並完整保留原始訊息酬載，供其他政策使用。

請參閱服務標示政策。

存取實體

AccessEntity 政策

  • 為提升成效，請使用 uuid 而非應用程式名稱來查詢應用程式。

請參閱「存取實體政策」。

記錄

  • 在各個套件和同一套件中使用通用的 syslog 政策。這樣就能維持一致的記錄格式。

請參閱訊息記錄政策。

監控

雲端客戶不需要檢查 Apigee Edge 的個別元件 (路由器、訊息處理器等)。根據客戶的健康狀態檢查要求，Apigee 的全球營運團隊會徹底監控所有元件，以及 API 健康狀態檢查。

Apigee Analytics

當 Analytics 評估錯誤百分比時，可以提供非重大的 API 監控功能。

請參閱「Google Analytics 資訊主頁」。

Trace

API Edge 管理 UI 中的追蹤工具可在 API 開發或實際運作期間，用於偵錯執行階段 API 問題。

請參閱「使用追蹤工具」。

安全性