一线大厂的最佳实践 - API 错误处理

今天的主题是API错误处理

正所谓一入江湖身不由己

至今还在探索中

如今到底如何

↓↓

-

1

-

前言

API 中的错误如何定义，请求过程中出错或请求处理中出错。API 无法解析传递的数据，API 本身有很多问题，甚至格式正确的请求也会进行失败。在这两种情况下，都需要进行分析查找原因。

无论是代码形式的错误还是简单的错误响应，错误代码可能是 API 领域中最有用的诊断元素，错误代码非常有用。API 响应阶段中的错误代码是开发人员可以将故障传达给用户的基本方式。

-

2

-

编写良好的错误代码

好的错误代码必须通过三个基本标准，才能真正发挥作用。好的错误代码应包括：

• 业务域标识，因此可以轻松确定问题的根源和领域；

• 内部参考 ID，用于特定于文档的错误符号。在某些情况下，只要内部参考表中包含 HTTP 状态码方案或类似的参考资料，就可以替换 HTTP 状态码。

• 人工可读的消息，概述了当前错误的上下文，原因和一般解决方案。

-

3

-

业界主流的处理方式

facebook

curl https://graph.facebook.com/v2.9/me?fields=id%2Cname%2Cpicture%2C%20picture&access_token=xxxxxxxxxxx

{
  error: {
    message: "An active access token must be used to query information about the current user.",
    type: "OAuthException",
    code: 2500,
    fbtrace_id: "ABdaipBGDyGFOyVCgrBfL56"
  }
}

Twitter

curl https://api.twitter.com/1.1/statuses/mentions_timeline.json

{
  errors: [{
    code: 215,
    message: "Bad Authentication data."
  }]
}

-

4

-

错误代码的定义

请求过程中出错，未进入处理逻辑。

{
   "domain": "pay",
   "code": 10501002,
   "message": "参数错误",
   "errors": [{
     "name": "bankNo",
     "message": "银行卡号不符合规范"
   }]
}

请求处理中出错

{
   "domain": "order",
   "code": 111501002,
   "message": "支付通道网络异常"
}

{
   "domain": "user",
   "code": 100501001,
   "message": "对应的用户不存在！"
}

错误代码详细说明：

• domain 定义了领域，方便定位错误的根源。

• code 定义了内部错误的编码

• message 描述了错误的原因

• error 对部分具体性错误进行了详细的说明

code 补充说明：异常码说明是由 8位 数字组成，前三位系统标识（从100开始），中间两位是模块标识（业务划分），后三位是异常标识（特定异常）

error 补充说明：当 message 不能准确描述错误产生的原因，需要细化每项错误说明时，可考虑使用 error 字段，来补充说明错误项。

domain 补充说明：底层框架里面封装了部分异常处理，比如参数校验错误这种 code 应该是全系统共用的，而不会有系统标识。导致就不能根据 code 识别出来是哪个系统发生错误了，链路一长就很难排查到底是哪的问题了，所以错误处理中动态去拿当前应用的业务域标识。

-

5

-

错误处理-Spring Boot

定义 Response 模型