您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

Eclipse PDE API Tools 入門：管理 API 相容性、版本號與使用限制

編輯：Java 相關知識

Eclipse PDE (Plug-in Development Environment) 內建 API Tools，協助開發者管理 API 生命週期：偵測二進位不相容、自動調整版本號、維護 @since 標籤、限制 API 使用方式（@noimplement 等）、識別非 API 代碼洩漏。本文以 Eclipse 3.4 (Ganymede) 為基礎介紹核心功能與實作範例。

什麼是 Eclipse API？

依命名慣例與 MANIFEST.MF 匯出套件決定：

元素類型	定義
API 套件	至少含一個 API 類別/介面的已匯出套件
內部套件	`org.eclipse.xyz.internal.*`，標記 `x-internal:=true`，可用但不保證相容
API 類別/介面	API 套件中的 public 類別/介面，或被其宣告/繼承的 public/protected 成員
API 方法/建構子	API 類別中宣告/繼承的 public/protected 方法/建構子
API 欄位	API 類別中宣告/繼承的 public/protected 欄位

訪問內部套件會收到「阻止訪問」警告，意味著代碼可能變更且無官方支援。

API Tools 核心功能

識別兩版本間的二進位不相容
依 Eclipse 版本規範自動更新外掛版本號
為新增 API 維護 @since 標籤
提供API 限制註解（@noimplement 等）
基於 MANIFEST.MF 定義 Bundle 間套件可見性
偵測非 API 代碼使用與內部類型洩漏至 API

啟用 API Tools 兩步驟

設定 API Baseline：Preferences → Plug-in Development → API Baselines，指向現有 Eclipse 安裝目錄，動態生成基準
專案加入 API Analysis：
- 既有專案：右鍵 → PDE Tools → API Tooling Setup Wizard，勾選專案 → Finish
- 新專案：New Plug-in Project Wizard 勾選 Enable API Analysis

API 限制註解實戰

註解	適用元素	效果
`@noimplement`	介面	客戶端不可 `implements`/`extends`
`@noextend`	類別	客戶端不可 `extends`
`@noinstantiate`	類別	客戶端不可實例化（任何建構子）
`@nooverride`	方法	客戶端不可 `override`
`@noreference`	方法/建構子/非 final 欄位	客戶端不可直接呼叫/引用

範例：Widget Factory API

// IWidget.java
package org.eclipse.example.widgetfactory;
/** @noimplement */
public interface IWidget {
  String getName();
  long getId();
}

// AbstractWidget.java
public abstract class AbstractWidget implements IWidget {
  /** @nooverride */
  public long getId() { return Math.round(Math.random()); }
}

// DefaultWidget.java
/** @noextend */
public class DefaultWidget extends AbstractWidget {
  public String getName() { return "The default widget"; }
}

客戶端違規偵測

// MyWidget.java - 警告：實作了 @noimplement 介面
public class MyWidget implements IWidget { ... }

// MyDefaultWidget.java - 警告：擴展 @noextend 類別、覆寫 @nooverride 方法
public class MyDefaultWidget extends DefaultWidget {
  @Override public long getId() { return 42; }
}