了解如何使用 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.engine API 類或接口 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。
