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 类别为 compat_test，则表示只有 Fuchsia 项目中的 CTF 测试可以依赖于 fuchsia.foo。如果有人想要更改 fuchsia.foo，则可能会破坏 Fuchsia 项目中的 CTF 测试，但不会破坏其他项目中的使用方。

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

如果不希望将预构建 partner SDK 原子中使用的 API 公开给 SDK 用户，则需要为这些 API 提供另一种类型的 SDK 类别。此 prebuilt 类别将强制执行与 partner 类别相同的 API 兼容性时间范围，而无需将这些 API 添加到 SDK API Surface 区域。

典型的 SDK Atom 在 SDK 之外开始其生命周期，没有 SDK 类别。当 SDK 中的主机工具或预编译库需要使用它时，系统可能会先将其添加到 SDK 的 host_tool 或 prebuilt 类别中。在某个时间点，API 委员会会将 SDK Atom 直接提升到 partner SDK 类别，通常是在合作伙伴需要访问 Atom 中包含的 API 时。

请注意，此机制与用于平台版本控制的 @available 机制相辅相成。@available 机制会记录 FIDL API 的更改时间和方式。SDK 类别机制决定了 API 设计师可以更改的速度政策。

类别

SDK 类别已在 每个 SDK Atom 都有一个 category 参数，该参数的值为以下值之一：

• compat_test：可用于配置和运行 CTF 测试，但不得公开用于 SDK 中的正式版或供主机工具使用。
• host_tool ：可以由平台组织提供的主机工具（例如 ffx）使用，但不得由 SDK 中的正式版代码或预构建二进制文件使用。
• prebuilt：可能是 SDK 中包含的预构建二进制文件用于与平台交互的 ABI 的一部分。
• partner ：包含在 SDK 中，供外部开发者直接使用该 API。

这些类别构成一个有序列表，受众群体呈单调递增趋势。例如，partner 类别中的 SDK Atom 必须可用于兼容性测试，partner 在此列表中位于 compat_test 之后。

承诺

将 API 添加到 partner 或 prebuilt 类别，就相当于向合作伙伴承诺，我们不会破坏其代码或对其施加不当的流失。每个拥有这类 API 的团队都有责任履行这些承诺。

host_tool

合作伙伴不会使用 host_tool API 编写自己的代码，也不会开发依赖于这些 API 的组件，但他们仍然会通过 Fuchsia 团队编写的开发者工具间接依赖于这些 API。由于 Fuchsia 团队拥有使用这些 API 的代码，因此我们可以更改这些 API，而不会流失合作伙伴。不过，使用 host_tool API 的工具通常会采用与其所对接的平台组件不同的修订版进行构建。因此，每当我们更改 host_tool API 时，都必须遵循我们的 ABI 兼容性政策。

也就是说，host_tool 类别的 API 所有者同意：

• 在其 API 上使用 FIDL 版本控制注解。
• 只能在 HEAD 或 NEXT 中修改其 API。一旦 API 级别被声明为稳定版，便不应再更改（请参阅 version_history.json）。
• 确保实现这些 API 的平台组件与 Fuchsia 支持的所有 API 级别兼容（请参阅 version_history.json）。

如需详细了解 API 兼容性，请参阅 API 演变指南。

prebuilt

合作伙伴不会使用 prebuilt API 编写自己的代码，但他们仍然通过 Fuchsia 团队编写的预构建库或软件包间接依赖于这些 API。由于 Fuchsia 团队拥有使用这些 API 的代码，因此我们可以更改这些 API，而不会流失合作伙伴。不过，使用 prebuilt API 的库和软件包通常会采用与其所对接的平台组件不同的修订版进行构建。因此，每当我们更改 prebuilt API 时，都必须遵循我们的 ABI 兼容性政策。

也就是说，prebuilt 类别的 API 所有者同意： * 履行上文 host_tool 部分中的所有版本控制承诺。

如需详细了解 API 兼容性，请参阅 API 演变指南。

partner

合作伙伴直接使用 partner API。这些 API 是我们合作伙伴构建应用的基础，我们有责任确保该基础可靠且稳定。

partner 类别的 API 所有者同意：

• 完成上述 prebuilt 部分中的所有版本控制承诺。

• 掌控合作伙伴在使用此 API 时的开发者体验，包括：

  • 提供良好的文档。
  • 遵循一致的样式。
  • 您希望在所用 SDK 中看到的任何其他内容。

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

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

  如果您决定进行不向后兼容的更改，则同意根据流失率政策支付该更改带来的大部分下游费用。

  在 API 稳定之前，更改更容易进行，因此任何计划中的 API 重构都应在将 API 添加到 SDK 类别之前完成，而不是之后。

更改历史记录

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