错误码与错误提示设计：最佳实践与资源指南

运维开发王义杰

发布于 2024-04-15 14:06:59

7490

发布于 2024-04-15 14:06:59

在软件开发的复杂世界中，错误是不可避免的。无论是因为外部系统的变化、用户输入的错误，还是内部逻辑的缺陷，错误都会出现。为了有效管理这些错误，并向用户和开发者提供清晰、有用的反馈，设计一套合理的错误码和错误提示系统变得至关重要。本文将探讨设计错误码和错误提示的最佳实践，并介绍一些可供参考的开源规范和模板。

错误码与错误提示设计的挑战

在软件项目的早期阶段就预测和规划所有可能的错误情况是一项挑战。设计过程需要在全面性和灵活性之间找到平衡点。此外，设计的错误码和提示不仅要对开发者有用，还要能够为最终用户提供清晰、易懂的信息。

设计最佳实践

系统化错误分类

创建一个系统化的错误分类体系是确保错误码和提示设计既灵活又全面的基础。这可以帮助组织和规划错误码，并提高代码的可读性和可维护性。

使用错误码模板

错误码模板可以帮助生成一致和规范的错误码。例如，模板可以基于错误的类型、来源和严重程度来生成错误码。

动态错误提示信息

实现根据错误上下文动态生成错误提示信息的机制可以提高错误信息的实用性，帮助开发人员和用户更快地定位和解决问题。

为未来的变化预留空间

在设计错误码时，预留一定范围的代码用于未来可能出现的新错误，可以最大限度地减少因添加新错误类型而导致的重构需求。

文档化和自动化

将所有错误码和错误提示信息文档化，并保持文档的最新状态是至关重要的。自动化工具可以帮助管理错误码库，确保遵循既定规则。

用户友好的错误提示

错误提示应清晰、易懂，避免使用技术性或模糊的语言，并提供解决问题的建议或行动指导，以提升用户体验。

开源规范与模板

开源社区提供了多种错误码规范和模板，可以作为设计自己的错误码系统的起点。包括：

1. HTTP 状态码

HTTP 状态码是Web开发中最常见的一种错误码规范，由IETF和W3C定义。它们覆盖了从成功响应到服务器错误的各种情况。虽然主要用于Web HTTP通信，但其分类方法和部分状态码可作为灵感，应用到其他类型的软件项目中。

1xx (信息响应)
2xx (成功)
3xx (重定向)
4xx (客户端错误)
5xx (服务器错误)

2. gRPC 状态码

gRPC是一个高性能、开源和通用的RPC框架，由Google主导开发，支持跨语言和平台。gRPC定义了一套自己的状态码，用于标识RPC调用的结果。这些状态码覆盖了各种RPC调用失败的情况，可以作为非Web项目错误码设计的参考。

https://grpc.io/docs/guides/status-codes/

3. Microsoft REST API Guidelines

Microsoft REST API Guidelines 包含了关于REST API设计的综合指南，其中包括错误处理和状态码的建议。这个指南为设计具有良好用户体验的API提供了宝贵的视角，其中的错误码和错误响应格式可作为RESTful服务或其他API设计的参考。

https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#710-response-status-codes

4. Google JSON Style Guide

Google JSON Style Guide 提供了JSON响应格式的规范，包括错误对象的设计。虽然它专为JSON设计，但提供的错误响应结构和思想可以适用于其他数据格式的API设计。

https://google.github.io/styleguide/jsoncstyleguide.xml#error


json
{
  "apiVersion": "2.0",
  "error": {
    "code": 404,
    "message": "File Not Found",
    "errors": [{
      "domain": "Calendar",
      "reason": "ResourceNotFoundException",
      "message": "File Not Found
    }]
  }
}

4. linux 系统错误码

Linux 系统和其它 Unix-like 系统中有一个定义良好的错误码体系，这些错误码定义在头文件 errno.h 中。这些错误码用于系统调用和一些库函数在遇到错误情况时返回，为开发者提供了一种检测和响应系统级错误的方式，对于涉及系统操作的开发场景可以参考。在ubuntu系统通过命令apt install moreutils安装moreutils后，即可通过errno -l命令列出错误码及描述。


bash
EPERM 1 Operation not permitted
ENOENT 2 No such file or directory
ESRCH 3 No such process
EINTR 4 Interrupted system call
EIO 5 Input/output error
ENXIO 6 No such device or address
E2BIG 7 Argument list too long
ENOEXEC 8 Exec format error
EBADF 9 Bad file descriptor
ECHILD 10 No child processes
EAGAIN 11 Resource temporarily unavailable
ENOMEM 12 Cannot allocate memory
EACCES 13 Permission denied
EFAULT 14 Bad address
ENOTBLK 15 Block device required
EBUSY 16 Device or resource busy
EEXIST 17 File exists
EXDEV 18 Invalid cross-device link
ENODEV 19 No such device
ENOTDIR 20 Not a directory
EISDIR 21 Is a directory
EINVAL 22 Invalid argument
ENFILE 23 Too many open files in system
EMFILE 24 Too many open files
ENOTTY 25 Inappropriate ioctl for device
ETXTBSY 26 Text file busy
EFBIG 27 File too large
ENOSPC 28 No space left on device
ESPIPE 29 Illegal seek
EROFS 30 Read-only file system
EMLINK 31 Too many links
EPIPE 32 Broken pipe
EDOM 33 Numerical argument out of domain
ERANGE 34 Numerical result out of range
EDEADLK 35 Resource deadlock avoided
ENAMETOOLONG 36 File name too long
ENOLCK 37 No locks available
ENOSYS 38 Function not implemented
ENOTEMPTY 39 Directory not empty
ELOOP 40 Too many levels of symbolic links
EWOULDBLOCK 11 Resource temporarily unavailable
ENOMSG 42 No message of desired type
EIDRM 43 Identifier removed
ECHRNG 44 Channel number out of range
EL2NSYNC 45 Level 2 not synchronized
EL3HLT 46 Level 3 halted
EL3RST 47 Level 3 reset
ELNRNG 48 Link number out of range
EUNATCH 49 Protocol driver not attached
ENOCSI 50 No CSI structure available
EL2HLT 51 Level 2 halted
EBADE 52 Invalid exchange
EBADR 53 Invalid request descriptor
EXFULL 54 Exchange full
ENOANO 55 No anode
EBADRQC 56 Invalid request code
EBADSLT 57 Invalid slot
EDEADLOCK 35 Resource deadlock avoided
EBFONT 59 Bad font file format
ENOSTR 60 Device not a stream
ENODATA 61 No data available
ETIME 62 Timer expired
ENOSR 63 Out of streams resources
ENONET 64 Machine is not on the network
ENOPKG 65 Package not installed
EREMOTE 66 Object is remote
ENOLINK 67 Link has been severed
EADV 68 Advertise error
ESRMNT 69 Srmount error
ECOMM 70 Communication error on send
EPROTO 71 Protocol error
EMULTIHOP 72 Multihop attempted
EDOTDOT 73 RFS specific error
EBADMSG 74 Bad message
EOVERFLOW 75 Value too large for defined data type
ENOTUNIQ 76 Name not unique on network
EBADFD 77 File descriptor in bad state
EREMCHG 78 Remote address changed
ELIBACC 79 Can not access a needed shared library
ELIBBAD 80 Accessing a corrupted shared library
ELIBSCN 81 .lib section in a.out corrupted
ELIBMAX 82 Attempting to link in too many shared libraries
ELIBEXEC 83 Cannot exec a shared library directly
EILSEQ 84 Invalid or incomplete multibyte or wide character
ERESTART 85 Interrupted system call should be restarted
ESTRPIPE 86 Streams pipe error
EUSERS 87 Too many users
ENOTSOCK 88 Socket operation on non-socket
EDESTADDRREQ 89 Destination address required
EMSGSIZE 90 Message too long
EPROTOTYPE 91 Protocol wrong type for socket
ENOPROTOOPT 92 Protocol not available
EPROTONOSUPPORT 93 Protocol not supported
ESOCKTNOSUPPORT 94 Socket type not supported
EOPNOTSUPP 95 Operation not supported
EPFNOSUPPORT 96 Protocol family not supported
EAFNOSUPPORT 97 Address family not supported by protocol
EADDRINUSE 98 Address already in use
EADDRNOTAVAIL 99 Cannot assign requested address
ENETDOWN 100 Network is down
ENETUNREACH 101 Network is unreachable
ENETRESET 102 Network dropped connection on reset
ECONNABORTED 103 Software caused connection abort
ECONNRESET 104 Connection reset by peer
ENOBUFS 105 No buffer space available
EISCONN 106 Transport endpoint is already connected
ENOTCONN 107 Transport endpoint is not connected
ESHUTDOWN 108 Cannot send after transport endpoint shutdown
ETOOMANYREFS 109 Too many references: cannot splice
ETIMEDOUT 110 Connection timed out
ECONNREFUSED 111 Connection refused
EHOSTDOWN 112 Host is down
EHOSTUNREACH 113 No route to host
EALREADY 114 Operation already in progress
EINPROGRESS 115 Operation now in progress
ESTALE 116 Stale file handle
EUCLEAN 117 Structure needs cleaning
ENOTNAM 118 Not a XENIX named type file
ENAVAIL 119 No XENIX semaphores available
EISNAM 120 Is a named type file
EREMOTEIO 121 Remote I/O error
EDQUOT 122 Disk quota exceeded
ENOMEDIUM 123 No medium found
EMEDIUMTYPE 124 Wrong medium type
ECANCELED 125 Operation canceled
ENOKEY 126 Required key not available
EKEYEXPIRED 127 Key has expired
EKEYREVOKED 128 Key has been revoked
EKEYREJECTED 129 Key was rejected by service
EOWNERDEAD 130 Owner died
ENOTRECOVERABLE 131 State not recoverable
ERFKILL 132 Operation not possible due to RF-kill
EHWPOISON 133 Memory page has hardware error
ENOTSUP 95 Operation not supported