36 lines
1.6 KiB
Markdown
36 lines
1.6 KiB
Markdown
# 整合邊界設計 (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
|
||
|
||
## 知識合約職責
|
||
- 提供整合邊界設計的理論指引
|
||
- 不直接產生整合合約或實作程式碼
|
||
|
||
## 不應做的事
|
||
- 不替特定外部系統選擇整合方式
|
||
- 不定義具體的逾時值或重試次數
|
||
- 不產生實作程式碼 |