需求分析案例：全局错误码设计

本文介绍了我在一些业务系统中遇到的错误提示问题，以及进行需求分析和设计实现的过程，欢迎进行交流和指点，一起进步。

1、需求起源

作为程序员，或多或少，都经历过如下场景：

  • 场景1：

    • 产品经理：xxx，用户反馈说收到一个看不懂的错误，你排查一下是什么问题:
      在这里插入图片描述
    • 程序员：这是哪个接口报的错？
    • 产品经理：我去问问用户，另外，你这个错误能不能写明白一点，让我们可以看得懂？
    • 程序员：要排查一下，某个变量没数据了，我改一下：我们的程序出小差了
    • 产品经理：啥叫变量变数据？错误提示后面把你的邮箱加上，出问题就找你吧，请联系xxx@beinet.cn
    • 程序员：好，我改：我们的程序出小差了，请联系xxx@beinet.cn
    • 产品经理：看你回邮件挺辛苦的，把邮箱改成客服的吧，要改成yyy@beinet.cn
    • 程序员：好，我改

  • 场景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模块抛出的 密码长度不足的错误；
    • 注：这个错误码定义的规范只是我这边的建议，你们可以根据各自的项目实际情况自行定义，方便理解和跟踪即可。

  • 提供一个错误码维护后台，进行错误码和用户错误提示的配置维护能力，保存到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
  • 注：你可以根据自己的情况，使用产品+模块+语言来定义文件名，如果错误码少，也可以全局就一个错误码文件。

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，实现自动的导入；
    因为导入时，只有程序员写的文字，为避免新增的错误码被用户看到，可以设置为告警，而不做导入；
  • 管理后台，增加多语言错误码比对能力，防止某些语言遗漏了配置，并支持批量导出和导入能力，方便内部员工操作。

后续有机会，我再整理一下整个错误码工程源码，并开源出来。

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.hqwc.cn/news/27973.html

如若内容造成侵权/违法违规/事实不符，请联系编程知识网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

GPT使用技巧

GPT使用技巧

五大原则 想要让ChatGPT产出有效的回答&#xff0c;需要遵循以下五个原则&#xff1a; 提问清晰&#xff1a; 请尽可能清晰地描述您的问题 简明扼要&#xff1a; 请尽量使用简单的语言和简洁的句子来表达您的问题 确认问题&#xff1a; 请确认您的问题是清晰、明确和完整…
阅读更多...
promise规范及应用(进阶)

promise规范及应用(进阶)

##promise解析 *啥是异步? //异步执行let count 1let timer setTimeout(function () {countconsole.log(in, count);}, 1000);console.log(out);// out>1000>in//循环执行let count 1let timer setInterval(function () {countconsole.log(in, count);}, 1000);con…
阅读更多...
【C++修炼之路】list 模拟实现

【C++修炼之路】list 模拟实现

&#x1f451;作者主页&#xff1a;安 度 因 &#x1f3e0;学习社区&#xff1a;StackFrame &#x1f4d6;专栏链接&#xff1a;C修炼之路 文章目录 一、读源码二、成员三、默认成员函数1、构造2、析构3、拷贝构造4、赋值重载 四、迭代器五、其他接口 如果无聊的话&#xff0c;…
阅读更多...
【学会动态规划】解码方法（4）

【学会动态规划】解码方法（4）

目录 动态规划怎么学&#xff1f; 1. 题目解析 2. 算法原理 1. 状态表示 2. 状态转移方程 3. 初始化 4. 填表顺序 5. 返回值 3. 代码编写 写在最后&#xff1a; 动态规划怎么学&#xff1f; 学习一个算法没有捷径&#xff0c;更何况是学习动态规划&#xff0c; 跟我…
阅读更多...
跟我一起从零开始学python（九）numpy+pandas+matplotlib

跟我一起从零开始学python（九）numpy+pandas+matplotlib

前言 回顾之前讲了python语法编程 &#xff0c;必修入门基础和网络编程&#xff0c;多线程/多进程/协程等方面的内容&#xff0c;后续讲到了数据库编程篇MySQL&#xff0c;Redis&#xff0c;MongoDB篇&#xff0c;和机器学习&#xff0c;全栈开发前面没看的也不用往前翻&#…
阅读更多...
macos使用搭建算法竞赛c/c++的g++/gcc编译环境(homebrew，含万能头，改环境变量，vscode/clion可用)

macos使用搭建算法竞赛c/c++的g++/gcc编译环境(homebrew，含万能头，改环境变量，vscode/clion可用)

文章目录 1、homebrew安装2、安装g3、改环境变量 1、homebrew安装 我没改镜像&#xff0c;直接网上脚本一键安装的&#xff0c;具体命令忘了&#xff0c;可能是这个 反正装这个的方法很多&#xff0c;网上一搜都有。 成功装上homebrew就行。 /bin/bash -c "$(curl -fsSL…
阅读更多...
Acwing.905 区间选点(贪心)

Acwing.905 区间选点(贪心)

题目 给定N个闭区间[a,bi]&#xff0c;请你在数轴上选择尽量少的点&#xff0c;使得每个区间内至少包含一个选出的点。输出选择的点的最小数量。 位于区间端点上的点也算作区间内。 输入格式 第一行包含整数N&#xff0c;表示区间数。 接下来N行&#xff0c;每行包含两个整数…
阅读更多...
【QT】元对象系统学习笔记（一）

【QT】元对象系统学习笔记（一）

QT元对象系统 01、元对象系统1.1、 元对象运行原则1.2、 Q_OBJECT宏1.3、 Qt Creator启动元对象系统1.4、 命令行启动元对象&#xff08;不常用&#xff09; 02、反射机制2.1、 Qt实现反射机制2.2、 反射机制获取类中成员函数的信息2.1.1、 QMetaMethon类2.1.2、QMetaObject类 …
阅读更多...
如何快速又高质量的输出PDF实验报告？

如何快速又高质量的输出PDF实验报告？

摘要&#xff1a;本文由葡萄城技术团队于CSDN原创并首发。转载请注明出处&#xff1a;葡萄城官网&#xff0c;葡萄城为开发者提供专业的开发工具、解决方案和服务&#xff0c;赋能开发者。 PDF文档的打印在很多应用场景中都会被使用到&#xff0c;最为常见的就是实验室信息管理…
阅读更多...
xred病毒分析

xred病毒分析

概述 xred病毒是一种感染型病毒&#xff0c;会感染系统中特定目录下的exe和xlsx文件&#xff0c;该病毒会将自身伪装成Synaptics触摸板驱动程序&#xff0c;使用Dephi编写。 样本的基本信息 Verified: Unsigned Link date: 6:22 1992/6/20 Company: Synaptics Description: S…
阅读更多...
华南农业大学|图像处理与分析技术综合设计|题目解答：定位数显区域并分离电表数字

华南农业大学|图像处理与分析技术综合设计|题目解答：定位数显区域并分离电表数字

设计任务 图 28 是一幅正在运行的数字电表图像&#xff08;ipa28.jpg&#xff09;&#xff0c;试采用图像处理与分析 技术&#xff0c;设计适当的算法和程序&#xff0c;找出电表的数显区域&#xff0c;计算目标区域的长宽比 和像素面积&#xff1b;并提取其中面积最大的 …
阅读更多...
Service：微服务架构的应对之道

Service：微服务架构的应对之道

Service 的工作原理和 LVS、Nginx 差不多&#xff0c;Kubernetes 会给它分配一个静态 IP 地址&#xff0c;然后它再去自动管理、维护后面动态变化的 Pod 集合&#xff0c;当客户端访问 Service&#xff0c;它就根据某种策略&#xff0c;把流量转发给后面的某个 Pod。 Service 使…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023