此处提供的接口分类法分类旨在为接口的开发人员和用户提供指导。该分类指导开发人员声明界面的目标受众或用户及其稳定性。
给界面用户带来的好处:知道使用或不使用哪些界面及其稳定性。
对开发人员的好处:防止接口的意外更改,从而避免对用户或其他组件或系统的意外影响。这在具有许多开发人员的大型系统中特别有用,这些开发人员可能并不都具有项目的共享状态/历史记录。
Hadoop采用以下接口分类,该分类源自OpenSolaris分类法,并且在某种程度上源自Yahoo内部使用的分类法。界面具有两个主要属性:“受众”和“稳定性”。
听众表示界面的潜在消费者。尽管许多接口是实现的内部/专用接口,但其他接口是公共/外部接口,这些接口应供应用程序和/或客户端更广泛地使用。例如,在posix中,libc是外部或公共接口,而内核的大部分是内部或私有接口。此外,某些接口还针对其他特定子系统。
识别界面的受众有助于定义破坏界面的影响。例如,可以打破受众是少数特定子系统的接口的兼容性。另一方面,破坏数百万互联网用户所依赖的协议接口可能不适合。
Hadoop使用以下类型的受众,以增加/扩大可见性的顺序:
Hadoop没有公司专用分类,该分类专用于打算由公司内其他项目使用的API,因为它不适用于开源项目。此外,某些API的注释方式为@VisibleForTesting(来自com.google.common .annotations.VisibleForTesting)-它们应严格用于单元测试,应被视为“私有” API。
对API的更改可分为两大类:兼容和不兼容。兼容更改是满足以下条件的更改:
任何不满足这三个条件的更改都是不兼容的更改。仅声明兼容更改不会破坏现有客户。这些示例是兼容的更改:
这些示例是不兼容的更改:
稳定性表示接口的稳定性,以及何时允许对接口进行兼容和不兼容的更改。Hadoop API具有以下级别的稳定性。
稳定的接口被公开为首选的通信方式。稳定的界面在主要发行版中不会发生不兼容的更改,因此可以作为安全的开发目标。稳定的接口可能会在次要发行版之间兼容发展。
允许进行不兼容的更改:重大(X.0.0)允许进行兼容的更改:维护(xyZ)
不断发展的界面通常是公开的,以便用户或外部代码在功能稳定之前就可以使用它。但是,对接口应该“最终”稳定并提升为稳定的期望并不是将接口标记为“正在演进”的要求。
仅在次要发行版中才允许Evolving接口进行不兼容的更改。
允许进行不兼容的更改:次要(xY0)允许进行兼容的更改:维护(xyZ)
如何记录Hadoop API的分类?
每个接口或类都将使用org.apache.hadoop.classification包中的注释记录受众和稳定性。
Maven目标javadoc:javadoc生成的Javadoc仅列出公共API。
可以通过包含它们的包的受众派生java类和java接口的受众。因此,将每个java程序包的受众声明为公共或私有(以及私有受众变化)很有用。
如何为其他接口(例如CLI)记录分类?
为什么Java范围(私有,包私有和公共)不够好?
但是如果它是Java公共的,我可以轻松访问Private接口。保护和控制在哪里?
为什么要麻烦声明私有接口的稳定性?专用接口不是总是不稳定的吗?
使用稳定的专用接口的应用程序有什么危害?与Public Stable接口有什么不同?
为什么要打扰有限私有公司?它不是对某些项目给予特殊待遇吗?这不公平。
让我们将所有私有接口都视为针对所有Hadoop的受限私有。如果Hadoop系列中的项目可以访问私有类有什么害处?
并非所有的公共接口都稳定吗?