Dart 之元数据与注解

前言

图书馆里,一本旧版教材可能贴着"请优先借阅新版"的标签。标签没有改动书里的内容,却能提醒借书的人作出选择。如果没有人看标签,旧书还是会照常被借走。

Dart 代码里的注解也有类似的作用。@Deprecated 可以提醒使用者换用新接口,@override 可以让分析器检查一个方法是否真的覆写了父类成员。分析器是检查代码的工具,编辑器里的许多错误和警告提示就来自它。

元数据是给代码补充的信息,注解是把这些信息写在代码上的方式。 例如,一个函数的名字、参数和函数体说明它怎样工作;函数前的 @Deprecated 则补充说明:它已经不推荐使用,应当换用其他函数。

一、注解给代码补充了什么

1.1 信息附在声明上

元数据也被称为代码的"静态信息",因为程序还没运行,工具就能从代码里读到它。这里的"静态"与 static 成员不是同一个意思。

例如,新函数已经替代了旧函数,但旧函数暂时还要保留,就可以在旧函数上标记迁移信息:

dart 复制代码
@Deprecated('请改用 sendMessage')
void sendText(String text) {
  sendMessage(text);
}

void sendMessage(String text) {
  print('发送:$text');
}

void main() {
  sendMessage('你好');
}

@Deprecated 放在 sendText 声明前,作用于这个旧函数。括号里的文字给使用者说明替代方案。函数体仍然负责转发消息;注解并没有把函数体改写成别的操作。

这与写一行"这个方法过时了"的注释有什么区别?

普通注释主要给人阅读。注解具有语言规定的结构,工具可以识别它关联的声明和携带的数据。 分析器认识 Deprecated 的含义,因此能在使用 sendText 时给出弃用提示;普通注释中的一句话不会产生同样的检查。

注解通常写在类、函数、成员、参数等声明前,也可以用于库声明或导入、导出等指令。它不是可以随意插在运算表达式前的装饰符。能不能用于某个具体位置,还要看语言语法和该注解的约定。

1.2 @ 后面为什么有时带括号

注解以 @ 开头,后面常见两种形式:

写法 @ 后面是什么 例子
引用一个编译期常量 已经定义好的常量对象 @override、@deprecated
调用常量构造函数 根据参数创建常量对象 @Deprecated('请改用新接口')

"编译期常量"是编译阶段就能确定的值。注解要给工具提供静态信息,所以不能等程序运行以后,再根据用户输入决定它的内容。

这里的括号不是"现在就执行一个普通方法"的意思。@Deprecated 使用的是常量构造函数,而且注解本身就是常量上下文,不需要再写 const。 自定义注解也遵守这个规则。

@override、@Deprecated、@deprecated 和 @pragma 来自自动导入的 dart:core,不需要为它们额外安装包。元数据

二、@override:让分析器核对覆写意图

2.1 覆写由成员关系决定

@override 表示"这个实例成员打算覆写或实现父类、接口中已有的成员"。 它把我们的意图告诉分析器,让工具检查代码是否符合这个意图。

dart 复制代码
class Alarm {
  void ring() {
    print('响铃');
  }
}

class QuietAlarm extends Alarm {
  @override
  void ring() {
    print('震动');
  }
}

void main() {
  Alarm alarm = QuietAlarm();
  alarm.ring(); // 震动
}

QuietAlarm 继承 Alarm,并提供了自己的 ring 实现。运行时对象是 QuietAlarm,所以调用它的 ring,输出"震动"。

即使去掉 @override,这段代码仍然会覆写,结果也仍然是"震动"。 真正决定覆写的是继承或接口关系,以及成员名称和签名是否符合要求;注解让这个意图能够被核对。

2.2 用注解发现拼写错误

如果把 ring 误写成 rign:

dart 复制代码
class Alarm {
  void ring() {}
}

class QuietAlarm extends Alarm {
  @override
  void rign() {} // 拼错了,父类没有 rign
}

void main() {}

分析器会给出 override_on_non_overriding_member,指出这个成员没有覆写任何已有成员。

如果不加注解,rign 会被当成一个新方法。工具不会知道原本想写的是 ring,程序也仍然继续使用父类的 ring。代码可以通过基本语法检查,却没有替换预期的行为。

@override 也适用于实现接口的实例成员,以及符合覆写规则的 getter、setter 和字段产生的访问器。顶级函数、静态方法不属于这种实例成员覆写关系。

还要区分两种检查:名称写错时,注解能帮助发现"意图没有实现";参数或返回类型不符合覆写规则时,即使不写 @override,类型检查也会报错。注解不能使错误的覆写变合法。override

三、@Deprecated:告诉使用者怎样迁移

3.1 弃用不等于马上不能用

弃用表示某个接口不再推荐使用,使用者应迁移到替代方案。 为了让已有代码有时间调整,旧接口往往还会保留一段时间。

这就像一条公交线路准备调整:提前告知乘客应该改乘哪一路,不等于贴出通知的当天就把车停掉。

在第一节的代码里,旧函数 sendText 仍然能发送消息。其他包使用这个旧接口时,分析器会给出弃用诊断;换成 sendMessage 后,既保留发送行为,也消除了对旧接口的依赖。

因此,弃用消息应写清楚"改用什么"。有明确计划时,也可以说明预计移除的版本。假设一个名为 legacy_api 的包在 lib/legacy.dart 中提供接口:

dart 复制代码
@Deprecated('请改用 sendMessage;计划在 2.0.0 移除')
void sendText(String text) {
  sendMessage(text);
}

void sendMessage(String text) {
  print('发送:$text');
}

另一个项目添加这个包作为依赖后,在 main.dart 中使用它:

dart 复制代码
import 'package:legacy_api/legacy.dart';

void main() {
  sendText('你好'); // 弃用提示;当前仍会输出"发送:你好"
}

使用方位于另一个包时,分析器会在调用处给出弃用提示。弃用提示的具体范围还受工具版本和配置影响,因此判断一个接口是否弃用,首先要看它的声明和 API 说明。

这段消息是给使用者看的迁移说明。版本到了 2.0.0,Dart 不会自动删除这个函数;真正移除接口,仍需要维护者修改代码。

@deprecated 是不带迁移消息的简写。两者都能表达弃用,但 @Deprecated 可以把"下一步怎么改"说明白,通常更合适。大小写也要分清:Deprecated 是类,deprecated 是已经定义好的常量。

弃用一个类时,它的成员也会被视为弃用;但父类某个成员被弃用,不代表子类覆写的同名成员自动带上弃用标记。不能只看名字判断,仍要看正在使用的声明。

3.2 只弃用某一种用法

有时需要限制的只是某一种用法,而不是让整个接口退出使用。例如,一个类仍然允许创建对象,但维护者不希望外部继续继承它。把整个类标为弃用,会让"正常创建对象"也受到影响。

当前 SDK 提供了更细的标记:

注解形式 提醒迁移的用法
@Deprecated.extend('原因') 用 extends 继承这个类
@Deprecated.implement('原因') 用 implements 实现这个类或混入的接口
@Deprecated.subclass('原因') 用 extends 或 implements 建立子类型
@Deprecated.mixin('原因') 用 with 混入这个类
@Deprecated.instantiate('原因') 创建这个类的实例
@Deprecated.optional('原因') 调用时没有给被标注的可选参数传值

例如,@Deprecated.extend 只是提醒"继承这种用法将退出",不会自动把类变成 final,也不会连带禁止创建对象。需要语言层面限制继承时,应使用适合的类修饰符。

最后一个尤其容易看反:@Deprecated.optional 弃用的是"省略参数",目的是提醒调用方提前为将来必填做好准备。

例如,在 connection.dart 中声明:

dart 复制代码
void connect({
  @Deprecated.optional('请显式传入 timeoutSeconds,后续将改为必填')
  int timeoutSeconds = 30,
}) {
  print('超时:$timeoutSeconds 秒');
}

在 main.dart 中调用:

dart 复制代码
import 'connection.dart';

void main() {
  connect(); // 提示不应再省略这个参数,当前仍使用默认值 30
  connect(timeoutSeconds: 10); // 已显式提供,不触发这条弃用提示
}

这与在参数上使用普通 @Deprecated 的方向不同:普通弃用标记提醒"不要再使用这个参数";optional 提醒"不要再省略这个参数"。两者不能互换。

这些命名构造函数属于较新的 Dart SDK。旧 SDK 如果报告"找不到构造函数",需要核对项目 SDK 版本,不能直接换成含义不同的注解。Deprecated

四、package:meta:把更多约定交给工具检查

有些意图无法仅靠类型和语法表达。例如:"这个类的状态不应该变化""子类扩展这个方法时,必须保留父类的清理工作"。package:meta 为这类意图提供了分析器认识的注解。

使用 package:meta 前,需要把它添加到项目依赖中:

bash 复制代码
dart pub add meta

代码中再导入 package:meta/meta.dart。本节示例使用 meta 1.19.0。

4.1 @immutable 检查字段,却不会冻结所有内容

@immutable 表示这个类及其子类型的实例字段应该都是 final,包括继承的实例字段。 分析器会检查是否有可重新赋值的实例字段。

dart 复制代码
import 'package:meta/meta.dart';

@immutable
class ShoppingList {
  final List<String> items;

  const ShoppingList(this.items);
}

void main() {
  final list = ShoppingList(['面包']);
  list.items.add('牛奶');
  print(list.items); // [面包, 牛奶]
}

代码已经标记为 immutable,为什么列表还可以添加"牛奶"?

因为 items 是 final,只能保证它不能重新指向另一张列表。字段不能重新赋值,不代表字段指向的对象内部不能改变。 这段代码没有更换列表,只是修改了同一张列表里的内容,所以 @immutable 不会阻止这次修改。

想让这个例子中的列表内容也不能修改,需要另外选择不可修改的列表:

dart 复制代码
import 'package:meta/meta.dart';

@immutable
class ShoppingList {
  final List<String> items;

  ShoppingList(Iterable<String> items)
      : items = List<String>.unmodifiable(items);
}

void main() {
  final source = <String>['面包'];
  final list = ShoppingList(source);
  source.add('牛奶');
  print(list.items); // [面包]

  // list.items.add('鸡蛋'); // 取消注释后,运行时抛出 UnsupportedError
}

构造函数根据传入内容建立一张不可修改的列表,所以外面的 source 增加元素,不会改变 list.items,通过 list.items 也不能添加、删除或替换元素。

这里的元素是 String;如果元素本身是包含可变字段的对象,仍需另外处理那些对象的可变状态。不可修改的列表也不等于深度冻结整棵对象结构。

如果去掉 items 声明中的 final,分析器会给出 must_be_immutable 诊断,但不会自动补上 final。注解负责表达和检查意图,真正约束赋值的是 final,约束列表修改的是所选用的列表实现。immutable

4.2 @mustCallSuper 保留父类已有的工作

父类可能已经负责释放资源。子类增加自己的清理逻辑时,如果完全覆盖父类方法而忘记调用它,就可能漏掉原来的工作。

dart 复制代码
import 'package:meta/meta.dart';

class Resource {
  @mustCallSuper
  void dispose() {
    print('释放公共资源');
  }
}

class ImageResource extends Resource {
  @override
  void dispose() {
    print('释放图片资源');
    super.dispose();
  }
}

void main() {
  ImageResource().dispose();
}

输出顺序为:

text 复制代码
释放图片资源
释放公共资源

@mustCallSuper 标在父类有实现的实例成员上,要求覆写它的成员也调用被覆写的实现。删除示例中的 super.dispose(),分析器就会报告 must_call_super。

@mustCallSuper 不会自动插入父类调用,也不统一规定它必须放在方法开头或结尾。 调用次序要看父类的接口约定和具体业务;本例先释放图片资源,再释放公共资源。

两个注解检查的是不同的事情:@override 检查这个方法是否覆写了已有成员,@mustCallSuper 检查覆写时是否调用了父类要求保留的实现。

4.3 访问约定不等于语言访问权限

还有一些注解主要说明"这个声明应该在哪里使用":

注解 表达的意图 不能误解成什么
@protected 实例成员主要供声明库内部,以及库外子类型等允许的实例上下文使用 不是"只有子类能访问";在库外通常应通过当前对象 this 访问,不能随意访问另一个对象的该成员
@visibleForTesting 原本公开只是为了让测试能够访问;定义库内或包的 test 目录中的使用符合其约定 不会让一个私有名称突然变成公开,也不是所有业务代码都应该调用的接口
@internal 这个声明属于包的内部实现,不应被包外代码依赖 不会把名称自动改成以下划线开头的库私有名称

这些约定主要由分析器反馈。Dart 中以下划线开头的名称是库私有,这是语言规则;给公开名称贴上 @protected,并不会把它改造成同样的私有机制。

同样,现代 Dart 的 required、sealed 是语言关键字,不应与名称相近的旧注解混为一谈。需要必填命名参数时写 required,不要为了模仿旧代码改用 @required。meta

五、自定义注解:先定义信息,再决定谁来处理

5.1 用常量对象保存需要说明的内容

自定义注解就是自行定义可用作元数据的常量对象。 常见做法是定义一个带常量构造函数的类,让它保存工具需要的信息。

dart 复制代码
class Todo {
  final String owner;
  final String task;

  const Todo(this.owner, this.task);
}

const review = Todo('小林', '复核金额计算');

@Todo('小周', '补充退款规则')
void refund() {
  print('处理退款');
}

@review
void calculateTotal() {
  print('计算金额');
}

void main() {
  refund();
  calculateTotal();
}

这里有两种写法:refund 前通过常量构造函数提供具体任务;calculateTotal 前引用已经定义好的 review 常量。两者都把一个 Todo 对象作为元数据附在函数声明上。

Todo 的字段是 final,构造函数是 const,传入的字符串也是编译期常量,所以可以用于注解。构造函数里的 const 表示它能够创建常量对象;注解位置已经要求常量,不再另写 const。

如果把 owner 换成运行时读取的用户名,或者把 Todo 改成只有普通构造函数,就不能原样用作这个注解了。final 只表示变量不能再次赋值,不能保证它的值是编译期常量。

运行这段程序,只会输出:

text 复制代码
处理退款
计算金额

不会自动给小周发任务,也不会自动检查退款规则是否已补齐。我们只定义了"记录负责人和事项"的信息;如果希望工具汇总待办,还需要另外实现读取和处理这些信息的工具。分析器并不知道 Todo 这个名字意味着什么业务规则。

5.2 用 @Target 限定注解适用的位置

如果 Todo 只打算用于函数和方法,把它贴到类上可能是误用。可以用 package:meta 提供的 Target 表达这种位置约束:

dart 复制代码
import 'package:meta/meta_meta.dart';

@Target({TargetKind.function, TargetKind.method})
class Todo {
  final String task;

  const Todo(this.task);
}

@Todo('补充校验')
void save() {}

class Editor {
  @Todo('补充撤销操作')
  void edit() {}
}

void main() {}

function 对应顶级函数,method 对应类里的方法,所以两处 Todo 用法都符合约定。若把 @Todo 放在 Editor 的类声明前,分析器会给出 invalid_annotation_target。

Target 来自 package:meta/meta_meta.dart。它描述的是 Todo 这个注解允许用在哪里,所以标在 Todo 类上;save 和 edit 使用 Todo 时,就会受到这条位置约定的检查。

Target 只为分析器增加位置检查,仍然不会替 Todo 实现待办汇总功能。Target

六、谁来处理注解,决定它怎样发挥作用

注解写在代码上以后,需要由认识它的工具读取,才能产生相应的提示或处理结果:

分析器认识 @override、@Deprecated 和 meta 中约定的注解,于是在编辑器或执行 dart analyze 时进行对应检查。能看到提示,是因为工具已经实现了这些规则。

有些包则通过构建工具处理注解。例如 JSON 序列化中的 @JsonSerializable,通常由 json_annotation 提供注解,再由 json_serializable 配合构建工具生成转换代码。转换方法是在生成步骤中产生的,因此除了写下注解,还需要安装、配置相应工具,并执行生成命令。 JSON 序列化

还有一种内置形式 @pragma,它向特定 Dart 工具提供指令或提示,具体名称和参数由对应工具定义。它可能影响编译器如何处理代码,不能把"所有注解都不影响最终程序"当成通用结论,也不要把它当成随手添加的性能优化开关。pragma

框架如果要在运行时读取元数据,需要自行提供这部分能力。Dart 不会因为函数上有一个 @,就在每次调用时自动运行对应逻辑。

面对一个陌生注解,先看它保存了什么信息、哪个工具识别它,以及这个工具在分析阶段、构建阶段还是运行时处理它。这样才能判断需要安装什么、执行什么,以及它能保证什么。

七、总结

元数据给代码附加静态信息,注解用 @ 把常量对象关联到声明等结构上。它可以说明意图、提供配置,也可以成为工具处理代码的入口。

@override 帮助核对覆写意图,覆写本身仍由成员关系和类型规则决定;@Deprecated 提供迁移提醒,旧接口是否保留仍由代码决定。package:meta 扩展了分析器能够理解的约定,但不能代替 final、required、库私有名称等语言规则。

自定义注解既要定义信息,也要有相应的处理者。看懂一个注解的关键,是看懂谁使用这些信息,以及它实际执行了什么检查或处理。

八、测试题

  1. 用自己的话区分元数据、注解和普通注释。为什么定义一个叫 Todo 的注解,不会自动得到待办检查功能?
  2. 第二节中去掉 QuietAlarm.ring 上的 @override,调用结果会改变吗?如果把 ring 拼成 rign,注解又能帮助发现什么?
  3. 一个方法标了 @Deprecated('请改用新方法;2.0.0 移除')。它现在还能运行吗?版本到了 2.0.0 会自动被 Dart 删除吗?
  4. 一个可选参数加上 @Deprecated.optional 后,是"传这个参数"还是"不传这个参数"会收到对应提示?它与普通 @Deprecated 有什么不同?
  5. @immutable 类有一个 final List 字段,能否仅凭这个注解断定列表元素不能增加?如果把列表换成不可修改的列表,元素对象本身也一定不可变吗?
  6. 子类覆写 @mustCallSuper 标记的方法却没有调用 super。分析器会做什么,运行时又会自动补上什么吗?
  7. Todo 只有普通构造函数,参数也是运行时读取的字符串。它能否直接写成注解?要改正这两个问题,分别需要什么条件?
  8. 给 Todo 加上只允许函数和方法的 Target 后,误把它用于类声明,会触发什么检查?这个设置能否顺便实现 Todo 的业务功能?
  9. 给类写上 @JsonSerializable 后没有生成转换代码。为什么仅看"注解已经写上"不足以判断配置正确?应该继续确认什么?
相关推荐
三少爷的鞋2 小时前
很多开发者把物理上的分层,当成了架构
android
FungLeo3 小时前
FengCMS · PHP+MySQL 升级实录 · MySQL DDL不能回滚:模型字段结构操作的失败续做
android·mysql·php·工程实践·fengcms
雨白3 小时前
Android 建造者模式实战:从 AlertDialog 源码到 TopBar 的两种实现
android
_祝你今天愉快6 小时前
Android 高级绘制:[五] 贝塞尔曲线与计算规则
android
FungLeo21 小时前
FengCMS · PHP+MySQL 升级实录 · 危险默认值之殇:root/123456、认证码 8888 写进配置加载器
android·mysql·php·安全加固·fengcms
yz_aiks21 小时前
Termux 使用教程:把安卓手机变成随身 Linux(装 Python、SSH 远程、跑自动化脚本)
android·linux·python·智能手机·ssh·termux
booboosui1 天前
编号没变,消息还是来了:Mac 端通知读取漏第二条的原因
android
雨白2 天前
单例设计模式:从 Java/Kotlin 实现到 Android 实战
android
hai_android2 天前
一行 asLiveData,背后是一座生命周期的桥
android·java·kotlin