當程式開發代理能夠透過結構化合約建立、檢查、使用、復原、移交和移除後端資源,這個後端才算可以由代理操作。能夠調用執行期 API 只是其中一步,項目設定、憑證、失敗處理、擁有權和清理也必須涵蓋。
最快的測試方式,是追蹤一個數據庫或一次部署的完整生命週期。只要缺少狀態或刪除合約,代理就仍然需要依賴人操作儀表板。
代理可以存取,不代表代理可以操作
在代理可存取的後端中,人先完成設定,應用程式才可以調用數據庫或 API。代理可操作的後端則更進一步,讓經過授權的代理也能執行建立和維持這個狀態所需的管理工作。
| 生命週期階段 | 可存取的後端 | 可操作的後端 |
|---|---|---|
| 建立 | 人使用管理介面 | 代理調用設有類型的建立操作 |
| 探索 | 人複製 ID 和 URL | 代理取得結構化識別碼和端點 |
| 使用 | 應用程式調用服務 | 應用程式使用範圍受限的數據平面憑證 |
| 復原 | 人閱讀日誌並重試 | 代理讀取操作狀態並按照重試合約處理 |
| 輪替 | 人更換密鑰 | 代理要求輪替,而且不會看到上游憑證 |
| 移交 | 帳戶一開始就屬於某個人 | 人透過明確流程認領或接管擁有權 |
| 刪除 | 在管理介面操作 | 透過獲授權的刪除操作執行,並附有依賴關係和復原規則 |
代理原生基礎設施指南將同樣的區別套用到完整平台。
分開控制平面與數據平面
控制平面負責建立資源、變更設定、報告狀態、處理擁有權和執行計費規則;數據平面則回應應用程式請求。兩者應使用不同的憑證。
程式開發代理在建置時可能需要管理憑證,但部署後的應用程式只應取得所需的數據平面權限。瀏覽器套件不應拿到任何一種憑證,除非該憑證明確設計為公開資訊,或會被換成短效工作階段權杖。
NIST 的零信任指南主張按照主體、資源和政策作出存取決策,而不是按照網絡位置判斷。這項原則在此同樣適用:針對代理的身份、要求的資源和操作進行授權,再由服務執行決策。
讓資源建立過程可以觀察
建立調用應傳回資源 ID 和操作狀態。如果工作會非同步繼續執行,就要提供狀態查詢操作,並使用 ready、failed 或 deleted 等穩定的終止狀態。
不要讓代理從儀表板 URL 或 DNS 紀錄是否存在來推測資源是否就緒。平台應清楚說明哪些項目已就緒、哪些仍在等待。
定義安全的寫入行為
每一項寫入操作都應記載:
- 操作是否具冪等性;
- 用哪個操作識別碼或冪等鍵識別重試;
- 伺服器會保留該鍵多久;
- 逾時後,結果是已知還是未知;
- 調用端如何取回原始結果;
- 哪些失敗可以安全重試。
Stripe 的冪等性文件是一個清晰的公開例子:系統會儲存某個鍵第一次執行的結果,並在之後傳回同一結果。你的合約可以採用不同的保存期限和參數規則,但必須同樣明確。
傳回能夠決定下一步的錯誤
代理需要穩定的錯誤代碼、簡短訊息和結構化詳情。以下區別會直接影響之後的操作:
| 錯誤 | 下一步 |
|---|---|
invalid_request |
修正指定欄位 |
not_authorized |
停止操作,並要求權限更窄或不同的身份 |
approval_required |
向人顯示待批准的確切操作 |
operation_in_progress |
輪詢所提供的操作 ID |
rate_limited |
等到指定的重試時間 |
quota_exceeded |
停止,或在變更方案或支出前先詢問 |
dependency_conflict |
處理指定的依賴資源 |
HTML 錯誤頁或籠統的 500 錯誤會迫使代理猜測。資源配置期間的猜測,會造成重複建立資源,也會令清理工作出錯。
將擁有權與初始建立分開
用戶還不想建立帳戶時,代理可能已經需要建立隔離項目。這類項目仍須設定到期時間,並提供日後由人認領的流程。只有在用戶明確同意後,認領操作才能擴大擁有權,而且批准 URL 不應洩露代理的暫時密鑰。
Cohesivity 採用這種模式。npx @cohesivity/init 會建立或重用一個有效 72 小時的暫時租戶。資源文件位於 /offerings/<name>,資源透過管理平面配置,而應用程式則使用獨立的邊緣憑證。之後才由人透過同意流程認領。
使用程式開發代理配置後端資源的實作指南展示了完整流程。
依賴資源前先測試刪除
建立一個可隨時棄用的資源,中斷建立流程、再次執行、輪替存取權,最後將它刪除。確認依賴服務能夠繼續運作;如果不能,刪除操作也應以結構化說明指出阻擋原因。同時確認舊憑證已經失效。
下方提示會針對項目已使用的一項資源執行相同的生命週期檢查,而且不會改動供應商端的任何內容。