错误码的标准化，带来的价值

日志：作为系统向用户及系统内其它子模块所输出当前运行状况的一种方式，其中往往蕴含着大量有效的潜在信息。如果用户能够有效阅读日志，将能够快速掌握系统当前的运行状况以及问题所在。其中，报错信息作为一种特殊的日志，它所输出的内容代表了系统的异常情况，是一种『求关注、求修复』的信号。如果报错信息简洁明了，用户则可以通过报错信息来快速定位问题并解决问题，快速恢复系统运行。

不过，许多错误日志的内容都十分冗长，阅读起来费时费力，如果需要从大量无效信息中提取最关键的有效信息，难度不亚于大海捞针。为了帮助系统研发人员以及使用者能够更加方便地管理和理解错误，因此就需要『错误码』来帮助用户快速了解阅读错误日志，快速过滤问题根源。

价值：错误码标准化

错误码的价值是显而易见的，因此不同的系统中都有各自定义的错误码。比如 Oracle 的经典报错 ORA-01555，比较有经验的 DBA 根据报错信息就能大致了解报错原因，好多 DBA 更是对一些常见的错误码耳熟能详。但仅仅依靠错误码还不够，系统中需要有一套结构化的设计来管理错误码，才能为用户提供系统性的问题快速过滤方法。

另一方面，不仅是用户受益于错误码标准化所带来的效率提升，系统本身作为服务提供方也是受益的。错误码标准化可以帮助系统的研发人员以标准化的方式来管理和输出错误，使整套研发和运维流程更加体系化。

ShardingSphere 错误码标准化

其原则与架构设计

ShardingSphere 错误码分为两类，一类是 SQL 类，一类是服务器类，本文主要介绍 SQL 类错误码。

在『简洁输出错误，高效解决问题』原则的基础上，ShardingSphere SQL 类错误码架构设计与主流关系型数据库的错误码规范保持一致。包含标准的 SQL State，Vendor Code 和详细错误信息， SQL 执行错误时输出日志的同时也会返回给客户端。

如此一来极大降低了用户的学习成本，使用户能够便捷准确定位到问题，进一步提升 ShardingSphere 的易用性。下面将通过一条错误语句分别在 MySQL 和 ShardingSphere-Proxy 的报错输出，来进一步展开对错误码的介绍，其中 ERROR 提示后依次是错误码 、SQL State 以及详细错误信息。

MySQL 的语法错误输出

mysql> SELECT * where FROM no_such_table;
ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'where FROM no_such_table' at line 1

ShardingSphere-Proxy 的语法错误输出

mysql> SELECT * where FROM no_such_table;
ERROR 12000 (42000): You have an error in your SQL syntax: SELECT * where FROM no_such_table, no viable alternative at input 'SELECT*whereFROM' at line 1, position 15, near 'FROM'

其中关于 SQL State，ShardingSphere 作为数据库的扩展层，在日常对数据库的操作访问过程中也很可能抛出异常，SQL State 就是用于返回数据库的报错信息。

补充介绍一下 "SQLstate" 字符串，该字符串遵守 XOPEN SQLstate 约定或 SQL:2003 约定。SQLState 字符串的值在适当的规范中描述。DatabaseMetaData 的方法 getSQLStateType 可用于确定驱动程序返回 XOPEN 类型还是 SQL:2003 类型。

错误码的架构

ShardingSphere 的错误码分为三部分，与 MySQL、Oracle 保持一致也是由5位数字组成：

第一部分为架构位，由第一位的数字组成，例如：数字 1xxxx 代表内核；数字 2xxxx 代表功能；数字 3xxxx 代表通用错误。

第二部分为功能模块位，由第二、三位的数字组成，例如内核类的功能模块位为第二位数字，功能类的功能模块位为第二、三位。

第三部分为功能模块位的内部错误位，排在功能模块位的后面，也就是由四、五位数字组成。

内核的错误码架构：

内核类的报错有9类分别使用（0-8）标注，具体分类如下：

1%d(Category)%d%d%d(Sequence) 

Categories of Kernel:

• metadata(0)

• data(1)

• syntax(2)

• connection(3)

• transaction(4)

• lock(5)

• audit(6)

• cluster(7)

• pipeline(8)

功能类的错误码架构：

功能类的报错分类两级，第一级代表不同功能使用（00-99）标注，第二级代表不同功能内的报错分类，具体分类如下：

2%d%d(Feature)%d(Category)%d(Sequence) 

Feature Codes:

• Sharding(0)

• Readwrite-splitting(2)

• Database-discovery(3)

• SQL translator(4)

• Traffic(5)

• Encryption(7)

• Shadow(8)

  ‍

Categories of Feature:

• metadata(0,1)

• data(2,3)

• syntax(4,5)

• connection(6,7)

• algorithm(8)

• customized-algorithm(9)

通用类的错误码架构：

通用类的报错分类一级，使用数字3开头。不过此类报错比较少，篇幅问题这里不进行额外的举例说明。

错误码示例：

内核语法类报错示例：

目前已经整理完成的标准错误码 200 多条，并且还在持续更新中。

🔍「 ShardingSphere 官方错误码示例 」🔗 https://shardingsphere.apache.org/document/current/cn/user-manual/error-code/sql-error-code/