本文介绍了我在一些业务系统中遇到的错误提示问题,以及进行需求分析和设计实现的过程,欢迎进行交流和指点,一起进步。
1、需求起源
作为程序员,或多或少,都经历过如下场景:
-
场景1:
- 产品经理:xxx,用户反馈说收到一个看不懂的错误,你排查一下是什么问题:
- 程序员:这是哪个接口报的错?
- 产品经理:我去问问用户,另外,你这个错误能不能写明白一点,让我们可以看得懂?
- 程序员:要排查一下,某个变量没数据了,我改一下:
我们的程序出小差了
- 产品经理:啥叫变量变数据?错误提示后面把你的邮箱加上,出问题就找你吧,请联系xxx@beinet.cn
- 程序员:好,我改:
我们的程序出小差了,请联系xxx@beinet.cn
- 产品经理:看你回邮件挺辛苦的,把邮箱改成客服的吧,要改成yyy@beinet.cn
- 程序员:好,我改
- 产品经理:xxx,用户反馈说收到一个看不懂的错误,你排查一下是什么问题:
-
场景2:
- 产品经理:我们的产品,注册时的错误提示:
公司名称已被占用
,这个提示太简短,要改一下; - 程序员:好,我改一下,发布上线了;
- 产品经理:政策变了,不让用公司这个词,公司要改成团队,你再改一下;
- 程序员:好,我改
- 产品经理:又那啥了,再改一下,改成xxxx
- 程序员:我能不能不改啊……
- 产品经理:我们的产品,注册时的错误提示:
这种需求是合理的,可是类似的场景多了,程序员容易被打断,也会很烦躁;我们自然不能跟着产品经理的节奏,要想办法优化。
原始错误提示存在的问题:
- 开发人员定义的错误文字,被直接展示给用户,导致用户体验较差或其它误会;
- 政策变化或产品需要,导致一些敏感词需要替换;
- 产品定义错误文字,硬编码在代码(前端或后端 )里,而修改错误提示,需要开发介入和发布。
历次经历过的优化方案:
- 第1次:服务端把所有的错误提示,放在一个枚举类里,这样每次都只需要去这个文件里修改,再发布就好了;
但是每次还要发布啊,尤其是服务节点多了,时间还不短; - 第2次:每个错误提示,分配一个错误编号,并写入数据库,代码里定义一个全局变量,定时读取数据库,比如每分钟更新一次;
而所有返回错误提示的地方,全部改用错误编号,去全局变量里查找错误提示并返回;
这样,产品经理要改提示,程序员用SQL刷库就好了,再也不需要发布了;
可是,为什么改个提示,还要我程序员来操作啊? - 第3次:搞一个后台,可以编辑这个数据库表,并开放权限给产品经理;
这下安静了,改提示,再也不需要我们程序员介入了。
什么?前端也会报错,比如公司名称必须5个字以上
,这是前端报的错,能不能也放后端搞? - 第4次:前端也改造一下,前端的每个错误提示也改成错误编号,根据错误编号从后端的数据库里查找对应的错误提示,进行展示;
这回没啥事了吧。
啥?有些错误提示,要增加一个链接,引导用户去修复这个错误?要加字段?
这个获取错误提示的API又应该属于哪个业务的领域?
每个业务又都有自己的错误提示啊?
数据库挂了,用户那边显示不了错误,而且会不会读取错误码超时,连累其它业务?
一个小小的错误提示,怎么这么多事?
2、需求分析
那么对于错误提示,产品的真实需求是什么?我们具体分析一下:
每个产品不可避免都会出错,包括用户的无效操作导致出错、产品本身的缺陷导致出错,
对于这些错误,我们的产品要能:
- 提供正确的反馈:告知用户操作成功还是失败;
- 能帮助用户理解和引导解决问题:提供易于理解的、明确的错误信息,让用户知道出了什么问题,如何解决;
- 提升用户体验:错误提示应该要站在用户角度,让用户感到被关注、被尊重和被帮助,可以提升用户的满意度和忠诚度;
- 符合法律法规和业界明示暗示的规则。
要达到这些目的,我们的错误提示,不可避免的会经常变更:
- 错误提示不易于理解,被内部发现,或外部投诉,导致需要调整;
- 错误提示有政策风险、环境要求等,需要进行调整;
- 错误提示需要可扩展,如增加引导链接、增加图片、可配置某些错误不显示,支持国际化多语言能力支持
边界确认:
- 不管前端后端,都应该关注业务实现,出现错误就抛出去,怎么展示给用户,展示什么,都不应该是具体业务内的职责;
这也符合职责单一原则 - 由专门的后台服务,负责每个业务的错误,转换为具体的用户提示,输出给前端
- 前端可以专门封装一个模块或SDK,输入错误,找后台转换,并按业务规则进行展示
3、设计与实现
综合到成本、性能、通用性等各方面的评估,最终选型和过程如下 :
-
错误码定义:
- 定义产品ID,每个产品或业务定义不同的ID,以区分不同产品;
注:建议结合公司的立项流程,使用那边定义的项目编号;比如Android客户端定义为30 - 每个产品的不同模块,再定义模块ID,以区分产品里的不同模块;
比如Android客户端里的SDK模块定义为2 - 每个模块的程序员,在编码时为每个错误,定义一个错误码编号,如用户输入的密码长度不足,编号定为123;
则:Android客户端定义为30,SDK模块定义为2,再加错误码编号123,此时完整的错误码为302123,
对于程序员来说,看到这个错误码302123,就知道是Android设备端SDK模块抛出的 密码长度不足的错误; - 注:这个错误码定义的规范只是我这边的建议,你们可以根据各自的项目实际情况自行定义,方便理解和跟踪即可。
- 定义产品ID,每个产品或业务定义不同的ID,以区分不同产品;
-
提供一个错误码维护后台,进行错误码和用户错误提示的配置维护能力,保存到MySQL数据库;
增加操作规范要求:- 程序员新增错误码时,他必须去维护后台添加该错误码编号,及对应的开发说明;
- 出现新的错误码时,产品经理或运营人员,必须去配置相应的用户文案和引导链接等信息;
- 可以增加监控,扫描所有模块里的错误码,出现未配置的错误码时进行钉钉群告警。
-
当错误码数据有变更时,维护后台会自动生成js 和 json两种格式的文件,可以选择上传到资源服务器、或阿里云oss、或aws-S3;
注:在项目配置里(或数据库里)根据不同产品配置,可以配置各自的静态资源文件存储目标位置。 -
前端封装一个SDK,读取对应的js或json静态资源文件,进行缓存并定时刷新(建议利用http的304协议机制判断和更新);
- 当遇到错误时,根据代码返回的错误码编号,去查找静态资源文件里的对应错误提示,进行展示给用户;
- 如果未找到错误提示(遗漏配置),则展示通用的错误提示,如:
我们的系统打了个盹,请稍候再试。
设计优点:
- 没有API,仅静态资源文件,几乎不需要考虑性能问题,成本问题也几乎可以忽略;
- 只提供一个管理后台的配置页面和一张表,可以夹杂在统一的管理后台中,迁移方便;
- 提供js和json两种格式,通用性强;
- 支持各种需要对用户展示错误提示和错误引导的场景,包括:浏览器前端、Windows客户端、iOs客户端、Android客户端等等;
- 可扩展性强,只要保证原有的格式不变,在后面新增字段,均没有任何影响;
- 可SaaS化,通过产品标识进行租户区分和错误码生成;
- 提升排错能力,可以通过配置是否展示错误码给用户,当用户截图反馈问题时,可以根据错误码快速定位哪个产品哪个模块出错;
尤其是微服务化时,链路的哪个模块抛出的错误一目了解;
建议增加链路跟踪ID展示(可以虚化放在背景图中,不影响用户体验)
3.1、数据库设计参考
CREATE TABLE `t_errcodes` (`id` int NOT NULL AUTO_INCREMENT COMMENT '自增ID',`product_id` int NOT NULL COMMENT '产品标识',`err_code` int NOT NULL COMMENT '错误码',`rd_desc` varchar(1000) NOT NULL DEFAULT '' COMMENT '开发人员备注,不输出给前端',`lang` varchar(10) NOT NULL DEFAULT 'zh-CN' COMMENT '所属语言',`err_type` varchar(100) NOT NULL DEFAULT '' COMMENT '错误分类',`show` tinyint NOT NULL DEFAULT 0 COMMENT '是否展示给用户',`retry` tinyint NOT NULL DEFAULT 0 COMMENT '出错是否允许重试',`process_desc` varchar(1000) NOT NULL DEFAULT '' COMMENT '用户错误处理文案',`process_url` varchar(1000) NOT NULL DEFAULT '' COMMENT '用户错误引导链接',`tag` varchar(50) NOT NULL DEFAULT '' COMMENT '标签',`create_date` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',`update_date` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',PRIMARY KEY (`id`) USING BTREE,UNIQUE INDEX `unq_err_code`(`lang`, `err_code`, `product_id`) USING BTREE
) ENGINE = InnoDB COMMENT = '错误码配置表';
3.2、静态资源文件生成规则参考
在管理后台进行错误码编辑后,会自动为每个产品、每个语言,创建一个js文件和json文件,使用参考如下:
- 文件命名规则:
- js文件命名为【errcode-产品标识-语言.js】,如:
产品标识为Android的40,语言为en-US,则文件名为 errcode-40-en-US.js - json文件命名为【产品标识-errcode-语言.json】,如:
产品标识为Android的40,语言为en-US,则文件名为 errcode-40-en-US.json
- js文件命名为【errcode-产品标识-语言.js】,如:
- 注:你可以根据自己的情况,使用产品+模块+语言来定义文件名,如果错误码少,也可以全局就一个错误码文件。
3.3、静态资源文件使用参考
- js格式文件内容参考:
window.bn_globalErrorCode = {"40001": {"err_type": "about user","process_desc": "email already exists","process_url": "https://beinet.cn/help.html","show": 1,"retry": 1},"40121": {"err_type": "about login","process_desc": "password's length must longer than 6","process_url": null,"show": 1,"retry": 1}
};
注:为了压缩减小体积,我在实际生产系统使用的是下面这种单行/数组格式,如:
window.bn_globalErrorCode = {"40001":["about user","email already exists","https://beinet.cn/help.html",1,1],"40121":["err_type": "about login","password's length must longer than 6",null,1,1]};
Javascript前端使用代码参考(针对单行/数组格式):
<script src="https://oss.beinet.cn/errorCode/errcode-40-en-US.js"></script>
<script>function findUserDesc(code) {let obj = window.bn_globalErrorCode[code];if (!obj) return '未配置此错误码,返回通用错误说明'; // 这里找产品出一个通用错误文案if(obj[3] !== 1)return '这个错误不显示报文错误'; // show的内容,根据你的具体业务场景使用return obj[0] + ':' + obj[1];}let errCode = '40001';alert(findUserDesc(errCode)); // 会弹出:email already exists
</script>
- json格式文件内容参考:
json格式文件,与js文件相比,只少了前面的全局变量【window.bn_globalErrorCode】定义
4、自动导出与导入
为方便开发人员初始化和产品人员使用,我在生产环境也部署了一些工具:
- 后端框架层实现
/actuator/enums
接口,可以遍历项目中所有enum类,并输出为json,
然后在管理后台,把该接口输入,即可自动导入业务项目里的所有错误码枚举。
该端点类的代码实现参考,也可以直接去这里下载源码:
package beinet.cn.frontstudy.actuator;import org.reflections.Reflections;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;import java.lang.reflect.Field;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.util.*;
import java.util.stream.Collectors;/*** 遍历项目中所有枚举类,并显示的端点类** @author youbl* @since 2023/04/08*/
@Endpoint(id = "enums")
@Component
public class EnumListEndPoint {@Autowiredprivate ApplicationContext context;private Map<String, Object> enumMap;private void Init() throws IllegalAccessException, InvocationTargetException {Map<String, Object> beansWithAnnotation = context.getBeansWithAnnotation(SpringBootApplication.class);if (!beansWithAnnotation.isEmpty()) {Class<?> appClass = beansWithAnnotation.values().toArray()[0].getClass();Reflections reflections = new Reflections(getScanPackageName(appClass));Set<Class<? extends Enum>> enums = reflections.getSubTypesOf(Enum.class);for (Class<? extends Enum> enumClass : enums) {List<Method> methods = Arrays.stream(enumClass.getMethods()).filter(m -> m.getName().startsWith("get") && Modifier.isPublic(m.getModifiers()) && !Modifier.isStatic(m.getModifiers()) && m.getParameterCount() == 0).filter(m -> !m.getName().equals("getClass") && !m.getName().equals("getDeclaringClass")).collect(Collectors.toList());for (Method method : methods) {method.setAccessible(true);}EnumObject enumObject = new EnumObject();if (enumMap == null)enumMap = new HashMap<>();enumMap.put(enumClass.getTypeName(), enumObject);Field[] values = enumClass.getFields();for (Field enumItem : values) {if (enumItem.getType() != enumClass)continue;enumItem.setAccessible(true);Object enumValue = enumItem.get(null);String code = enumItem.getName();enumObject.Enums.put(code, getMap(enumValue, methods));}}}}private String getScanPackageName(Class<?> appClass) {SpringBootApplication anno = appClass.getAnnotation(SpringBootApplication.class);if (anno != null) {String[] packages = anno.scanBasePackages();if (packages != null && packages.length > 0)return packages[0];}return appClass.getPackage().getName();// .getPackageName();}@ReadOperationpublic Map<String, Object> read() throws InvocationTargetException, IllegalAccessException {if (enumMap == null) {synchronized (this) {if (enumMap == null)Init();if (enumMap == null)enumMap = new HashMap<>();}}return enumMap;}private Map<String, Object> getMap(Object enumInstance, List<Method> methods) throws InvocationTargetException, IllegalAccessException {Map<String, Object> map = new HashMap<>();for (Method method : methods) {map.put(method.getName().substring(3), method.invoke(enumInstance));}return map;}public static class EnumObject {public String Description;public Map<String, Map<String, Object>> Enums = new HashMap<>();}
}
- 通过定时任务定时扫描与导入,如crontab、xxljob之类,定时扫描所有业务项目的api,实现自动的导入;
因为导入时,只有程序员写的文字,为避免新增的错误码被用户看到,可以设置为告警,而不做导入; - 管理后台,增加多语言错误码比对能力,防止某些语言遗漏了配置,并支持批量导出和导入能力,方便内部员工操作。
后续有机会,我再整理一下整个错误码工程源码,并开源出来。