规范的错误信息

本文整理了 Google 官方文档中关于错误信息的编写规范。适用于有一定编程经验，尤其从事业务开发的程序员。

通过本文你可以：

• 写出风格统一、用户友好的错误信息
• 提高代码的可维护性，降低沟通成本

Google 文档原文：Error Messages

基本原则

• 错误不应该被掩盖 (Don’t fail silently)
• 遵循语言的规范 (Follow the programming language guides)
• 实现完整的错误模型 (Implement the full error model)

  包含错误码、错误内容、错误原因、处理方法

• 避免吞掉问题根源 (Avoid swallowing the root cause)
• 输出错误代码 (Log the error codes)
• 快速抛出错误 (Raise errors immediately)

解释错误原因

使用错误信息给用户解释原因时，应该遵循：

• 具体，准确，避免含糊。
• 在错误信息中包含用户输入的错误内容。如果输入的内容特别长：
  • 渐进地显示，提供一个可展开详情的省略号。
  • 截断内容，只保留必要部分。
• 明确告诉用户，系统的要求和限制

解释如何处理问题

• 对用户来说，错误信息必须有可操作性。也就是说，在解释了问题的原因后，说明如何解决这个问题。
• 最好给用户提供一个例子。

清晰的错误信息

• 简明扼要，使用主动语态。（这方面内容可以参考技术文档写作指南）
• 避免出现双重否定句式。
• 让目标用户能够理解，即根据用户掌握的知识，提供有帮助的内容。
• 专业术语应前后一致。

错误信息的格式

• 使用链接提供更多信息。
• 渐进式呈现错误信息（比如可以展开详情的省略号）。
• 错误提示应该贴近错误发生的位置。
• 避免错误信息滥用字体或颜色。
• 使用正确的语气:
  • 不要告诉用户错在哪，告诉用户应该做什么。
  • 避免责备、幽默、道歉的语气。

对后端开发的建议

• 错误要有错误码
• 可以在错误信息结构里提供一个指向错误解释的 ID，如：

  {
    "error": "Bad Request - Request is missing a required parameter: -collection_name. Update parameter and resubmit. Issue Reference Number BR0x0071"
  }