
前言
图书馆里,一本旧版教材可能贴着"请优先借阅新版"的标签。标签没有改动书里的内容,却能提醒借书的人作出选择。如果没有人看标签,旧书还是会照常被借走。
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、库私有名称等语言规则。
自定义注解既要定义信息,也要有相应的处理者。看懂一个注解的关键,是看懂谁使用这些信息,以及它实际执行了什么检查或处理。
八、测试题
- 用自己的话区分元数据、注解和普通注释。为什么定义一个叫 Todo 的注解,不会自动得到待办检查功能?
- 第二节中去掉 QuietAlarm.ring 上的 @override,调用结果会改变吗?如果把 ring 拼成 rign,注解又能帮助发现什么?
- 一个方法标了 @Deprecated('请改用新方法;2.0.0 移除')。它现在还能运行吗?版本到了 2.0.0 会自动被 Dart 删除吗?
- 一个可选参数加上 @Deprecated.optional 后,是"传这个参数"还是"不传这个参数"会收到对应提示?它与普通 @Deprecated 有什么不同?
- @immutable 类有一个 final List 字段,能否仅凭这个注解断定列表元素不能增加?如果把列表换成不可修改的列表,元素对象本身也一定不可变吗?
- 子类覆写 @mustCallSuper 标记的方法却没有调用 super。分析器会做什么,运行时又会自动补上什么吗?
- Todo 只有普通构造函数,参数也是运行时读取的字符串。它能否直接写成注解?要改正这两个问题,分别需要什么条件?
- 给 Todo 加上只允许函数和方法的 Target 后,误把它用于类声明,会触发什么检查?这个设置能否顺便实现 Todo 的业务功能?
- 给类写上 @JsonSerializable 后没有生成转换代码。为什么仅看"注解已经写上"不足以判断配置正确?应该继续确认什么?