SDK 类别

每个 SDK Atom 都有一个类别，用于定义 SDK 使用方可以看到的种类。 原子随着 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 项目可以依赖于 fuchsia.foo。如果有人想要 fuchsia.foo，他们有可能会破坏紫红色的消费者 但不会出现破坏其他项目中的使用方的风险。

再举一个例子，假设有一个包含 SDK 类别的 fuchsia.bar FIDL 库 为 partner，这意味着 fuchsia.bar 可同时在 Fuchsia 中使用 项目以及与 Fuchsia 项目合作1的 SDK 使用方。 当有人更改 fuchsia.bar 后，服务中断的风险会更高 使用者，因为这可能会破坏依赖于 fuchsia.bar 的合作伙伴。

最后，假设有一个 SDK 类别为 public 的 fuchsia.qux FIDL 库，这意味着 fuchsia.qux 可供公众使用。正在更改 fuchsia.qux 的风险非常高，因为 Google Cloud 软件开发团队开发的那套软件 一般公众可能是无界限的，也是不可知的。

除了定义逐渐增加的 API 使用方集之外，SDK 类别还定义了逐渐增加的稳定性时间范围。例如：fuchsia.foo 因为internal 类别限制暴露于 Fuchsia 项目本身。他人正在改变 fuchsia.foo 可以同时更改所有客户端和服务器， 表示 API 所需的稳定性窗口非常小或为零。相比之下，Fuchsia 与合作伙伴项目签订的协议中包含了对兼容性时间范围的预期。

目前，Fuchsia 没有任何 SDK 类别为 public 的 SDK Atom。 这意味着 Fuchsia 未承诺支持 公共资源。不过，在某个时候，Fuchsia 项目会开始 使用其 API 为公众提供支持。届时，Fuchsia 项目需要为这些 API 定义兼容性期限，该期限可能会比 partner API 的兼容性期限更长。

对于预构建的 API 中使用的 API，需要一个其他类型的 SDK 类别 partner 或 public SDK Atom（如果不希望向这些 API 公开这些 API） SDK 用户。系统将强制执行这partner_internal和public_internal个类别 API 兼容性窗口与 partner 和 public 类别相同 而无需将这些 API 添加到 SDK API Surface 区域。只有 由于没有public，因此将暂时引入“partner_internal”类别 SDK Atom。

典型的 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 类别机制决定了 政策。

类别

SDK 类别已在 每个 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

除了适用于 Fuchsia 项目中的所有代码的承诺之外，internal 类别中的 API 没有其他承诺。

如果您的 API 只由树内代码调用，且代码两侧 始终都是基于同一版本的 Fuchsia 来源（如两个平台组件相互通信的情况），然后 它应该是 internal。

请注意，即使您的 API 的所有客户端都在树中，也不足以说它属于 internal。例如，ffx 的来源为 紫红色树，但不满足第二个要求：构建了 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 级别，则需要在其代码库中进行修改，以适应您的更改。因此，请勿轻易进行这些更改。

    如果您确实觉得某项向后不兼容的更改值得一试，您同意 支付该变更的大部分下游费用，具体取决于 流失政策。

    与 partner API 相比，对 internal API 进行更改要容易得多，因此，任何计划中的 API 重构都应在将 API 添加到 partner 类别之前完成，而不是之后。

更改历史记录

  1. 目前，合作伙伴名单尚未公开。随着项目规模的扩大 可能需要重新审视我们的合作伙伴关系。 ↩