错误消息指南

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

包含什么、为什么和如何

从 Spark 抛出的异常应该回答五个 W 和如何

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

异常提供的上下文可以帮助回答谁（通常是用户）、何时（通常包含在通过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 源数据库和目标数据库不匹配。源数据库为 {}，但目标数据库为 {}。