错误消息指南

本指南是用于在 Apache Spark 中编写标准化和可操作的错误消息的参考。

包含什么、为什么和如何

Spark 抛出的异常应该回答五个 W 和 How

• 谁遇到了问题？
• 什么是问题？
• 问题何时发生？
• 问题在哪里发生？
• 问题为什么发生？
• 如何解决问题？

异常提供的上下文可以帮助回答谁（通常是用户）、何时（通常包含在通过 log4j 记录的日志中）和在哪里（通常包含在堆栈跟踪中）。但是，仅凭这些答案通常不足以让用户解决问题。一条能够回答剩余问题的错误消息——什么、为什么和如何——可以最大程度地减少用户沮丧感。

明确回答什么、为什么和如何

在许多情况下，错误消息应该明确回答什么、为什么和如何。

示例 1

无法为内部类 {} 生成编码器，因为无法访问定义该类的作用域。 尝试将此类移出其父类。

• 什么： 无法生成编码器内部类。
• 为什么： 无法访问定义该类的作用域。
• 如何： 尝试将此类移出其父类。

示例 2

如果建议的修复（如何）感觉很随意，那么解释为什么发生错误可以减少用户的沮丧感。

之前

不支持的函数名称 {}。

• 什么： 不支持的函数名称。
• 为什么： 不清楚。
• 如何： 不清楚。

之后

函数名称 {} 无效。 临时函数不能属于目录。 指定包含一个或两个部分的函数名称。

• 什么： 无效的函数名称。
• 为什么： 临时函数不能属于目录。
• 如何： 指定包含一个或两个部分的函数名称。

隐式回答如何

并非所有错误消息都应该如此冗长。 有时，明确解释如何解决问题是多余的； 在这种情况下，您可以跳过显式解释。

示例 1

无效的透视列 {}。 透视列必须是可比较的。

• 什么： 无效的透视列。
• 为什么： 透视列必须是可比较的。
• 如何（由为什么暗示）： 使用可比较的透视列。

示例 2

之前

无法为 {} 函数指定窗口框架

• 什么： 无法为函数指定窗口框架。
• 为什么： 不清楚。
• 如何： 不清楚。

之后

无法为窗口表达式 {} 指定框架。 窗口表达式包含函数框架 {} 和规范框架 {} 之间的不匹配。

• 什么： 无法为窗口表达式指定框架。
• 为什么： 窗口表达式包含函数框架和规范框架之间的不匹配。
• 如何（由为什么暗示）： 匹配函数框架和规范框架。

示例 3

之前

无法解析任何十进制数。

• 什么： 无法解析十进制数。
• 为什么： 不清楚。
• 如何： 不清楚。

之后

无效的十进制数 {}； 在位置 {} 解析时遇到错误。

• 什么： 无效的十进制数。
• 为什么： 十进制解析器在指定位置遇到错误。
• 如何（由为什么暗示）： 修复指定位置的错误。

隐式回答为什么和如何

有时，即使明确解释为什么发生问题也是多余的； 在这种情况下，您可以跳过显式解释。

路径不存在：{}

• 什么： 路径不存在。
• 为什么（由什么暗示）： 用户指定了无效路径。
• 如何（由什么暗示）： 使用其他路径。

使用清晰的语言

用语指南

短语	何时使用	示例
不支持	用户可能有理由认为该操作是受支持的，但事实并非如此。 如果开发人员添加了对该操作的支持，则此错误将来可能会消失。	数据类型 {} 不支持。
无效 / 不允许 / 意外	用户在指定操作时犯了一个错误。 该消息应告知用户如何解决该错误。	数组的大小为 {}，索引 {} 无效。
		为子句 {} 找到 {} 个生成器。 仅允许一个生成器。
		找到意外的状态格式版本 {}。 预期的版本为 1 或 2。
无法	系统遇到一个意外的错误，该错误不能合理地归因于用户错误。	无法编译 {}。
不能	任何时候，最好仅在上述替代方案之一不适用时使用。	无法为不支持的类型 {} 生成代码。

措辞指南

最佳实践	之前	之后
使用主动语态	DataType {} 不支持 {}.	{} 不支持数据类型 {}。
避免基于时间的陈述，例如承诺未来的支持	透视表中当前不支持 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 源数据库和目标数据库不匹配。 源数据库为 {}，但目标数据库为 {}。