本文档的目的是为下游开发者提供一个明确的参考，以便在针对 Hadoop 源代码构建应用程序时了解预期内容。本文档主要是对Hadoop 兼容性指南的提炼，因此重点关注不同 Hadoop 接口在不同发行版中的兼容性保证。
本文档的目标受众是任何从事构建或依赖 Apache Hadoop 的项目或应用程序的开发者，无论依赖关系是源代码本身、构建工件还是与正在运行的系统交互。
Hadoop 开发社区定期发布新的 Hadoop 发行版，以引入新功能并修复现有问题。发行版分为三类
在编写调用方法或使用属于 Apache Hadoop 的类的软件时，开发人员应遵守以下准则。如果不遵守这些准则，可能会导致从一个 Hadoop 版本过渡到另一个版本时出现问题。
包、类和方法可以用受众注释进行注释。三个隐私级别为：公共、受限私有和私有。下游开发人员应仅使用标记为公共的包、类、方法和字段。未标记为公共的包、类和方法被视为 Hadoop 内部，仅供 Hadoop 的其他组件使用。
如果元素的注释与其包含元素的注释冲突，则最具限制性的注释优先。例如，如果私有方法包含在公共类中，则该方法应视为私有。如果公共方法包含在私有类中，则该方法应视为私有。
如果方法没有隐私注释，则它会从其类继承其隐私。如果类没有隐私，则它会从其包继承其隐私。如果包没有隐私，则应假定为私有。
包、类和方法可以使用稳定性注释进行注释。稳定性有三种类型：稳定、演进和不稳定。稳定性注释确定允许进行不兼容更改的时间。稳定表示主要版本之间不允许进行任何不兼容更改。演进表示次要版本之间不允许进行任何不兼容更改。不稳定表示随时允许进行不兼容更改。作为下游开发人员，最好避免使用不稳定API，并在可能的情况下优先使用稳定API。
如果方法没有稳定性注释，则它将继承其类的稳定性。如果类没有稳定性，则它将继承其包的稳定性。如果包没有稳定性，则应假定它是不稳定的。
根据上述 API 稳定性规则，新版本允许如下更改 API
| 版本类型 | 稳定 API 更改 | 演进 API 更改 | 不稳定 API 更改 |
|---|---|---|---|
| 主要 | 允许 | 允许 | 允许 |
| 次要 | 不允许 | 允许 | 允许 |
| 维护 | 不允许 | 不允许 | 允许 |
请注意，主要版本允许破坏任何 API 的兼容性，即使 Hadoop 开发人员社区尽可能努力维持兼容性，即使跨主要版本也是如此。另请注意，不稳定API 可能会在任何时间发生更改，恕不另行通知。
标注为 @Deprecated 的类或方法不再安全可用。已弃用的元素应继续发挥作用，但可能会在后续版本中被移除。稳定性注释将确定可以移除已弃用元素的最早版本。Stable 元素在下一个主要版本之前无法移除。Evolving 元素在下一个次要版本之前无法移除。Unstable 元素随时可能被移除，通常在移除之前不会被标记为已弃用。Stable 和 Evolving 元素必须在可以移除之前分别标记为已弃用一个完整的主要或次要版本。例如，如果 Stable 在 Hadoop 3.1 中被标记为已弃用，则在 Hadoop 5.0 之前无法将其移除。
Apache Hadoop 开发者社区致力于确保 API 的行为在各个版本中保持一致，尽管为了正确性而进行的更改可能会导致行为发生变化。API JavaDoc 被认为是 API 预期行为的主要权威。在 JavaDoc 不足或缺失的情况下，单元测试被认为是预期行为的备用权威。在没有单元测试的情况下，应从命名中推断出预期行为。下游开发者应尽可能避免查看 API 本身的源代码以确定预期行为，因为这种方法可能会创建对实现细节的依赖，而 Hadoop 开发者社区并未明确将其视为预期行为。
在 JavaDoc 不足以推断预期行为的情况下，强烈建议下游开发者提交 Hadoop JIRA 以请求添加或改进 JavaDoc。
请注意，出于正确性原因而进行的修复可能会导致 API 预期行为发生变化，尽管预计此类变化将附带澄清新行为的文档。
Apache Hadoop 开发人员社区尝试维护跨版本最终用户应用程序的二进制兼容性。理想情况下，在升级到新的 Hadoop 版本时不需要更新应用程序，假设应用程序不使用私有、有限私有或不稳定API。MapReduce 应用程序尤其保证跨版本具有二进制兼容性。
Hadoop 兼容性规范规定了 Hadoop 开发社区应遵守的标准，但由于各种原因，源代码可能无法达到兼容性规范的理想状态。
下游开发人员将遇到的两个常见问题是
在这两种情况下，强烈建议下游开发人员通过向相应的开发人员邮件列表发送电子邮件或提交 JIRA或两者向 Hadoop 开发人员社区提出问题。开发人员社区感谢您的反馈。
在针对 Hadoop 开发应用程序时遇到问题时，鼓励下游开发人员联系 Hadoop 开发人员社区。如果一个开发人员遇到问题，那么很可能许多开发人员已经或将遇到此问题。
在使用 Hadoop 中的流的具体情况下，例如 FSDataOutputStream，应用程序可以使用StreamCapabilities类的函数以编程方式查询流的功能。根据流功能进行动态调整可以使应用程序在不断变化的实现和环境中更加健壮。
Hadoop REST API 是各种下游和内部应用程序和服务的首要接口。为了支持 REST 客户端，Hadoop REST API 已进行版本控制，并且在版本内不会发生不兼容的更改。端点本身以及受支持的参数列表和端点输出均不得在 REST 端点版本内发生不兼容的更改。但是，请注意，引入新字段和其他附加更改被视为兼容性更改，因此 REST API 的任何使用者都应灵活到足以忽略未知字段。
REST API 版本是一个数字，与 Hadoop 版本号无关。版本号编码在端点 URL 中，前缀为“v”，例如“v1”。只有在次要或主要版本中才能引入新的 REST 端点版本。REST 端点版本只有在被标记为弃用一个完整的次要版本后才能被移除。
Hadoop 会生成各种输出，这些输出可能会被应用程序客户端或下游库使用。在使用 Hadoop 输出时，请考虑以下事项
Hadoop 用于存储数据的二进制文件格式（例如序列文件、HAR 文件等）保证在次要版本之间保持兼容性。此外，在主要版本之间进行更改时，必须保持向后和向前兼容性。请注意，只有序列文件格式保证不会发生不兼容的更改，而不是其中包含的序列化类。
除了操作生成的数据之外，Hadoop 还以各种格式将其状态信息保存在各种数据存储中，例如 HDFS 元数据存储、YARN 资源管理器状态存储和 YARN 联合状态存储。所有 Hadoop 内部数据存储都被视为内部数据存储，并且对 Hadoop 来说是 私有的。下游开发人员不应尝试使用 Hadoop 状态存储中的数据，因为数据和/或数据格式可能会发生不可预测的变化。
构成 Hadoop 命令行界面的工具集既可供最终用户使用，也可供创建执行 CLI 工具并解析输出的下游开发人员使用。出于此原因，Hadoop CLI 工具被视为一个界面，并在主要版本之间保持稳定。在主要版本之间，不会删除或更改任何 CLI 工具选项。CLI 工具的输出也会在主要版本号内保持不变。请注意，对 CLI 工具输出的任何更改都被视为不兼容的更改，因此在主要版本之间，CLI 输出不会更改。请注意，CLI 工具输出不同于 CLI 工具生成的日志输出。日志输出不适用于自动使用，并且可能随时更改。
Hadoop 公开的 Web UI 仅供人工使用。抓取 UI 中的数据不是受支持的用例。不会做出任何努力来确保在不同版本中任何 Web UI 中显示的数据之间的任何兼容性。
Hadoop 使用两种主要形式的配置文件：XML 配置文件和日志记录配置文件。
XML 配置文件包含一组属性，形式为名称-值对。属性的名称和含义由 Hadoop 定义，并且保证在小版本之间保持稳定。属性只能在主要版本中删除，并且仅当它已被标记为至少一个完整主要版本的弃用属性时才能删除。大多数属性都有一个默认值，如果在 XML 配置文件中未明确设置该属性，则将使用该默认值。默认属性值不会在维护版本期间更改。有关各种 Hadoop 组件支持的属性的详细信息，请参阅组件文档。
下游开发人员和用户可以将自己的属性添加到 XML 配置文件中，供其工具和应用程序使用。尽管 Hadoop 并未对定义新属性做出正式限制，但与 Hadoop 定义的属性冲突的新属性可能导致意外和不良结果。建议用户避免使用与 Hadoop 定义的属性命名空间冲突的自定义配置属性名称，因此应避免使用 Hadoop 使用的任何前缀，例如 hadoop、io、ipc、fs、net、ftp、ha、file、dfs、mapred、mapreduce 和 yarn。
Hadoop 守护程序和 CLI 生成的日志输出受一组配置文件的控制。这些文件控制 Hadoop 各个组件将输出的最低日志消息级别，以及这些消息的存储位置和方式。在小版本发布之间，不会对日志配置进行任何减少、消除或重定向日志消息的更改。
Hadoop 使用多种格式的许多其他类型的配置文件，例如 JSON 资源配置文件或 XML 公平调度程序配置。在小版本发布中，不会对配置文件格式引入不兼容的更改。即使在小版本发布之间，如果可能，也会避免不兼容的配置文件格式更改。
作为 Hadoop 的下游开发人员或使用者，可以访问 Hadoop 平台的所有元素，包括源代码、配置文件、构建工件等。虽然平台的开放性允许这样做，但开发人员不应创建对 Hadoop 这些内部细节的依赖关系，因为它们可能会随时更改。但是，Hadoop 开发社区将尝试在主要版本中保持现有结构的稳定性。
Hadoop 配置文件、作业历史信息（作业历史服务器使用）和 Hadoop 生成的日志文件的位置和总体结构将在维护版本中保持不变。
Hadoop 构建过程生成的构建工件（如 JAR 文件）随时可能发生更改，不应将其视为可靠的，客户端工件除外。客户端工件及其内容将在主要版本中保持兼容性。Hadoop 开发社区的目标是允许应用程序代码在小版本中继续保持不变，并在可能的情况下跨主要版本保持不变。当前的客户端工件列表如下
某些 Hadoop 组件通过环境变量接收信息。例如，HADOOP_OPTS 环境变量被大多数 Hadoop 进程解释为在启动新 JVM 时要使用的附加 JVM 参数字符串。在小版本之间，Hadoop 解释环境变量的方式不会以不兼容的方式更改。换句话说，放入同一变量中的相同值应针对同一主要版本中的所有 Hadoop 版本产生相同的结果。
Hadoop 依赖大量第三方库来进行操作。Hadoop 开发者社区尽可能地隐藏这些依赖项，使其免于下游开发者看到。一些常见库（如 Guava）可能会导致 Hadoop 与下游应用程序之间出现严重的兼容性问题，如果这些依赖项在下游公开的话。尽管如此，Hadoop 确实公开了一些依赖项，尤其是在 Hadoop 3 之前。Hadoop 通过主要版本之间的客户端工件不会公开任何新依赖项。
一个常见的下游反模式是使用 hadoop classpath 的输出设置下游应用程序的类路径，或将所有包含在 Hadoop 中的第三方 JAR 添加到下游应用程序的类路径。这种做法在下游应用程序与 Hadoop 的第三方依赖项之间建立了紧密耦合，从而导致了一个脆弱的应用程序，难以随着 Hadoop 依赖项的更改而维护。强烈不建议采用这种做法。
Hadoop 依赖于 Java 虚拟机来进行操作，这可能会影响下游应用程序。为了最大程度地减少中断，Hadoop 主要版本之间不会更改 JVM 的最低支持版本。如果在主要版本之间当前最低支持的 JVM 版本不再受支持，则可能会在小版本中更改最低支持的 JVM 版本。
Hadoop 还包括几个本机组件，包括压缩、容器执行器二进制文件和各种本机集成。这些本机组件为 Hadoop 引入了一组本机依赖项。本机依赖项的集合可能会在次要版本中发生更改，但 Hadoop 开发人员社区将尽可能地将任何依赖项版本更改限制为次要版本更改。
Hadoop 目前由 Hadoop 开发人员社区在运行 x86 和 AMD 处理器的 Linux 和 Windows 上提供支持。这些操作系统和处理器在可预见的未来可能会继续得到支持。如果支持计划发生更改，将在至少一个完整的次要版本（但理想情况下是一个完整的主要版本）中将要删除的操作系统或处理器记录为已弃用，然后再实际删除。Hadoop 可以在其他操作系统和处理器架构上运行，但社区可能无法在出现问题时提供帮助。
对于 Hadoop 守护进程所需的最低资源在不同版本（甚至维护版本）之间如何更改，没有任何保证。尽管如此，Hadoop 开发人员社区将尝试避免在次要版本中增加需求。
Hadoop 支持的任何文件系统（例如通过 FileSystem API）在大多数情况下将在整个主要版本中继续受到支持。在主要版本中删除对文件系统支持的唯一情况是提供了到备用客户端实现的干净迁移路径。
有关针对 Apache Hadoop 开发应用程序和项目的疑问，请联系相关组件的开发者邮件列表