SDK 類別

每個 SDK Atom 都有一個類別，定義哪些類型的 SDK 使用者可以看到 Atom。隨著 SDK Atom 的成熟，我們可以提高其能見度，也就是提高穩定性保證。

提振精神

Fuchsia 透過結合 結構定義與 FIDL 中定義的通訊協定。Fuchsia 元件 專案也會使用與元件相同的機制 。因此 因此，我們得以採用統一機制 Fuchsia 為 Fuchsia 進行開發。

最簡單的做法是將所有 FIDL 定義放入 Fuchsia 然後讓所有開發人員都使用相同的 FIDL 定義 開發元件不過，這個方法會中斷 設計 API 的常見緊張之處：API 設計人員必須能夠 應用程式的設計和 API 消費者需要穩定性，才能讓 相互整合

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

設計

FIDL 程式庫是 SDK Atom 的其中一個例子，但還有其他類型的 SDK Atoms，包括 C++ 用戶端程式庫、說明文件和工具。SDK 類別適用於所有類型的 SDK Atom，但本文件會使用 FIDL 程式庫做為執行範例。

SDK 類別可藉由以下方式，在 API 的疊代與穩定性之間取得平衡： 瞭解不同的 API 使用者會有不同的穩定性需求。API (應用程式介面) 「近距離」的消費者而 API 設計人員通常不需要 穩定性，通常也是最先提供 提供對 API 設計人員的意見回饋

每個 SDK Atom 都會加註 SDK 類別，而該類別定義了 取用端依附於 SDK Atom舉例來說，如果 fuchsia.foo FIDL 程式庫的 SDK 類別為 internal，表示只有 Fuchsia 專案中的 SDK 使用者可以依附 fuchsia.foo。如果有人想變更電子郵件地址 fuchsia.foo，他們面臨困在富士夏境內消費者的風險 卻未面臨破壞其他專案消費者的風險。

再舉一例，假設 fuchsia.bar FIDL 程式庫含有 SDK 類別 的 partner，這表示 fuchsia.bar 在 Fuchsia 中皆可使用 。 變更 fuchsia.bar 時，會導致消費者發生問題的風險更高，因為這可能會導致依賴 fuchsia.bar 的合作夥伴發生問題。

最後，請考慮使用 fuchsia.qux FIDL 程式庫，其 SDK 類別為 public，也就是說一般大眾可以使用 fuchsia.qux。變更中 fuchsia.qux 是高風險的，因為 Google AI 開發的軟體集 一般大眾可能沒有能力無邊界且不知所措

除了定義以相同方式增加的 API 使用者組合 (SDK) 也會導致穩定性視窗增加例如：fuchsia.foo 可能因為internal 類別 限制 Fuchsia 專案本身的曝光度。變更 fuchsia.foo 的使用者可以同時變更所有用戶端和伺服器，這表示 API 所需的穩定性視窗非常小，甚至為零。變更者： 相較之下，Fchsia 與合作夥伴專案簽訂的協議包括 以及相容性期間的期望

目前，Fuchsia 沒有任何 SDK Atom 的 SDK 類別為 public，這表示 Fuchsia 並未承諾支援使用其 API 的一般大眾。不過，Fuchsia 專案將在某個時間點開始支援一般大眾使用其 API。當時，Fuchsia 專案 必須定義這些 API 的相容性視窗 超過 partner API 的相容性期間。

預先建構的 API 需要額外的 SDK 類別 不適合向 partner 或 public SDK Atom 公開這些 API SDK 使用者。這些「partner_internal」和「public_internal」類別會強制執行 與 partner 和 public 類別相同的 API 相容性期間 而不必將 API 新增至 SDK API 介面區域目前只會推出 partner_internal 類別，因為沒有 public SDK 原子。

一般 SDK Atom 會從 internal SDK 類別開始生命週期。某些 第一點，API 委員會可能會將 SDK Atom 升級為 partner SDK 類別，通常是在合作夥伴需要存取 Atom 中 API 時。 未來如果 Fuchsia 有非空白的 public SDK 類別 (SDK) Atom 可以從 partner 類別升級為 public 部分 SDK Atom 可能屬於 internal SDK 類別 無限期。其他人可能畢業至 partner，但從未畢業 public。

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

類別

SDK 類別已導入 `sdk_atom` GN 規則 每個 SDK Atom 都有包含下列任一值的 category 參數：

• excluded：已淘汰
• experimental：(這個 SDK 類別並不合理)；
• internal：支援在 Fuchsia 平台來源樹狀結構中使用；
• cts：可用於 Fuchsia 的相容性測試 (尚未支援)
• partner_internal：支援在 partner 類別的非來源 SDK 原子中使用，但不會公開給 SDK 使用者；
• partner：適用於特定合作夥伴；
• public：開放一般大眾使用 (尚未支援)

這些類別會形成排序清單，且目標對象會逐漸增加。舉例來說，public 類別中的 SDK Atom 一定會為 由於public在這份清單的partner後面，因此選取合作夥伴。

使用承諾

將 API 新增至 partner 或 partner_internal 類別，等同於向合作夥伴承諾，我們不會破壞他們的程式碼，也不會對他們施加不當的流失率。具備 API 的各個團隊 各類別都有責任履行這些承諾。

internal

internal 類別中的 API 除了適用於 Fuchsia 專案中的所有程式碼之外，其他都沒有任何承諾。

如果您的 API 只會由樹狀結構程式碼呼叫，且通訊的兩端一律是使用 Fuchsia 來源的相同修訂版本建構 (例如兩個平台元件彼此通訊的情況)，則應為 internal。

請注意，即使所有 API 用戶端都位於樹狀結構中，也不足以表示該 API 屬於 internal。舉例來說，ffx 的來源位於 Fuchsia 樹狀結構，但不符合第二個需求：已建立 ffx 子工具 Fuchsia 修訂版本經常與另一款裝置通訊。因此，ffx 子工具和 SDK 中提供的任何其他構件，都不得依賴 internal API。

partner_internal

合作夥伴不會使用 partner_internal API 編寫自己的程式碼，但仍會透過 Fuchsia 團隊編寫的工具、程式庫或套件，間接依賴這些 API。由於 Fuchsia 團隊擁有 因此我們可以在不流失合作夥伴的情況下變更這些 API。不過，使用 partner_internal API 的工具、程式庫和套件，通常會使用與其互動的平台元件不同的修訂版本來建構。因此，每當有人更新時，我們必須遵守 ABI 相容性政策 變更 partner_internal API。

換句話說，partner_internal 類別中 API 的擁有者同意：

• 在 API 上使用 FIDL 版本管理註解。
• 只在 in-development API 級別或 HEAD 修改 API。 一旦 API 級別宣告為穩定版，就不得再變更 (請參閱 version_history.json)。
• 請確保實作這些 API 的平台元件與 支援 Fuchsia 的 API 級別 (請參閱 version_history.json)。

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

partner

合作夥伴直接使用 partner API。這些 API 的基礎 建構應用程式時，我們有責任 這些基礎概念可以說是可靠穩固的基礎

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

• 使用 partner_internal 區段的所有版本管理承諾產品 。

• 擁有合作夥伴開發人員體驗，包括：

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

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

• 瞭解對新 API 級別回溯不相容的變更會使 提高合作夥伴的成本，即使遵循 API 演進史 指南。如果合作夥伴選擇更新目標 API 級別，就必須在程式碼集內進行修改，以便配合您的變更。因此，請不要進行這類變更 程度。

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

  變更 internal API 比 partner API 更容易，因此任何計劃中的 API 重構作業都應在將 API 新增至 partner 類別之前完成，而非之後。

變更記錄

• 首先記載於 RFC-0165：SDK 類別。