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

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

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.mzph.cn/news/4325.shtml

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

相关文章

智慧校园能源管控系统

智慧校园能源管控系统是一种搭载了物联网技术、大数据技术、大数据等技术性智能化能源管理方法系统&#xff0c;致力于为学校提供更高效、安全性、可信赖的能源供应管理和服务。该系统包括了校内的电力工程、水、气、暖等各类能源&#xff0c;根据对能源的实时检测、数据统计分…

文心一言 VS 讯飞星火 VS chatgpt (63)-- 算法导论6.5 2题

文心一言 VS 讯飞星火 VS chatgpt &#xff08;63&#xff09;-- 算法导论6.5 2题 二、试说明 MAX-HEAP-INSERT(A&#xff0c;10)在堆A(15&#xff0c;13&#xff0c;9&#xff0c;5&#xff0c;12&#xff0c;8&#xff0c;7&#xff0c;4&#xff0c;0&#xff0c;6&#xf…

【业务功能篇48】后端接口开发的统一规范

业务背景&#xff1a;日常工作中&#xff0c;我们开发接口时&#xff0c;一般都会涉及到参数校验、异常处理、封装结果返回等处理。而我们项目有时为了快速迭代&#xff0c;在这方面上有所疏忽&#xff0c;后续导致代码维护比较难&#xff0c;不同的开发人员的不同习惯&#xf…

HTTP进化史:从HTTP1的简单到HTTP3的强大

文章目录 &#x1f4c8;I. HTTP1⚡A. 基本特点⚡B. 特点⚡C. 优缺点 &#x1f4c8;II. HTTP2⚡A. 基本特点⚡B. 特点⚡C. 优缺点 &#x1f4c8;III. HTTP3⚡A. 基本特点⚡B. 特点⚡C. 优缺点 &#x1f4c8;IV. 总结&#x1f4c8;附录&#xff1a;「简历必备」前后端实战项目&am…

[RK3568] AMP架构

Rockchip 平台异构多系统 AMP&#xff08;非对称多核架构&#xff09;的开发软件包&#xff0c;支持 Linux(Kernel-4.19)、 Baremetal(HAL)、RTOS(RT-Thread) 组合AMP构建形式。 Baremetal(HAL) Baremetal表示裸机操作系统&#xff0c;HAL是裸机操作系统的一种。 裸机嵌入式系…

MySQL不适合创建索引的7种情况

1. 在where中使用不到的字段&#xff0c;不要设置索引 WHERE条件&#xff08;包括order by &#xff0c;group by&#xff09; 2. 数据量小的表最好不要使用索引 表记录太少&#xff0c;比如少于1000个&#xff0c;创建索引会先查索引&#xff0c;再回表&#xff0c;查询花费…

Git 常用命令

Git操作 克隆远程仓库到本地 # Git初始化&#xff08;仅一次使用的适合需要设置&#xff09; git config --global user.name "用户名" git config --global user.email "邮箱账号"# 朴实无华的拉取 git clone <url>分支 # 查看分支 git branch # …

Puppeteer 使用教程-实战篇(爬取图片、视频、音频,页面数据)

目录 前言 一、 获取实体店铺信息 二、 获取全国各省市县地图json数据 三、 cookies 四、 获取网络图片、视频资源 五、 自动化测试 总结 前言 续上篇&#xff0c;我们简单讲述一下puppeteer常见的应用场景&#xff0c;包括静态页面数据获取&#xff0c;网络请求获取截取…

第 5 章 Spark Shuffle 解析

第 5 章 Spark Shuffle 解析 5.1 Shuffle 的核心要点1. 数据分区&#xff1a;2.数据传输&#xff1a;3. 数据排序&#xff1a;4.数据聚合&#xff1a;5. 数据重分发&#xff1a;6.数据持久化&#xff1a;5.1.1 ShuffleMapStage 与 ResultStage 5.2 HashShuffle 解析5.2.1 未优化…

Appium python 框架

目录 前言 流程 结构 具体说说 run.py 思路 其他模块 前言 Appium是一个开源的移动应用自动化测试框架&#xff0c;它允许开发人员使用多种编程语言&#xff08;包括Python&#xff09;来编写自动化测试脚本。Appium框架提供了一套API和工具&#xff0c;可以与移动设备进…

基于单片机语音识别智能家居系统的设计与实现

功能介绍 以STM32单片机作为主控系统&#xff1b;液晶显示当前环境温湿度&#xff0c;用电器开关状态通过语音模块识别设定的语音&#xff1b;DHT11进行环境温湿度采集&#xff1b;通过语音播报模块报当前温湿度&#xff0c;智能回复通过语音识别可以打开灯&#xff0c;窗帘&am…

C语言-排序,初识指针

目录 【1】冒泡排序&#xff08;从小到大&#xff09; 【2】选择排序 【3】二维数组 【4】指针 【5】指针修饰 【6】大小端 【7】初见二级指针 练习&#xff1a; 【1】冒泡排序&#xff08;从小到大&#xff09; #include <stdio.h> //数组哪里的\0?自己和字符串…

Flink 在新能源场站运维的应用

摘要&#xff1a;本文整理自中南电力设计院工程师、注册测绘师姚远&#xff0c;在 Flink Forward Asia 2022 行业案例专场的分享。本篇内容主要分为四个部分&#xff1a; 建设背景 技术架构 应用落地 后续及其他 点击查看原文视频 & 演讲PPT 一、建设背景 建设背景主要…

Yalmip入门教程(3)-约束条件的定义

博客中所有内容均来源于自己学习过程中积累的经验以及对yalmip官方文档的翻译&#xff1a;https://yalmip.github.io/tutorials/ 之前的博客简单介绍了约束条件的定义方法&#xff0c;接下来将对其进行详细介绍。 首先简单复习一下&#xff1a; 1.定义约束条件可以使用矩阵拼接…

GRE和MGRE

目录 GRE GRE环境的搭建 MGRE MGRE的配置 MGRE环境下的RIP网络 MGRE实验 VPN 说到GRE&#xff0c;我们先来说个大家熟悉一点的&#xff0c;那就是VPN技术。 背景需求 企业、组织、商家等对专用网有强大的需求。 高性能、高速度和高安全性是专用网明显的优势。 物理专…

Notepad++ 配置python虚拟环境(Anaconda)

Notepad配置python运行环境步骤&#xff1a; 打开Notepad ->”运行”菜单->”运行”按钮在弹出的窗口内输入以下命令&#xff1a; 我的conda中存在虚拟环境 (1) base (2) pytorch_gpu 添加base环境至Notepad中 cmd /k chdir /d $(CURRENT_DIRECTORY) & call cond…

TX Barcode .NET for WPF Crack

TX Barcode .NET for WPF Crack 用于WPF软件的TX Barcode.NET包括一天完成的功能以及用于WPF的软件的2D条形码控制。 用于WPF的TX Barcode.NET的功能和属性&#xff1a; 它具有以下特性和属性&#xff0c;如&#xff1a; 常见的文字处理功能&#xff1a;它可以为用户和开发人员…

FastEdit ⚡:在10秒内编辑大型语言模型

概述&#xff1a; 这个仓库旨在通过一个单一的命令&#xff0c;有效地将新鲜且定制化的知识注入到大型语言模型中&#xff0c;以辅助开发人员的工作。 支持的模型&#xff1a;○ GPT-J (6B)○ LLaMA (7B/13B)○ BLOOM (7.1B)○ Falcon (7B)○ Baichuan (7B/13B)○ InternLM (7…

stable diffusion windows本地搭建的坑

刚刚2小时前&#xff0c;我搭好了&#xff0c;欣喜若狂&#xff0c;开放端口&#xff0c;同事也尝试了。我的配置 16G内存&#xff0c;AMD卡&#xff0c;有gpu但是没有用。这里不说具体步骤&#xff0c;只说坑点。 首先就是安装gfpgan、clip、openclip问题&#xff0c;我参考…

Kind | Kubernetes in Docker 把k8s装进docker!

有点像杰克船长的黑珍珠 目录 零、说明 一、安装 安装 Docker 安装 kubectl 安装 kind 二、创建/切换/删除集群 创建 切换 删除 将镜像加载到 kind 群集中 零、说明 官网&#xff1a;kind Kind&#xff1a; Kubernetes in Docker 的简称。kind 是一个使用 Docker 容…