SDK 類別

每個 SDK Atom 都有類別，可定義哪些類型的 SDK 消費者可以查看 Atom。隨著 SDK Atom 日趨成熟，我們可提高其曝光度，這表示穩定性保證也會隨之提升。

提振精神

Fuchsia 是由許多不同的元件組合而成，這些元件會使用 FIDL 中定義的結構定義通訊協定進行互動。Fuchsia 專案的元件會使用相同的機制相互互動，第三方編寫的元件也會透過這個機制與 Fuchsia 平台互動。因此，我們可使用統一機制開發 Fuchsia 和 Fuchsia 應用程式，這對我們來說是一大優勢。

最簡單的方法是將所有 FIDL 定義放入 Fuchsia SDK，然後讓所有開發人員在開發元件時使用相同的 FIDL 定義。不過，這種做法會因為 API 設計中常見的緊張關係而失效：API 設計人員需要能夠疊代設計，而 API 消費者則需要穩定性，才能在 API 基礎上建構。

本文說明 SDK 類別，這是 Fuchsia 用來平衡這些疑慮的主要機制。

設計

FIDL 程式庫是 SDK Atom 的一個例子，但還有其他類型的 SDK Atom，包括 C++ 用戶端程式庫、文件和工具。SDK 類別適用於各種 SDK Atom，但本文以 FIDL 程式庫為例。

SDK 類別會考量 API 的疊代和穩定性需求，因為不同 API 消費者的穩定性需求不同。與 API 設計人員「較接近」的 API 消費者通常較不需要穩定性，而且往往是第一批向 API 設計人員提供實作意見回饋的客戶。

每個 SDK Atom 都會註解 SDK 類別，定義哪些 SDK 消費者可以依附 SDK Atom。舉例來說，如果 fuchsia.foo FIDL 程式庫的 SDK 類別為 compat_test，表示只有 Fuchsia 專案中的 CTF 測試可以依附於 fuchsia.foo。如果有人想變更 fuchsia.foo，可能會導致 Fuchsia 專案中的 CTF 測試中斷，但不會導致其他專案中的消費者中斷。

舉例來說，假設 fuchsia.bar FIDL 程式庫的 SDK 類別為 partner，表示 fuchsia.bar 可在 Fuchsia 專案中使用，也可供與 Fuchsia 專案合作的 SDK 消費者使用¹。如果有人變更 fuchsia.bar，可能會導致依附於 fuchsia.bar 的合作夥伴中斷，進而對消費者造成影響，因此風險較高。

如果不想向 SDK 使用者公開這些 API，預先建構的 partner SDK 原子所用的 API 就需要額外的 SDK 類別。這個 prebuilt 類別會強制執行與 partner 類別相同的 API 相容性視窗，但不需要將這些 API 新增至 SDK API 介面區域。

典型的 SDK Atom 會在 SDK 外部開始生命週期，且沒有 SDK 類別。如果 SDK 中的主機工具或預先編譯的程式庫需要使用，則可能會先加入 SDK 的 host_tool 或 prebuilt 類別。在某個時間點，API 委員會會將 SDK Atom 升級至 partner SDK 類別，通常是合作夥伴需要存取 Atom 中包含的 API 時。

請注意，這項機制是 @available 機制的補充，適用於平台版本管理。@available 機制會記錄 FIDL API 的變更時間和方式。SDK 類別機制會決定 API 設計人員可多快進行變更的政策。

類別

SDK 類別已在 <0x0A每個 SDK Atom 都有 category 參數，且值為下列其中一項：

• compat_test：可用於設定及執行 CTF 測試，但可能不會在 SDK 中公開供正式版使用，也不會由主機工具使用。
• host_tool ：可供平台機構提供的主機工具 (例如 ffx) 使用，但不得供 SDK 中的正式版程式碼或預先建構的二進位檔使用。
• prebuilt：可能是 ABI 的一部分，SDK 中包含的預先建構二進位檔會使用這個 ABI 與平台互動。
• partner ：包含在 SDK 中，供樹狀結構外的開發人員直接使用 API。

這些類別會形成排序清單，目標對象數量單調遞增。舉例來說，partner 類別中的 SDK Atom 必須適用於相容性測試 partner，且相容性測試必須位於這個清單的 compat_test 之後。

如要瞭解如何將 API、程式庫或現有 SDK 原子升級至其中一個類別，請參閱「升級 API」。

承諾

將 API 新增至 partner 或 prebuilt 類別，即代表我們向合作夥伴承諾不會破壞他們的程式碼，也不會對他們造成不當的流失。如果團隊擁有上述任一類別的 API，就必須遵守這些承諾。

host_tool

合作夥伴不會使用 host_tool API 編寫自己的程式碼，也不會開發依賴這些 API 的元件，但仍會間接透過 Fuchsia 團隊編寫的開發人員工具依賴這些 API。由於 Fuchsia 團隊擁有使用這些 API 的程式碼，因此我們可以在不影響合作夥伴的情況下變更這些 API。不過，使用 host_tool API 的工具通常會以不同修訂版本建構，而非與其通訊的平台元件。因此，每當我們變更 host_tool API 時，都必須遵守 ABI 相容性政策。

也就是說，host_tool 類別中的 API 擁有者同意：

• 在 API 上使用 FIDL 版本控管註解。
• 請務必只在 HEAD 或 NEXT 修改 API。 API 層級宣告為穩定版後，就不應再變更 (請參閱 version_history.json)。
• 確保實作這些 API 的平台元件與所有 Fuchsia 支援的 API 級別相容 (請參閱 version_history.json)。

如要進一步瞭解 API 相容性，請參閱 API 演進指南。

prebuilt

合作夥伴不會使用 prebuilt API 編寫自己的程式碼，但仍會間接透過 Fuchsia 團隊編寫的預先建構程式庫或套件，依附這些 API。由於 Fuchsia 團隊擁有使用這些 API 的程式碼，因此我們可以在不影響合作夥伴的情況下變更這些 API。不過，使用 prebuilt API 的程式庫和套件通常會從不同修訂版本建構，而非與其通訊的平台元件。因此，每當我們變更 prebuilt API 時，都必須遵守 ABI 相容性政策。

也就是說，prebuilt 類別中的 API 擁有者同意： * 遵守上述 host_tool 專區中的所有版本控管承諾。

如要進一步瞭解 API 相容性，請參閱 API 演進指南。

partner

合作夥伴直接使用 partner API。合作夥伴會以這些 API 為基礎建構應用程式，因此我們有責任確保這些基礎穩定可靠。

partner 類別中的 API 擁有者同意：

• 請遵守上述「prebuilt」一節中的所有版本控管承諾。

• 負責與此 API 相關的合作夥伴開發人員體驗，包括：

  • 提供優質文件。
  • 遵循一致的樣式。
  • 您希望在使用的 SDK 中看到哪些其他內容。

  如需相關規則和建議，請參閱 API 開發指南。

• 瞭解即使我們遵循 API 演進指南，新 API 級別的回溯不相容變更仍會對合作夥伴造成成本。如果合作夥伴選擇更新目標 API 級別，就必須在程式碼庫中進行修改，以配合您的變更。因此，請務必謹慎進行這類變更。

  如果您決定要進行回溯不相容的變更，即表示您同意根據流失政策，支付該變更的大部分下游成本。

  在 API 穩定前進行變更容易得多，因此任何預計的 API 重構作業，都應在將 API 新增至 SDK 類別「之前」完成，而非之後。

變更記錄

• 首次記錄於 RFC-0165：SDK 類別。