本文档的重点是为下游开发人员提供清晰的参考，以供参考针对Hadoop源库构建应用程序时的期望。本文档主要是对Hadoop兼容性指南的精炼，因此着重于跨版本的各种Hadoop接口的兼容性保证。
Hadoop开发社区会定期发布新的Hadoop版本，以引入新功能并解决现有问题。Realeses分为三类：
在编写调用方法或使用属于Apache Hadoop的类的软件时，开发人员应遵循以下准则。不遵守准则可能会导致从一个Hadoop版本过渡到另一个Hadoop版本的问题。
包，类和方法可以使用受众注释来注释。三种隐私级别是：公共，有限私有和私有。下游开发人员应仅使用标记为Public的包，类，方法和字段。未标记为Public的包，类和方法被认为是Hadoop内部的，仅供Hadoop的其他组件使用。
如果元素的注释与其包含元素的注释冲突，则限制性最强的注释优先。例如，如果Public类中包含Private方法，则该方法应视为Private。如果Private类中包含Public方法，则该方法应视为Private。
如果方法没有隐私注释，则它从其类继承其隐私。如果一个类没有隐私，它将从其包继承其隐私。如果软件包没有隐私，则应假定其为Private。
包，类和方法可以用稳定性注释来注释。稳定分为三类：稳定，不断发展和不稳定。稳定性注释确定何时允许进行不兼容的更改。稳定意味着不允许在主要版本之间进行不兼容的更改。不断发展意味着在次要发行版之间不允许有不兼容的更改。不稳定表示随时可以进行不兼容的更改。作为下游开发人员，最好避免使用不稳定的 API，并尽可能选择稳定的API 。
如果方法没有稳定性注释，则它从其类继承其稳定性。如果一个类没有稳定性，它将从其包继承其稳定性。如果包装没有稳定性，则应将其视为不稳定。
根据上述关于API稳定性的规则，允许新版本按以下方式更改API：
| 发行类型 | 稳定的API更改 | 不断变化的API变更 | API不稳定 |
|---|---|---|---|
| 重大的 | 允许的 | 允许的 | 允许的 |
| 次要 | 不允许 | 允许的 | 允许的 |
| 保养 | 不允许 | 不允许 | 允许的 |
请注意，即使Hadoop开发人员社区力求尽可能保持兼容性，即使跨主要版本，也允许主要版本破坏任何API的兼容性。另请注意，不稳定的 API可能随时更改，恕不另行通知。
注释为@Deprecated的类或方法将不再安全使用。不推荐使用的元素应该继续起作用，但是可能并且很可能在后续发行版中将其删除。稳定性注释将确定何时可以删除不赞成使用的元素的最早发布。一个稳定的元素不能被删除，直到下一个重要版本。一个不断发展的元素不能被删除，直到下一个次要版本。一个不稳定的元件可以在任何时候被移除并且为废弃它被删除之前通常将不被标记。必须先将稳定和不断发展的元素标记为不推荐使用，以完全释放主要版本或次要版本，然后再将其删除。例如，如果稳定在Hadoop 3.1中被标记为已弃用，直到Hadoop 5.0才能将其删除。
Apache Hadoop开发人员社区致力于确保API的行为在各个版本之间保持一致，尽管正确性的更改可能会导致行为的更改。API JavaDoc被认为是API预期行为的主要授权。如果JavaDoc不足或丢失，则将单元测试视为预期行为的后备授权。如果没有单元测试，则应从命名中推断出预期的行为。下游开发人员应尽可能避免查看API本身的源代码来确定预期的行为，因为该方法会创建对实现细节的依赖，而Hadoop开发社区并未明确地将其依赖于预期的行为。
如果JavaDocs不足以推断预期的行为，强烈建议下游开发人员提交Hadoop JIRA，以请求添加或改进JavaDocs。
请注意，出于正确性原因进行的修复可能会导致API的预期行为发生更改，尽管此类更改预计会随附说明新行为的文档。
Apache Hadoop开发人员社区试图维护跨发行版的最终用户应用程序的二进制兼容性。理想情况下，假设应用程序未使用Private，Limited-Private或Unstable API ，则在升级到新的Hadoop版本时，无需更新应用程序。特别是MapReduce应用程序可确保跨版本的二进制兼容性。
在Hadoop的兼容性规范规定的标准是Hadoop的开发社区有望维持，但由于种种原因，源代码可能不会辜负的理想兼容性规范。
下游开发人员将遇到的两个常见问题是：
在这两种情况下，都强烈建议下游开发人员向Hadoop开发人员社区提出问题，方法是将电子邮件发送到适当的开发人员邮件列表或提交JIRA或同时提交这两种方法。开发者社区感谢您的反馈。
在针对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使用两种主要形式的配置文件：XML配置文件和日志记录配置文件。
XML配置文件包含一组作为名称/值对的属性。属性的名称和含义由Hadoop定义，并保证在次要版本中稳定。只有在至少一个完整的主要版本中将其标记为不推荐使用时，才可以在主要版本中删除该属性。如果未在XML配置文件中显式设置该属性，则大多数属性都有默认值。在维护版本中，不会更改默认属性值。有关各种Hadoop组件支持的属性的详细信息，请参阅组件文档。
下游开发人员和用户可以将自己的属性添加到XML配置文件中，以供其工具和应用程序使用。尽管Hadoop在定义新属性方面没有正式的限制，但是与Hadoop定义的属性冲突的新属性可能会导致意想不到的不良结果。鼓励用户避免使用与Hadoop定义的属性的名称空间冲突的自定义配置属性名称，因此应避免使用Hadoop使用的任何前缀，例如hadoop，io，ipc，fs，net，file，ftp，kfs，ha，文件，dfs，mapred，mapreduce和yarn。
作为Hadoop的下游开发人员或使用者，可以访问Hadoop平台的所有元素，包括源代码，配置文件，构建工件等。尽管平台的开放性质允许它，但开发人员不应在这些内部组件上创建依赖关系。 Hadoop的详细信息，因为它们可能随时更改。但是，Hadoop开发社区将尝试在一个主要版本中保持现有结构的稳定性。
Hadoop配置文件的位置和一般结构，作业历史记录信息（由作业历史记录服务器使用）以及由Hadoop生成的日志文件将在维护版本之间进行维护。
由Hadoop生成过程生成的生成工件（例如JAR文件）随时可能更改，除了客户端工件外，不应将其视为可靠的。客户端工件及其内容将在主要版本中保持兼容。Hadoop开发社区的目标是允许应用程序代码在次要版本之间以及可能的情况下在主要版本之间继续保持不变。当前客户端工件的列表如下：
某些Hadoop组件通过环境变量接收信息。例如，大多数Hadoop进程将HADOOP_OPTS环境变量解释为在启动新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目前受到运行在x86和AMD处理器上的Linux和Windows上的Hadoop开发人员社区的支持。在可预见的将来，这些操作系统和处理器可能仍会受到支持。如果支持计划发生更改，则要删除的OS或处理器至少在完整的次要版本（但最好是完整的主要版本）之前被记录为已弃用，然后才实际删除。Hadoop可以在其他OS和处理器体系结构上运行，但是社区可能无法在出现问题时提供帮助。
不能保证Hadoop守护程序所需的最小资源在各个版本（甚至维护版本）之间如何变化。尽管如此，Hadoop开发人员社区将尽力避免在次要版本中增加要求。
在大多数情况下，在整个主要版本中，将继续继续支持所有受支持的Hadoop文件系统（例如通过FileSystem API）。可以在主要版本中放弃对文件系统的支持的唯一情况是，是否提供了到备用客户端实现的干净迁移路径。