错误码如何设计才合理?

本文涉及的产品
日志服务 SLS,月写入数据量 50GB 1个月
简介: 对于错误码的设计,不同的开发团队有不同的风格习惯。本文分享阿里文娱技术专家长统对于错误码的看法,希望从错误码使用的不同场景讨论得到一个合理的错误码规约,得到一个面向日志错误码标准和一个面向外部传递的错误码标准。

image.png

一 前言

在工作中,接触过不少外部接口,其中包括:支付宝,微信支付,微博开发平台,阿里云等等。每家公司错误码风格都不尽相同,有使用纯数字的,有使用纯英文的,也有使用字母和数字组合的。也接触过很多内部系统,错误码设计也不尽相同。

错误码的输出路径

面向日志输出

  • 服务内传递,最终是输出到日志。
  • 域内服务间,比如同时大麦电商之间的系统,最终目的是输出到日志。

面向外部传递

  • 域内向域外
  • 服务端传递到前端
  • OpenAPI 错误码
  • 内部不同域之间

错误码使用场景

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

本文希望从错误码使用的不同场景讨论得到一个合理的错误码规约,得到一个面向日志错误码标准和一个面向外部传递的错误码标准。

PS:本文引用全部引自阿里巴巴《Java 开发手册》,下称《手册》。

二 什么是错误码

错误码要回答的最根本的问题是,谁的错?错在哪?

那么一个错误能表示出谁的错和错在哪里就是一个好的错误码吗?答案显然是否定的,这个标准太基础了。

  • 好的错误码必须能够快速知晓错误来源。
  • 好的错误码必须易于记忆和对比。
  • 好的错误码必须能够脱离文档和系统平台达到线下轻量沟通的目的(这个要求比较高)。

引自《手册》- 异常日志-错误码

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

说明:错误码想得过于完美和复杂,就像康熙字典中的生僻字一样,用词似乎精准,但是字典不容易随身携带并且简单易懂。
正例:错误码回答的问题是谁的错?错在哪?
1)错误码必须能够快速知晓错误来源,可快速判断是谁的问题。
2)错误码易于记忆和比对(代码中容易 equals)。
3)错误码能够脱离文档和系统平台达到线下轻量化地自由沟通的目的。

这个原则写在异常日志-错误码这个章节,我认为同样适用在面向用户的错误码。

image.png

三 错误码规范

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

纯数字错误码

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

说明:数字是一个整体,每位数字的地位和含义是相同的。
反例:一个五位数字 12345,第1位是错误等级,第 2 位是错误来源,345 是编号,人的大脑不会主动地分辨每位数字的不同含义。

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

纯字母错误码

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

  • 对于使用汉语的我们用英语去准确描述一个错误有时是比较困难的。
  • 纯英文字母的错误码不利于排序。

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

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

快速溯源 | 简单易记 | 沟通标准化

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

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

怎么能达到这个效果呢?

  • 首先要有一套标准并且在域内各个业务都在用同样的标准。
  • 其次要求错误码有自我解释的能力是有信息含量的有意义。
  • 最后在域内要传递错误码。

错误码标准的意义

开宗明义借用了《手册》对于错误码定义的原则作为错误码规范能够给我们带来的收益。我想再次强调并且试着从反面阐述没有错误码标准会带来的成本。

错误码是用来做沟通的:系统与系统间的沟通,人与人间的沟通,人与系统间的沟通。

试想下面这个场景:

韩梅梅看到一个异常日志其中一个纯数字的错误码。

韩梅梅需要理解这串数字代表的是什么,它到底是不是一个错误码,经过几秒钟确定下来这是一个错误码,但她不能确定这是不是本系统中错误码,因为在她负责的系统是由韩梅梅、Lucy 和 Lily 三个人共同维护的,每个人都按照自己的理解定义了一套错误码。

韩梅梅去系统源码中查找这个错误码,但是发现这个错误码并不是本系统的错误码。

然后再前翻两页后翻两页从日志上下文中确定这是李雷负责系统的错误码,“Li Lie,how old are you?”。

韩梅梅把错误码甩到李雷脸上,李雷一脸懵逼,这是我的系统的错误码吗?

李雷也不确定,因为李雷负责的系统是由李雷、林涛和 Jim 维护的,也是三人共同维护的。

李雷只好打开源码,还真是!

上边的场景经过了发现-初判断-判断来源-确定来源-沟通-二次判断-二次确认七个步骤。

希望上边的场景描述能够说明没有统一标准的错误所带来的成本。

四 面向日志的错误码

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

  • 用来快速溯源找到问题。
  • 用来形成监控大盘。

错误码设计

《手册》对于错误码的建议有非常多的可取参考的地方:

错误码不体现版本号和错误等级信息。

说明:错误码以不断追加的方式进行兼容。错误等级由日志和错误码本身的释义来决定。

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

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

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

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

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

错误码分为一级宏观错误码、二级宏观错误码、三级宏观错误码。

错误码即人性,感性认知+口口相传,使用纯数字来进行错误码编排不利于感性记忆和分类。
说明:数字是一个整体,每位数字的地位和含义是相同的。

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

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

  • 应用标识,表示错误属于哪个应用,三位数字。
  • 功能域标识,表示错误属于应用中的哪个功能模块,三位数字。
  • 错误类型,表示错误属于那种类型,一位字母。
  • 错误编码,错误类型下的具体错误,三位数字。

image.png

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

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

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

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

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

当然对于分为四段的错误码同样尤其不好的一面,应用标识和功能域标识需要有专人去管理或者开发一个错误码管理工具,否则时间一长很容易产生定义的混乱形成破窗。

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

不用枚举定义错误码

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

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

五 面向外部传递的错误码

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

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

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

错误码设计

根据《手册》给出的错误码定义建议设计出的面向外部传递的错误码共五位,并且有如下分类:

  • 错误类型,表示错误来源,一位字母。
  • 错误编码,表示具体错误,四位数字。

image.png

错误码的后三位编号与 HTTP 状态码没有任何关系。

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

说明:数字是一个整体,每位数字的地位和含义是相同的。
反例:一个五位数字 12345,第1位是错误等级,第 2 位是错误来源,345 是编号,人的大脑不会主动地分辨每位数字的不同含义。

下图是《手册》给出的错误码示例:

image.png

他山之石

他山之石不一定能攻玉。

谷歌 API 错误码定义

谷歌 API 的错误码定义与 HTTP 状态码有着非常强的联系,并且是一个全数字错误码定义。

没有明显的错误分类,快速识别和自解释能力比较弱。

image.png

腾讯 OpenAPI(文智)错误码定义

这也是一个全数字的错误码,没有明确的分类字段,纯数字的某一位已看不出明显的分类。

不利于进行感性记忆。
image.png

微博 API 错误码定义

同样是全数字的错误码定义:

image.png

其他建议

《手册》中有一条建议:

全部正常,但不得不填充错误码时返回五个零:00000。

这也是在其他家 API 错误码中能够看到的定义。

参考

《阿里巴巴java开发手册》
《Google API Design Guide 》(https://www.bookstack.cn/books/API-design-guide
《阿里云-文件存储-错误码》(https://help.aliyun.com/document_detail/62603.html
《微博开放平台-API-错误码》(https://open.weibo.com/wiki/Help/error
《腾讯开放平台-错误码》(https://wiki.open.qq.com/wiki/%E9%94%99%E8%AF%AF%E7%A0%81

相关实践学习
日志服务之使用Nginx模式采集日志
本文介绍如何通过日志服务控制台创建Nginx模式的Logtail配置快速采集Nginx日志并进行多维度分析。
目录
相关文章
|
5月前
|
存储
modbus异常错误码说明
modbus异常错误码说明
114 1
|
23天前
|
监控 前端开发 API
错误码设计规范探索
本文介绍了错误码设计规范,包括模块化分层、错误码结构及定义、可扩展性与可维护性等方面。错误码用于标识程序中的特定错误,便于快速定位和解决。文中详细描述了全局通用错误码和业务错误码的设计方法,并提出了5-6位数字编码方案,确保错误码的唯一性和可读性。同时,强调了错误码与日志系统的集成及多语言支持的重要性,提供了多个参考文献供进一步学习。
43 2
|
5月前
|
存储 数据库
第二章 一般错误信息 - 错误代码 100 到 199
第二章 一般错误信息 - 错误代码 100 到 199
49 0
|
3月前
|
运维 Kubernetes API
阿里云云效操作报错合集之API返回的错误信息,错误码为"Operate.NoPermission",该如何解决
本合集将整理呈现用户在使用过程中遇到的报错及其对应的解决办法,包括但不限于账户权限设置错误、项目配置不正确、代码提交冲突、构建任务执行失败、测试环境异常、需求流转阻塞等问题。阿里云云效是一站式企业级研发协同和DevOps平台,为企业提供从需求规划、开发、测试、发布到运维、运营的全流程端到端服务和工具支撑,致力于提升企业的研发效能和创新能力。
|
5月前
|
数据库 数据安全/隐私保护
第一章 一般错误信息 - 错误代码 0 到 99
第一章 一般错误信息 - 错误代码 0 到 99
41 0
|
11月前
|
Cloud Native Linux Go
听说你还在自己做重复劳动?看我一键生成错误码映射
听说你还在自己做重复劳动?看我一键生成错误码映射
|
5月前
|
小程序 定位技术 Android开发
小程序质量提升丨定位问题解决方案(错误码11)
小程序质量提升丨定位问题解决方案(错误码11)
105 6
|
SQL 关系型数据库 数据库连接
【笔记】错误码
本文档列出了PolarDB-X返回的常见错误码及解决方法。
340 0
|
SQL Dubbo 安全
关于“错误码”设计方面的思考|系统异常,我****
这篇文章给大家分享一下关于“错误码”设计方面的思考。其实提到“错误码”我的第一反映是:混乱。 特别是在微服务架构之下,各个团队都有一套自己的“错误码”,甚至在一个团队里面不同的微服务都有自己的一套码值,这些“一套一套”的错误码,各成一派,互不通气。 但是一旦微服务上下游交互涉及到错误码转换的时候,总有一方就开始痛了,因为总有一方要承担兼容转换、令人“恶心”的逻辑。 我也见过试图在一片混乱中“力挽狂澜”的案例,比如由基础架构组提供统一的错误码管理平台,如果某个系统需要错误码就去该管理平台上去申请。 这个想法固然是好的,但是我认为存在的一个巨大的问题就是:历史码值的治理。
|
搜索推荐 小程序 NoSQL
如何设计API返回码(错误码)?
客户端请求 API,通常需要通过返回码来判断 API 返回的结果是否符合预期,以及该如何处理返回的内容等 相信很多同学都吃过返回码定义混乱的亏,有的 API 用返回码是 int 类型,有的是 string 类型,有的用 0 表示成功,又有的用 1 表示成功,还有用”true” 表示成功,碰上这种事情,只能说:头疼 API 返回码的设计还是要认真对待,毕竟好的返回码设计可以降低沟通成本以及程序的维护成本
247 0