错误码的设计使用

一、前言

承接上一篇的日志系统，有了日志系统为什么还要设计错误码系统呢，单纯的日志系统，再单应用的时候看日志解决问题还是可以胜任的，而出错也一般都是自身配置，资源超限诸如此类的，而企业级商用的系统，往往都是若干系统协调调用，其中任何一个系统出了问题，都有可能导致某个服务或者功能不可用，再通过调用顺序依次排查日志，不仅费时费力，而且由于相互依赖调用很难定位，那么日志系统在这时候就显得有点促襟见肘，错误码这个设计思想就孕育而生。

错误码使用场景

1. 通过错误码配置监控大盘。
2. 通过日志进行问题排查，快速定位问题。
3. 后端服务之间错误码传递。
4. 前端展示的错误提示/OpenAPI。

各个系统间面向日志错误码标准和一个面向外部传递的错误码应该建立一个统一的标准。

PS：本文部分引自阿里巴巴《Java 开发手册》，下称《手册》。

二 什么是错误码

好的错误码必须快速知晓错误来源而且易于记忆和对比。

好的错误码必须能够脱离文档和系统平台达到线下轻量沟通的目的（这个要求比较高）。

错误码的制定原则：快速溯源、简单易记、沟通标准化。

说明：错误码想得过于完美和复杂，就像康熙字典中的生僻字一样，用词似乎精准，但是字典不容易随身携带并且简单易懂。

正例：错误码回答的问题是谁的错？错在哪？

1）错误码必须能够快速知晓错误来源，可快速判断是谁的问题。

2）错误码易于记忆和比对（代码中容易 equals）。

3）错误码能够脱离文档和系统平台达到线下轻量化地自由沟通的目的。

三 错误码规范

错误码定义要有字母也要有数字

1. 纯数字错误码

错误码即人性，感性认知+口口相传，使用纯数字来进行错误码编排不利于感性记忆和分类。

说明：数字是一个整体，每位数字的地位和含义是相同的。

反例：一个五位数字 12345，第1位是错误等级，第 2 位是错误来源，345 是编号，人的大脑不会主动地分辨每位数字的不同含义。

《手册》说明了纯数字错误码存在的问题。

2. 纯字母错误码

那么纯字母错误码不香吗？有两个问题：

对于使用汉语的我们用英语去准确描述一个错误有时是比较困难的。

纯英文字母的错误码不利于排序。

错误码尽量有利于不同文化背景的开发者进行交流与代码协作。

说明：英文单词形式的错误码不利于非英语母语国家（如阿拉伯语、希伯来语、俄罗斯语等）之间的开发者互相协作。

3. 基于以上两点
其实实际使用场景中比较推荐的是纯数字+文档的方式，用头几位作为系统标识，中间几位为系统的模块标识，最后几位为实际错误码，这样便于维护扩展，区分系统的时候查询文档就可以可以快速确认。
例如：10 001 0001
10订单系统 001数据库连接模块 0001数据库连接超时
快速溯源 | 简单易记 | 沟通标准化

什么是快速溯源？就是一眼看上去就知道哪里出了什么问题。

李雷负责 A 服务，韩梅梅负责 B 服务。韩梅梅发现服务 B 出现了一个错误码，韩梅梅能够快速定位这是服务 A 的内部业务异常造成的问题，这个时候韩梅梅就可以拿着错误码找到李雷说，“hi，Li Lei，How old are you。(李雷，怎么老是你)”。李雷拿过来错误码一看，内心万马奔腾，一下就能知道这是上游 Polly 负责的应用阿尔法出了错。

四 面向日志的错误码

输出到日志的错误码有两个用途：

用来快速溯源找到问题。

用来形成监控大盘。

错误码不能直接输出给用户作为提示信息使用。

说明：堆栈（stack_trace）、错误信息(error_message)、错误码（error_code）、提示信息（user_tip）是一个有效关联并互相转义的和谐整体，但是请勿互相越俎代庖。

在获取第三方服务错误码时，向上抛出允许本系统转义，由 C 转为 B，并且在错误信息上带上原有的第三方错误码。

结合错误码设计原则、错误码用途、规约建议，面向服务端日志的错误码应该是如下形式。

《手册》中建议
错误码分为一级宏观错误码、二级宏观错误码、三级宏观错误码。

错误码即人性，感性认知+口口相传，使用纯数字来进行错误码编排不利于感性记忆和分类。

说明：数字是一个整体，每位数字的地位和含义是相同的。

反例：一个五位数字 12345，第 1 位是错误等级，第 2 位是错误来源，345 是编号，人的大脑不会主动地分辨每位数字的不同含义。

按照《手册》的建议设计出的面向日志的错误码定义共十三位（十位有意义，三位连接符），并且应该具有如下分类：

应用标识，表示错误属于哪个应用，三位数字。

功能域标识，表示错误属于应用中的哪个功能模块，三位数字。

错误类型，表示错误属于那种类型，一位字母。

错误编码，错误类型下的具体错误，三位数字。

《手册》还有一条是规定错误码应该如何定义：

错误码为字符串类型，共 5 位，分成两个部分：错误产生来源+四位数字编号。

说明：错误产生来源分为 A/B/C，A 表示错误来源于用户，比如参数错误，用户安装版本过低，用户支付超时等问题；B 表示错误来源于当前系统，往往是业务逻辑出错，或程序健壮性差等问题；C 表示错误来源于第三方服务，比如 CDN 服务出错，消息投递超时等问题；四位数字编号从 0001 到 9999，大类之间的步长间距预留 100。

五位错误码的好处是易记，但是对于面向日志的错误码场景利用错误码制作需要分类的业务监控大盘将变得比较困难，比如统计应用 A 的功能 B 的错误出现次数。

同样在系统间传递这个类型的错误码非常有可能发生错误码冲突。

《手册》对于错误码定义我认为非常适合面向外部传递的错误码。简单、易记、是大家熟悉的错误码样式，并且透出的错误码数量是非常有限的。

不用枚举定义错误码

国际化支持是一个不使用枚举定义错误码很重要的理由。

我们通过 i18n 的支持可以做到错误码、错误状态、错误描述的管理。

五 面向外部传递的错误码

面向外部传递的错误码是为了把域内的错误信息传递出去。

可以让域外系统通过错误码进行错误码进行后续的动作或是中断操作或是记录日志继续执行。

可以让前端通过错误码给出用户准确的错误提示或者忽略错误进行重试。

全部正常，但不得不填充错误码，约定俗成的返回五个零：00000。