了解如何使用 Eclipse 管理应用程序的 API
创建 Application Public Interface（API），尤其是管理各个版本的 API 十分困难。了解如何利用 Eclipse 的 PDE API Tools 来简化此过程，并且无缝地将其集成到日常开发中。注意，本文专门针对 Eclipse V3.4：Ganymede。
在详细介绍 Eclipse Plug-in Development Environment（PDE）内的 Application Public Interface（API）工具之前，让我们谈一谈 Eclipse 中的 API 的含义。
什 么是 API？
您是否曾经在 Eclipse 中收到以下警告或错误，并且想知道它们的含义是什么？
图 1. 阻止访问
内部包
根据 命名约定，能否真正在插件中构成包 API 取决于是否把包导出到 MANIFEST.MF 文件中。如果是，则视为 API。要创建不是 API 的内容，您可以用 x-internal:=true 属性标记导出的包。这将指示 Eclipse 导 出的包可供使用，但是被视为内部包。
导致警告的原因很可能是您正在访问不能使用某种形式的 API 公开访问的代码。通常，API 元素都经过良好记录并且有某种规范。另一方面，非 API 元素被视为内部 实现详细信息，并且常常不附带发布文档。上图的 Eclipse 通知您访问了这些内部元素。Eclipse 礼貌 地警告您正在访问可能更改并且不受官方支持的代码。那么，确切地说 API 是什么？
由于 Eclipse 基于 Java™ 编程语言，因此有四种 API 元素。让我们逐个查看。
API 包 至少包 含一个 API 类或 API 接口的包。
表 1. Eclipse 平台中的包命名约定
命名约定 示例包 org.eclipse.xyz.* org.eclipse.ui、 org.eclipse.swt.widgets org.eclipse.xyz.internal.* org.eclipse.comp are.internal、 org.eclipse.ui.internal org.eclipse.xyz.internal.provisional.* org. eclipse.equinox.internal.provisional.p2.engineAPI 类或接口 API 包中的 public 类或接口，或者在某个其他 API 类或接口中声明或继承的 public 或 protected 类或接口成员 。 API 方法 在 API 类或接口中声明或继承的 public 或 protected 方法或构造函数。 API 字段 在 API 类或接口中声明或继承的 public 或 protected 字段。
现在我们已经知道各种各样的 API 元素 ，让我们讨论 API Tools 及它如何能为您管理这些 API 元素。
什么是 API Tools？
API Tools 的目的是帮助维护优秀的 API。API Tools 通过报告 API 缺陷来实现维护，例如二进制文件不兼 容、不正确的插件版本号、缺少或不正确的 @since 标记及在插件之间使用非 API 代码。具体地说，它 设计用于：
识别两个版本的软件组件或产品之间的二进制文件不兼容问题。
基于 Eclipse 版本控制方案更新插件的版本号。
为新添加的类、接口和方法更新 @since 标记。
提供新的 javadoc 标记和代码，帮助注释有特殊限制的类型。
利用现有信息（位于 MANIFEST.MF 中）定义 Bundle 之间的包的可见性。
在插件之间识别非 API 代码的使用。
识别非 API 类型是否泄露到 API 中。
添加 API Tools
要在项目内使用 API Tools，您需要完成两项工作：设置 API 基准和向相关的项目添加 API Tools 属性。
设置 API 基准
要知道是否在破坏 API 的规范，需要设置某种基准以进行兼容性分析。在 API Tools 中， 这称为 API 基准并且可以通过 API Baselines 首选项页面设置（参见图 2）。设置 API 基准就像指向 基于现有的 Eclipse 安装一样简单。当 API Tools 扫描插件时，它将为您动态生成一个基准。在设置基 准后，需要让 Eclipse 项目利用 API Tools。注意，此过程也可以作为构建系统的一部分以无序方式完 成，但是这不在本文讨论范围内，并且建议查阅 API Tools wiki 以获得更多信息（请参阅 参考资料） 。
图 2. 添加 API 基准
添加 API Tools 项 目属性
要查看与 API Tools 相关的任何错误或警告，您的项目需要添加 API Analysis 属性和构 建器。这可以通过两种方法完成，并且依赖于是否要将 API Tools 应用到现有项目中。如果与现有项目 结合使用，建议的方法是使用 API Tooling Setup 向导（参见图 3）。右键单击项目并选择 PDE Tools > API Tooling Setup 可以访问该向导。在向导中，只需单击想要转换为使用 API Tools 的项目并单 击 Finish。这就完成了！
图 3. API Tooling Setup 向导
也可以在创建插件 项目时利用 API Tools。在 Eclipse V3.4 中，New Plug-in Project 向导增加了额外的复选框 Enable API Analysis 把 API 分析属性添加到项目中。
图 4. 新插件项目向导中的 API Tools
使用 API Tools
现在我们知道如何将项目设为使用 API Tools，让我们查看一些示例，了解 API Tools 是如何帮助我们的。API Tools 拥有一组注释，您可以在各个 API 元素中使用这些注释以增强限 制。
表 2. API 限制
注释 有效的 API 元素 描述 @noimplement 接口 表示客户端不能实现此接口。使用关联接口的 implements 或 extends 关键字的所有类将被标记为有问题。 @noextend 类 表示客户端不能扩展该类。使用关联类的 extends 关键字的所有类将被标记为有问题。 @noinstantiate 类 表示客户端不能初始化该类。用任何构造函数 初始化关联类的所有代码将被标记为有问题。 @nooverride 方法 表示客户端不能重新声明该方法。定义覆盖关联方法的方法的所有子类将被标记为有问题。 @noreference 方法、构造函数和字段（非最终） 表示客户端不能 引用此方法、构造函数或非最终字段。直接调用关联方法或构造函数，或者引用关联的非最终字段的所有 代码将被标记为有问题。现在您已经知道了可用的 API 限制注释，让我们看 看一些示例，了解它们在现实世界中是如何工作的。
API 限制示例
让我们从一个非常简单 的示例开始，如带有允许生成小部件的 API 的插件。
清单 1. IWidget.java
package org.eclipse.example.widgetfacTory;/*** A simple widget** @noimplement*/public interface IWidget { public String getName(); public long getId();}
在本例中，小部件只有名称和标识符。用限制注释接口，可以告诉客户端不实现此接口，因为 我们需要客户端实现以下的抽象小部件。
清单 2. AbstractWidget.java
package org.eclipse.example.widgetfacTory;/*** An abstract widget*/public abstract class AbstractWidget implements IWidget { /** * @nooverride */ public long getId() { return Math.round(Math.random()); }}
我们的抽象小部件有一个用 API 限制注释的方法，它告诉客户端不要覆盖此方法。让我们创 建一个可用的默认小部件。
清单 3. DefaultWidget.java
package org.eclipse.example.widgetfacTory;/*** A default widget, this class isn't meant to be extended.** Implementation is provided as-is.** @noextend*/public class DefaultWidget extends AbstractWidget { public String getName() { return "The default widget"; }}
我们为客户端提供的默认小部件非常简单。它主要用于使用而非扩展。我们可以在自己的插件 内随意扩展该类，或创建其他可用的默认小部件。因此，假设我们是这个小部件 API 的客户，看看会发 生什么。让我们创建两个类：MyWidget（实现 IWidget）和 MyDefaultWidget（扩展 DefaultWidget）。 作为小部件 API 的客户，我会看到什么？对于 MyWidget 类，我们将看到一个警告，说明我们正在实现 不能由客户实现的 API 接口（参见图 5）。对于 MyDefaultWidget 类，将看到关于非法扩展 DefaultWidget 类以及非法覆盖 getId() 方法的警告。
图 5. MyWidget.java
图 6. MyDefaultWidget.java
这个简单的示例让 您清晰地了解到如何向 API 客户呈现关于 API 的使用信息。
二进制文件不兼容
声明 API 时遇到的问题是：如何知道何时真正将 API 从一个版本拆分到另一个软件版本中。例如，拆分 API 的简 单方法是更改先前定义的 API 方法的方法签名。为了方便演示，我将用常见的 PluginRegistry 类在 Eclipse 代码库中完成该操作。
图 7. 二进制文件不兼容的更改
在本例中，我修改了现有的 API 方法 findEntry(String id)，而 API Tools 足够智能，可以意识到 这将拆分这个 API 类的客户。拆分 API 有许多其他方法，并且 API Tools 将提供所有这些方法的检查 。结果是，所有这些二进制文件的不兼容更改都可以在 API Tools 首选项页上配置。
图 8. API Tools 首选项
版本化
处理 API 遇到的另一个问题是版本管理。我认为版本管理有两个方面：一是提出版本化策略，二是强 制执行该策略。API Tools 将遵循 Eclipse 版本化指导信息（请参阅 参考资料），这些指导信息非常依 赖于 OSGi 版本化模式。为简单起见，版本号由四部分组成 — 三个整数和一个字符串，分别是 major.minor.service.qualifier。
每个版本分段将捕捉不同的意图。主要分段表示 API 中的拆分，次要分段表示外部可见的更改（如新 API），服务分段表示错误修正和开发流程更改，而限定符分段表示特殊构建。
由于进行了某些更改（比如添加新 API 方法或修复 bug）而必须更改插件版本号时，应该记住比较困 难且容易出错的部分。过去的常见问题是开发人员常常在发生更改时就提升次要版本，而不是在更改新 API 更改时 — 例如，在开始 Eclipse SDK 的 3.4 流程时，通常只提升次要版本，假定将来进行的更改 会导致修改次要版本。但是，有了 API Tools，版本管理就不再容易出错，因为 API Tools 可以根据 API 基准告诉您正确的插件版本，并强制执行。例如，如果我把一个方法添加某个插件的版本号为 3.3.0 的 API 类中，API Tools 将显示什么呢？
无序的 API Tools 和报表
虽然在无序环境中使用 API Tools 不是本文的讨论范围，但它是可行的。这就是 Eclipse 构建的任 务，它将生成 API 基准和 API 报表。API Tools 包括一些帮助您完成此操作的 Ant 任务。请查看 org.eclipse.pde.api.tools 插件以获得关于 Ant 任务的更多信息。
图 9. 版本错误
API Tools 显示了两个错误，表示应当更新方法的 @since 标记以明确声明该方法属于 3.4 API。另 一个错误表示插件版本将在 MANIFEST.MF 文件中提高。如果详细查看这个错误，我们会看到 API Tools 甚至善意地提供了恰当的快速修正，以将版本号更新为正确版本。
图 10. MANIFEST.MF Quickfix
结束语
本文简单介绍了 API Tools 以及它的一些功能。必须注意的是，本文仅介绍了 API Tools 对项目有 用的几个功能。例如，您可以在无序环境中使用 API Tools，并且还可以用它生成捕捉 API 违规的报表 。我希望您了解 API 和版本化的重要性，并开始在项目中使用 API Tools。
爱情不是避难所，想进去避难的话，是会被赶出来的。
