建置多平台 Kotlin 程式庫

當建立 Kotlin 程式庫時，請考慮支援 Kotlin Multiplatform 並進行建置與發佈。 這能擴大程式庫的受眾範圍，使其與針對多個平台開發的專案相容。

以下章節提供的指南可協助您有效地建置 Kotlin Multiplatform 程式庫。

擴大觸及範圍

為了讓您的程式庫能作為相依性提供給最多數量的專案， 請目標支援盡可能多的 Kotlin Multiplatform 目標平台。

如果您的程式庫不支援多平台專案（無論是程式庫還是應用程式）所使用的平台， 該專案將難以依賴您的程式庫。 在這種情況下，專案可能必須在某些平台使用您的程式庫，而針對其他平台則需實作獨立的解決方案， 或者乾脆選擇另一個支援其所有平台的替代程式庫。

為了簡化構件產出，請使用交叉編譯從任何主機發佈 Kotlin Multiplatform 程式庫。 這讓您能夠在沒有 Apple 電腦的情況下，為 Apple 目標平台產生 .klib 構件。

對於 Kotlin/Native 目標平台，請考慮使用分層方法來支援所有可能的目標。

針對通用程式碼設計 API

在建立程式庫時，應將 API 設計為可從通用 Kotlin 程式碼中使用，而不是編寫平台特定的實作。

請盡可能提供合理的預設配置，並包含平台特定的配置選項。 良好的預設值能讓使用者從通用 Kotlin 程式碼中使用程式庫的 API，而無需為了配置程式庫而編寫平台特定的實作。

請根據以下優先順序，將 API 放置在最廣泛相關的原始碼集中：

• commonMain 原始碼集： commonMain 原始碼集中的 API 可用於程式庫支援的所有平台。請致力於將程式庫的大部分 API 放置於此。
• 中間原始碼集： 如果某些平台不支援特定的 API，請使用中間原始碼集來針對特定平台。 例如，您可以為支援多執行緒的目標建立 concurrent 原始碼集，或為所有非 JVM 目標建立 nonJvm 原始碼集。
• 平台特定原始碼集： 對於平台特定的 API，請使用如 androidMain 之類的原始碼集。

若要進一步了解 Kotlin Multiplatform 專案的原始碼集，請參閱階層式專案結構。

確保跨平台行為一致

為了確保您的程式庫在所有支援的平台上表現一致， 多平台程式庫中的 API 應在所有平台上接受相同範圍的有效輸入、執行相同的操作， 並傳回相同的結果。 同樣地，程式庫應以統一的方式處理無效輸入，並在所有平台上一致地回報錯誤或拋出例外。

不一致的行為會使程式庫難以使用，並迫使使用者在通用程式碼中加入條件邏輯來管理平台特定的差異。

您可以使用 expect 與 actual 宣告在通用程式碼中宣告函式， 並配合平台特定的實作，以完全存取各個平台的原生 API。 這些實作也必須具備相同的行為，以確保能從通用程式碼中可靠地使用。

當 API 在跨平台行為一致時，只需在 commonMain 原始碼集中撰寫一次文件。

如果平台差異無法避免（例如當某個平台 支援更廣泛的輸入集時），請盡可能減少差異。例如，您可能不想為了與其他平台匹配而限制某個平台的功能。在這種情況下，請明確說明具體的差異。

在所有平台上進行測試

多平台程式庫可以擁有寫在通用程式碼中的多平台測試，並在所有平台上執行。 定期在您支援的平台上執行此通用測試套件，可確保程式庫的行為正確且一致。

定期在所有發佈的平台上測試 Kotlin/Native 目標平台可能具有挑戰性。 然而，為了確保更廣泛的相容性，請考慮為其能支援的所有目標發佈程式庫，並在測試相容性時使用分層方法。

使用 kotlin-test 程式庫在通用程式碼中編寫測試，並使用平台特定的測試執行器執行測試。

考慮非 Kotlin 使用者

Kotlin Multiplatform 在其支援的目標平台上提供與原生 API 和語言的互通性。 建立 Kotlin Multiplatform 程式庫時，請考慮使用者是否需要從 Kotlin 以外的語言 使用您程式庫的型別與宣告。

例如，如果您程式庫中的某些型別將透過互通性公開給 Swift 程式碼， 請將這些型別設計為易於從 Swift 存取。 Kotlin-Swift 互通性百科 (Kotlin-Swift interopedia) 提供了有關 Kotlin API 在從 Swift 呼叫時呈現方式的實用洞察。

推廣您的程式庫

您的程式庫可以收錄在 JetBrains 的搜尋平台。 該平台旨在讓使用者能根據目標平台輕鬆尋找 Kotlin Multiplatform 程式庫。

符合標準的程式庫會自動加入。如需更多關於如何加入您的程式庫的資訊，請參閱常見問題。