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

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

本文旨在提供一套標準和最佳做法，協助您使用 Apigee Edge 進行開發。這裡涵蓋的主題包括設計、程式碼、政策使用、監控和偵錯。這些資訊是根據開發人員與 Apigee 合作實作成功 API 計畫的經驗彙整而成。這份文件會不時更新。

除了本文的指南，您或許也會覺得 Apigee Edge Antipatterns 社群貼文很有幫助。

開發標準

註解和文件

  • 在 ProxyEndpoint 和 TargetEndpoint 設定中提供內嵌註解。註解 可提高流程的可讀性，特別是當政策檔案名稱不夠清楚，無法表達流程的基礎功能時。
  • 請發布具參考價值的實用評論。避免使用明顯的註解。
  • 使用一致的縮排、間距、垂直對齊方式等。

架構樣式編碼

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

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

命名慣例

  • 「政策」name 屬性和 XML 政策檔案名稱必須相同。
  • Script 和 ServiceCallout 政策 name 屬性，以及資源檔案的名稱應完全相同。
  • DisplayName 應向從未處理過該 API Proxy 的使用者，如實說明政策功能。
  • 根據政策功能命名。Apigee 建議您為政策建立一致的命名慣例。 舉例來說，你可以使用簡短的前置字串，後面接上一連串以破折號分隔的描述性字詞。例如，AssignMessage 政策的 AM-xxx。 另請參閱 apigeelint 工具。
  • 資源檔案請使用適當的副檔名，JavaScript 檔案請使用 .js，Python 檔案請使用 .py，Java JAR 檔案請使用 .jar。
  • 變數名稱應保持一致。如果您選擇樣式 (例如 camelCase 或 under_score)，請在整個 API Proxy 中使用該樣式。
  • 盡可能使用變數前置字元，根據變數用途整理變數，例如 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 是在條件式 Route 清單中最後定義。ProxyEndpoint 會由上至下評估 RouteRule。
    請參閱 API Proxy 設定參考資料。
  • API Proxy 套件大小：API Proxy 套件不得超過 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 版本控管的看法和建議，請參閱網路 API 設計：缺少的環節電子書中的「版本控管」一節。

啟用 CORS

發布 API 前，您需要在 API Proxy 上啟用 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」標頭。如要對 API Proxy 執行 POST 作業，且酬載為空白，您必須傳遞 Content-Length 0。
  • 在 Edge for Private Cloud 4.16.01 以上版本中，請在 /opt/apigee/router.properties 或 message-processor.properties 中設定下列屬性，即可變更限制。詳情請參閱「在路由器或訊息處理器上設定訊息大小上限」。

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

錯誤處理

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

請參閱「處理故障」。

如需業界最佳做法，請參閱 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 組合時)，請使用 JavaScript。target.url
  • 複雜的酬載剖析作業，例如疊代 JSON 物件和 Base64 編碼/解碼。
  • JavaScript 政策設有時間限制，因此系統會封鎖無限迴圈。
  • 請一律使用 JavaScript 步驟，並將檔案放在 jsc 資源資料夾中。 JavaScript 政策類型會在部署時預先編譯程式碼。

請參閱「使用 JavaScript 程式設計 API 代理項目」。

Java

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

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

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 Proxy 資源資料夾。這樣可縮短部署時間，並允許多個 API Proxy 參照相同的 JAR 檔案。另一個好處是類別載入器隔離。
  • 請勿使用 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 查詢應用程式，而非應用程式名稱。

請參閱存取實體政策。

記錄

  • 在套件和同一套件內使用常見的系統記錄政策。這樣一來，記錄格式就會保持一致。

請參閱 MessageLogging 政策。

監控

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

Apigee Analytics

Analytics 可提供非重大 API 監控，因為系統會評估錯誤百分比。

請參閱「數據分析資訊主頁」。

追蹤記錄

API Edge 管理使用者介面中的追蹤工具，有助於在 API 的開發或生產作業期間，偵錯執行階段 API 問題。

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

安全性