Skip to main content

错误处理

有效的错误处理能使系统更加健壮、易于调试。本文定义一个通用的错误数据结构，整理了常见的标准错误，对于错误的监控与处理也给出了通用的方案。

错误对象#

错误对象是一个标准的 JSON object，数据结构如下：

名称类型必须说明
namestring必须可读的唯一名字。例如： UNAUTHORIZED
messagestring必须未提供授权信息（Access Token）
detailsarray可选错误的额外详细信息。error_details 类型数组

error_details 对象：

名称类型必须说明
fieldstring必须引起错误的字段名称。输入有效性验证时会用到。
reasonstring必须错误的原因。

认证授权错误#

认证授权相关的错误只允许返回 401 或 403。以下是常见的错误类型定义，如果不能满足业务需求可以在此基础上扩展细化。

状态码错误代码及描述原因
401 UnauthorizedUNAUTHORIZED
未提供授权信息（Access Token）		访问本资源需要授权，未提供授权信息（Access Token）
401 UnauthorizedINVALID_CREDENTIALS
无效的用户身份信息		用户名密码错误
401 UnauthorizedINVALID_ACCESS_TOKEN
无效的 Access Token		系统无法识别本 Access Token
  • 格式错误
  • 非系统发行的 Access Token
  • Access Token 已被强制终止
    • 401 UnauthorizedACCESS_TOKEN_EXPIRED
    Access Token 过期    		Access Token 过期
    403 ForbiddenNO_PRIVILEDGE
    没有足够权限访问本资源    		尽管调用者提供了有效的凭证（Access Token ），但没有被授予访问本资源的权限

    输入验证错误#

    输入验证基于两个方面的原因：保证业务功能合理性、保证系统安全。从业务的合理性来说，用户提交的参数都需要进行验证。如在业务层面可能要求密码必须大于 8 位且至少含有一个特殊字符等。

    这里只描述保证业务功能合理性的部分，安全相关的部分将有相应的方案应对，不会有错误返回。

    状态码错误代码及描述原因
    400 Bad RequestINVALID_REQUEST
    无法解析请求中 JSON 数据    		发送请求时请求体不符合标准的JSON格式，服务器无法正确解析
    400 Bad RequestVALIDATION_FAILED
    未通过输入参数校验
  • 缺少必要的元素
  • 字段数据格式不正确（长度限制、数字格式、日期格式、邮件格式等）

    • 示例：创建学生未通过输入验证

    POST /students
    Request：略
    Response：
    HTTP/1.1 400 Bad Request
    {
    "error": {
    "name": "VALIDATION_FAILED",
    "message": "未通过输入参数校验",
    "details": [
    {
    "field": "name",
    "reson": "姓名不能为空"
    },
    {
    "field": "birthday",
    "reson": "生日格式不正确（YYYY-MM-DD）"
    }
    ]
    }
    }

    其它标准错误#

    状态码错误代码及描述原因
    404 Not FoundRESOURCE_NOT_FOUND
    指定的资源不存在    		请求的 URI 不正确或 URI 对应的资源不存在。
    如：数据中没有和指定主键匹配的数据。
    405 Method Not AllowedMETHOD_NOT_SUPPORTED
    服务端没有实现请求的 HTTP 方法    		服务不支持请求的 HTTP 方法
    406 Not AcceptableMEDIA_TYPE_NOT_ACCEPTABLE
    服务端没有实现客户端可接受的媒体类型    		服务端不能用客户端请求的媒体类型返回答应。
    如客户端发送可接收 application/xml，服务端却只能生成 application/json 的应答
    415 Unsupported Media TypeUNSUPPORTED_MEDIA_TYPE
    服务端不支持请求中有效载荷的媒体类型    		服务端不能处理请求中有效载荷的媒体类型。如客户端发送 application/xml 类型请求，服务端只接收 application/json 媒体类型
    429 Unprocessable EntitRATE_LIMIT_REACHED
    到达API 限流值，阻塞请求    		用户在规定的时间内的请求次数达到了API 请求的限流值。如某 API 设置为在 10 分钟内最多 100 次的 API 调用
    500 Internal Server ErrorINTERNAL_SERVER_ERROR
    内部服务错误    		服务端发生了非预期的错误，如空指针，数组越界等。
    503 Service UnavailableSERVICE_UNAVAILABLE
    服务无效    		因临时维护服务端不能处理请求

    STALE_DATA_STATE

    非标准错误#

    非标准错误指的是业务异常，是业务逻辑的分支，这类错误只允许返回 400 。如 一个话题关闭以后就不可以再回复，如这时调用添加回复 API，系统返回 话题已关闭，不可回复。

    状态码错误代码及描述原因
    400 Bad RequestPOST_CLOSED
    话题已关闭，不可回复`    		-

    错误监控#