opencode-workflow/skills/integration-boundary-design/README.zh-TW.md

整合邊界設計 (Integration Boundary Design) 知識合約指南

概述

integration-boundary-design 是知識合約，用來提供整合邊界設計的原則與模式。涵蓋外部 API 整合、Webhook 處理、Polling、重試策略、速率限制與失敗模式處理。供 design-architecture 在定義 Integration Boundaries 時參考。

核心原則

整合隔離

• 外部系統失敗不得級聯到系統失敗
• Circuit Breaker 必須保護內部服務
• 整合程式碼必須與商業邏輯隔離（Anti-Corruption Layer）

明確合約

• 每個外部整合必須有明確定義的合約
• 合約必須包含請求/回應結構、錯誤碼與 SLA
• 變更必須版本化並盡可能向後相容

假設失敗

• 外部系統會失敗、逾時、返回非預期資料
• 必須為每個整合定義逾時、重試與回退

設計重點

• 外部 API 整合：同步呼叫、非同步呼叫、Batch 呼叫、串流
• Webhook 處理：Inbound Webhooks（接收）與 Outbound Webhooks（發送）
• Polling：增量 Polling、輪詢間隔與資料差距處理
• 重試策略：退避策略、重試預算、最大總重試時間
• 速率限制：Token Bucket、Leaky Bucket、Fixed Window、Sliding Window
• 失敗模式處理：Transient、Permanent、Partial、Cascading Failure

知識合約職責

• 提供整合邊界設計的理論指引
• 不直接產生整合合約或實作程式碼

不應做的事

• 不替特定外部系統選擇整合方式
• 不定義具體的逾時值或重試次數
• 不產生實作程式碼