[ADP-46] API 規範例外
每個團隊或業務單位在設計API時可能會有特定的考慮或獨特的需求。ADP (API 設計原則)的作用是協助和支持每個 API 設計者創建有效和較為一致的 API，而不是作為嚴格的規則執行者。ADP 作為一個資源，提供最佳實踐和建議以促進設計過程，但並不意味著要嚴格規定。
我們認知到在指定受眾為小於 COMPONENT_INTERNAL 層級的 API，可能有正當理由稍微偏離既定慣例。這些 API 在特定組件或系統內部使用，因此可能有獨特的限制或要求，需要對標準指南進行小幅調整。因此，在這些情況下允許小幅偏離慣例是合理的，只要不損害 API 的整體完整性、可維護性或互操作性。這種靈活性旨在使團隊能夠滿足其特定需求，同時仍遵守良好 API 設計的核心原則。
對於受眾為 PARTNER_EXTERNAL 層級的 API，也可能需要根據合作夥伴的需求做出一些調整。
例外處理流程
- 應該(SHOULD)記錄被豁免的具體指南，並參考ADP-757。
- 應該(SHOULD)提供明確的例外理由。
- 應該(SHOULD)概述任何潛在風險或影響。
- DRAFT 提交給API治理團隊審核。
- 在實施例外之前可(MAY)獲得批准。
文件重要性
當授予例外時，至關重要的是要徹底記錄偏差情況，包括背後的理由和任何潛在影響。此文件應易於所有相關利益相關者訪問。
定期審查
應定期審查例外情況，以確保它們仍然必要，並且不會對整體API生態系統產生負面影響。這個審查過程有助於長期保持一致性和品質。
可接受例外的示例
- 需要非標準數據格式的遺留(legacy)系統整合。
- 針對高容量內部API的性能優化。
- 符合特定監管要求。
- 其他。
COMPONENT_INTERNAL的範圍
COMPONENT_INTERNAL API是那些專門在特定組件或系統內使用的API，不向外部消費者或其他內部團隊公開。這些API具有有限的範圍和受眾，這可能證明某些偏離標準指南是合理的。
在考慮API指南例外時，請記住以下幾點:
例外應該是例外，而不是常規。大多數情況下，遵循標準指南將產生最佳結果。
仔細權衡偏離指南的好處和潛在風險。確保例外確實為您的特定用例帶來價值。
保持透明度至關重要。確保所有相關方都了解例外情況及其理由。
定期重新評估例外情況。隨著時間的推移，最初的理由可能不再適用。
使用例外作為學習機會。它們可能揭示指南中需要更新或擴展的領域。