元数据 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)