错误码设计规范探索

本文涉及的产品
日志服务 SLS,月写入数据量 50GB 1个月
简介: 本文介绍了错误码设计规范,包括模块化分层、错误码结构及定义、可扩展性与可维护性等方面。错误码用于标识程序中的特定错误,便于快速定位和解决。文中详细描述了全局通用错误码和业务错误码的设计方法,并提出了5-6位数字编码方案,确保错误码的唯一性和可读性。同时,强调了错误码与日志系统的集成及多语言支持的重要性,提供了多个参考文献供进一步学习。


错误码设计规范

错误码(Error Code)是在计算机科学中用来标识程序或系统中发生特定类型错误的数值。以便快速溯源、简单易记、沟通标准化。

参考工业大公司的实践经验,设计一套属于本公司的错误码规范,以确保自研系统的可维护性、扩展性和可理解性。

一、模块化和分层次

               全局通用错误码:系统级别的错误,比如权限验证失败、请求参数错误、服务器内部错误等。这些错误码通常是项目的基础框架定义的,能够适用于不同模块和服务。

               业务错误码:业务层的错误通常是针对具体业务场景的,比如用户相关的操作失败、订单处理出错等。业务错误码往往是各个模块自己定义的,但可以遵循某种规范,便于统一管理。

               模块细化:按功能模块来细化错误码。例如,1000 系列的错误码对应的是用户相关的错误,2000 系列的错误码是订单相关的,3000 系列的错误码是订单审计相关的。这有助于快速定位问题所在的模块。

二、定义和结构

一种较简单的错误码格式:纯数字错误码, 5~6 位数,其中不同位代表不同的信息。例如:

               前两位:系统或模块标识

               中间两位:具体的业务功能

               后两位:错误的具体类型 这样设计不仅能防止错误码冲突,也能通过错误码快速分析问题。

例如:

               100xx 表示用户模块,10001 表示用户未找到,10002 表示用户权限不足。

               200xx 表示订单模块,20001 表示订单未支付,20002 表示订单已取消。

三、可扩展性与可维护性

               动态扩展:在设计错误码时为未来的功能扩展留出空间。比如每个模块设计时可能会预留一定的错误码范围(步长间距),以便未来新增业务时,不会影响现有业务逻辑。

               统一管理:错误码集中在一个公共的配置文件或数据库中统一管理,例如Enum枚举表,数据库错误词典等。

               高效查阅:错误码一般不直接展示给用户,需要前端转义或处理;错误码规范更多是面向开发团队,包括前端、后端、测试都参与问题排查过程,因此需要提供详细的错误文档说明,方便开发人员查阅和维护。

四、错误码与日志/监控系统集成

           1.    错误码和错误日志的区别和关系

错误码(Error Code)和错误日志(Error Log)都是在软件开发和系统管理中用来诊断和解决问题的重要措施,但它们有着不同的作用和表现形式。

区别:

               形式:错误码是一个简短的标识符,而错误日志是一段文本信息或者数据库记录,也可以设计一套结构化的错误

               用途:错误码主要用于快速识别错误类别;错误日志则提供了更详细的错误信息。

               细节程度:错误码通常不会包含太多细节,而错误日志可以包含丰富的上下文信息。

关系

尽管错误码和错误日志有区别,但它们通常是相辅相成的。当一个错误发生时,程序可能会同时记录错误日志并返回一个错误码。在排查问题时,错误码可以帮助快速定位到问题的类型,而错误日志则提供了具体发生了什么以及在什么样的环境下发生的上下文。结合使用两者可以使问题解决更加高效。

           2.    日志系统

需要建立一套日志系统(监控大盘),通过日志系统记录错误码和错误信息,便于后续的监控和问题排查。这些日志通常会被发送到集中式的日志服务,比如 ELK 或者 Splunk,开发人员可以通过错误码快速定位问题。

一种方案:NLog + Splunk 方案:将 NLog 作为.NetCore后端的日志记录框架;Splunk 作为日志管理和分析平台,二者联合构成日志系统。

五、多语言支持

错误码的国际化(Internationalization,常简写为i18n)是指使错误信息能够适应不同语言和地区的用户需求的过程,而不需要重新设计软件。这包括但不限于将错误信息翻译成不同的语言,以及确保这些信息符合当地的文化习惯和阅读习惯。

参考:

《阿里巴巴java开发手册》 (错误码如何设计才合理?-阿里云开发者社区

《Google API Design Guide 》(《Google API Design Guide (谷歌API设计指南)中文版》 - 书栈网 · BookStack

《阿里云-文件存储-错误码》(NAS API调用出现问题时返回的错误码信息-阿里云帮助中心_(NAS)-阿里云帮助中心

《微博开放平台-API-错误码》(Help/error - 微博API

《腾讯开放平台-错误码》(https://wiki.open.qq.com/wiki/%E9%94%99%E8%AF%AF%E7%A0%81

相关实践学习
日志服务之使用Nginx模式采集日志
本文介绍如何通过日志服务控制台创建Nginx模式的Logtail配置快速采集Nginx日志并进行多维度分析。
目录
相关文章
|
监控 前端开发 Java
错误码如何设计才合理?
对于错误码的设计,不同的开发团队有不同的风格习惯。本文分享阿里文娱技术专家长统对于错误码的看法,希望从错误码使用的不同场景讨论得到一个合理的错误码规约,得到一个面向日志错误码标准和一个面向外部传递的错误码标准。
10387 3
错误码如何设计才合理?
|
21天前
|
API
阿里云短信平台API错误码提示错误天级流控显示小时级错误码
阿里云短信平台API错误码提示错误天级流控显示小时级错误码
|
3月前
|
安全 API 数据安全/隐私保护
API 接口设计规范
API 接口设计规范
161 10
|
5月前
|
安全 API 数据安全/隐私保护
关于API安全设计5A原则
【6月更文挑战第1天】5A原则包括身份认证、授权、访问控制、可审计性和资产保护,是安全设计的核心要素。
|
6月前
|
小程序 定位技术 Android开发
小程序质量提升丨定位问题解决方案(错误码11)
小程序质量提升丨定位问题解决方案(错误码11)
113 6
|
SQL 关系型数据库 数据库连接
【笔记】错误码
本文档列出了PolarDB-X返回的常见错误码及解决方法。
349 0
|
SQL Dubbo 安全
关于“错误码”设计方面的思考|系统异常,我****
这篇文章给大家分享一下关于“错误码”设计方面的思考。其实提到“错误码”我的第一反映是:混乱。 特别是在微服务架构之下,各个团队都有一套自己的“错误码”,甚至在一个团队里面不同的微服务都有自己的一套码值,这些“一套一套”的错误码,各成一派,互不通气。 但是一旦微服务上下游交互涉及到错误码转换的时候,总有一方就开始痛了,因为总有一方要承担兼容转换、令人“恶心”的逻辑。 我也见过试图在一片混乱中“力挽狂澜”的案例,比如由基础架构组提供统一的错误码管理平台,如果某个系统需要错误码就去该管理平台上去申请。 这个想法固然是好的,但是我认为存在的一个巨大的问题就是:历史码值的治理。
|
算法 程序员 API
如何写一个合格的API文档
如何写一个合格的API文档
528 0
如何写一个合格的API文档
|
搜索推荐 小程序 NoSQL
如何设计API返回码(错误码)?
客户端请求 API,通常需要通过返回码来判断 API 返回的结果是否符合预期,以及该如何处理返回的内容等 相信很多同学都吃过返回码定义混乱的亏,有的 API 用返回码是 int 类型,有的是 string 类型,有的用 0 表示成功,又有的用 1 表示成功,还有用”true” 表示成功,碰上这种事情,只能说:头疼 API 返回码的设计还是要认真对待,毕竟好的返回码设计可以降低沟通成本以及程序的维护成本
257 0
|
XML 存储 SQL
REST API 设计规范(上)
REST API 设计规范
243 0