中繼資料 Metadata

什麼是中繼資料註解

以 @ 開頭，為程式碼附加靜態額外資訊，編譯器 / IDE / 靜態分析器可讀取，不會影響執行邏輯。

兩種合法寫法：

1. 內建編譯期常數：@override、@deprecated
2. 常數建構子呼叫：@Deprecated("提示文字")、自訂 @Todo("xxx", "xxx")

通常用於類別、方法、變數、函式、參數、匯入、列舉等

@Deprecated

標記 API 已淘汰，必須寫明替代方案、移除時間；另有細分場景的靜態方法。

class Television {
  /// 替代方案：使用 turnOn
  @Deprecated('請改用 turnOn()，此方法將於2026年底移除')
  void activate() {
    turnOn();
  }

  void turnOn() {
    print("電視開機");
  }
}

// 細分淘汰場景範例
@Deprecated.instantiate() // 禁止使用 new 建立此類別實體
class OldDevice {}

@Deprecated.extend() // 禁止其他類別繼承此類別
class Base {}

// 嘗試繼承 Base，編輯器會出現淘汰警告
class Sub extends Base {}

void main() {
  Television tv = Television();
  // 呼叫標記 @Deprecated 的方法，IDE 會顯示刪除線與警告
  tv.activate();
  // 建議使用的新方法
  tv.turnOn();

  // 建立 OldDevice 實體，觸發 @Deprecated.instantiate() 警告
  OldDevice device = OldDevice();
}
Code language: Dart (dart)

以上程式仍可正常編譯執行，僅會在編譯器與 IDE 顯示警告。讀者可使用 Android Studio、IDEA 等工具測試。

@deprecated

無自訂提示文字，僅簡單標記淘汰，優先使用 @Deprecated("說明")

@deprecated
void oldFunc() {}
Code language: Dart (dart)

@override

標記覆寫父類別 / 介面同名成員，IDE 會進行檢查：若方法名稱打錯會報紅色錯誤。

class Animal {
  void speak() {}
}

class Dog extends Animal {
  // @override 標註：覆寫父類別的 speak 方法
  @override
  void speak() {
    print("汪汪");
  }
}

class Cat extends Animal {
  @override
  void speak() {
    print("喵喵");
  }
}

class Pig extends Animal {
   // 未覆寫
}

void main() {
  Animal dog = Dog();
  Animal cat = Cat();
  Animal pig = Pig();

  dog.speak(); // 輸出：汪汪
  cat.speak(); // 輸出：喵喵
  pig.speak();
}
Code language: Dart (dart)

@pragma

傳遞底層最佳化 / 識別指令給編譯器、靜態分析器，多用於底層開發。

// 範例：告知編譯器將此函式內聯展開
@pragma('vm:prefer-inline')
int add(int a, int b) => a + b;
Code language: Dart (dart)