目录

Dart 2 迁移指南

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_newunnecessary_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'

更多资源