錯誤訊息指南

本指南是撰寫 Apache Spark 中標準化且可操作錯誤訊息的參考。

包含原因、緣由和解決方法

從 Spark 拋出的例外應回答五個 W 和一個 H

• 誰遇到問題？
• 什麼問題？
• 何時發生問題？
• 哪裡發生問題？
• 為什麼發生問題？
• 如何解決問題？

例外提供的內容有助於回答誰（通常是使用者）、何時（通常透過 log4j 包含在記錄中）和哪裡（通常包含在堆疊追蹤中）。但是，這些答案通常不足以讓使用者解決問題。回答剩餘問題（什麼、為什麼和如何）的錯誤訊息可將使用者的挫折感降至最低。

明確回答什麼、為什麼和如何

在許多情況下，錯誤訊息應明確回答什麼、為什麼和如何。

範例 1

無法為內部類別 {} 產生編碼器，因為無法存取定義此類別的範圍。請嘗試將此類別移出其父類別。

• 什麼：無法產生編碼器內部類別。
• 為什麼：無法存取定義類別的範圍。
• 如何：嘗試將此類別移出其父類別。

範例 2

如果建議的修正（如何）感覺很武斷，提供錯誤發生的原因可以減少使用者的挫折感。

之前

不支援 函數名稱 {}。

• 問題：不支援的函數名稱。
• 原因：不明。
• 解決方法：不明。

之後

函數名稱 {} 無效。暫時函數無法屬於目錄。請指定一個一或兩部分的函數名稱。

• 問題：無效的函數名稱。
• 原因：暫時函數無法屬於目錄。
• 解決方法：指定一個一或兩部分的函數名稱。

隱含回答解決方法

並非所有錯誤訊息都應該如此詳細。有時候，明確說明如何解決問題會是多餘的；在這種情況下，你可以略過明確的說明。

範例 1

無效的樞紐欄位 {}。樞紐欄位必須可比較。

• 問題：無效的樞紐欄位。
• 原因：樞紐欄位必須可比較。
• 解決方法 (由原因暗示)：使用可比較的樞紐欄位。

範例 2

之前

無法為 {} 函數指定視窗框架

• 問題：無法為函數指定視窗框架。
• 原因：不明。
• 解決方法：不明。

之後

無法為視窗表達式 {} 指定框架。視窗表達式包含函數框架 {} 和規格框架 {} 之間的不相符。

• 問題：無法為視窗表達式指定框架。
• 原因：視窗表達式包含函數框架和規格框架之間的不相符。
• 解決方法 (由原因暗示)：比對函數框架和規格框架。

範例 3

之前

無法剖析任何小數。

• 問題：無法剖析小數。
• 原因：不明。
• 解決方法：不明。

之後

無效的小數 {}；在位置 {} 剖析時遇到錯誤。

• 問題：無效的小數。
• 原因：小數剖析器在指定的位置遇到錯誤。
• 解決方法 (由原因暗示)：修正指定位置的錯誤。

隱含回答原因和解決方法

有時候，即使明確說明原因問題發生也會是多餘的；在這種情況下，你可以略過明確的說明。

路徑不存在：{}

• 問題：路徑不存在。
• 原因 (由問題暗示)：使用者指定無效的路徑。
• 解決方法 (由問題暗示)：使用不同的路徑。

使用明確的語言

詞彙指南

片語	使用時機	範例
不支援	使用者可能合理地假設支援此操作，但事實並非如此。如果開發人員新增對此操作的支援，此錯誤可能會在未來消失。	資料類型 {} 不支援。
無效 / 不允許 / 意外	使用者在指定操作時發生錯誤。訊息應告知使用者如何解決錯誤。	陣列大小為 {}，索引 {} 無效。
		為子句 {} 找到 {} 個產生器。只允許一個產生器 存在。
		找到 意外 的狀態格式版本 {}。預期的版本為 1 或 2。
無法	系統遇到無法合理歸咎於使用者錯誤的意外錯誤。	無法編譯 {}。
無法	任何時候，最好只在上述任何替代方案不適用的情況下使用。	無法為不支援的類型 {} 產生程式碼。

措辭指南

最佳實務	之前	之後
使用主動語態	資料類型 {} 不受 {} 支援。	{} 不支援 資料類型 {}。
避免使用基於時間的陳述，例如承諾未來支援	樞紐目前 不支援 Pandas UDF 彙總運算式。	樞紐 不支援 Pandas UDF 彙總運算式。
	尚未 支援 Parquet 類型：{}。	{} 不支援 Parquet 類型。
使用現在式描述錯誤並提供建議	無法在 {} 的 {} 找到參考欄。	無法在 {} 的 {} 找到參考欄。
	連接策略提示參數 應該是識別碼或字串，但實際上是 {}。	無法使用連接策略提示參數 {}。請使用資料表名稱或識別碼指定參數。
如果解決方案不明確，請提供具體範例	{} 提示預期參數為分割區編號。	{} 提示預期一個分割號碼作為參數。 例如，用 {}(3) 指定 3 個分割。
避免聽起來像指控、批判或侮辱	您必須為 {} 指定一個金額。	{} 不能為空。為 {} 指定一個金額。
直接了當	Spark 資料來源 V2 中不允許 LEGACY 儲存指派原則。 請將 spark.sql.storeAssignmentPolicy 組態設定為 其他值。	Spark 資料來源 V2 不允許 LEGACY 儲存指派原則。將 spark.sql.storeAssignment 組態設定為 ANSI 或 STRICT。
在使用者介面錯誤中不要使用程式設計術語	RENAME TABLE 來源和目的地資料庫不匹配： '{}' != '{}'。	RENAME TABLE 來源和目的地資料庫不匹配。來源資料庫為 {}，但目的地資料庫為 {}。