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

这篇具有很好参考价值的文章主要介绍了需求分析案例:全局错误码设计。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

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

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 {
    @Autowired
    private 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();
    }

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

后续有机会,我再整理一下整个错误码工程源码,并开源出来。文章来源地址https://www.toymoban.com/news/detail-565355.html

到了这里,关于需求分析案例:全局错误码设计的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • 【架构设计】高并发架构实战:从需求分析到系统设计

      很多软件工程师的职业规划是 成为架构师 ,但是要成为架构师很多时候要求 先有架构设计经验 ,而不做架构师又怎么会有架构设计经验呢?那么要 如何获得架构设计经验 呢? 高并发是指系统在同一时间内处理的请求量非常大,通常是指每秒处理的请求量达到数千到数百

    2024年02月15日
    浏览(59)
  • 高并发架构实战:从需求分析到系统设计

    很多软件工程师的职业规划是 成为架构师 ,但是要成为架构师很多时候要求 先有架构设计经验 ,而不做架构师又怎么会有架构设计经验呢?那么要 如何获得架构设计经验 呢? 一方面可以 通过工作来学习 ,观察所在团队的架构师是如何工作的,协助他做一些架构设计和落

    2024年02月15日
    浏览(57)
  • 【高并发】高并发架构实战:从需求分析到系统设计

               Yan-英杰的主页 悟已往之不谏 知来者之可追   C++程序员,2024届电子信息研究生            很多软件工程师的职业规划是 成为架构师 ,但是要成为架构师很多时候要求 先有架构设计经验 ,而不做架构师又怎么会有架构设计经验呢?那么要 如何获得架构

    2024年02月16日
    浏览(57)
  • 【数据库原理】(29)数据库设计-需求分析阶段

    需求分析就是调查、收集、分析、最后定义用户对数据库的各种要求。它是整个数据库设计的基础和出发点,其结果将直接影响后面各步的设计,甚至决定着最终设计的数据库的好坏与成败。为此,首先必须知道需求分析的任务是什么,以及采用什么样的方法进行需求分析。 这阶

    2024年01月17日
    浏览(58)
  • 无人超市系统的设计与实现:从需求分析到实际应用

    ✍✍计算机编程指导师 ⭐⭐个人介绍:自己非常喜欢研究技术问题!专业做Java、Python、微信小程序、安卓、大数据、爬虫、Golang、大屏等实战项目。 ⛽⛽实战项目:有源码或者技术上的问题欢迎在评论区一起讨论交流! ⚡⚡ Java实战 | SpringBoot/SSM Python实战项目 | Django 微信小

    2024年01月17日
    浏览(36)
  • 系统架构设计专业技能 ·结构化需求分析 - 数据流图

    现在的一切都是为将来的梦想编织翅膀,让梦想在现实中展翅高飞。 Now everything is for the future of dream weaving wings, let the dream fly in reality. 点击进入系列文章目录 实体 实体可能是: (1)人物角色: 如客户、管理员、主管、经理、老师、学生 (2)组织机构 :如银行、供应商、募捐机

    2024年02月09日
    浏览(53)
  • 云计算考核 - 分析电子银行需求采用微服务架构对系统进行设计

    (3)贷款相关功能 :申请贷款或信用卡;网上增加透支额度 (4)投资帐户相关微服务 :购买和管理投资账户;查看使用投资研究;网上投资推荐. 2. 微服务的划分 基于微服务的网上银行系统是融合微服务架构思想和软件三层架构设计思想进行构造。首先,在整体架构层面

    2024年04月23日
    浏览(39)
  • 【大虾送书第一期】《高并发架构实战:从需求分析到系统设计》

    目录 ✨写在前面 ✨足够真实的高并发系统设计场景 ✨贴合工作场景的设计文档形式 ✨求同存异的典型系统架构案例      🦐博客主页:大虾好吃吗的博客      🦐专栏地址:免费送书活动专栏地址         很多软件工程师的职业规划是 成为架构师 ,但是要成为架构

    2024年02月13日
    浏览(52)
  • 【码银送书第二期】《高并发架构实战:从需求分析到系统设计》

    很多软件工程师的职业规划是 成为架构师 ,但是要成为架构师很多时候要求 先有架构设计经验 ,而不做架构师又怎么会有架构设计经验呢?那么要 如何获得架构设计经验 呢? 一方面可以 通过工作来学习 ,观察所在团队的架构师是如何工作的,协助他做一些架构设计和落

    2024年02月12日
    浏览(58)
  • 【系统分析设计】基于AR的智能健身系统(2)系统分析说明书(需求规格说明书)

    项目为信管必修课程【系统分析设计】的课程项目,成员为本人与同校另一名同学,项目内容仅供参考,不足之处请包涵(因为交完作业懒得改...)。此部分为项目【需求分析书】,前期已经进行了相关调研,请参考【系统分析设计】基于AR的智能健身系统(1)-CSDN博客。 后

    2024年04月29日
    浏览(44)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包