不健全的空值安全

Dart 程式可能包含一些空值安全的函式庫和一些不安全的函式庫。這些混合版本程式依賴於不健全的空值安全。

混合語言版本的能力讓套件維護者可以遷移他們的程式碼，並且知道即使是舊版使用者也能獲得新的錯誤修正和其他改進。但是，混合版本程式無法獲得空值安全所能帶來的所有優勢。

本頁面描述健全和不健全空值安全之間的差異，目的是幫助您決定何時遷移至空值安全。在概念討論之後，接著是逐步遷移的說明，以及測試和執行混合版本程式的詳細資訊。

Dart 透過靜態和執行階段檢查的組合來提供健全的空值安全。每個選擇加入空值安全的 Dart 函式庫都會獲得所有靜態檢查，以及更嚴格的編譯時期錯誤。即使在包含不安全函式庫的混合版本程式中也是如此。當您開始將部分程式碼遷移到空值安全時，就會開始獲得這些好處。

然而，混合版本程式無法擁有完全空值安全應用程式所擁有的執行階段健全性保證。null 有可能從不安全的函式庫洩漏到空值安全的程式碼中，因為阻止這種情況會破壞未遷移程式碼的現有行為。

為了在保持與舊版函式庫的執行階段相容性的同時，為完全空值安全的程式提供健全性，Dart 工具支援兩種模式

• 混合版本程式以不健全的空值安全執行。null 參考錯誤有可能在執行階段發生，但僅僅是因為 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

   使用較低的 SDK 約束 2.12.0 執行 dart pub get 會將套件中每個函式庫的預設語言版本設定為 2.12，使它們全部選擇加入空值安全。

3. 在您的 IDE 中開啟套件。
   您可能會看到很多分析錯誤。這沒關係。

4. 在您不想在目前遷移期間考慮的任何 Dart 檔案的頂部新增語言版本註解

   dart

   // @dart=2.9

   對於 2.12 套件中的函式庫使用語言版本 2.9 可以減少來自未遷移程式碼的分析錯誤 (紅色波浪線)。但是，不健全的空值安全會減少分析器可以使用的資訊。例如，分析器可能會假設參數類型是非可為 null 的，即使 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.7.1 版本。頁面上次更新時間為 2024-12-10。 檢視原始碼 或 回報問題。