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 可供公众使用）的 fuchsia.qux FIDL 库。更改 fuchsia.qux 的风险非常高，因为公众开发的软件集可能是无限且不可知的。

除了定义同中心增加的 API 使用方集之外，SDK 类别还定义了增加的稳定性期。例如，fuchsia.foo 每天之间可能会有很大变化，因为 internal 类别限制了对 Fuchsia 项目本身的曝光。更改 fuchsia.foo 的人可以同时更改所有客户端和服务器，这意味着 API 所需的稳定性窗口要么很小，要么为零。相比之下，Fucsia 与合作伙伴项目签订的协议中包含对兼容性窗口的预期。

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

如果不希望向 SDK 用户公开预构建的 partner 或 public SDK Atom，则需要为这些 API 添加其他类型的 SDK 类别。这些 partner_internal 和 public_internal 类别将强制执行与 partner 和 public 类别相同的 API 兼容性窗口，而无需将这些 API 添加到 SDK API Surface 区域。由于没有 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：Atom 不得包含在 SDK 中；
• 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 项目中所有代码的承诺之外，internal 类别中的 API 仅具有极少的承诺。

如果您的 API 仅通过树内代码调用，并且通信双方始终是根据 Fuchsia 源代码的同一修订版本构建而成（就像两个平台组件会相互通信的情况），那么它应该为 internal。

请注意，即使 API 的所有客户端都在树内，也不足以说它属于 internal。例如，ffx 的源代码在紫红色树中，但不符合第二个要求：在一个 Fuchsia 修订版本中构建的 ffx 子工具经常与在另一个修订版本中构建的设备进行通信。因此，ffx 子工具以及 SDK 中提供的任何其他工件不得依赖于 internal API。

partner_internal

合作伙伴不使用 partner_internal API 编写自己的代码，但仍通过 Fuchsia 团队编写的工具、库或软件包间接依赖这些 API。由于使用这些 API 的代码归 Fuchsia 团队所有，因此我们可以在不流失合作伙伴的情况下更改这些 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 类别中。