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

希望大家可以收获：

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个基本规则需要注意：

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

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

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

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

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

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

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

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

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

2. 收缩自定义的errcode,errmessage到对应的枚举中，进行统一的编码和错误信息配置；

3. 网关提供接口和前端页面，展示所有的错误码和错误信息，建议处理方法； 作为一个补充的查找建议操作的方案；（可在网关汇聚所有的微服务中的错误码信息，并展示出来）

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

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

​

2. 后端返回数据格式
   | 字段 | 说明 |
   | --- | --- |
   | errCode | 错误码 |
   | errMessage | 提示消息 |
   | data | 返回结果 |
   | traceId | skywalking的跟踪ID |

3. 前端实现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样例。

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