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 项目内部使用方的风险，但不会出现破坏其他项目中的使用方的风险。

再举一个例子，假设一个 SDK 类别为 partner 的 fuchsia.bar FIDL 库，这意味着 fuchsia.bar 可以在 Fuchsia 项目中使用，也可供与 Fuchsia 项目合作的¹ SDK 使用者使用。当有人更改 fuchsia.bar 时，他们破坏使用者的风险更大，因为他们可能会破坏依赖于 fuchsia.bar 的合作伙伴。

最后，我们来考虑一个 SDK 类别为 public 的 fuchsia.qux FIDL 库，这意味着 fuchsia.qux 可供公众使用。更改 fuchsia.qux 的风险非常高，因为公众开发的软件集可能是无界限和不可知的。

除了定义同心增加的 API 使用者集之外，SDK 类别还定义了增加的稳定性窗口。例如，由于 internal 类别限制了对 Fuchsia 项目本身的访问，因此 fuchsia.foo 在一天之间可能会发生巨大变化。更改 fuchsia.foo 的人可能会同时更改所有客户端和服务器，这意味着 API 所需的稳定性窗口非常小或为零。相比之下，Fucsia 与合作伙伴项目签订的协议包括对兼容性窗口的预期。

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

对于预构建的 partner 或 public SDK Atom 中使用的 API，如果不希望向 SDK 用户公开这些 API，则需要提供其他类型的 SDK 类别。这些 partner_internal 和 public_internal 类别将强制执行与 partner 和 public 类别相同的 API 兼容性窗口，而无需将这些 API 添加到 SDK API 接口区域。由于没有 public SDK Atom，因此目前仅引入 partner_internal 类别。

典型的 SDK Atom 从 internal SDK 类别中开始其生命周期。有时，当合作伙伴需要访问 Atom 中包含的 API 时，API 委员会可能会将 SDK Atom 归类为 partner SDK 类别。将来，当 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

除了适用于 Fucsia 项目中的所有代码的承诺之外，internal 类别中的 API 具有最少的承诺。

如果您的 API 仅由树内代码调用，并且通信两端始终基于 Fuchsia 源代码的同一修订版本构建（就像两个平台组件相互通信的情况一样），则应为 internal。

请注意，即使 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 部分中的所有版本控制承诺。

• 负责合作伙伴在此 API 方面的开发者体验，包括：

  • 提供优质文档。
  • 遵循一致的风格。
  • 您希望在正在使用的 SDK 中看到的任何其他内容。

  如需了解相关规则和建议，请参阅 API 开发指南。

• 承认，对新 API 级别进行向后不兼容的更改会给合作伙伴带来成本，即使我们遵循 API 演变指南也是如此。如果合作伙伴选择更新其目标 API 级别，则需要在其代码库中进行修改以适应您的更改。因此，不应轻易进行这些更改。

  如果您确定某个向后不兼容性更改值得进行，您同意根据流失政策支付该更改的大部分下游费用。

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

更改历史记录

• 首次记录在 RFC-0165：SDK 类别中。