程序员你是如何解决软件系统的易排错性？

2022-04-20 11:46:24

希望大家可以收获：

1，背景分析是否贴合工作的实际场景，能否触及痛点；

2，统一的技术方案，并演示最终的实现效果；

3，前端和后端相对完整的技术实现方案，系统的思考方式；

背景和需求

不同人群对错误处理的期望不同：这里基于业务系统简单列表汇总；

人群	错误提示的期望
业务系统产品经理	错误提示也是产品设计的一部分，标识正常业务的边界，基于错误提示可以快速的进行业务功能的边界条件，关键流程流向提示；
业务系统测试人员	能定提示到是到底是前端还是后端的问题，快速的分类bug，指派给对应的开发人员;进行需求的二次确认，一些参数边界的提示信息必须符合产品规约。
业务系统前端开发人员	联调的时候，后端的错误可以提示哪里出错了，如果是参数错误，让我指引我哪个参数错了，我好调整如果是后端逻辑或者内部错误，方便我提供截图和traceId给到后端开发，让后端去解决；
业务系统运维人员	后端资源耗尽了，最好可以提示我哪块资源不足，如何补充；中间件有问题了，告知我哪个中间件，建议的运维方法；如果实在无法在界面上告诉我，可以快速看到对应的应用日志，丢回给开发去进一步定位问题。
业务系统后端开发人员	开发和集成测试环境，最好在界面上或者控制台能看到堆栈信息，哪行代码出错了；最次也要能从界面或者控制台，或者抓包中找到traceId，方便我从日志中或者调用链跟踪系统中快速的定位问题，方便快速解决问题；
业务系统管理层	可服务性好，站在用户的角度，希望有规范的提示和回到正确流程的提示；站在客户方的二开或者集成工程师角度，希望错误码能统一，并且对提示，方便我快速集成和二开；站在开发周期来说，希望错误提示可以加快前后端联调，测试的工作效率；
架构师	错误处理公共组件化，兼顾开发期的可扩展性，复用性，易用性，以及兼顾运行期的可服务性；
二开用户（业务系统B端-开发人员）	我要错误编码，还要指导提示，最好在本接口中返回给我，或者指引我一个文档，我按照编码去查；能加速我快速的集成或者二开；
用户：业务系统B-C端用户	告诉我哪里出错了，正确的使用方法，让我可以回到正确的流程；最好还能显示级别；提示不能为空，不能有英文，不能有堆栈信息，不能有我看不懂的信息
客户：业务系统B端应用配置人员	同C端用户，主要是告诉我哪里操作错了，让我可以回到正确的流程中；

下面进行抽象和汇总。

一个合适的错误处理方案应该是怎样的？

统一技术方案

位置	处理要点	说明
前端	前端实现axios拦截器异常捕获，封装组件实现，展示逻辑&形式	原则：服务端能响应的、能返回错误的，提示语使用后端返回服务端不能响应的、不能返回错误的，提示语使用前端约定
后端	对rest接口进行统一异常的捕获并转换为错误码，错误消息；对直接组装的统一错误码，错误消息，进行统一的管理，按照微服务进行错误码进行封装；封装为组件形式，错误码按照接口的规约进行限制，应用级别的错误码和错误消息分散在微服务中；	错误分两种形式：1，通过异常输出错误；2，通过组装错误码和错误消息拼装错误返回信息；异常分为3类：1，参数校验或者接口url资源定位不到，需要提示前端调整；2，内部的逻辑错误或者jvm异常，通过RuntimeException抛出；3，依赖的公共组件错误，给出环境问题或者调用问题的提示；

后端

形式：中间件的方式，定义暴露的配置属性，对异常进行统一的处理封装；

这里做一下调整，统一把分散在微服务里面错误码枚举放到团队公共的SDK中；

后端错误的分类：

内部：主要是对前端，大部分错误通过异常的方式抛出，后端做统一的处理；

外部系统：主要对接外部系统，有些是直接拼接错误码和错误消息的方式输出的；

建立在服务可用，即httpStatus=200的基础上，内部异常的分类：

错误描述	说明
输入参数非法	参数缺失，参数不符合规则要求，请求类型不支持
逻辑错误	不具备操作权限，jvm内部的异常，比如NPE等，方法超时，运行时异常（空指针等）
内部环境错误	依赖的中间件不可用或者调用方法报错，比如SQL写错了了

如果网关服务不可用： nginx需要有对应的40X , 友好json数据

如果网关后面的后端服务不可用：后端服务需要返回 40X，50X的友好json数据；

用户	nginx 故障	后端网关	后端服务
前端资源	404友好提示页面	不经过	不经过
前端访问后端资源	url错误，浏览器默认404页面	路由找不到，404转换为json数据	40x转换为json数据 50x自然转换成了json数据

查看老业务系统的代码，现在后端的错误处理方式分两种：

错误处理方式	说明	目前的缺点
统一异常处理	通过在web-api-service工程中通过@RestControllerAdvice 标注一个统一的异常处理类对每一种类别的异常进行处理统计如下表	异常的层级和分类不够清晰有些异常 e.getmessage可能是英语，看不懂；
直接拼装错误码和错误消息	分散在业务代码中，见下面的截图和部分代码截取	无法统一管理错误码和错误信息，并且错误信息中无正确操作指引信息

老业务系统统一异常处理分类

异常分类	父类	错误码	说明
RuntimeException	Exception	SERVER_ERROR(50000L, "服务异常")	运行时异常
MissingServletRequestParameterException	ServletRequestBindingException-》NestedServletException-》ServletException-》Exception	ILLEGAL_PARAMETER_ERR(10005L, "非法的参数")缺少必传参数+paramName	接口参数绑定异常
HttpMessageNotReadableException	HttpMessageConversionException-》NestedRuntimeException-》RuntimeException-》Exception	CLASS_CAST_ERR(10009L, "类型转换异常"),	JSON转换异常，包含更多的消息转换异常
HttpRequestMethodNotSupportedException	ServletException-》Exception	METHOD_NOT_SUPPORT(40007L, "请求方法不正确"),	ajax的http方法写错，或者签名不对，如媒体类型等；
ServiceException
RuntimeException->Exception	引擎层自定义的code,msg,异常数据	在引擎层进行了编码和MSG的规范
BusinessRuleException	RuntimeException->Exception	引擎层自定义的code,msg,异常数据2	在引擎层进行了编码和MSG的规范
PortalException	RuntimeException->Exception	Web Api异常 Portal 抛出的自定义异常 code msg 异常数据自定义	webAPI异常范围太广泛 code msg 的定义不太规范，有随意定义的代码出现
RemotingException	Exception	调用远程服务失败 REMOTING_ERR(10006L, "调用远程服务失败")	webAPI调用引擎的dubbo服务异常
RpcException	RuntimeException->Exception	调用远程服务失败 REMOTING_ERR(10006L, "调用远程服务失败")	dubbo框架异常
UndeclaredThrowableException	RuntimeException->Exception	一般用在在调用代理的方法调用的时候抛出的检查异常__ _分别匹配_LicenseException ServiceException RuntimeException 如果类型匹配不上，code,msg __SERVER_ERROR(50000L, "服务异常"),	未定义异常未定义抛出异常这里做了一个统一处理，理论上是不起作用的，会提前分流到对应的异常类型中去
InvocationTargetException	ReflectiveOperationException-》Exception	用在调用代理的方法或者构造函数的时候抛出的检查型异常____SERVER_ERROR(50000L, "服务异常"),	进入托底异常
LicenseException	ServiceException-》RuntimeException->Exception	校验许可证抛出的异常code msg 异常数据自定义	许可证异常，引擎层的自定义异常
ConstraintViolationException	ValidationException->RuntimeException-》Exception	ILLEGAL_PARAMETER_ERR(10005L, "非法的参数"),	参数校验异常
MethodArgumentNotValidException	MethodArgumentNotValidException->Exception
MaxUploadSizeExceededException	MultipartException-》NestedRuntimeException-》RuntimeException-》Exception	OSS_UPLOAD_SIZE_LIMIT_EXCEEDED(10025L,"文件上传超出大小限制")	oss上传文件超出大小限制异常

直接拼接错误码返回

 if (oauth2Authentication.isAuthenticated()) {
            UserModel user = dubboConfigService.getSystemSecurityFacade().getUserByUsername(oauth2Authentication.getName());
            return ResponseResult.builder().errcode(0L).data(user).errmsg("授权用户信息加载成功").build();
        } else {
            return ResponseResult.builder().errcode(10403L).errmsg("未授权").build();
        }

异常的知识补充：

Exception: 可以预见到的异常情况，应该被捕获或者处理，在java中，分为检查异常（编译期）和不检查异常（运行期）。

Error: 出现了错误系统不能正常运行或者恢复，一般情况不容易发生；

共同点：都继承自Throwable，在java中只有Throwable的子类可以被catch或者throw;

ERROR一般是后端服务挂了，一般无法恢复，提示501 服务不可用或者404 ；

Throwable 异常的基类，一般不直接处理；

重点处理的Exception和RuntimeException

异常分类	说明
CheckedException 检查型异常，	一般直接继承Exception,(RuntimeException除外)，需要显示的try-catch 否则编译报错
RuntimeException 运行时异常	程序运行过程中发生的异常，编译器无法提前发现，一般的业务异常都是运行时异常；

在处理异常的时候，有4个基本规则需要注意：

不要catch 最普遍的Exception ，而应该优先捕获具体的异常，可以留下足够的诊断信息；
不要生吞异常，应该尝试抛出或者写到日志，否则无法判断异常发生的位置；
不要使用e.printStackTrace(),在分布式系统中，无法确定输出到了什么位置，应该输出到日志中；
提早抛出，晚点捕获；提高效率

自定义异常的时候需要注意两点：
1，尽量不要定义检查异常
2，异常需要保留足够的诊断信息，但是也需要脱敏；

新业务系统错误码统一管理

按照微服务统一的规范枚举统一管理错误码，错误信息，并填充建议操作信息，可通过共同接口进行规范；

比如design微服务定义微服务级别的错误码枚举需要实现 ErrorCodeI接口，填充服务名称，错误码，错误提示信息，正确操作指引信息；

public interface ErrorCodeI {
    /**
     * 错误码
     * @return
     */
    String getErrCode();

    /**
     * 错误描述
     * @return
     */
    String getErrDesc();

    /**
     * 获取微服务的名称
     * @return
     */
    default String getServiceName(){
        return null;
    }

    /**
     * 获取恢复错误的正确指导
     * @return
     */
    default String getCorrectGuid(){
        return null;
    }
}

收缩自定义的errcode,errmessage到对应的枚举中，进行统一的编码和错误信息配置；
网关提供接口和前端页面，展示所有的错误码和错误信息，建议处理方法；作为一个补充的查找建议操作的方案；（可在网关汇聚所有的微服务中的错误码信息，并展示出来）

新业务系统异常体系分级分类

1,输入参数异常（提示给到前端）

2,逻辑业务异常，JVM运行时异常（各微服务按照类别自行扩展）

3,内部异常（中间件的连接错误和异常，进行统一封装）

4, 托底的异常捕获（如果不是以上的异常，直接提示服务器内部错误，并提供可以查错的地方；）

分别配置好对应的errcode, errmsg需要考虑到英文的情况，可对已经发现的中间件异常进行定义前置名称，英文异常信息通过翻译接口解决，最差要做托底中文信息替换；

前端

**原则：
服务端能响应的、能返回错误的，提示语使用后端返回
服务端不能响应的、不能返回错误的，提示语使用前端约定
**1. 状态码一览表

Http Status	Code	Error Code	等级	提示语	备注
200	200			B
	201			B
300	300	-	-	-	通常不需要提示
	...	-	-	-	同上
400	400			B
				B
				B
				B
				B
				B
				B
				B
				B
				B
				B
				B
	401			B	权限相关，提示登陆或无权限
	402
	403			F/B
	404			F	NOT FOUND
	...
500	500			F	服务端异常
	501			F
	502			F

后端返回数据格式
| 字段 | 说明 |
| --- | --- |
| errCode | 错误码 |
| errMessage | 提示消息 |
| data | 返回结果 |
| traceId | skywalking的跟踪ID |
前端实现axios拦截器异常捕获，封装组件实现，展示逻辑&形式

组件文档：部署到服务器上再统一放开

岗位角度	需求补充
后端	1，提供一个统一操作异常的工具类，替代throw new Exception(),规范异常的抛出 2，错误码的规则：8位 1-2服务 3-4异常分类 5-8 序号，防止多微服错误码重叠 3，错误提示信息和正确引导分成两个字段返回到前端；
前端	1，提示的风格具体应该是什么样的，可能是UED来定义，但是我们的框架要支持灵活的去扩展实现这种信息提示的展示， 2，再提供一套风格的UI,手动关闭toast提示；3，前端出错了的错误堆栈或者位置信息应该有地方可查；
测试
管理	1，后期可考虑加入客户主动反馈错误功能，通过业务人员间接传递特别影响技术团队的口碑；（福春）
运维实施	1，错误码的提示可以直接链接到统一的错误码说明页面，加快实施人员的效率；2. 如果提示不够，通过traceID能到对应的分布式日志系统查到调用链的信息；

日常开发中如何使用

错误码：如果是系统内部的，即不对外部的第三方系统开发，错误码使用字符串，可读性更好；

如果是对外部的第三方系统的，可使用统一的数字编码，也可使用字符串，根据需要来；

加入你负责一个服务的开发，下面两种场景是你必须要考虑的。

团队公用SDK中定义微服务对应的错误枚举

写法如下：在client包中；

package com.xxx.app.paas.client.exception;

import com.alibaba.cola.dto.ErrorCodeI;
import lombok.AllArgsConstructor;
import lombok.Getter;

/**
 * @author carter
 * create_date  2020/7/7 13:55
 * description     应用级别的错误码统一定义
 */

@AllArgsConstructor
public enum  ConsoleErrorCodeEnum implements ErrorCodeI {

    PARAM_ERR("11010000","参数检查出错","请按照输入提示输入或者选择"),
    BIZ_CREATE_GATEWAY_ERR("11020001","创建网关出错","请检查应用的编码最好只包含字母和数字"),
    BIZ_CREATE_CONFIG_ERR("11020002","创建配置文件出错","请联系运维人员检查应用的配置文件模板在nacos中是否存在"),
    SYS_DATABASE_LINK_ERR("11030001","数据库出错","请联系运维人员检查数据库的连接信息"),
    SYS_NPE_ERR("11030002","空指针错误","请联系开发人员解决问题"),

    //已知异常转换
    DIVISOR_CAN_NOT_BE_ZERO("DIVISOR_CAN_NOT_BE_ZERO","除数不能为0","请联系开发人员检查你的除数是不是0"),

    //安装部署
    INSTALL_ERR_START_PATH("11019000","启动失败，无法获取正确的pid","请输入正确的包文件路径或启动命令有误"),
    INSTALL_ERR_START_FILE("11019001","文件不存在","请确保包文件存在"),
    INSTALL_ERR_SAVE_NS("11019002","相同的命名空间不能安装第二套云枢","请正确选择注册中心的namespace"),
    ;

    private String errorCode;

    private String errorDesc;

    @Getter
    private String correctGuid;




    @Override
    public String getErrCode() {
        return errorCode;
    }

    @Override
    public String getErrDesc() {
        return errorDesc;
    }

    @Override
    public String getServiceName() {
        return "app-paas";
    }


}

如何抛出业务或者系统异常？

统一通过类Exceptions来抛出异常；

com.alibaba.cola.exception.Exceptions

使用实例如下：

package com.xxx.app.paas.controller;

import com.alibaba.cola.exception.Exceptions;
import com.xxx.app.paas.domain.exception.ConsoleErrorCodeEnum;
import org.springframework.util.Assert;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author carter
 * create_date  2020/7/8 11:19
 * description     错误测试接口
 */
@RestController
public class ErrorCodeControllerI {


    //校验异常
    @GetMapping("/error/check_param")
    public void checkParamException() {
        Assert.isTrue(1 == 2, "xxx参数校验错误");
    }


    //业务异常
    @GetMapping("/error/biz")
    public void bizException() {
        Exceptions.throwBizException(ConsoleErrorCodeEnum.BIZ_CREATE_CONFIG_ERR);
    }

    //系统异常
    @GetMapping("/error/sys")
    public void sysException() {
        String a = null;
        a.getBytes();
    }


    //已经识别的系统异常，可以给特定的错误提示和错误码
    @GetMapping("/error/sys2")
    public void sys2Exception() {
        try {
            int i = 3 / 0;
        } catch (Exception exception) {
            Exceptions.throwSysException(ConsoleErrorCodeEnum.DIVISOR_CAN_NOT_BE_ZERO, exception);
        }
    }

}

前端进行预设样式的提示。

已有的错误处理融合

如果已经有自己的错误处理了，跟统一异常处理进行融合，融合方式具体情况具体分析。提供统一的扩展方式。

可单独找 @李福春(lifuchun) 一起看整改方式。

工程分工和任务跟进

完成标志：在测试环境中提示规范，有价值。

明确指出是哪个服务的什么问题，建议提示一定要准确到位。测试做验证。

小结

作为一名程序员，需要站在更高的角度，用产品思维，系统思维，终局思维，商业运营思维去看待出现的痛点问题。

通过从前到后的约定错误和异常提示，解决各个岗位对软件系统排错性的建设。

下期我直接输出一个统一的java异常处理的后端SDK样例。

原创不易，关注诚可贵，转发价更高！转载请注明出处，让我们互通有无，共同进步，欢迎沟通交流。

码农公寓

程序员你是如何解决软件系统的易排错性？

背景和需求

统一技术方案

后端

老业务系统统一异常处理分类

直接拼接错误码返回

新业务系统错误码统一管理

新业务系统异常体系分级分类

前端

更多的需求点

日常开发中如何使用

团队公用SDK中定义微服务对应的错误枚举

如何抛出业务或者系统异常？

已有的错误处理融合

工程分工和任务跟进

小结

码农公寓

背景和需求

统一技术方案

后端

老业务系统统一异常处理分类

直接拼接错误码返回

新业务系统错误码统一管理

新业务系统异常体系分级分类

前端

更多的需求点

日常开发中如何使用

团队公用SDK中定义微服务对应的错误枚举

如何抛出业务或者系统异常？

已有的错误处理融合

工程分工和任务跟进

小结

相关文章