错误码设计规范
错误码(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)