错误码与错误提示设计

1、背景介绍

在软件开发的复杂世界中，错误是不可避免的。无论是因为外部系统的变化、用户输入的错误，还是内部逻辑的缺陷，错误都会出现。为了有效管理这些错误，并向用户和开发者提供清晰、有用的反馈，设计一套合理的错误码和错误提示系统变得至关重要。因此一方面需要满足开发者的错误设计，另外也需要将错误友好的反馈给用户。

需要注意的是，错误说明是展示给用户的，最好直接告诉用户“该怎么做”而不是“哪里错了”，并且错误说明中不应该包含敏感信息（例如：堆栈信息）。但是为了方便问题排查，我们可以在系统内部日志中打印详细的错误堆栈信息。

制定一套错误码规约还是相对容易的，难的是在长期的实践中如何管理并正确使用错误码，保证不被滥用，其复杂程度跟项目规模相匹配。在规约设计时，应该以服务业务为导向，避免过度设计，保持简洁；在管理使用时，应该以先到先得的原则统一审批生效，生效后永久固定。以上就是我对于错误码规约制定一些想法，规则的制定是灵活的，可变通的，同样也没有绝对的好与坏，只要可以满足你的业务需求就是好的，优秀的。

2、软件内部框架好的错误码与错误提示设计是什么样？

2.1、错误码

2.1.1、错误码设计原则

快速溯源：错误码应能迅速帮助开发者定位问题来源，减少排查时间。
沟通标准化：在团队内部或跨团队之间，错误码的设计应遵循统一的规范，以降低沟通成本。
业务属性：错误码应体现业务系统的报错位置及原因，赋予一定的业务属性。
唯一性：错误码必须是错误的唯一标识，避免重复和混淆。
可扩展性：在设计时应预留一定范围的代码用于未来可能出现的新错误。

2.1.2、错误码设计方案

格式规范：
- 错误码可以采用字符数字组合表示，例如使用四段式结构，每段表示不同含义（如系统标识、错误类型、错误级别、序列号等）。
- 错误码内容格式应固定，统一长度，便于管理和使用。
内容清晰：
- 错误码的内容应简明扼要，能够直接反映错误类型或原因。
- 避免使用模糊或技术性的语言，确保开发者和用户都能理解。
文档化：
- 将所有错误码和错误提示信息文档化，并保持文档的最新状态。
- 文档应包含错误码的详细说明、触发条件、解决方案等信息。

2.2、错误提示

2.2.1、错误提示设计原则

简洁明了：错误提示应使用简洁明了的语言，避免冗长和复杂的表述。
必要信息：错误提示应包含必要的信息，帮助用户快速理解问题所在。
避免技术术语：尽量避免使用专业的技术术语，以减少用户的理解难度。
提供解决方案：如果可能，错误提示应提供解决问题的建议或行动指导。
情感友好：错误提示应保持情感友好，避免使用否定词或责备用户的语言。

2.2.2、错误提示设计方案

结构化展示：
- 错误提示可以采用结构化的方式展示，如包含错误码、错误说明、解决方案等部分。
- 对于复杂的错误，可以提供详细的错误堆栈信息或参考文档链接，但应确保这些信息对普通用户隐藏或可选显示。
位置合理：
- 错误提示应出现在用户易于发现的位置，如表单提交后的页面顶部或错误字段附近。
- 确保用户无需滚动页面即可看到错误提示。
视觉突出：
- 使用醒目的颜色或图标来突出显示错误提示，以吸引用户的注意力。
- 确保错误提示在视觉上与其他页面元素区分开来。

3、错误码及日志开源框架有哪些？

以下是一些开源框架，它们提供了强大的错误码处理功能，帮助开发者高效地管理和调试软件错误。

3.1、Slim Whoops

- 项目地址：https://gitcode.com/zeuxisoo/php-slim-whoops
- 特点：Slim Whoops 是一个为 PHP Slim 框架设计的优雅错误处理工具。它基于 Composer 安装，支持多种版本的 Slim 框架，从 v1 到 v4。通过简单的中间件集成，可以轻松地添加到 Slim 应用中。其核心特性在于使用了 Whoops 库，该库以其友好的界面和强大的错误信息展示而闻名。

3.2、FeedbackReporter

- 项目地址：https://gitcode.com/tcurdt/feedbackreporter
- 特点：FeedbackReporter 框架旨在简化桌面应用的错误报告流程。它采用模块化设计，包括异常处理、调用栈跟踪等功能，并且易于集成到应用程序中。该框架借鉴了 Fraser Speirs 和 Jens Alfke 的工作成果，如 Multipart/Form 构造和异常处理，保证了高质量的错误报告。

3.3、Gin框架

- 项目地址：https://github.com/gin-gonic/gin
- 特点：Gin 是一个用 Go 语言编写的 HTTP web 框架，它提供了错误码处理机制，帮助开发者更好地处理异常情况，提高程序的健壮性。在 Gin 框架中，开发者可以定义错误码，封装错误处理函数，并在路由处理函数中使用这些函数来处理不同类型的异常情况。

3.4、melonDB

- 项目地址：https://github.com/Water-Melon/Melon
- 特点：melonDB 是一个用 C 语言编写的开源数据库，它提供了错误码管理功能。melonDB 的错误码设计独特，使用 32 位整数表示，其中包含了错误码、源文件路径和行号等信息。这种设计使得错误信息更加丰富，有助于开发者快速定位和解决问题。

4、日志监控及分析工具

从可维护性角度来讲，有了好的错误码及错误日志，那么日志分析及监控工具的设计是比较简单。有利于开发、测试、运维人员进行错误的分析，快速的定位问题。

开源的日志工具：如Logstash、Fluentd等，可以帮助收集和分析错误日志，从而发现错误码的使用情况和潜在问题。
开源的监控工具：如Prometheus、Grafana等，可以实时监控系统的运行状态和错误情况，及时发现并解决问题。

5、用户操作错误设计

用户操作错误提示的设计应以提高用户体验为目标，确保错误信息的明确性、友好性、可见性和及时性。同时，遵循设计原则并考虑自定义与可扩展性，以满足不同用户的需求和期望。

1. 明确性
错误描述清晰：错误提示应直接明了地指出问题所在，避免使用模糊或技术性的语言。确保用户能够理解错误信息的含义，并知道如何解决问题。
错误码与说明结合：如果系统使用错误码，那么错误提示应同时包含错误码和相应的解释说明。这样，用户可以通过错误码快速查找解决方案，而解释说明则有助于非技术用户理解问题。
2. 友好性
情感友好：错误提示应保持情感友好，避免使用责备或消极的语言。采用积极、鼓励的语气，让用户感受到系统的帮助和支持。
提供解决方案：如果可能，错误提示应提供解决问题的建议或行动指导。这有助于用户快速恢复操作，减少挫败感。
3. 可见性
位置合理：错误提示应出现在用户易于发现的位置，如页面顶部、错误字段附近或弹出窗口中。确保用户无需滚动页面即可看到错误提示。
视觉突出：使用醒目的颜色、图标或字体样式来突出显示错误提示，以吸引用户的注意力。
4. 反馈及时性
即时反馈：在用户进行操作时，系统应即时反馈操作结果。如果操作有误，应立即显示错误提示，避免用户在不明确的状态下继续操作。
进度提示：对于需要等待的操作，系统应提供进度提示，让用户知道操作正在进行中以及预计的完成时间。
5. 自定义与可扩展性
错误码管理：建立统一的错误码管理系统，确保错误码的唯一性和规范性。同时，为未来的新错误预留扩展空间。
本地化支持：根据用户的语言偏好和地区设置，提供本地化的错误提示信息，以增强用户体验。
6. 遵循设计原则
简洁明了：避免在错误提示中堆砌过多信息，保持信息的简洁性和针对性。
一致性：保持错误提示的设计风格、语言风格和操作方式的一致性，以降低用户的学习成本。
可访问性：确保错误提示信息对所有用户都是可访问的，包括视觉、听觉或运动障碍用户。

6、参考

6.1、参考网站

https://zhuanlan.zhihu.com/p/651916931

https://zhuanlan.zhihu.com/p/486899287

https://juejin.cn/post/7094128414772166663

https://cloud.tencent.com/developer/article/2409169

6.2、错误码实例

6.2.1、枚举类错误码

// 在下面的代码中只给出了部分有代表性的错误码
@Getter
@AllArgsConstructor
public enum CommonErrorEnum implements IResponseEnum {/*** 成功*/SUCCESS("000000", 200, "SUCCESS"),/*** 参数校验(Valid)异常*/PARAM_VALID_ERROR("U00P01", 400, "参数校验异常"),/*** Token已过期*/TOKEN_EXPIRED("U00A02", 401, "Token已过期"),/*** 未授权，不能访问*/AUTH_INVALID("U00A05", 403, "未授权，不能访问"),/*** 服务器繁忙，请稍后重试*/SERVER_BUSY("U00S00", 500,"服务器繁忙"),/*** 未知异常，无法识别的异常*/SERVER_ERROR("U00O99", 500, "未知异常"),/*** Servlet请求类异常（部分）*/NoHandlerFoundException("U00N02", 404, "资源找不到"),HttpRequestMethodNotSupportedException("U00N03", 405, "HTTP请求方式不受支持"),HttpMediaTypeNotSupportedException("U00N05", 415, "HTTP请求头的 Content-Type 不受支持"),;/*** 返回码*/private String code;/*** 状态码*/private Integer http;/*** 返回消息*/private String message;
// /**
// * 参考文档 （可选）
// */
// private String reference;
}

6.2.2、错误码设计方案

错误码实例方案，

错误码应该是统一长度，且内容格式也应该固定的，而不应该是随机编码产生的。其内容可以是一个整数，也可以是一个字符串，但它必须是错误的唯一标识。通过研究对比各个平台的错误码，我总结出了一个比较实用的错误码设计方案：使用字符数字组合表示，一共有4段组成，不同段表示不同含义（应用标识、模块、错误类型、错误码）。

例如，下面模块用于生成错误返回值。该模块可以生成一个int型错误码，用来定位错误文件、错误行数以及错误类型。其中，32位 int 中，8位用于表示错误码，14位表示行数，9位表示文件名下标。即，该int型值的使用限制为：

支持255个错误码（0xff为表留值）
支持每个文件16383行（0x3ffff为保留值）
支持511个文件（0x1ff为保留值）
仅针对文件名，而非文件路径名，因此应尽量避免不同目录下出现同名代码文件
超出该限制的情况下，程序并不会发生异常或者报错，而是会报出Unknown ...的错误，