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

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

本文件旨在提供一組標準和最佳做法，協助您透過 Apigee Edge 進行開發。說明的主題包括設計、程式設計、政策使用方式、監控和偵錯。我們收集到開發人員與 Apigee 合作，成功執行 API 計畫的經驗而收集到的資訊。這份文件會持續更新，而且不時更新。

除了這裡的規範之外，您也可以參閱 Apigee Edge 反模式社群貼文，

開發標準

註解與說明文件

  • 在 ProxyEndpoint 和 TargetEndpoint 設定中提供內嵌註解。註解可提高資料流的可讀性，尤其當政策檔案名稱不足以說明資料流的基礎功能時，更是如此。
  • 提供實用的評論。避免顯而易見的留言。
  • 使用一致的縮排、間距、垂直對齊等。

架構式程式設計

架構式編碼是指將 API Proxy 資源儲存在您自己的版本管控系統中，以便在本機開發環境之間重複使用。舉例來說，如要重複使用政策，請將政策儲存在原始碼控制系統，讓開發人員能夠同步至該政策，並在自己的 Proxy 開發環境中使用。

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

命名慣例

  • 政策 name 屬性與 XML 政策檔案名稱必須相同。
  • 指令碼和 Service callout 政策 name 屬性和資源檔案名稱必須相同。
  • DisplayName 應向從未與該 API Proxy 合作的使用者準確描述政策功能。
  • 根據函式命名政策。Apigee 建議您為政策建立一致的命名慣例。舉例來說，您可以使用簡短的前置字元，後面加上一連串以連字號分隔的描述性字詞。例如 AM-xxx 適用於 AssignMessage 政策。另請參閱 apigeelint 工具。
  • 為資源檔案使用適當的副檔名，JavaScript 使用 .js，Python 請使用 .py，Java JAR 檔案則使用 .jar。
  • 變數名稱應一致。如果您選擇的樣式 (例如駝峰式大小寫或底線)，請在整個 API Proxy 中使用該樣式。
  • 盡可能使用變數前置字串，以便根據用途整理變數，例如 Consumer.username 和 Consumer.password。

API Proxy 開發

初步設計注意事項

  • 如需符合 REST 樣式的 API 設計指南，請下載電子書《 Web API Design: The Missing Link》。
  • 盡可能運用 Apigee Edge 政策和功能建構 API Proxy。避免在 JavaScript、Java 或 Python 資源中編寫所有 Proxy 邏輯。
  • 以有條理的方式建構流程。多個流程 (每項都有單一條件) 更適合與同一個 PreFlow 和 Postflow 的多個條件連結。
  • 設為「failsafe」，並將 ProxyEndpoint BasePath 設為 / 來建立預設的 API Proxy。這可用來將基本 API 要求重新導向至開發人員網站、傳回自訂回應，或是執行比傳回預設 messaging.adaptors.http.flow.ApplicationNotFound 更實用的其他動作。
  • 使用 TargetServer 資源，將 TargetEndpoint 設定與具體網址分離，以支援跨環境推送。
    請參閱跨後端伺服器負載平衡的相關說明。
  • 如有多個 RouteRules，請將其建立為「default」，也就是沒有條件的 RouteRule。確保在條件式路徑清單中定義預設 RouteRule。系統會在 ProxyEndpoint 中由上而下評估 RouteRules。
    請參閱 API Proxy 設定參考資料。
  • API Proxy 組合大小：API Proxy 組合不得超過 15 MB。在 Apigee Edge 中，您可以透過修改下列位置的 thrift_framed_transport_size_in_mb 屬性來變更大小限制：cassandra.yaml (在 Cassandra 中) 和 conf/apigee/management-server/repository.properties。
  • API 版本管理：如需 Apigee 的 API 版本管理想法和建議，請參閱《Web API Design: The Missing Link》(網路 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

錯誤處理

  • 運用 FaultRules 處理所有錯誤處理作業。(ExFault 政策可用於停止訊息 Flow，並將處理傳送至 FaultRules Flow)。
  • 在 FaultRules 流程中，使用 AssignMessage 政策建立故障回應，而非 riseFault 政策。根據發生的錯誤類型有條件執行 AssignMessage 政策。
  • 一律納入預設的「catch-all」錯誤處理常式，以便系統產生的錯誤對應到客戶定義的錯誤回應格式。
  • 如果可能，錯誤回應應一律與貴公司或專案可用的任何標準格式相符。
  • 使用有意義的實用錯誤訊息，向錯誤狀況建議解決方案。

請參閱「處理錯誤」。

如要瞭解業界最佳做法，請參閱「符合 REST 樣式的錯誤回應設計」一文。

保留

鍵/值對應

  • 僅針對有限的資料集使用鍵/值對應。而不是長期的資料儲存庫。
  • 使用鍵/值對應時請考慮使用效能，因為這項資訊會儲存在 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 政策已經過強化、最佳化及支援。例如，建立酬載、從酬載中擷取資訊 (XPath、JSONPath) 等。請使用標準 AssignMessage 和 ExtractVariables 政策，而非 JavaScript (可能的話)。
  • 相較於 Python 和 Java，建議使用 JavaScript。不過，如果效能是主要要求，則應透過 JavaScript 使用 Java。

JavaScript

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

請參閱「使用 JavaScript 編寫 API Proxy」。

Java

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

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

Python

  • 除非絕對必要，否則請勿使用 Python。Python 指令碼可能會對簡易執行作業造成效能瓶頸，因為系統會在執行階段解譯這類指令碼。

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

  • 使用 Global try/catch 或同等功能。
  • 擲回有意義的例外狀況，並正確擷取這些例外狀況，以便用於錯誤回應。
  • 及早擲回例外狀況。請勿使用全域 try/catch 來處理所有例外狀況。
  • 視需要執行空值和未定義的檢查。例如擷取選用流程變數時，即可執行此操作。
  • 避免在指令碼呼叫中提出 HTTP/S 要求。請改用 Apigee 服務呼叫政策，因為這項政策會妥善處理連線。

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

請參閱服務呼叫政策。

存取實體

AccessEntity 政策

  • 為了獲得更佳效能，請按照uuid (而非應用程式名稱) 查詢應用程式。

請參閱存取實體政策。

記錄

  • 在不同套件和同一個軟體包中使用通用的系統記錄政策。這樣就能維持一致的記錄格式。

請參閱 MessageLogging 政策。

Monitoring

Cloud 客戶不需要檢查 Apigee Edge 的個別元件 (路由器、訊息處理器等)。如果客戶要求進行健康狀態檢查，Apigee 的 Global Operations 團隊會徹底監控所有元件，以及 API 健康狀態檢查。

Apigee 數據分析

Analytics (分析) 可以提供非關鍵的 API 監控功能，因為系統會測量錯誤百分比。

請參閱「Analytics (分析) 資訊主頁」一文。

追蹤記錄

API Edge 管理 UI 中的追蹤記錄工具在 API 開發或實際工作環境作業期間，對於執行階段 API 問題進行偵錯就能派上用場。

請參閱使用追蹤記錄工具。

安全性