浅谈API错误码设计

错误码的设计原则：快速追踪溯源、简单、描述清晰（客户视角）。

1.快速追踪溯源：一个好的错误码应该使开发者和运维人员能够迅速识别错误的根源（比如APP看到用户提示错误信息，见名思意即可快速定位是ABCDEF哪个系统的什么问题），避免在不同系统或文档之间来回查找。

2.简单清晰易记：有效的错误码设计需要考虑其可读性和可比性，错误码应该有一个清晰的结构和逻辑，方便在代码中进行比较和处理。

3.信息描述清晰：很多错误码message描述连团队内同事都看不懂，何况调用你API的开发人员呢，所以要把message描述的清晰明了。

这些设计原则有助于构建一个高效、可靠且易于使用的错误码。通过遵循这些原则，可以确保错误码在实际应用中发挥出最大的价值。

API--错误码设计

在服务器接口设计中，定义接口错误码是至关重要的一环。通常，服务端会设定一系列的错误码，以便于指导接口调用者或用户采取恰当的操作。这些错误码可能涉及诸如参数非法、配置出错、内部异常等多种情况，为用户提供明确的反馈。

1）Response响应

在Response响应方面，我们的 API 将返回一个结构化的 JSON 对象，该对象包含以下三个关键属性：

1.code（状态码）: 这是一个标准化的数字代码，用于表明请求的处理结果。每个状态码都对应一个特定的情况，使得客户端可以快速识别请求的状态。

2.message（状态码描述）: 该字段提供了一个简短且清晰的描述，解释了状态码的含义。这将帮助客户端了解请求成功与否，如果出现问题，它将提供足够的信息以指导进一步的行动。

3.data（响应数据）: 这是实际的响应内容，包含了请求成功时所需的数据。这个数据对象的结构将根据具体的 API 调用而有所不同，但它总是以一种易于客户端解析和使用的格式提供。

字段	类型	描述
code	String	业务状态码
message	String	错误码描述，需要描述清晰明了
data	Object	封装对象

案例如下：

public class PromiseResponse<T> {    /**     * 错误编码     */    private String code;
    /**     * 提示信息     */    private String message;
    /**     * 业务数据     */    private T data

{  "code": 200,  "message": "成功",  "data": {    "transferTime": "Mon Jul 29 00:01:00 CST 2024",    "endOrderTime": "Mon Jul 29 18:00:00 CST 2024",    "outStoreTime": "Tue Jul 30 00:00:00 CST 2024",    "jitEndDate": "Tue Jul 30 00:00:00 CST 2024",    "storeDeliveryHandoverTime": "Tue Jul 30 01:00:00 CST 2024",    "deliveryTime": "Thu Aug 01 22:00:00 CST 2024",    "routeProductionResult": {      "ruleType": null,      "ruleName": null    },    "promiseControlResult": {      "controlResultCode": 2,      "suspendReasonCode": 0,      "suspendReason": null,      "abnormalLink": 0,      "abnormalLinkName": null,      "abnormalReason": null    }  }}

当发生可以重试的错误码时客户端应该以指数级增长的间隔来重试请求。除非文档中进行了说明。对于其他错误，重试操作可能并不可行，请先确保请求是幂等的并查看错误消息以获得指引。

3）错误传播

如果 API 服务依赖于其他服务，则不应盲目地将这些服务中的错误传播给客户端。翻译错误时，有如下建议：

• 错误码转换，比如下游返回错误码A，需要转换你对外的错误码B

• 错误码描述可追加下游错误码描述信息，让链路错误码描述清晰可见

• 最终对用户肯定是需要隐藏下游实现细节和机密信息，让用户体验良好的错误提示信息

4）❌不合理案例

❌不合理的API错误码，不合理地方如下：

1、错误码无规则：比较混乱。比如错误码一会1，一会-50，-1等，没有规则 

2、错误码过细：错误码定义过细过多、过度随意，将会导致调用方对错误处理的逻辑复杂，无法很好的对错误码进行转义或收敛。比如入参错误定义了N个错误码，其实定义一个入参错误码即可，错误码描述可以描述具体的错误码信息。

3、错误码描述不清晰：一堆英文，他人看不懂

5）✅行业案例

5.1京东云错误码

1）现在场景链路错误码信息

现有应用基本都是没有错误码传递功能，比如下图 Y应用出现故障，需要排查对应的依赖服务ABC，服务B返回的是服务B自定义的错误码B，但通过B是无法快速定位故障应用是C2。服务B经过各种排查，最终定位是服务B2的问题，服务B2通过错误码B2也无法快速定位是故障应用C2，继续每个应用排查，最终定位是服务C2错误。

2）错误码传递（转换）

接收下层模块发来的错误码A，错误码A是当下层模块有故障分支时生成的；然后将自身生成的错误码B和所接收到的错误码A合成错误码AB，将错误码AB传递给上层模块。

接收单元，用于接收下层模块发来的错误码A，错误码A是当下层模块有故障分支时生成的；

合成单元，用于将自身生成的错误码B和所接收到的错误码A合成错误码AB；

发送单元，用于将所述错误码AB传递给上层模块。

错误码在传递的过程中携带各层模块的故障分支信息，这样，根据错误码就可以确定错误码的传递路径，以便精确的定位故障错误原因，提高可维护性。

前面介绍了API的错误码设计及错误码传递，本章节探讨全链路错误码如何串联起来，不一定对，只是个人的思考，并且实践起来也是比较困难的不太现实

1）痛点：全链路排查问题慢

在京东复杂的系统架构中，故障诊断往往像是在迷宫中寻路。想象一下，一个由多达20+个相互依赖的系统组成的服务链路，从入口到底层的第N个服务，每个系统都是潜在的故障点。当前，一旦系统出现问题，都是上游拉群，定位问题拉下游N个系统，线上语音讨论是哪个出现的问题故障导致的，整个流程可能需要耗费长达1-2个小时甚至更长时间才能追踪到问题实际出现在M系统上。这个过程不仅耗时，而且效率低下。

在这种复杂系统架构中，目前故障诊断的技术面临多个挑战和缺点，主要包括：

1、时间消耗长、效率低下：当系统出现问题时，故障诊断需要逐个检查各个系统，需要长时间才能定位到问题所在的系统，这直接影响了故障恢复时间和系统的整体可用性。

2、复杂性管理不足：在多个相互依赖的系统中，即使是小问题也可能迅速演变成复杂问题，现有的技术似乎没有很好地管理这种复杂性。

3、信息孤岛：系统间可能存在信息隔离，导致故障信息不能快速传递，增加了诊断时间。

4、依赖专业知识：可能过度依赖工程师的专业知识和经验进行故障排查，这不仅效率低，而且不利于知识传承和团队协作。

2）设计思想

如下图：如果服务C2有故障，则通过全链路traceId可快速查看Y的故障对应的错误码，根据错误码定位是因为C2应用故障导致的。

日志错误码架构思路如下：

1677474.49460.17235995037011944.3460091.193151.9140|WMS_10001|调用Promise（系统B）系统异常，缺少预计妥投时间

1677474.49460.17235995037011944.3460091.193151.9140|PROMIES_10002|Promise调用路由系统(系统C）异常，缺少预计妥投时间

1677474.49460.17235995037011944.3460091.193151.9140|ROUTE_20003|派送范围维护->未查找到配置数据，请排查派送范围维护，派送地址：四川-达州市-宣汉县-龙泉土家族乡，产品：生鲜特殊次晨，生鲜特惠次晨，生鲜标快

这样通traceId（17235995037011944.3460091.193151.9140）可拿到链路中的AB（B1,B2,B3)C系统的错误码,其中B1/B2/B3等系统无错误，则可不打错误码。

具体系统设计图如下：

7.如果错误码信息被识别为异常或高优先级事件，系统将自动触发报警服务，通过多种方式（如咚咚、电子邮件、京Me等）通知相关干系人。对于紧急情况，系统还可以通过电话等方式直接联系一线人员，确保问题得到及时处理。

3）挑战性：链路改造范围广