错误码设计规范探索

本文涉及的产品
日志服务 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日志并进行多维度分析。
目录
相关文章
|
JSON 负载均衡 前端开发
一文带你详细了解Open API设计规范
一文带你详细了解Open API设计规范
3585 1
|
监控 前端开发 Java
错误码如何设计才合理?
对于错误码的设计,不同的开发团队有不同的风格习惯。本文分享阿里文娱技术专家长统对于错误码的看法,希望从错误码使用的不同场景讨论得到一个合理的错误码规约,得到一个面向日志错误码标准和一个面向外部传递的错误码标准。
10472 3
错误码如何设计才合理?
|
23天前
|
API 开发者
提供一份 1688 商品详情接口的错误码及解决方法
本文介绍了 1688 商品详情接口常见的错误码及其解决方法,包括 401(未授权)、403(禁止访问)、404(未找到)、429(请求过多)和 500/502/504(服务器错误)。详细说明了每个错误码的含义及相应的解决步骤,帮助开发者快速定位并解决问题。
|
1月前
|
API
阿里云短信平台API错误码提示错误天级流控显示小时级错误码
阿里云短信平台API错误码提示错误天级流控显示小时级错误码
|
3月前
|
小程序 Java 程序员
【规范】Apifox就应该这么玩
本文作者通过对比Postman与Apifox,分享了在项目中使用Apifox进行接口文档整理的方法,旨在帮助读者提升工作效率。文章详细介绍了Apifox目录整理策略、环境管理技巧及前置/后置操作的应用,使接口管理更加有序高效。无论是在短期开发还是长期迭代项目中,这些方法都能帮助开发者更好地管理和维护接口文档。
49 0
【规范】Apifox就应该这么玩
|
3月前
|
安全 API 数据安全/隐私保护
API 接口设计规范
API 接口设计规范
163 10
|
6月前
|
程序员
程序员为何对需求变更心存畏惧?
在当今日新月异的软件开发行业中,在快速变化、充满不确定性的软件开发行业中,项目的复杂性和动态性日益增加,而其中一个始终绕不开的话题就是需求变更,需求变更几乎成为了家常便饭。对于大部分程序员而言,面对需求的调整或修改,往往会产生一种普遍的“畏惧感”,这种心理反应并非空穴来风,而是由多方面因素共同作用的结果。所以说尽管这是行业常态,但程序员们对于需求变更的反应却往往带有明显的紧张与谨慎。那么本文就来简单聊聊关于程序员为什么对需求变更“心存畏惧”,也欢迎大家在评论区留言交流。
66 2
程序员为何对需求变更心存畏惧?
|
6月前
|
小程序 定位技术 Android开发
小程序质量提升丨定位问题解决方案(错误码11)
小程序质量提升丨定位问题解决方案(错误码11)
113 6
|
SQL 关系型数据库 数据库连接
【笔记】错误码
本文档列出了PolarDB-X返回的常见错误码及解决方法。
352 0
|
SQL Dubbo 安全
关于“错误码”设计方面的思考|系统异常,我****
这篇文章给大家分享一下关于“错误码”设计方面的思考。其实提到“错误码”我的第一反映是:混乱。 特别是在微服务架构之下,各个团队都有一套自己的“错误码”,甚至在一个团队里面不同的微服务都有自己的一套码值,这些“一套一套”的错误码,各成一派,互不通气。 但是一旦微服务上下游交互涉及到错误码转换的时候,总有一方就开始痛了,因为总有一方要承担兼容转换、令人“恶心”的逻辑。 我也见过试图在一片混乱中“力挽狂澜”的案例,比如由基础架构组提供统一的错误码管理平台,如果某个系统需要错误码就去该管理平台上去申请。 这个想法固然是好的,但是我认为存在的一个巨大的问题就是:历史码值的治理。