目录

Dart 2 迁移指南

目录

keyboard_arrow_down keyboard_arrow_up

Dart 2 有一些与早期版本 Dart 不同的关键点。本文将会简单地介绍这些差异并提供了一些将代码迁移到 Dart 2 的建议。

至于 为什么 Dart 2 要做这些改变，你可以查阅 Dart 2 公告

差异点

Dart 语言、库、编译系统以及 Web 开发工具都已经有所变化。

语言和库

工具

迁移你的代码

如何迁移你的代码取决于你的代码有多古老以及运行在什么平台。有关如何迁移 Web 应用的帮助请查阅 [ Web 应用迁移指南][webdev dart2]。如果你迁移一个 Flutter 应用，请查阅 变革公告 如果你发布了 package，则除了适配平台不同的特性之外，还需要遵循 下述的 package 迁移说明。

通用流程

下面是迁移到 Dart 2 的一个流程概述。

  1. 获取一个最新的 Flutter 或 Dart SDK 版本以及你所使用的 IDE 的最新插件。

  2. 升级你应用依赖的 package。

  3. 运行 dart2_fix 工具，它可以帮助迁移一些过时的 Dart 1.x API 到 Dart 2。

  4. 运行分析器以找出 编译时错误 以及弃用提示。

    • Flutter：flutter analyze 或使用 Android Studio/IntelliJ 或 VS Code 的问题视图。

    • 服务端或 Web：[dart analyze][dartanalyzer]

  5. 修复代码问题并再次运行分析器，重复该操作直到你的代码通过静态分析。

  6. 运行测试以找出 运行时错误

    • 运行你软件所有的 [自动化测试]。

    • 执行手动测试以查找控制台错误。

    考虑添加自动化测试来捕获你发现的问题。

  7. 修复问题知道你的代码可以正常运行。

  8. 可选的： 移除 new 以及不必要的 const 关键字。

    • 你可以手动地移除它们或者使用类似 dart format --fix 这样的工具。

    • 为了找到 new 和不必要的 const 出现的地方，可以将 unnecessary_new 和 unnecessary_const 规则添加至 分析选项文件 的 linter 部分。

迁移 package

作为一个 package 的拥有者，你需要遵循下列几项：

  • 遵循你的 package 所支持的平台的迁移技巧（详见 上述）。

  • 确保你的 package 通过了 Dart 2 分析（查阅上面的运行分析器）。

  • 确保你 package 的使用者知道如何上报问题。

  • 能够对上报的问题快速地作出响应。

  • 如果代码的变更导致无法向后兼容，请升级最低的 SDK 版本限制。

迁移 Web 应用

如果需要将你的 Web 应用更新到使用 Dart 2.x，你需要先更新一波 工具。

你还要对 <script> 元素进行如下的改动，以更新编译后的 Dart 代码引用：

  • 删除 <script defer src="packages/browser/dart.js"></script>

  • 用 <script defer src="foo.dart.js"></script> 替换
    <script defer src="foo.dart" type="application/dart"></script>

变化以及向后兼容性

如果你必须更改 package 的代码，请 尝试令其可以在 1.x 中使用，就像其在 Dart 2 中使用那样。例如，你可能需要添加类型注解（或者如果一个已被移除的 API）去使用一个替代的 1.x API。

如果代码的变更导致无法向后兼容，请升级最低的 SDK 限制

测试你代码的变更 以确保你的 package 在使用时可以如你所愿地运行。

SDK 版本上限

一旦你的 package 通过了 Dart 2 分析，请更新版本上限以表明其支持兼容到 Dart 2：

environment:
  # 只能在 Dart 2 中使用
  sdk: '>=2.0.0 <3.0.0'

如果你计划保持与旧版 Dart 的兼容性，请相应地调整 SDK 为较低的版本限制：

environment:
  # 可以在 Dart 1（1.20.1 开始）以及 Dart 2 中使用。
  sdk: '>=1.20.1 <3.0.0'

如果你使用 2.0 后引入的功能 请确保你指定了正确的 SDK 下限：

environment:
  # 可以在 2.1 中使用但不能在 2.0 中使用
  sdk: '>=2.1.0 <3.0.0'

更多资源