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 测试，但不会破坏其他项目中的消费者。

再举一个例子，假设有一个 fuchsia.bar FIDL 库，其 SDK 类别为 partner，这意味着 fuchsia.bar 既可以在 Fuchsia 项目中使用，也可以由与 Fuchsia 项目合作的 SDK 消费者使用¹。如果有人更改 fuchsia.bar，则可能会破坏依赖于 fuchsia.bar 的合作伙伴，从而导致消费者出现更多问题。

如果不想向 SDK 用户公开预建 partner SDK atom 中使用的 API，则需要添加一种 SDK 类别。此 prebuilt 类别将强制执行与 partner 类别相同的 API 兼容性窗口，而无需将这些 API 添加到 SDK API Surface 区域。

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

请注意，此机制是对平台版本控制的 @available 机制的补充。@available 机制用于记录 FIDL API 的变更时间和方式。SDK 类别机制决定了 API 设计者可以多快进行更改的政策。

类别

已在 `sdk_atom` GN 规则中实现 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、库或现有 SDK atom 提升到这些类别之一，请参阅提升 API。

承诺

将 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 类别中。