本文档介绍了Apache Hadoop项目的兼容性目标。列举了影响Hadoop开发人员，下游项目和最终用户的Hadoop版本之间的不同类型的兼容性。对于每种类型的兼容性，本文档将：
所有Hadoop接口均根据目标受众和稳定性进行分类，以保持与先前版本的兼容性。有关分类的详细信息，请参见Hadoop接口分类法。
本文档供Hadoop开发人员社区使用。本文档描述了应该从哪个角度查看对Hadoop项目的更改。为了使最终用户和第三方开发人员对跨发行版兼容性充满信心，开发人员社区必须确保开发工作遵守这些策略。项目提交者有责任验证所有更改是保持兼容性还是被明确标记为不兼容。
在组件内，Hadoop开发人员可以自由使用私有和受限私有API，但是在使用来自其他模块的组件时，Hadoop开发人员应遵循与第三方开发人员相同的准则：请勿使用私有或受限私有（除非明确允许）接口和在可能的情况下，更喜欢稳定接口而不是演进接口或不稳定接口。在不可能的情况下，首选解决方案是扩大API的受众范围，而不是引入或永久保留这些兼容性准则的例外。在Maven模块中工作时，Hadoop开发人员应在使用其他Maven模块中的组件时应遵守相同的限制条件。
最重要的是，Hadoop开发人员必须注意其变更的影响。稳定的接口在主要版本之间不得更改。不断发展的接口在次要版本之间不得更改。必须为观众和稳定性适当地标记新的类和组件。有关何时使用各种标签的详细信息，请参见Hadoop接口分类法。通常，所有新接口和API都应使用标签数量最多的标签（例如，私有不稳定），以免妨碍接口或API的意图。
关键字“必须”，“不得”，“必须”，“应”，“不得”，“应”，“不应”，“推荐”，“可”和“可选”应解释为在RFC 2119中进行了描述。
Java API提供了@Deprecated批注，以将API元素标记为标记为要删除。注释的标准含义是不应使用API元素，并且可以在更高版本中将其删除。
在所有情况下，从API中删除元素都是不兼容的更改。元素的稳定性应确定何时允许这种更改。一个稳定为过时了整整主要版本才能删除它，并不得在未成年人或维护版本中移除的元素必须标明。一个不断发展为过时了整整次要版本后才能删除它和一个维护发行期间不得拆除元素必须标明。一个不稳定元件可以在任何时候被除去。在可能的情况下，应至少将不稳定元素标记为已弃用，至少释放一个之后再将其删除。例如，如果某个方法在Hadoop 2.8中被标记为已弃用，则直到Hadoop 4.0才能将其删除。
开发人员应该使用@InterfaceAudience和@InterfaceStability注释对所有Hadoop接口和类进行注释，以描述目标受众和稳定性。
注释可以在包，类或方法级别应用。如果方法没有隐私或稳定性注释，则它应从其所属的类继承其预期的受众或稳定性级别。如果一个类没有隐私或稳定性注释，则它将从其所属的包继承其预期的受众或稳定性级别。如果一个包没有隐私或稳定性注释，则应分别将其假定为Private和Unstable。
如果元素的听众或稳定注解与其父级的相应注解（无论是显式的还是继承的）相冲突，则该元素的听众或稳定性（分别）应由限制性更强的注解来确定。例如，如果Public类中包含Private方法，则该方法应被视为Private。如果Private类中包含Public方法，则该方法应视为Private。
兼容性策略应由相关的包，类或成员变量或方法注释确定。
注意：从原始文件生成的API必须与滚动升级兼容。有关更多详细信息，请参见“有线协议兼容性”部分。因此，API和有线协议的兼容性策略必须齐头并进。
Apache Hadoop努力确保API的行为在各个版本之间保持一致，尽管正确性的更改可能会导致行为的更改。API行为应由JavaDoc API文档（在此文档中存在且完整）指定。当JavaDoc API文档不可用时，应由相关单元测试所期望的行为来指定行为。如果没有JavaDoc API文档或单元测试的内容，则预期的行为被认为是显而易见的，并且应该假定是接口命名所暗示的最小功能。社区正在更加严格地指定一些API，并增强测试套件以验证是否符合规范，从而为可轻松测试的行为子集有效地创建了正式规范。
可以更改任何API的行为，以根据API的稳定性来修复错误行为，并伴随更新现有文档和测试和/或添加新文档或测试来进行。
Apache Hadoop修订版应该保留二进制兼容性，以便最终用户应用程序可以继续工作而无需进行任何修改。同一主要版本中的次要Apache Hadoop版本必须保持兼容性，以便现有的MapReduce应用程序（例如，最终用户应用程序和项目，例如Apache Pig，Apache Hive等），现有的YARN应用程序（例如，最终用户应用程序和项目，例如Apache Spark，Apache Tez等人）以及直接访问HDFS的应用程序（例如，最终用户应用程序和项目，例如Apache HBase，Apache Flume等人）在与同一主要版本中的任何Apache Hadoop集群一起使用时均无需修改即可工作，并且无需重新编译发布为原始构建目标。
特别是对于MapReduce应用程序，即使用org.apache.hadoop.mapred和/或org.apache.hadoop.mapreduce API的应用程序，开发人员社区应支持主要版本之间的二进制兼容性。所有主要版本均应兼容支持MapReduce API。有关更多详细信息，请参见hadoop-1.x和hadoop-2.x之间的MapReduce应用程序兼容性。
某些应用程序可能会受到磁盘布局更改或其他内部更改的影响。有关如何处理对非API接口的不兼容更改的策略，请参阅以下各节。
Hadoop包括几个本地组件，包括压缩，容器执行程序二进制文件和各种本地集成。这些本机组件在编译时和运行时都为Hadoop引入了一组本机依赖关系，例如cmake，gcc，zlib等。这组本机依赖关系是Hadoop ABI的一部分。
Hadoop在编译时和/或运行时所依赖的本机组件的最低要求版本应被视为Evolving。在主要版本的次要版本之间，最低要求版本不应增加，尽管可能会由于安全问题，许可问题或其他原因而进行更新。当必须在主要版本的次要版本之间更新Hadoop依赖的本机组件时，在可能的情况下，更改应仅更改组件的次要版本，而不更改主要版本。
线兼容性是指数据在Hadoop流程之间“通过线”传输。Hadoop使用协议缓冲区进行大多数RPC通信。保持兼容性要求禁止如下所述的修改。还应考虑非RPC通信，例如，使用HTTP传输HDFS映像作为快照的一部分或传输MapReduce映射任务输出。通信可以分类如下：
除了协议本身的兼容性以外，维持跨版本通信还要求所支持的传输也要稳定。传输更改的最可能来源来自安全传输，例如SSL。将服务从SSLv2升级到SSLv3可能会破坏现有的SSLv2客户端。在主要版本的次要版本之间，不应提高任何传输的受支持的最低主要版本，尽管可能会由于安全问题，许可问题或其他原因而进行更新。当必须在主要版本的次要版本之间更新传输时，在可能的情况下，更改应仅更改组件的次要版本而不更改主要版本。
服务端口被视为传输机制的一部分。默认服务端口号必须保持一致，以防止破坏客户端。
Hadoop有线协议在.proto（ProtocolBuffers）文件中定义。客户端-服务器和服务器-服务器协议应根据其.proto文件中注明的受众群体和稳定性分类进行分类。在没有分类的情况下，应该假定协议是Private和Stable。
对.proto文件的以下更改应被认为是兼容的：
对.proto文件的以下更改应被视为不兼容：
对.proto文件的以下更改应被视为不兼容：
未通过.proto文件定义的Hadoop有线协议应被视为Private和Stable。
除了稳定性之外，Hadoop的有线协议还必须根据以下规定在主要版本的次要版本之间向前兼容：
新的传输机制只能在次要或主要版本更改的情况下引入。现有传输机制必须在主要版本中的所有次要版本中继续得到支持。默认服务端口号应视为稳定。
REST API兼容性适用于公开的REST端点（URL）和响应数据格式。Hadoop REST API专门用于客户端在各个版本（甚至主要版本）中的稳定使用。就本文档而言，公开的PEST API是公开文档中记录的API。以下是公开的REST API的非详尽列表：
每个API都有一个特定于API的版本号。任何不兼容的更改都必须增加API版本号。
几个组件具有审核日志记录系统，它们以机器可读格式记录系统信息。对该数据格式进行不兼容的更改可能会破坏现有的自动化实用程序。对于审核日志，不兼容的更改是指更改格式的任何更改，以使现有解析器不再能够解析日志。
用户和系统级数据（包括元数据）存储在各种格式的文件中。对用于存储数据/元数据的元数据或文件格式的更改可能会导致版本之间的不兼容性。每种文件格式都在下面介绍。
Hadoop内部数据也可以存储在文件或其他数据存储中。更改这些数据存储的架构可能会导致不兼容。
HDFS以专用文件格式保留元数据（图像和编辑日志）。格式或元数据的不兼容更改会阻止后续版本读取较旧的元数据。不兼容的更改必须包括一个可以升级现有元数据的过程。
根据更改的不兼容程度，可能会出现以下潜在情况：
HDFS数据节点将数据存储在专用目录结构中。对目录结构的不兼容更改可能会阻止较早的发行版访问存储的数据。不兼容的更改必须包括一个可以升级现有数据目录的过程。
对于Hadoop S3客户端（s3a）中读取或修改文件元数据的每个操作，该文件元数据的卷影副本都存储在单独的元数据存储中，这为元数据提供了类似HDFS的一致性，并且还可以提供更快的查找速度。文件状态或目录列表之类的东西。使用指示兼容性的版本标记创建S3A保护表。
YARN资源管理器将有关群集状态的信息存储在外部状态存储中，以用于故障转移和恢复。如果用于状态存储数据的架构不保持兼容，则资源管理器将无法恢复其状态，并且将无法启动。状态存储数据模式包括指示兼容性的版本号。
Hadoop命令行程序可以直接通过系统外壳或外壳脚本使用。CLI既包括面向用户的命令（例如hdfs命令或yarn命令），也包括面向管理员的命令（例如用于启动和停止守护程序的脚本）。更改命令路径，删除或重命名命令行选项，参数顺序或命令返回代码以及输出中断兼容性会给用户带来不利影响。
Web UI（尤其是网页的内容和布局）的更改可能会干扰屏幕上抓取网页以获取信息的尝试。但是，Hadoop Web UI页面并不意味着要被删除，例如出于自动化目的。希望用户使用REST API以编程方式访问群集信息。
用户依赖于Hadoop集群的行为在各个版本之间保持一致。导致群集行为异常不同的更改可能会导致沮丧和长时间的采用周期。假设群集的配置文件保持不变，则不应添加任何新配置来更改现有群集的行为。对于定义的任何新设置，应注意确保新设置不会更改现有群集的行为。
用户使用Hadoop定义的属性来配置并向Hadoop和自定义属性提供提示，以将信息传递给作业。鼓励用户避免使用与Hadoop定义的属性的名称空间冲突的自定义配置属性名称，并应避免使用Hadoop使用的任何前缀，例如hadoop，io，ipc，fs，net，file，ftp，kfs，ha，file ，dfs，mapred，mapreduce和yarn。
除了属性文件之外，Hadoop还使用其他配置文件来设置系统行为，例如公平调度程序配置文件或资源配置文件配置文件。
源代码，工件（源和测试），用户日志，配置文件，输出和作业历史记录都存储在本地文件系统或HDFS的磁盘上。更改这些用户可访问文件的目录结构可能会破坏兼容性，即使在原始路径是通过符号链接保留的情况下（例如，当路径被配置为不遵循符号链接的servlet访问时）。
Hadoop provides several client artifacts that applications use to interact with the system. These artifacts typically have their own dependencies on common libraries. In the cases where these dependencies are exposed to end user applications or downstream consumers (i.e. not shaded) changes to these dependencies can be disruptive. Developers are strongly encouraged to avoid exposing dependencies to clients by using techniques such as shading.
With regard to dependencies, adding a dependency is an incompatible change, whereas removing a dependency is a compatible change.
Some user applications built against Hadoop may add all Hadoop JAR files (including Hadoop’s library dependencies) to the application’s classpath. Adding new dependencies or updating the versions of existing dependencies may interfere with those in applications’ classpaths and hence their correct operation. Users are therefore discouraged from adopting this practice.
Users and related projects often utilize the environment variables exported by Hadoop (e.g. HADOOP_CONF_DIR). Removing or renaming environment variables can therefore impact end user applications.
Hadoop uses Maven for project management. Changes to the contents of generated artifacts can impact existing user applications.
The contents of Hadoop test artifacts SHALL be considered Private and Unstable. Test artifacts include all JAR files generated from test source code and all JAR files that include “tests” in the file name.
The Hadoop client artifacts SHALL be considered Public and Stable. Client artifacts are the following:
All other build artifacts SHALL be considered Private and Unstable.
To keep up with the latest advances in hardware, operating systems, JVMs, and other software, new Hadoop releases may include features that require newer hardware, operating systems releases, or JVM versions than previous Hadoop releases. For a specific environment, upgrading Hadoop might require upgrading other dependent software components.
Here are some relevant JIRAs and pages related to the topic: