Hadoop 文档

General

Common

HDFS

MapReduce

MapReduce REST APIs

YARN

YARN REST APIs

YARN Service

Submarine

Hadoop Compatible File Systems

Auth

Tools

Reference

Configuration

动机

此处提供的接口分类法分类旨在为接口的开发人员和用户提供指导。该分类指导开发人员声明界面的目标受众或用户及其稳定性。

  • 给界面用户带来的好处:知道使用或不使用哪些界面及其稳定性。

  • 对开发人员的好处:防止接口的意外更改,从而避免对用户或其他组件或系统的意外影响。这在具有许多开发人员的大型系统中特别有用,这些开发人员可能并不都具有项目的共享状态/历史记录。

接口分类

Hadoop采用以下接口分类,该分类源自OpenSolaris分类法,并且在某种程度上源自Yahoo内部使用的分类法。界面具有两个主要属性:“受众”和“稳定性”。

听众

听众表示界面的潜在消费者。尽管许多接口是实现的内部/专用接口,但其他接口是公共/外部接口,这些接口应供应用程序和/或客户端更广泛地使用。例如,在posix中,libc是外部或公共接口,而内核的大部分是内部或私有接口。此外,某些接口还针对其他特定子系统。

识别界面的受众有助于定义破坏界面的影响。例如,可以打破受众是少数特定子系统的接口的兼容性。另一方面,破坏数百万互联网用户所依赖的协议接口可能不适合。

Hadoop使用以下类型的受众,以增加/扩大可见性的顺序:

Hadoop没有公司专用分类,该分类专用于打算由公司内其他项目使用的API,因为它不适用于开源项目。此外,某些API的注释方式为@VisibleForTesting(来自com.google.common .annotations.VisibleForTesting)-它们应严格用于单元测试,应被视为“私有” API。

私人的

专用接口仅供项目内部使用(例如HDFS或MapReduce),不应由应用程序或其他项目使用。项目的大多数接口都是专用的(也称为项目专用)。除非有意将接口暴露给外部使用,否则应将其标记为私有。

私人有限公司

一组特定的项目或系统(通常是紧密相关的项目)使用Limited-Private接口。其他项目或系统不应使用该界面。对接口的更改将与指定的项目进行通信/协商。例如,在Hadoop项目中,某些接口是LimitedPrivate {HDFS,MapReduce},因为它们是HDFS和MapReduce项目的专用接口。

上市

公共接口可供任何应用程序通用。

变更相容性

对API的更改可分为两大类:兼容和不兼容。兼容更改是满足以下条件的更改:

  • 没有删除现有功能,
  • 没有对现有功能进行任何修改,以防止被构造为在更改之前使用该接口的客户端使用它们,以及
  • 不会添加任何功能,这些功能要求更改为构造为使用接口的客户端,然后再进行更改。

任何不满足这三个条件的更改都是不兼容的更改。仅声明兼容更改不会破坏现有客户。这些示例是兼容的更改:

  • 向Java类添加方法,
  • 向RESTful Web服务添加可选参数,或者
  • 向XML文档添加标签。
  • 使界面的受众注释更广泛(例如,从私有到公共)或更改兼容性注释更严格(例如,从演进到稳定)

这些示例是不兼容的更改:

  • 从Java类中删除方法,
  • 向Java接口添加方法,
  • 向RESTful Web服务添加必需的参数,或
  • 重命名JSON文档中的字段。
  • 使界面的受众注释范围更广(例如,从“公共”到“有限私人”),或者更改兼容性注释的限制更严格(例如,从“演进”到“不稳定”)

稳定性

稳定性表示接口的稳定性,以及何时允许对接口进行兼容和不兼容的更改。Hadoop API具有以下级别的稳定性。

稳定

稳定的接口被公开为首选的通信方式。稳定的界面在主要发行版中不会发生不兼容的更改,因此可以作为安全的开发目标。稳定的接口可能会在次要发行版之间兼容发展。

允许进行不兼容的更改:重大(X.0.0)允许进行兼容的更改:维护(xyZ)

不断发展

不断发展的界面通常是公开的,以便用户或外部代码在功能稳定之前就可以使用它。但是,对接口应该“最终”稳定并提升为稳定的期望并不是将接口标记为“正在演进”的要求。

仅在次要发行版中才允许Evolving接口进行不兼容的更改。

允许进行不兼容的更改:次要(xY0)允许进行兼容的更改:维护(xyZ)

不稳定的

不稳定接口是不保证兼容性的接口。不稳定的接口不一定是不稳定的。通常会暴露不稳定的接口,因为用户或外部代码需要访问不打算使用的接口。该接口公开为不稳定接口,以明确声明即使该接口公开,它也不是首选的访问路径,并且不为其提供兼容性保证。

除非有理由在接口上提供兼容性保证,否则无论接口是否公开,都应将其标记为不稳定。在大多数情况下,专用接口也应该不稳定。

随时可以对不稳定接口进行不兼容的更改。

允许进行不兼容的更改:维护(xyZ)允许进行兼容的更改:维护(xyZ)

不推荐使用

不推荐使用的接口将来可能会被删除,因此不应使用。即使这样,不推荐使用的接口也将继续起作用,直到将其删除。何时可以删除不推荐使用的接口,取决于它是否也是稳定,演进或不稳定的。

分类如何记录?

如何记录Hadoop API的分类?

  • 每个接口或类都将使用org.apache.hadoop.classification包中的注释记录受众和稳定性。

  • Maven目标javadoc:javadoc生成的Javadoc仅列出公共API。

  • 可以通过包含它们的包的受众派生java类和java接口的受众。因此,将每个java程序包的受众声明为公共或私有(以及私有受众变化)很有用。

如何为其他接口(例如CLI)记录分类?

常问问题

  • 为什么Java范围(私有,包私有和公共)不够好?

    • Java的作用域不是很完整。人们常常被迫公开一门课程,以便其他内部组件使用它。它还没有C ++之类的朋友或私有子包。
  • 但是如果它是Java公共的,我可以轻松访问Private接口。保护和控制在哪里?

    • 此分类方案的目的不是提供绝对访问控制。其目的是与用户和开发人员进行沟通。一个可以访问libc中的私有实现功能;但是,如果他们更改了内部实现的详细信息,则该应用程序将中断,并且几乎不会从提供libc的人员那里得到同情。使用非公开接口时,可以理解风险。
  • 为什么要麻烦声明私有接口的稳定性?专用接口不是总是不稳定的吗?

    • 专用接口并不总是不稳定的。在稳定的情况下,它们会捕获系统的内部属性,并将这些属性传达给系统内部用户和接口开发人员。
      • 例如,在HDFS中,NN-DN协议是私有但稳定的,可以帮助实现滚动升级。稳定性注释表明,即使此接口是私有的,也不应以不兼容的方式对其进行更改。
      • 例如,在HDFS,FSImage中,“稳定”名称提供了更灵活的回滚。
  • 使用稳定的专用接口的应用程序有什么危害?与Public Stable接口有什么不同?

    • 虽然标记为“稳定”的专用接口仅在主要发行版本上进行了更改,但如果该接口的提供者也愿意更改该接口的内部使用者,则它可能会在其他时间中断。此外,由于变更的影响更大,因此公共稳定接口在主要版本上收支平衡的可能性较小(即使允许破坏兼容性)。如果使用专用接口(无论其稳定性如何),都将面临不兼容的风险。
  • 为什么要打扰有限私有公司?它不是对某些项目给予特殊待遇吗?这不公平。

    • 大多数接口应为“公共”或“专用”。除非接口明确打算用于一般用途,否则接口应为私有。
    • 受限私有用于非常规用途的接口。他们接触到需要特殊挂钩的相关项目。这样的分类对接口的供应商和消费者都有成本。如果将来有需要中断接口,则两者都将必须一起工作。例如,供应商和消费者将必须共同努力以协调发布各自项目。不得轻视此合同-如有可能,请使用Private。如果该接口确实供所有应用程序通用,则使用Public。永远记住,将接口设为“公共”会带来巨大的责任负担。有时,有限私有是正确的。
    • 限制私有接口的一个很好的例子是BlockLocations。该接口是暴露于MapReduce和HBase的相当低级的接口。该界面很可能会改变,届时必须与MapReduce开发团队协调发布工作。虽然MapReduce和HDFS始终在今天同步发布,但该策略可能会改变。
    • 如果您有一个有限私有界面,其中列出了许多项目,那么该界面很可能会被公开。
  • 让我们将所有私有接口都视为针对所有Hadoop的受限私有。如果Hadoop系列中的项目可以访问私有类有什么害处?

    • 在代码中,曾经有很多情况,一个项目依赖于另一个项目的内部实现细节。付出了巨大的努力来清理这些问题。对于所有Hadoop,将所有接口作为“有限私有”开放将为重新引入此类耦合问题打开大门。
  • 并非所有的公共接口都稳定吗?

    • 早期可能会将“公共”界面标记为“不断发展”。这里有希望做出努力以进行兼容的更改,但可能需要在较小的发行版本中将其破坏。
    • 不稳定的公共接口的一个示例是提供仍在开发中的基于标准主体的接口的实现。例如,许多公司试图率先进入市场,即使IETF尚未完全完成该协议,也提供了新NFS协议的实现。由于稳定性是由标准主体控制的,因此实现者无法以引起最少中断的方式改进接口。因此,将接口标记为不稳定是合适的。