01 错误码
【强制】 错误码的制定原则:快速溯源、沟通标准化。
说明
错误码想得过于完美和复杂,就像康熙字典的生僻字一样,用词似乎精准,但是字典不容易随身携带且简单易懂。
正例 错误码回答的问题是谁的错?错在哪?
- 错误码必须能够快速知晓错误来源,可快速判断是谁的问题。
- 错误码必须能够进行清晰地比对(代码中容易 equals)。
- 错误码有利于团队快速对错误原因达到一致认知。
【强制】 错误码不应体现版本号和错误等级信息。
说明
错误码以不断追加的方式进行兼容。错误等级由日志和错误码本身的释义来决定。
【强制】 全部正常,但不得不填充错误码时,返回五个零:
00000。【强制】 错误码为字符串类型,共 5 位,分为两部分:错误产生来源 + 四位数字编号。
说明
错误产生来源分为 A/B/C:
- A 表示错误来源于用户,比如参数错误,用户安装版本过低,用户支付超时等问题;
- B 表示错误来源于当前系统,往往是业务逻辑出错,或程序健壮性差等问题;
- C 表示错误来源于第三方服务,比如 CDN 服务出错,消息投递超时等问题;
四位数字编号从 0001 到 9999,大类之间的步长间距预留 100,参考文末附表 3 错误码列表。
【强制】 编号不与公司业务架构,更不与组织架构挂钩,以先到先得的原则在统一平台上进行,审批生效,编号即被永久固定。
【强制】 错误码使用者避免随意定义新的错误码。
说明
尽可能在原有错误码附表中找到语义相同或者相近的错误码在代码中使用即可。
【强制】 错误码不能直接输出给用户作为提示信息使用。
说明
堆栈(
stack_trace)、错误信息(error_message)、错误码(error_code)、提示信息(user_tip)是一个有效关联并互相转义的和谐整体,但是请勿互相越俎代庖。【推荐】 错误码之外的业务信息应由
error_message承载,而不是让错误码本身涵盖过多具体业务属性。【推荐】 在获取第三方服务错误码时,向上抛出允许本系统转义,由
C转为B,并且在错误信息上带上原有的第三方错误码。【参考】 错误码可分为一级、二级、三级宏观错误码。
说明
在无法更加具体确定的错误场景中,可以直接使用一级宏观错误码:
A0001(用户端错误)、B0001(系统执行出错)、C0001(调用第三方服务出错)。正例
调用第三方服务出错是一级,中间件错误是二级,消息服务出错是三级。
【参考】 错误码的后三位编号与 HTTP 状态码没有任何关系。
【参考】 错误码有利于不同文化背景的开发者进行交流与代码协作。
说明
英文单词形式的错误码不利于非英语母语国家(如阿拉伯语、希伯来语、俄罗斯语等)之间的开发者互相协作。
【参考】 错误码应具有人性化,结合感性认知与口口相传。使用纯数字进行错误码编排不利于感性记忆和分类。
说明
数字是一个整体,每位数字的地位和含义相同。
反例
一个五位数字
12345,第 1 位表示错误等级,第 2 位表示错误来源,345为编号,但人的大脑不会主动地拆开并分辨每位数字的不同含义。