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 消費者1 使用。變更 fuchsia.bar 時,會導致消費者發生問題的風險更高,因為這可能會導致依賴 fuchsia.bar 的合作夥伴發生問題。

最後,請考慮使用 fuchsia.qux FIDL 程式庫,其 SDK 類別為 public,表示 fuchsia.qux 可供一般大眾使用。變更 fuchsia.qux 風險極高,因為一般大眾開發的軟體集合可能沒有限制,也無法得知。

除了定義同心圓不斷增加的 API 使用者集合,SDK 類別也會定義不斷增加的穩定性視窗。舉例來說,fuchsia.foo 可能會在一天內大幅變動,因為 internal 類別會限制 Fuchsia 專案本身的曝光率。變更 fuchsia.foo 的使用者可以同時變更所有用戶端和伺服器,這表示 API 所需的穩定性視窗非常小,甚至為零。相較之下,Fuchsia 與合作夥伴專案簽訂的協議中,包含了相容性時程的預期。

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

如果不希望將這些 API 公開給 SDK 使用者,則必須為預先建構的 partnerpublic SDK 原子中使用的 API 新增 SDK 類型。這些 partner_internalpublic_internal 類別會強制執行與 partnerpublic 類別相同的 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 都有一個 category 參數,其中包含下列其中一個值:

  • internal:已淘汰 (不允許新用途)
  • cts:可用於 Fuchsia 的相容性測試 (尚未支援)
  • partner_internal:支援在 partner 類別的非來源 SDK 原子中使用,但不會向 SDK 使用者公開
  • partner:特定合作夥伴可使用
  • public:一般大眾可使用 (尚未支援)

這些類別會形成排序清單,目標對象數量會逐漸增加。舉例來說,public 類別中的 SDK Atom 必須提供給特定合作夥伴,因為 public 在這個清單中位於 partner 之後。

承諾

將 API 新增至 partnerpartner_internal 類別,等同於向合作夥伴承諾,我們不會破壞他們的程式碼,也不會對他們施加不當的流失率。每個團隊都必須負責遵守這些承諾,這些團隊必須擁有上述任一類別的 API。

internal

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

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

請注意,即使所有 API 用戶端都位於樹狀結構中,也不足以表示該 API 屬於 internal。舉例來說,ffx 的來源位於 Fuchsia 樹狀結構中,但不符合第二個條件:在一個 Fuchsia 修訂版本中建構的 ffx 子工具,會經常與在另一個修訂版本中建構的裝置通訊。因此,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 是合作夥伴建構應用程式的基礎,我們有責任確保這個基礎可靠且穩定。

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

  • 請根據上述 partner_internal 部分的說明,做出所有版本承諾。
  • 掌握合作夥伴的開發人員體驗,包括:

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

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

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

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

    變更 internal API 比 partner API 更容易,因此應在將 API 新增至 partner 類別之前,而不是之後,進行任何已規劃的 API 重構作業。

變更記錄


  1. 目前合作夥伴的組合並未公開。隨著專案規模擴大,我們可能需要重新檢視合作夥伴關係的處理方式。