从0到1，错误码如何设计和实现？

一、为什么做错误码

随着3D云设计工具的发展，用户可通过云设计工具，进行家居、公装、建筑、地产等全空间领域的云设计。

目前，群核科技（酷家乐）广泛应用于企业的设计、营销、管理等解决方案中，用以提升企业的效能。在3D云设计工具的功能不断丰富和完善中，整个设计系统涉及到的业务线和功能模块越来越多。以云设计工具4.0为例，其中包含较多的设计工具，如硬装、定制和BIM等。对于工具的线上问题反馈，存在线上问题定位难、排查效率低和信息不全等问题，导致用户线上问题解决链路长、时效性低，运营和业务支撑侧人力资源成本高，产研侧问题定位和排查成本高等问题。

思考：是否可在用户出现线上问题时，给与一定的错误提示来引导和解决问题？

二、错误码是什么

在用户遇到业务异常时，系统提供相应的“错误码”，给与帮助和引导问题解决，进行问题的快速定位。

用户场景演示：

三、错误码应用价值

| 客服系统：一键获取帮助、FAQ快速解答、客诉精准分类

| 解忧杂货铺、业务急救箱：一键搜索信息、问题快速定位

| 管理中心：问题快速定位（描述、敏捷组和FAQ）

| 工单：问题准确描述和反馈

强大的基建能力支撑，接入和管理成本降低80%
线上巡检：业务异常闭环巡检
监控警报：无缝对接监控警报
客诉分类：简单准确

如果有了错误码，我们会有什么样的价值？

3.1 故障定位快客户不焦虑大家不抓瞎

用户侧价值

线上问题时效增强
缩短问题链路
自助解决能力提升

运营和业务支撑

节约线上问题类的人力资源成本投入

产研侧价值

提升线上问题收集分类和问题分析，提高定位问题效率
减少人力成本
故障监控和错误码大盘，提前感知业务错误率

3.2 接入简单基建完善管理方便

错误码提供了完善的基建支持能力，可以让业务方高效接入、管理和维护。

强大的基建能力支撑，接入和管理成本降低80%

四、如何设计和实现

4.1 系统架构和流程

整体系统结构主要由错误码统一协议规范、基建配置、错误码管理中心、前后端业务、以及错误码工具包和前端解析插件组成，如下图所示。

错误码统一协议规范：提供错误码的统一格式、接口返回和消息获取方式。基建配置为错误码提供相应的基建服务，和各个基建打通，主要包含：服务资源管理中心、分布式配置中心和监控警报组成。错误码管理中心：错误码管理、FAQ管理、数据统计和线上巡检。为了业务前后端能高效接入和应用，提供了错误码工具包和前端解析插件，方便业务线进行快速接入。错误码生成流程如下图所示：

（1）服务资源管理中心的资源管理服务资源管理中心用以管理3D云设计软件的所有服务资源。

新申请的服务，先从服务资源管理中心申请服务资源，生成服务标识；
对于服务资源管理中心的已有服务，在前置工作中，已生成服务标识；

（2）错误码管理中心定时同步服务资源管理中心的服务资源情况，并自动计算错误码服务唯一标识；

（3）错误码管理中心推送错误码服务唯一标识到分布式配置中心

已存在的服务：错误码管理中心一次性推送所有云设计服务的错误码唯一标识到分布式配置
新创建的服务：创建服务时，错误码管理中心获取该服务的错误码唯一标识，自动推动到分布式配置中心，并将这唯一标识记录到该服务的对应的分布式配置页面中。

（4）云设计后端服务调用中间件提供错误码工具包中，获取完整的错误码和错误描述。在业务后端内部调用异常时，返回错误消息体。

（5）错误码信息上报监控（监控支持）

监控支持错误码标准数据格式搜集：错误码、描述、服务和接口等，支持自定义警报支持和特定错误码筛选和统计。

（6）错误码管理中心定时同步监控数据，更新错误码信息，如错误码、描述、接口和服务等。

4.2 协议规范

错误码统一格式

后端采用中心化配置管理数据库中的服务树来对后端服务做区分，统一格式如下表所示：

（1）大部门归属（Owner Team）：大部门归属标识

（2）业务线（PDL）：业务线标识

（3）服务（SERVICE）：服务标识

（4）保留位（SER/CLUSTER）：保留拓展位

（5）错误类型（TYPE）：后端错误码、前端错误码和反馈等

（6）错误码数据域（ErrorData）：用以标识业务错误码，如001表示工具CAD解析异常。

以工具下某服务为例，根据配置管理数据库中的服务树上的标签和数据域，可如下表示：

注：5 2 0 0 0 0 0 1 表示工具CAD解析异常

接口返回格式

{
    "c":"0"，        //状态码，成功为0，错误的情况下返回上述统一格式的错误码
    "m":"错误消息", //错误提示信息，"c":"0"则无
    "d":"结果"      //具体的返回结果数据
}

后端服务的消费方来源于业务前端和其他业务后端。业务前端通过http调用直接请求业务后端，后端服务之间通过rpc接口相互调用，为了做到对接的统一（一个业务前端对接多个业务后端，一个后端服务也会对接多个其它后端服务，同时存在一个后端服务透传依赖方后端服务返回数据的情况），需要定义统一的接口数据返回格式。同时为了区分业务异常与系统异常（网关超时，网关不通，限流熔断，网络错误等），经过业务处理的所有请求返回HTTP Status Code都为200，具体的业务异常和业务错误信息体现在上述返回数据结构的 ”c“ code字段以及 ”m“ message字段。对于系统异常，因为没有经过业务后端处理，所以请求返回HTTP Status Code为实际的错误码，比如网关超时返回503，网关不通返回404等。

消息获取流程

消息获取流程可用如下流程表示：1.用户进行方案设计时，业务前端向业务后端发起请求。2.当出现内部调用异常时，根据前端请求的请求头和错误码，返回相应的错误消息体；3.工具后端返回错误码和错误消息体给工具前端；4.工具前端将错误码和错误消息展示给用户；5.用户到相应的帮助中心，如客服系统、微信程序获取相应的帮助；

4.3 管理中心

考虑到区分错误码占位表后，由各业务线自己错误码数据域的管理和协调，可能出现管理和协调困难、以及人工维护带来的线上错误码和管理中心不一致等问题，增加维护成本。为解决错误码占位符和数据域的管理协调问题、错误码和管理中心的维护问题，采用错误码管理中心进行规范科学的错误码管理中心，主要分成：

4.4 基建支持和高效接入

4.4.1 监控警报

错误码无缝衔接监控警报，支持自定义报警和统计。错误码监控报警能力：

数据查询：即时查询监控项
统计和分析：监控看板管理中心看板设置
错误码数量占比：按错误码分类占比
错误码区间次数: 以5min时间粒度统计区间新增错误码数量
个性化报警：支持特定错误码，过滤某些错误码的警报设置
错误码监控大盘

实现方式：

在分布式调用链追踪框架进行埋点，使得调用链中拥有错误码code，标识字段已完成；
错误码中间件工具包统一打印错误日志，用于监控警报和统计，例如：ANALYZE {"_uniqueId":"00000112-5629-462c-465d-d1fbb1890001","code":"0000 0001","message":"方案错误","behaviorDescription":"ecodeException"}
统一配置错误码报警，无需业务方关心

监控大盘：

每周发现错误码异常 18K个，可有效应用于业务监控大盘。

4.4.2 错误码工具包和前端解析插件

错误码工具包

由各个业务方自己接入错误码，存在重复代码和工作量冗余，为方便接入，提升接入效率。对错误码的返回结构进行封装，具有通用的识别和解析能力。支持内容：

结构的封装和解析
错误码字段配置
错误码字段获取
监控拓展和支持

业务使用时：抛出异常构建Result返回获得结果：抛出异常被全局异常处理器捕获，结果格式符合webstandard标准

前端解析插件

工具业务线使用场景和接口繁多，具有以下现状：

存在加密和不加密两种接口
已加密接口，存在多种加密方式

为解决业务线工具在接入错误码后，业务前端可正常解析错误码返回，统一各业务方前端统一解析插件，减少接入成本。支持方式：

返回错误码时，中间件增加header，如x-code: 0000 0001
前端根据header来判断哪些是错误码返回，将数据解析后返回给业务前端，进行业务逻辑处理

4.4 效能提升

4.4.1 提高客诉分析人效

错误码优化后的客户线上问题处理流程：

用户遇到线上问题；
提交错误码进行快速定位和尝试解决问题；
若未解决，客服提交错误码的精准分类和工单；
根据错误码信息提交问题，技术侧进行快速处理；

4.4.2 线上巡检

为了更好的感知线上情况，提供错误码业务监控大盘的线上巡检能力，融入迭代并形成闭环。

巡检设置

选择服务标签
巡检的错误码：如0001，0002（可多次批量加入）
自行配置通知方式提醒
巡检频率：当前默认为警报次数
在研发系统平台自动创建缺陷和改进

巡检通知

测试效能平台通知
支持通过WebHook自行配置通知的方式，如企业微信机器人等

巡检示例

五、规划和展望

5.1 提升场景覆盖度

目前工具业务线已应用于硬装、定制、水电等业务线中，完成错误码一期接入，形成了用户、客服和技术团队的闭环链路。由于业务线排期紧张，当前覆盖场景不全面，后期将提升工具的场景覆盖度，覆盖用户高频操作场景。

5.2 智能工单的深度结合

现有工单系统中，通过已增加的错误码字段，可以更直观准确地描述用户反馈信息。而由于当前工单当前依赖人为创建，存在人效低的不足。后期规划通过错误码设置，自动创建错误码工单，减少人为工单依赖。同时在工单自动获取错误码对应信息，如描述、处理和解决方案等信息，提高人效。

文章作者：阿江