Dart 2 迁移指南

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

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

差异点

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

语言和库

工具

迁移你的代码

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

通用流程

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

Flutter:flutter pub upgrade

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

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

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

  • 运行测试以找出 运行时错误

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

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

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

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

  • 可选的:**移除 new 以及不必要的 const 关键字。**

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

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

迁移包

作为一个包的拥有者,你需要遵循下列几项:

  • 遵循你的包所支持的平台的迁移技巧(详见 上述)。

  • 确保你的包通过了 Dart 2 分析(查阅上面的运行分析器)。

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

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

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

变化以及向后兼容性

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

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

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

SDK 版本上限

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

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

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

  1. environment:
  2. # 可以在 Dart 1(1.20.1 开始)以及 Dart 2 中使用。
  3. sdk: '>=1.20.1 <3.0.0'

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

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

包版本必须有 <3.0.0 的上限限制以便在 Dart 2 稳定版以及随后的发行版中使用。Dart 2 在构建编译稳定发行版前的开发版本时有较为宽松的上限限制检查,你可以在此情况下使用没有 SDK 限制或者上限限制 <2.0.0 的包。

更多资源

DartPad