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 的合作夥伴發生問題。

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

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

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

類別

SDK 類別已在 每個 SDK Atom 都有一個 category 參數，其中包含下列其中一個值：

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

這些類別會形成排序清單，目標對象數量會逐漸增加。舉例來說，partner 類別中的 SDK Atom 必須可用於相容性測試，因此 partner 會在這份清單中排在 compat_test 之後。

承諾

將 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 部分，並做出所有版本承諾。

• 掌握合作夥伴的開發人員體驗，包括：

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

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

• 請注意，即使我們遵循 API 演進指南，對新 API 級別進行不相容變更也會對合作夥伴造成成本。如果合作夥伴選擇更新目標 API 級別，就必須在程式碼集內進行修改，以便配合您的變更。因此，請勿輕易進行這些變更。

  如果您決定進行回溯不相容的變更，則您同意依據流失政策支付這項變更的大部分後續成本。

  在 API 穩定前，變更會比較容易，因此應在將 API 新增至 SDK 類別的前，而不是之後，進行任何已規劃的 API 重構。

變更記錄

• 首次在 RFC-0165：SDK 類別中說明。