RFC-0165：SDK 類別

RFC-0165：SDK 類別
狀態已接受
區域
  • 開發人員
說明

SDK Atom 提供包含應用程式成熟度和目標對象的類別。
變更
作者
審查人員
提交日期 (年/月)2022-05-13
審查日期 (年/月)2022-05-31

編輯此 RFC

編輯 RFC 中繼資料

摘要

每個 SDK Atom 都有一個類別，用來定義哪些 SDK 使用者可以查看 Atom。隨著 SDK Atom 逐漸成熟，我們得以提高其可見度，從而提升了其穩定性。

提振精神

Fuchsia 將多種不同元件結合使用通訊協定與 FIDL 中定義的結構定義互動。Fuchsia 專案中的元件彼此互動的機制，相同由第三方編寫的元件會與 Fuchsia 平台互動。因此，我們擁有統一的機制，能同時用於開發 Fuchsia 及為 Fuchsia 進行開發。

最簡單的方法是將所有 FIDL 定義放入 Fuchsia SDK，然後讓所有開發人員使用相同的 FIDL 定義來開發元件。然而，這種做法會因為設計 API 時的複雜程度而失效：API 設計人員需要疊代設計其設計，且 API 使用者需要穩定性，才能在 API 的基礎上進行建構。

本文件說明 SDK 類別，這是平衡這些疑慮的現有機制。RFC 程序之前的 SDK 類別。本文件旨在記錄現有機制。

類別不是 Fuchsia 用來因應這種壓力的唯一機制。舉例來說，Fuchsia 也會限制元件可透過能力轉送功能依附的 FIDL 通訊協定。這些機制是互補的，因為沒有能力轉送，元件作者可能會想建立內部 FIDL 定義的本機副本，而不是等待這些副本新增到 SDK。同樣地，如果沒有 SDK 類別，元件作者可能會根據內部 FIDL 通訊協定在各自的元件之間進行通訊。

相關人員

誰擔心是否接受這個 RFC？(本節為選填，但建議填寫)。

講師：

  • neelsa@google.com

審查者：

  • dschuyler@google.com
  • jamesr@google.com
  • jeremymanson@google.com
  • neelsa@google.com
  • sebmarchand@google.com
  • sethladd@google.com

社群媒體化：

這個 RFC 已略過資源調度階段，因為機制已完全實作。

定義

SDK Atom 是可包含在 SDK 中的一組檔案。Fuchsia 代表在 GN 中使用 sdk_atom 範本的 SDK Atom。

SDK 目標是指可建立 SDK 的建構目標。舉例來說，//sdk:core 是建立 Core SDK 的建構目標的 GN 標籤。由於這些目標會為 IDK 建立 JSON 中繼資料，因此將這些目標稱為 IDK 目標可能更加準確。SDK 實際工作環境的下一階段會使用此 JSON 中繼資料，產生完全整合的 Fuuchsia SDK (例如使用 Bazel 的建構系統)。

設計

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 的合作夥伴，因而更有可能破壞消費者。

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

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

相較之下，Fchsia 與合作夥伴專案之間的協議也包含相容性期間的期望。例如，我們目前與合作夥伴達成協議，將相容性維持在六週的相容性期間，不過這個時間可能會在即將發布的 RFC 中改變。本協議意味著 fuchsia.bar 不得從一天大幅變更到次日。反之，我們需要以維持相容性視窗的方式逐步變更 fuchsia.bar。

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

一般的 SDK Atom 會在 internal SDK 類別中開始生命週期。在某些情況下，API 委員會可能會將 SDK Atom 升級為 partner SDK 類別，通常在合作夥伴需要存取 Atom 中包含的 API 時。日後，當 Fuchsia 有非空白的 public SDK 類別時，SDK Atom 也可以從 partner 類別升級至 public 類別。部分 SDK Atom 可能無限期保留在 internal SDK 類別中。其他可能升級至 partner，但永遠不會升級到 public。

這個生命週期目前並不完整，因為該生命週期並未涵蓋 SDK Atom 的淘汰和移除。舉例來說，我們可能需要為 SDK Atom 新增 historical 類別，但這些類別目前雖然很實用，但仍具有歷史值。這種現有模型的擴充功能超出這個 RFC 的範疇。

請注意，這個機制可以輔助平台版本管理的 @available 機制。@available 機制會「記錄」FIDL API 的變更時間和方式。SDK 類別機制會決定 API 設計人員進行變更的政策。

實作

建構 SDK 的 GN 規則中已實作 SDK 類別。每個 SDK Atom 都有一個具有下列任一值的 category 參數：

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

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

experimental 類別並不合理，因為我們有更好的機制 (例如GN visibility)，藉此控管 Fuchsia 平台原始碼樹狀結構中的程式碼使用情形。系統很快就會移除這個類別。

每個 SDK 目標也都有 category 參數，可定義 SDK 出貨的一組消費者。建構系統會強制執行 SDK 目標中的所有項目，都必須提供該目標對象可接受的 SDK 類別。舉例來說，partner 的 SDK 可能包含授權為 public 的 SDK Atom (因為 public 在上方清單中的 partner 之後)，但不能納入僅供 internal 使用的 SDK Atom (因為 internal 在這份清單中的 partner 之前)。

excluded SDK 類別是用來再次檢查，避免特定目標納入 SDK。事實上，excluded 是該意圖的說明文件，可以讓程式碼審查人員仔細考慮該值的變更。

回溯相容性

一般來說，將 SDK Atom 公開給較大且規模較大的目標對象，會導致 SDK 類別有所變動。縮減 SDK Atom 集合的取用端時，系統會有效地將這些 API 從檢視畫面中刪除，如果未妥善協調，可能會導致這些取用者中斷。

安全性考量

SDK 類別並非安全性機制。惡意人士可以讀取 Fuchsia 開放原始碼專案中的所有 FIDL 定義，並以攻擊者能想到的任何各種方式使用。這項機制只能使工程程序更順暢地執行。

隱私權注意事項

SDK 類別及其適用 SDK Atom 的一切資訊都會公開。

測試

系統會在建構期間透過建構設定強制執行 SDK 類別。不過，我們尚未針對這個機制進行了許多測試。SDK 相關 GN 範本的變更可能會破壞機制，導致 SDK Atom 納入不適當的 SDK 目標。我們有幾種多餘的機制 (包括 SDK 資訊清單) 來擷取設定錯誤，但我們目前仰賴程式碼審查人員留意 SDK 資訊清單和 SDK 類別之間不一致的問題，以找出 SDK 類別機制中的迴歸。

說明文件

編寫這個 RFC 的目的是記錄 SDK 類別目前的狀態。另請參閱其他適用於開發人員的說明文件，瞭解 Fuchsia 針對各式各樣的 SDK 做出的穩定性承諾。

缺點、替代方案和未知

此方法的主要缺點是可套用 SDK 類別的粗細精細程度。舉例來說，您可以想像另一種方法：將個別 FIDL 通訊協定元素指派給 SDK 類別，類似於個別通訊協定元素指派 @available 屬性的方式。

現有 SDK 類別機制的優點在於，該機制適用於所有類型的 SDK Atom。不過，我們可能希望更精細的機制來處理特定種類的 SDK Atom (例如FIDL 通訊協定)。

先前的圖片和參考資料

大多數平台都具備類似的機制，可在 API 穩定運作時逐步拓展目標對象。舉例來說，Apple 在開發 macOS 和 iOS 適用的 API 時，會採用類似的機制。在這些作業系統的開發程序中，每個架構都有三種 API 組合：可在架構本身中使用的內部 API、適用於作業系統建構作業中的其他架構的私人 API，以及作業系統為一般公開建構應用程式提供的公用 API。

部分其他平台的 SDK 發布流程中會進行「標頭清除」步驟，可在將 SDK 發布給更廣大的目標對象前，從標頭中移除文字。使用「未去除」標頭的消費者，可以依賴使用已移除標頭的更多 API 組合。這項機制與 SDK 類別類似，但運作方式較精細，且目標對象評分通常較少。

  1. 目前合作夥伴組合並未公開。隨著專案規模擴大，我們可能需要重新審視合作的方式。 ↩