函式庫作者指南簡介

本指南總結了設計函式庫時應考量的最佳實踐與想法。

為了發揮效益，函式庫必須達成某些基本目標。具體而言，它應做到：

定義其問題領域，並實作一系列相關的功能需求以解決其定義的問題。例如，一個 HTTP 客戶端可能旨在支援所有 HTTP 請求類型，並理解各種標頭、內容類型和狀態碼。
符合適合該問題領域的非功能性標準。這些通常涉及效能、可靠性、安全性及可用性。這些標準的相對重要性差異甚大。例如，為批次處理設計的函式庫可能不需要如同為日內交易設計的函式庫那樣的效能水準。
識別和定義功能性與非功能性需求的過程是一個複雜主題，在軟體工程中已被廣泛研究。本指南不深入涵蓋這些主題，因為它們超出其範圍。

本指南的主要焦點是探討函式庫必須具備哪些特徵才能對其使用者保持相關性並受歡迎。這些特徵包括：

最小化心智複雜度： 所有開發者都必須考量其程式碼的可讀性與可維護性。降低他人閱讀、理解和使用您的 API 所需的心智負擔至關重要。實現這一點需要建立清晰、一致、可預測且易於偵錯的函式庫。
向後相容性： 發布 API 新版本時，請確保現有 API 仍能正常運作。務必提前明確溝通並記錄任何破壞性變更。為使用者提供一個直接、清晰且漸進的途徑來採用新的 API 或設計變更。
資訊豐富的文件： 函式庫隨附的文件不僅僅是重複函式和類型宣告。它應該是全面的，並且專門為函式庫的受眾量身定制。它應該準確反映各種使用者角色的需求和情境，確保提供必要的資訊，同時不過於簡單或複雜。始終包含清晰的範例，平衡解釋性文字與實用程式碼範例。

此外，為您的 Kotlin 函式庫建立多平台支援可以擴展其在針對不同環境的專案中的適用性。設計能在共用程式碼和平台特定程式碼中可靠運作的 API，可以提高函式庫在所有支援目標中的多功能性及可用性。

以下章節將更深入探討這些特徵，並提供實用建議，說明您如何為您的函式庫使用者提供最佳體驗。

接下來