--- layout: post title: 07.hadoop-2.7.2官网文档翻译-Hadoop接口类别 category: 技术 tags: Hadoop keywords: description: Hadoop接口分类：受众级和稳定级 --- {:toc} ### 动机 这里提供的接口分类是为指导开发者和用户的接口。该分类引导开发人员声明目标受众或者接口的用户，并且也声明它的稳定性。 - 对接口的用户的好处：知道哪个接口可用或不可用以及他们的稳定性 - 对开发者的好处：防止接口的意外变化，对用户或其他组件或系统的意外影响。对于不都有分享状态/历史的项目的很多开发者，这是特别有用的大系统。 ### 接口分级 Hadoop采用以下接口分类，该分类从[OpenSolaris分类](http://www.opensolaris.org/os/community/arc/policies/interface-taxonomy/#Advice){:target="_blank"}衍生出来并在一定程度上，来自于雅虎内部使用的分类。 接口有两种主要属性：受众和稳定 #### Audience(受众) Audience指出接口的潜在消费者。虽然许多接口都是内部实现或私有实现，其他的公共/外部接口是为了更广泛的被程序/客户端消费的。 比如，在POSIX中，`libc`是外部或公共的接口，而内核中大部分是内部或私有接口。也有一些接口是针对其他特定的子系统的。 识别接口的受众有助于定义打破它的影响。例如,打破受众是小数量指定子系统的接口的兼容性可能是OK的。另一方面，打破上百万的互联网用户依赖的协议接口可能是不好的。 为了增加可见度，Hadoop使用下面的几种受众： - `Private` - 该接口是为项目内部使用的(比如HDFS,MapReduce),并且不应该被应用程序或其他项目使用。它可以在任何时候没有提示的改变。项目中的大部分接口都是私有的(也可以叫：`project-private`)。 - `Limited-Private` - 该接口被指定的项目集或者系统(一般是紧密相关的项目)使用。其他项目或系统不应当使用该接口。接口的更改要与指定的姓名进行沟通，协商。 比如：在Hadoop项目中，一些接口是`LimitedPrivate`{HDFS,MapReduce},但他们对于HDFS或者MapReduce项目是私有的。 - `Public` - 该接口一般被任何应用程序使用。 Hadoop没有`Company-Private`(公司私有)的分类，意思是公司内部的其他项目依赖使用的API。因为它不支持开源项目。某些API也被注解为`@VisibleForTesting`（来自`com.google.common .annotations.VisibleForTesting`）-这些都是要严格用于单元测试并应该被视为私有的API。 #### Stability（稳定） Stability指出在接口进行不兼容的改变时，一个接口的稳定性。Hadoop的API有一下几种稳定级别。 - Stable(稳定) - 可以进化，同时保持小版本边界的兼容性。换句话说就是，只在主版本允许不兼容的改变被标记为稳定状态。 - Evolving(演进) - 正在演进，但是在小版本中允许不兼容的变化。 - Unstable(不稳定) - 任何时候都允许不稳定API的不兼容性改变。通常只用于私有接口场景。 - 然而，有人可能会称之为一个所谓的公共接口，强调它不应该被用来作为一个接口。对于公共接口，标记它为非接口可能比不稳定态更适合。 - 不稳定公共访问接口的例子(非接口)：GUI，输出格式改变的CLI。 - Deprecated(过期) - 那些在未来会被移除或不应该再被使用的接口。 ---- ### 分类是如何记录的 Hadoop的API是如何分类被记录的呢？ - 使用`org.apache.hadoop.classification`包内的注解，每个接口或类都有受众和稳定性记录 - 由maven target javadoc:javadoc 生成的javadoc仅仅包含公共API。 - 通过他们所包含的包的受众，可以得到java类和java接口的受众。因此，将每个包的受众声明为Public或private（随着私有受众的变化）是有用的。 ### FAQ - 为什么java的范围(private，package private 和public)不够好 - java的返回不够完全。为了其他内部组件的使用，类经常被强制为公共类型。它没有像`C++`中的友元或子包私有类型。 - 如果java是公共的，我可以很容易的获得一个私有的实现。保护和控制在哪里？ - 该目的不是提供绝对的访问控制。它的目标是与用户或开发者交流。一个人可以访问`libc`的私有实现方法；然而如果改变内部实现细节，你的程序将会崩溃并且你也不会从支持`libc`的人们那里获得任何同情。 如果你使用了非公开的接口，你懂的.. - 为什么要费事声明一个私有接口的稳定性呢？私有接口总是不稳定的吗？ - 私有接口不总是不稳定的。在他们稳定可以获取系统内部实行的情况下，可以将这些属性提供给它的内部用户或接口的开发者。 - 例如：在HDFS中,NN-DN协议是私有的但是稳定的，可以帮助实现滚动升级。它传达了该接口不应该以非兼容性更改，即使它也是私有的。 - 例如：在HDFS中，fsimage的稳定可以帮助提高回滚的灵活性。 - 在应用程序中使用一个私有的稳定接口有什么危害？它和公共的稳定接口有什么不同呢？ - 当一个私有接口被标记为稳定，意味着只能在主版本中改变。如果该接口的提供者想更改该接口的内部用户，稳定性将会被打破。此外一个公共稳定的接口即使在主版本也不大可能会打破兼容性（即使允许打破兼容性）。 因为更改的影响是巨大的。如果你使用了私有接口(先不管稳定性如何)，会有不兼容的危险。 - 为什么要操心`Limited-private`?它不是给予一些项目的特别待遇吗？这是不公平的。 - 首先，大部分接口是公共或私有的；事实上，让我们规定它更强大：使得它为私有除非想要把它暴露出去作为一般使用。 - 有限私有适用于不为一般使用的接口的。他们暴露给需要指定钩子的相关项目。这样的分类在限制性接口的供应者和消费者间有一个成本。 如果在未来有打破接口兼容性的需要，这两个将不得不协同工作。例如,供应者和消费者将不得不共努力得到各自的项目的协同发布。 如果你可以不使用私有这样做，这将不应该被轻视。如果接口是真的为所有应用程序的一般用途，那么这样做。 但是记住标记接口为公共需要承担巨大责任。有时限制性私有刚刚好。 - 限制性私有接口的一个很好的例子是`BlockLocations`,这是相当底层的接口，我们希望将他暴露给MR可能是HBase。我们可能会改变他的轨迹，那是我们会与MR团队在版本对接上有个协调。 虽然MR和HDFS总是在同一天发布，他们也可能改变轨迹。 - 如果你在许多项目上有限制性私有的接口，那么你是在愚弄你自己，那几乎就是公共的了。 - 对于Hadoop家族，声明一个指定的受众类别叫Hadoop级别私有或许是值得的。 - 让我们对所有的接口作为Hadoop的私有。那Hadoop家族中的项目访问私有类有什么危害吗？ - 我们想要MR访问在HDFS内部实现的class类，在代码中曾经有许多这样的层侵略，导致我们最近几年一直在清理。我们不希望想HDFS和MR这样的主要组件间内没有分隔的层入侵重新回来。 - 所有的公共接口都是稳定的吗？ - 可能会在公共接口的早期标记为`演进`，在这里，会为兼容性努力，但是兼容性在小版本可能会被打破。 - 公共接口不稳定的一个例子是，基于接口提供了一个标准的实现但仍然在开发中。比如，在进入市场的第一次尝试，大部分公司提供新的NFS协议的实现，即使该协议还没有被IETF全部完成。实现者不能使接口进化的原因至少存在。 因为稳定性是有标准组织控制的。这里就适当的为接口打上不稳定的标签。