Microservices Contract Review — 跨服務 API 不一致的 8 個典型漏洞

微服務最大的痛不是寫不出來、是「服務 A 改了但 B 不知道」。Spec review 時除了單一 API、還要看跨服務的 contract 是不是會崩。這篇給你完整框架。

單體 review 看 1 個檔、微服務看 N × M 個介面。

Review 該問：

• 新增欄位有 nullable / default？
• Consumer 端有 null check?
• Schema 變更通知流程？

// Provider 加新狀態
type OrderStatus = 'pending' | 'paid' | 'shipped' | 'cancelled' | 'refunded'; // ← 新加

// Consumer 寫法
switch (status) {
  case 'pending': return '處理中';
  case 'paid': return '已付款';
  case 'shipped': return '已出貨';
  case 'cancelled': return '已取消';
  // ❌ refunded 沒處理 → undefined
}

Review 該問：

• 新增 enum 有對齊 consumer 嗎？
• Default case 處理？
• Enum 拓展屬 breaking change?（不全是、但要分類）

Service A (v1) ---calls---> Service B (v2)
                              ↑
                         v1 早已 deprecate
                         但 Service A 沒升

Review 該問：

• 版本 deprecation policy?
• 多少 consumer 用 v1?
• Migration 強制 deadline?

Provider v1: error.code = "INSUFFICIENT_BALANCE"
Provider v2: error.code = "INSUFFICIENT_FUNDS"  ← 改了

Consumer:
if (err.code === "INSUFFICIENT_BALANCE") { /* 處理 */ }
// ❌ v2 後永遠跑不到這

Review 該問：

• 錯誤碼有 changelog 嗎？
• 是否視為 breaking change?

User → API Gateway (60s timeout)
       → Service A (10s)
         → Service B (30s)
           → DB (5s)

User 等了 60s 才看到錯誤、但 Service B 早超 A 的 timeout 了

Review 該問：

• 每層 timeout 是否 propagate?
• 是否設 deadline 一致?
• Retry 策略誰負責?

Review 該問：

• 哪一層 retry?
• Idempotency key?
• Exponential backoff?

Review 該問：

• 日期一律 ISO 8601?
• 數字 precision 規範?
• Enum 是 string 還是 int?

Producer 順序送:
  msg1: order.created
  msg2: order.paid
  msg3: order.shipped

Consumer 收到:
  msg3 (網路快)
  msg1
  msg2

Consumer 處理 msg3 時 → 「order 不存在」

Review 該問：

• 訊息有 sequence number?
• Consumer 有 idempotency?
• Out-of-order 容錯機制?

Pact 工作流

// Consumer (寫期望)
import { Pact } from '@pact-foundation/pact';

const provider = new Pact({
  consumer: 'web-app',
  provider: 'user-service',
});

await provider.addInteraction({
  state: 'user 123 exists',
  uponReceiving: 'a request for user 123',
  withRequest: { method: 'GET', path: '/users/123' },
  willRespondWith: {
    status: 200,
    body: { id: 123, email: '[email protected]' },
  },
});

# Provider (verify 跑 pact file)
pact-verifier --provider-base-url http://localhost:8080 \
              --pact-url ./pacts/web-app-user-service.json

Provider 改 schema 不符合 → CI 直接擋。

1. 微服務的 bug 不在單一服務、在介面
2. Contract test > Integration test 為主、Integration 為輔
3. 沒 deprecation policy = 沒 versioning
4. Retry 一條鏈只一個地方做
5. Trace ID 不傳 = debug 不可能

微服務 spec review 是 QA 在分散式系統的主場。單一服務的 spec review 用既有 Spec Review Checklist、跨服務用這份。導入 Pact + 強制 deprecation policy + 統一 timeout / retry — 三個月後 production incident 砍 80%。