不安全的空安全

Dart 程序可能包含一些是 空安全的 库和一些不是的库。这些混合版本程序依赖于不安全的空安全。

混合 语言版本 的能力使包维护者能够迁移他们的代码，并知道即使是旧版用户也可以获得新的错误修复和其他改进。但是，混合版本程序无法获得空安全带来的所有优势。

此页面描述了健全的空安全和不健全的空安全之间的区别，目的是帮助您决定何时迁移到空安全。概念讨论之后是增量迁移的说明，然后是有关测试和运行混合版本程序的详细信息。

Dart 通过静态和运行时检查的组合提供健全的空安全。每个选择加入空安全的 Dart 库都获得所有静态检查，并具有更严格的编译时错误。即使在包含不安全空库的混合版本程序中，情况也是如此。一旦开始将部分代码迁移到空安全，您就开始获得这些好处。

但是，混合版本程序无法获得完全空安全应用具有的运行时健全性保证。null 可能会从不安全空库泄漏到空安全代码中，因为阻止这种情况会破坏未迁移代码的现有行为。

为了在提供运行时与旧版库的兼容性的同时，为完全空安全的程序提供健全性，Dart 工具支持两种模式

• 混合版本程序在不安全的空安全下运行。在运行时可能发生null引用错误，但这仅仅是因为null或可空类型从某个不安全空库中逃逸并进入空安全代码中。

• 当程序完全迁移并且其所有库都是空安全的时，它将在健全的空安全下运行，并具有健全性带来的所有保证和编译器优化。

如果可能，健全的空安全是您想要的。如果程序的主入口点库已选择加入空安全，则 Dart 工具会自动在健全模式下运行程序。如果您导入不安全空库，则工具会打印警告以告知您它们只能在不安全的空安全下运行。

由于 Dart 支持混合版本程序，因此您可以一次迁移一个库（通常是一个 Dart 文件），同时仍然能够运行程序及其测试。

我们建议您首先迁移叶子库—不导入包中其他文件的库。然后迁移直接依赖于叶子库的库。最后迁移具有最多包内依赖项的库。

例如，假设您有一个lib/src/util.dart文件，它导入其他（空安全的）包和核心库，但没有任何import '<local_path>'指令。考虑首先迁移util.dart，然后迁移仅依赖于util.dart的文件。如果任何库具有循环导入（例如，A 导入 B，B 导入 C，C 导入 A），请考虑一起迁移这些库。

您可以使用 迁移工具 增量迁移。要选择退出文件或目录，请单击绿色复选框。在以下屏幕截图中，bin目录中的所有文件都已选择退出。

每个选择退出的文件都将保持不变，除了一个 2.9 语言版本注释。您以后可以再次运行dart migrate以继续迁移。任何已迁移的文件都将显示一个禁用的复选框：一旦文件迁移，您就不能取消迁移它。

如果要手动增量迁移包，请按照以下步骤操作

1. 编辑包的pubspec.yaml文件，将最小 SDK 约束设置为至少2.12.0

   yaml

   environment:
     sdk: '>=2.12.0 <3.0.0'

2. 重新生成 包配置文件

   $ dart pub get

   使用2.12.0的较低 SDK 约束运行dart pub get会将包中每个库的默认语言版本设置为 2.12，从而选择加入空安全。

3. 在您的 IDE 中打开包。
   您可能会看到很多分析错误。没关系。

4. 在您不想在当前迁移期间考虑的任何 Dart 文件的顶部添加 语言版本注释

   dart

   // @dart=2.9

   对于位于 2.12 包中的库使用语言版本 2.9 可以减少来自未迁移代码的分析错误（红色波浪线）。但是，不安全的空安全减少了分析器可以使用的信息。例如，分析器可能会假设参数类型是非空的，即使 2.9 文件可能会传入 null 值。

5. 迁移每个 Dart 文件的代码，使用分析器识别静态错误。
   通过添加?、!、required和late（根据需要）消除静态错误。

要测试或运行混合版本代码，您需要禁用健全的空安全。您可以通过两种方式执行此操作

• 使用--no-sound-null-safety标志对dart或flutter命令禁用健全的空安全

  $ dart --no-sound-null-safety run
  $ flutter run --no-sound-null-safety

• 或者，将入口点（包含main()函数的文件）中的语言版本设置为 2.9。在 Flutter 应用中，此文件通常命名为lib/main.dart。在命令行应用中，此文件通常命名为bin/<packageName>.dart。您还可以选择退出test下的文件，因为它们也是入口点。示例

  dart

  // @dart=2.9
  import 'src/my_app.dart';
  
  void main() {
    //...
  }

在期间您的增量迁移过程中，使用这两种机制中的任何一种选择退出测试可能会有用，但这意味着您没有在启用完整空安全的情况下测试您的代码。在完成库的增量迁移后，务必将测试选择回空安全。

除非另有说明，否则本网站上的文档反映了 Dart 3.5.3。页面上次更新于 2024-04-11。 查看源代码 或 报告问题。