Popular MVC框架API错误码使用示例

简介

此项目用于演示如何使用popularmvc提供的统一错误处理机制灵活应对业务中的异常场景。主要有以下几种场景：

1. 可以区分错误码类型，popularmvc将api的错误码分为两大类，系统错误码和业务错误码。系统错误码用以描述API的常见通用性错误提示，例如：用户调用的接口不存在；业务错误码用以描述业务中的异常场景，比如：用户账号不存在，登录失败！
2. 系统错误码保持有限的个数，只存在数值型的码值，各个子系统中系统错误码均保持一致；
3. 业务错误码可以按数值型码值的区间对不同的子系统进行分段，也支持字符串形式的码值；
4. 业务错误码可以灵活自定义，提前配置字符串形式的码值可以做到自动生成数字型的码值，如果不指定字符串的码值，将使用统一的默认业务数值型码值；
5. 系统错误码和业务错误码均可以灵活自定义码值，用来兼容旧系统的的错误码；

错误码均可以通过使用抛出业务异常的方式进行接口返回，popularmvc将自动对这些异常进行处理，然后统一返回到接口调用者。

• demo源码传送门

项目示例

1 项目结构

• 项目结构

  │  pom.xml
  │  README.md
  │      
  └─src
      ├─main
      │  ├─java
      │  │  └─com
      │  │      └─danyuanblog
      │  │          └─framework
      │  │              └─demo
      │  │                  └─popularmvc
      │  │                      │  StartDemoApplication.java
      │  │                      │  
      │  │                      └─controller
      │  │                              TestThrowBusinessErrorController.java
      │  │                              
      │  └─resources
      │          application.yml
      │          
      └─test
          └─java
              └─com
                  └─danyuanblog
                      └─framework
                          └─popular
                              └─mvc
  

• 引入模块依赖，在pom.xml添加

	<dependency>
		<groupId>com.danyuanblog.framework</groupId>
		<artifactId>popular-web-mvc</artifactId>
		<version>${popular-web-mvc.version}</version>
	</dependency>

2 启用PopularMvc框架

/**  
* Title StartDemoApplication.java  
* Description  
* @author danyuan
* @date Oct 31, 2020
* @version 1.0.0
* site: www.danyuanblog.com
*/ 
package com.danyuanblog.framework.demo.popularmvc;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.danyuanblog.framework.popularmvc.annotation.EnablePopularMvc;

@SpringBootApplication
@EnablePopularMvc
public class StartDemoApplication {

	public static void main(String[] args) {
		SpringApplication.run(StartDemoApplication.class, args);
	}
}

3 配置信息

错误码配置信息如下application.yml

popularmvc:
  error: #错误码相关配置
    #自定义系统错误码值,格式【枚举名 ：数值】
    systemErrorCodes: 
      NOT_FOUND: 404
    #业务异常定义，格式【错误码多语言字典值 ：错误码指代的默认中文翻译描述信息】
    #每个服务的业务错误码值可以设置在某个区间，在一个大型系统中不同区间的错误码能直观的反应出是哪个服务抛出的问题
    #业务错误码默认起始值
    businessCodeStart: 200001
    #业务错误码默认最大值
    businessCodeEnd: 999999
    #业务异常错误码值
    businessErrorCodes: 
      #默认将会自动生成业务错误码值
      USER_ACCOUNT_NOT_FOUND.desc: "用户账号[{0}]未找到!"
      #自定义业务错误码值示例
      USER_PASSWORD_ERROR:
        code: 200006
        desc: "密码错误，请检查！"

4 演示代码解析

4.1 业务异常使用示例

业务异常的使用主要分两种应用场景：

1. 需要特定的业务异常码值标识，客户端需要使用特定的码值做对应的逻辑处理
2. 只需要简单提示错误信息即可，没必要指定特殊错误码值

示例代码如下所示。

• 接口源码TestThrowBusinessErrorController.java

  /**  
  * Title TestThrowBusinessErrorController.java  
  * Description  
  * @author danyuan
  * @date Jan 4, 2021
  * @version 1.0.0
  * site: www.danyuanblog.com
  */ 
  package com.danyuanblog.framework.demo.popularmvc.controller;
  
  import javax.validation.Valid;
  import javax.validation.constraints.NotEmpty;
  
  import io.swagger.annotations.Api;
  import io.swagger.annotations.ApiOperation;
  
  import org.springframework.validation.annotation.Validated;
  import org.springframework.web.bind.annotation.GetMapping;
  import org.springframework.web.bind.annotation.PostMapping;
  import org.springframework.web.bind.annotation.RestController;
  
  import com.danyuanblog.framework.popularmvc.exception.BusinessException;
  
  
  @Api(tags = "测试接口抛出业务异常信息相关接口列表")
  @RestController
  @Validated
  public class TestThrowBusinessErrorController {
  	
  	@PostMapping("login")
  	@ApiOperation(value="测试登录失败", notes="测试提示账户登录信息存在错误,这种方式适用于比较规范的错误码管理，便于调用者对不同的业务错误码做出对应的处理。")
  	public void login(@Valid @NotEmpty String account, @Valid @NotEmpty String password){
  		//TODO: 执行业务逻辑
  		
  		//TODO：当发现账户信息不存在，直接抛出异常即可
  		if(!"admin".equals(account)){
  			throw new BusinessException("USER_ACCOUNT_NOT_FOUND").setParam(account);
  		}
  		
  		//TODO：当发现密码错误时，直接抛出异常
  		if(!"123456".equals(password)){
  			throw new BusinessException("USER_PASSWORD_ERROR");
  		}
  		
  		//TODO：组装响应信息，然后返回
  		
  	}
  	
  	@GetMapping("promptSimpleTips")
  	@ApiOperation(value="测试简单提示类业务异常", notes="这种业务异常不需要特定的业务异常码值，可以直接硬编码在代码里，推荐使用枚举统一规范一下。")
  	public void promptSimpleTips(){
  		throw new BusinessException("系统在本月10-15号进行维护，给您带来的不便，敬请理解，谢谢！");
  	}
  	
  }