Graceful Response 构建 Spring Boot 下优雅的响应处理

一、Graceful Response

Graceful Response 是一个 Spring Boot 技术栈下的优雅响应处理器，提供一站式统一返回值封装、全局异常处理、自定义异常错误码等功能，使用Graceful Response进行web接口开发不仅可以节省大量的时间，还可以提高代码质量，使代码逻辑更清晰。

github地址：https://github.com/feiniaojin/graceful-response

对应 SpringBoot 版本

Spring Boot版本	Graceful Response版本	graceful-response-example分支
2.x	3.4.0-boot2	3.4.0-boot2
3.x	3.4.0-boot3	3.4.0-boot3

二、快速使用

引入依赖：

<dependency><groupId>com.feiniaojin</groupId><artifactId>graceful-response</artifactId><version>3.4.0-boot2</version>
</dependency>

启动类增加注解：

@EnableGracefulResponse

声明测试接口：

@Slf4j
@RestController
@RequestMapping("/test")
public class TestController {/*** 返回对象形式*/@GetMapping("/t1")public Map<String, String> t1() {//具体逻辑return Collections.singletonMap("status","abc");}/*** Command 形式*/@GetMapping("/t2")public void t2() {// 具体逻辑}
}

测试 /test/t1 接口：

在这里插入图片描述

测试 /test/t2 接口：

在这里插入图片描述

三、返回格式调整

Graceful Response 内置了两种风格的返回，可以通过修改 graceful-response.response-style 进行切换，分别是：

默认格式：

graceful-response:response-style: 0

{"status": {"code": 200,"msg": "success"},"payload": {}
}

第二种模式：

graceful-response:response-style: 1

格式如下：

{"code": "200","msg": "success","data": {}
}

如果需要自定义返回格式则需要实现 Response 接口，并在配置中通过graceful-response.response-class-full-name 进行指定，例如：

@Data
public class CustomResponse implements Response {private String code;private Long timestamp = System.currentTimeMillis();private String message;private Object data = Collections.EMPTY_MAP;@Overridepublic void setStatus(ResponseStatus statusLine) {this.code = statusLine.getCode();this.message = statusLine.getMsg();}@Override@JsonIgnorepublic ResponseStatus getStatus() {return null;}@Overridepublic void setPayload(Object payload) {this.data = payload;}@Override@JsonIgnorepublic Object getPayload() {return null;}
}

然后在配置文件中声明：

graceful-response:response-class-full-name: com.bxc.retrydemo.handler.CustomResponse

再次访问上面的测试接口：

在这里插入图片描述

四、自定义异常和错误码

当抛出异常时我们希望根据不同的异常返回不同的错误码，在 Graceful Response 中为我们提供了 @ExceptionMapper 注解，可以快速的指定返回的错误码和提示。

例如：

@ExceptionMapper(code = "1003", msg = "自定义异常", msgReplaceable = true)
public class MyException extends RuntimeException {public MyException() {super();}public MyException(String message) {super(message);}public MyException(String message, Throwable cause) {super(message, cause);}public MyException(Throwable cause) {super(cause);}public MyException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {super(message, cause, enableSuppression, writableStackTrace);}
}

测试接口修改：

@Slf4j
@RestController
@RequestMapping("/test")
public class TestController {/*** 返回对象形式*/@GetMapping("/t1")public Map<String, String> t1(Integer a) {//具体逻辑// ....// 抛出异常if (a == 0){throw new MyException();}return Collections.singletonMap("status","abc");}/*** Command 形式*/@GetMapping("/t2")public void t2(Integer a) {//具体逻辑// ....// 抛出异常if (a == 0){throw new MyException("t2 接口执行异常");}}
}

测试 /test/t1 接口：
在这里插入图片描述

测试 /test/t2 接口：

在这里插入图片描述

五、参数校验异常错误码

有的时候我们需要校验某个参数是否合法，当在不同情况下需要返回不同的错误码，在 Graceful Response 中对JSR-303数据校验规范和Hibernate Validator进行了增强，Graceful Response自身不提供参数校验的功能，但是用户使用了Hibernate Validator后，Graceful Response可以通过@ValidationStatusCode注解为参数校验结果提供响应码，并将其统一封装返回。

例如：

@Data
public class TestDTO {@NotNull(message = "name 不可为空")@Length(min = 1, max = 5, message = "name 的长度在 1-5 之间")@ValidationStatusCode(code = "1003")private String name;@NotNull(message = "age 不可为空")@Min(value = 0,message = "age 不可小于 0 ")@ValidationStatusCode(code = "1004")private Integer age;
}

声明测试接口：

@Slf4j
@RestController
@RequestMapping("/test")
public class TestController {@PostMapping("/t3")public void t3(@Validated TestDTO dto) {//具体逻辑// ....}
}

测试 /test/t3 接口：

在这里插入图片描述

六、手动抛出指定状态码和信息

Graceful Response 提供了 GracefulResponse 通用工具类，在需要抛出GracefulResponseException时，只需要调用raiseException方法即可。

例如：

@Slf4j
@RestController
@RequestMapping("/test")
public class TestController {/*** 返回对象形式*/@GetMapping("/t1")public Map<String, String> t1(Integer a) {//具体逻辑// ....// 抛出异常if (a == 0) {GracefulResponse.raiseException("1065", "自定义抛出异常");}return Collections.singletonMap("status", "abc");}
}

测试 /test/t1 接口：

在这里插入图片描述

七、例外请求放行

Graceful Response 会对所有的 controller 方法处理，如果希望跳过自定处理返回可以可以添加 @ExcludeFromGracefulResponse注解：

例如：

@Slf4j
@RestController
@RequestMapping("/test")
public class TestController {/*** 返回对象形式*/@GetMapping("/t1")@ExcludeFromGracefulResponsepublic Map<String, String> t1(Integer a) {//具体逻辑// ....return Collections.singletonMap("status", "abc");}
}

在这里插入图片描述
也可以根据包名进行排除，例如：

graceful-response:exclude-packages:- springfox.**

graceful-response:exclude-packages:- org.springframework.boot.actuate.*

八、常用配置

graceful-response:# 自定义Response类的全限定名，默认为空。 # 配置response-class-full-name后，response-style将不再生效response-class-full-name:# 是否打印异常日志，默认为falseprint-exception-in-global-advice: false# Response风格，不配置默认为0response-style: 0# 自定义的成功响应码，不配置则为0default-success-code: 0# 自定义的成功提示，默认为okdefault-success-msg: ok# 自定义的失败响应码，默认为1default-error-code: 1# 自定义的失败提示，默认为errordefault-error-msg: error# 全局的参数校验错误码，默认等于default-error-codedefault-validate-error-code:# 例外包路径(支持数字, *和**通配符匹配)，该包路径下的controller将被忽略处理exclude-packages:- com.lizhiadmin.pro.module.*.controller# 设置是否将原生异常错误信息detailMessage字段填充到Response的msg中# 默认为false，即不打开origin-exception-using-detail-message: false