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 類別為 internal，這表示只有 Fuchsia 專案中的 SDK 取用者可以使用 fuchsia.foo。如果有人想要變更 fuchsia.foo，則在 Fuchsia 專案中，會有中斷消費者的風險，但他們不會有在其他專案中中斷消費者的風險。

再舉一個例子，假設 fuchsia.bar FIDL 程式庫的 SDK 類別為 partner，這表示 fuchsia.bar 可在 Fuchsia 專案中，以及與 Fuchsia 專案合作的 SDK 用戶使用 ¹。 當使用者變更 fuchsia.bar 時，可能會破壞使用 fuchsia.bar 的合作夥伴，因而更有可能破壞消費者。

最後，請考慮 SDK 類別為 public 的 fuchsia.qux FIDL 程式庫，這表示 fuchsia.qux 可供一般大眾使用。變更 fuchsia.qux 具有極高風險，因為一般大眾開發的軟體組合可能有不受限制且無法告知。

除了定義逐漸增加的 API 使用者組合外，SDK 類別也定義了增加穩定性期。舉例來說，fuchsia.foo 可能會從一天大幅變化到下一天，因為 internal 類別會限制 Fuchsia 專案本身的曝光。如果變更 fuchsia.foo，所有用戶端和伺服器可能會同時變更，這表示 API 所需的穩定性視窗非常小或零。相較之下，Fchsia 與合作夥伴專案之間的協議包括了相容性期間的期望。

目前 Fuchsia 沒有任何 SDK 類別為 public 的 SDK Atom，這表示 Fuchsia 並未承諾使用其 API 支援一般大眾。不過，在某些情況下， Fuchsia 專案將開始使用其 API 支援一般大眾。屆時， Fuchsia 專案需要定義這些 API 的相容性期間，且可能會比 partner API 的相容性期間長。

如果預先建構的 partner 或 public SDK Atom 用於向 SDK 使用者公開這些 API，則必須設定額外的 SDK 類別。這些 partner_internal 和 public_internal 類別會強制執行與 partner 和 public 類別相同的 API 相容性期間，無須將這些 API 新增至 SDK API 介面區域。由於沒有 public SDK Atom，因此目前只會導入 partner_internal 類別。

一般的 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_atom`每個 SDK Atom 都有一個具有下列任一值的 category 參數：

• excluded：SDK 不得包含 Atom。
• experimental：(這個 SDK 類別不適用)
• internal：支援在 Fuchsia 平台來源樹狀結構中使用；
• cts：支援 Fuchsia 相容性測試；
• partner_internal：支援在 partner 類別的非來源 SDK Atom 中使用，但不會向 SDK 使用者公開；
• partner：支援特定合作夥伴；
• public：供一般大眾使用。

這些類別會形成一份經過排序的清單，其中包含單調增加的目標對象。舉例來說，public 類別中的 SDK Atom 一律可供特定合作夥伴使用，因為 public 位於這份清單的 partner 之後。

承諾使用合約

將 API 加入 partner 或 partner_internal 類別金額給合作夥伴，但我們不會破壞合作夥伴的程式碼，也不會對合作夥伴造成不當流失。凡是在這些類別下擁有 API 的團隊，都有責任堅持這些承諾。

internal

除了適用於 Fuchsia 專案中所有程式碼的 API，internal 類別的 API 對承諾有最少的使用承諾。

如果只有由「樹狀結構中」呼叫 API，且通訊的兩側一律是透過 Fuchsia 來源的相同修訂版本建構 (這兩個平台元件彼此通訊的情況一樣)，則類型應為 internal。

請注意，即使您所有 API 的用戶端都是樹狀結構內，但不足以表明其屬於 internal。舉例來說，ffx 的來源位於 Fuchsia 樹狀結構，但不符合第二個要求：以某個 Fuchsia 修訂版本建構的 ffx 子工具通常會與另一個在另一個 Fuchsia 版本建構的裝置通訊。因此，ffx 子工具以及 SDK 中隨附的任何其他構件，不得依賴 internal API。

partner_internal

合作夥伴不會使用 partner_internal API 自行編寫程式碼，但仍會透過 Fuchsia 團隊編寫的工具、程式庫或套件「間接」仰賴這些 API。由於 Fuchsia 團隊擁有使用這些 API 的程式碼，因此我們可以變更這些 API，不必煩惱合作夥伴的煩惱。不過，使用 partner_internal API 的工具、程式庫和套件一般是透過與其通訊平台元件不同的修訂版本建構。因此，每次變更 partner_internal API 時，我們都必須遵循 ABI 相容性政策。

簡單地說，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 是 Google 合作夥伴建構應用程式時的基礎，我們有責任確保該基礎架構穩定可靠。

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

• 建立上文 partner_internal 部分的所有版本管理承諾。

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

  • 提供優質文件。
  • 遵循一致的風格。
  • 您希望在目前使用的 SDK 中看到的其他項目。

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

• 請注意，即使我們遵守 API 演變指南，對於無法回溯相容的新 API 級別變更，合作夥伴也會產生費用。如果合作夥伴選擇更新目標 API 級別，就需要在程式碼集內進行修改，才能配合您的變更。因此，建議您不用稍做變更。

  如果您「確定」值得採取回溯不相容的變更，則同意根據流失政策，為該變更支付大部分的下游費用。

  變更 internal API 比 partner API 簡單容易，因此所有預計的 API 重構作業都應在將 API 新增至 partner 類別「之前」完成，而不是在新增之後完成。

變更記錄

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