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.feiniaojingroupId>
<artifactId>graceful-responseartifactId>
<version>3.4.0-boot2version>
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;
@Override
public void setStatus(ResponseStatus statusLine) {
this.code = statusLine.getCode();
this.message = statusLine.getMsg();
}
@Override
@JsonIgnore
public ResponseStatus getStatus() {
return null;
}
@Override
public void setPayload(Object payload) {
this.data = payload;
}
@Override
@JsonIgnore
public 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")
@ExcludeFromGracefulResponse
public 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:
# 是否打印异常日志，默认为false
print-exception-in-global-advice: false
# Response风格，不配置默认为0
response-style: 0
# 自定义的成功响应码，不配置则为0
default-success-code: 0
# 自定义的成功提示，默认为ok
default-success-msg: ok
# 自定义的失败响应码，默认为1
default-error-code: 1
# 自定义的失败提示，默认为error
default-error-msg: error
# 全局的参数校验错误码，默认等于default-error-code
default-validate-error-code:
# 例外包路径(支持数字, *和**通配符匹配)，该包路径下的controller将被忽略处理
exclude-packages:
- com.lizhiadmin.pro.module.*.controller
# 设置是否将原生异常错误信息detailMessage字段填充到Response的msg中
# 默认为false，即不打开
origin-exception-using-detail-message: false