写点什么

一站式统一返回值封装、异常处理、异常错误码解决方案—最强的 Sping Boot 接口优雅响应处理器 | 京东云技术团队

  • 2023-05-09
    北京
  • 本文字数:5685 字

    阅读完需:约 19 分钟

一站式统一返回值封装、异常处理、异常错误码解决方案—最强的Sping Boot接口优雅响应处理器 | 京东云技术团队

作者:京东物流 覃玉杰

1. 简介

Graceful Response 是一个 Spring Boot 体系下的优雅响应处理器,提供一站式统一返回值封装、异常处理、异常错误码等功能。


使用 Graceful Response 进行 web 接口开发不仅可以节省大量的时间,还可以提高代码质量,使代码逻辑更清晰。


强烈推荐你花 3 分钟学会它!


Graceful Response 的 Github 地址: https://github.com/feiniaojin/graceful-response ,欢迎 star!


Graceful Response 的案例工程代码:https://github.com/feiniaojin/graceful-response-example.git

2. Spring Boot Web API 接口数据返回的现状

我们进行 Spring Boo Web API 接口开发时,通常大部分的 Controller 代码是这样的:


public class Controller {    @GetMapping("/query")    @ResponseBody    public Response query(Parameter params) {
Response res = new Response(); try { //1.校验params参数,非空校验、长度校验 if (illegal(params)) { res.setCode(1); res.setMsg("error"); return res; } //2.调用Service的一系列操作 Data data = service.query(params); //3.执行正确时,将操作结果设置到res对象中 res.setData(data); res.setCode(0); res.setMsg("ok"); return res; } catch (BizException1 e) { //4.异常处理:一堆丑陋的try...catch,如果有错误码的,还需要手工填充错误码 res.setCode(1024); res.setMsg("error"); return res; } catch (BizException2 e) { //4.异常处理:一堆丑陋的try...catch,如果有错误码的,还需要手工填充错误码 res.setCode(2048); res.setMsg("error"); return res; } catch (Exception e) { //4.异常处理:一堆丑陋的try...catch,如果有错误码的,还需要手工填充错误码 res.setCode(1); res.setMsg("error"); return res; } }}
复制代码


这段代码存在什么问题呢?真正的业务逻辑被冗余代码淹没,可读性太差。


真正执行业务的代码只有


Data data=service.query(params);
复制代码


其他代码不管是正常执行还是异常处理,都是为了异常封装、把结果封装为特定的格式,例如以下格式:


{  "code": 0,  "msg": "ok",  "data": {    "id": 1,    "name": "username"  }}
复制代码


这样的逻辑每个接口都需要处理一遍,都是繁琐的重复劳动。


现在,只需要引入 Graceful Response 组件并通过 @EnableGracefulResponse 启用,就可以直接返回业务结果并自动完成 response 的格式封装。


以下是使用 Graceful Response 之后的代码,实现同样的返回值封装、异常处理、异常错误码功能,但可以看到代码变得非常简洁,可读性非常强。


public class Controller {    @GetMapping("/query")    @ResponseBody    public Data query(Parameter params) {       return service.query(params);    }}
复制代码

3. 快速入门

3.1 引入 maven 依赖

graceful-response 已发布至 maven 中央仓库,可以直接引入到项目中,maven 依赖如下:


<dependency>    <groupId>com.feiniaojin</groupId>    <artifactId>graceful-response</artifactId>    <version>2.0</version></dependency>
复制代码

3.2 在启动类中引入 @EnableGracefulResponse 注解

@EnableGracefulResponse@SpringBootApplicationpublic class ExampleApplication {    public static void main(String[] args) {        SpringApplication.run(ExampleApplication.class, args);    }}
复制代码

3.3 Controller 方法直接返回结果

• 普通的查询


@Controllerpublic class Controller {    @RequestMapping("/get")    @ResponseBody    public UserInfoView get(Long id) {        log.info("id={}", id);        return UserInfoView.builder().id(id).name("name" + id).build();    }}
复制代码


UserInfoView 的源码:


@Data@Builderpublic class UserInfoView {    private Long id;    private String name;}
复制代码


这个接口直接返回了 UserInfoView的实例对象,调用接口时,Graceful Response 将自动封装为以下格式:


{  "status": {    "code": "0",    "msg": "ok"  },  "payload": {    "id": 1,    "name": "name1"  }}
复制代码


可以看到UserInfoView被自动封装到 payload 字段中。


Graceful Response 提供了两种风格的 Response,可以通过在 application.properties 文件中配置 gr.responseStyle=1,将以以下的格式进行返回:


{  "code": "0",  "msg": "ok",  "data": {    "id": 1,    "name": "name1"  }}
复制代码


如果这两种风格也不能满足需要,我们还可以根据自己的需要进行自定义返回的 Response 格式。详细见本文 4.3 自定义 Respnse 格式。


• 异常处理的场景


通过 Graceful Response,我们不需要专门在 Controller 中处理异常,详细见 4.1 Graceful Response 异常错误码处理。


• 返回值为空的场景


某些 Command 类型的方法只执行修改操作,不返回数据,这个时候我们可以直接在 Controller 中返回 void,Graceful Response 会自动封装默认的操作成功 Response 报文。


@Controllerpublic class Controller {    @RequestMapping("/void")    @ResponseBody    public void testVoidResponse() {        //省略业务操作    }}
复制代码


testVoidResponse方法的返回时 void,调用这个接口时,将返回:


{  "status": {    "code": "200",    "msg": "success"  },  "payload": {}}
复制代码

3.4 Service 方法业务处理

在引入 Graceful Response 后,Service 层的方法的可读性可以得到极大的提升。


• 接口直接返回业务数据类型,而不是 Response,更具备可读性


public interface ExampleService {    UserInfoView query1(Query query);}
复制代码


• Service 接口实现类中,直接抛自定义的业务异常,Graceful Response 将其转化为返回错误码和错误提示


public class ExampleServiceImpl implements ExampleService {    @Resource    private UserInfoMapper mapper;
public UserInfoView query1(Query query) { UserInfo userInfo = mapper.findOne(query.getId()); if (Objects.isNull(userInfo)) { //这里直接抛自定义异常,异常通过@ExceptionMapper修饰,提供异常码和异常提示 throw new NotFoundException(); } // 省略后续业务操作 }}
复制代码


/** * NotFoundException的定义,使用@ExceptionMapper注解修饰 * code:代表接口的异常码 * msg:代表接口的异常提示 */@ExceptionMapper(code = "1404", msg = "找不到对象")public class NotFoundException extends RuntimeException {
}
复制代码


//Controller不再捕获处理异常@RequestMapping("/get")@ResponseBodypublic UserInfoView get(Query query)) {    return exampleService.query1(query);}
复制代码


当 Service 方法抛出 NotFoundException 异常时,接口将直接返回错误码,不需要手工 set,极大地简化了异常处理逻辑。


{  "status": {    "code": "1404",    "msg": "找不到对象"  },  "payload": {}}
复制代码


验证:启动 example 工程后,请求 http://localhost:9090/example/notfound

4. 进阶用法

4.1 Graceful Response 异常错误码处理

以下是使用 Graceful Response 进行异常、错误码处理的开发步骤。


• 创建自定义异常


通过继承 RuntimeException 类创建自定义的异常,采用 @ExceptionMapper注解修饰,注解的 code属性为返回码,msg属性为错误提示信息。


关于是继承 RuntimeException 还是继承 Exception,读者可以根据实际情况去选择,Graceful Response 对两者都支持。


@ExceptionMapper(code = "1007", msg = "有内鬼,终止交易")public static final class RatException extends RuntimeException {
}
复制代码


• Service 执行具体逻辑


Service 执行业务逻辑的过程中,需要抛异常的时候直接抛出去即可。由于已经通过 @ExceptionMapper 定义了该异常的错误码,我们不需要再单独的维护异常码枚举与异常类的关系。


//Service层伪代码public class Service {    public void illegalTransaction() {        //需要抛异常的时候直接抛        if (check()) {            throw new RatException();        }        doIllegalTransaction();    }}
复制代码


Controller 层调用 Service 层伪代码:


public class Controller {    @RequestMapping("/test3")    public void test3() {        //Controller中不会进行异常处理,也不会手工set错误码,只关心核心操作,其他的统统交给Graceful Response        exampleService.illegalTransaction();    }}
复制代码


在浏览器中请求 controller 的/test3 方法,有异常时将会返回:


{  "status": {    "code": "1007",    "msg": "有内鬼,终止交易"  },  "payload": {  }}
复制代码

4.2 外部异常别名

案例工程( https://github.com/feiniaojin/graceful-response-example.git )启动后, 通过浏览器访问一个不存在的接口,例如 http://localhost:9090/example/get2?id=1


如果没开启 Graceful Response,将会跳转到 404 页面,主要原因是应用内部产生了 NoHandlerFoundException异常。如果开启了 Graceful Response,默认会返回 code=1 的错误码。


这类非自定义的异常,如果需要自定义一个错误码返回,将不得不对每个异常编写 Advice 逻辑,在 Advice 中设置错误码和提示信息,这样做也非常繁琐。


Graceful Response 可以非常轻松地解决给这类外部异常定义错误码和提示信息的问题。


以下为操作步骤:


• 创建异常别名,并用 @ExceptionAliasFor注解修饰


@ExceptionAliasFor(code = "1404", msg = "Not Found", aliasFor = NoHandlerFoundException.class)public class NotFoundException extends RuntimeException {}
复制代码


code:捕获异常时返回的错误码


msg:异常提示信息


aliasFor:表示将成为哪个异常的别名,通过这个属性关联到对应异常。


• 注册异常别名


创建一个继承了 AbstractExceptionAliasRegisterConfig 的配置类,在实现的 registerAlias 方法中进行注册。


@Configurationpublic class GracefulResponseConfig extends AbstractExceptionAliasRegisterConfig {
@Override protected void registerAlias(ExceptionAliasRegister aliasRegister) { aliasRegister.doRegisterExceptionAlias(NotFoundException.class); }}
复制代码


• 浏览器访问不存在的 URL


再次访问 http://localhost:9090/example/get2?id=1 ,服务端将返回以下 json,正是在 ExceptionAliasFor 中定义的内容


{  "code": "1404",  "msg": "not found",  "data": {  }}
复制代码

4.3 自定义 Response 格式

Graceful Response 内置了两种风格的响应格式,可以在 application.properties 文件中通过gr.responseStyle进行配置


• gr.responseStyle=0,或者不配置(默认情况)


将以以下的格式进行返回:


{  "status": {    "code": "1007",    "msg": "有内鬼,终止交易"  },  "payload": {  }}
复制代码


• gr.responseStyle=1


将以以下的格式进行返回:


{  "code": "1404",  "msg": "not found",  "data": {  }}
复制代码


• 自定义响应格式


如果以上两种格式均不能满足业务需要,可以通过自定义去满足,Response


例如以下响应:


public class CustomResponseImpl implements Response {
private String code;
private Long timestamp = System.currentTimeMillis();
private String msg;
private Object data = Collections.EMPTY_MAP;
@Override public void setStatus(ResponseStatus statusLine) { this.code = statusLine.getCode(); this.msg = 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; }
public String getCode() { return code; }
public void setCode(String code) { this.code = code; }
public String getMsg() { return msg; }
public void setMsg(String msg) { this.msg = msg; }
public Object getData() { return data; }
public void setData(Object data) { this.data = data; }
public Long getTimestamp() { return timestamp; }}
复制代码


注意,不需要返回的属性可以返回 null 或者加上 @JsonIgnore 注解


• 配置gr.responseClassFullName


将 CustomResponseImpl 的全限定名配置到 gr.responseClassFullName 属性。


gr.responseClassFullName=com.feiniaojin.gracefuresponse.example.config.CustomResponseImpl
复制代码


注意,配置 gr.responseClassFullName 后,gr.responseStyle 将不再生效。


实际的响应报文如下:


{    "code":"200",    "timestamp":1682489591319,    "msg":"success",    "data":{
}}
复制代码


如果还是不能满足需求,那么可以考虑同时自定义实现 Response 和 ResponseFactory 这两个接口。

5. 常用配置

Graceful Response 在版本迭代中,根据用户反馈提供了一些常用的配置项,列举如下:


• gr.printExceptionInGlobalAdvice 是否打印异常日志,默认为 false


• gr.responseClassFullName 自定义 Response 类的全限定名,默认为空。 配置 gr.responseClassFullName 后,gr.responseStyle 将不再生效


• gr.responseStyleResponse 风格,不配置默认为 0


• gr.defaultSuccessCode 自定义的成功响应码,不配置则为 0


• gr.defaultSuccessMsg 自定义的成功提示,默认为 ok


• gr.defaultFailCode 自定义的失败响应码,默认为 1


• gr.defaultFailMsg 自定义的失败提示,默认为 error

发布于: 刚刚阅读数: 3
用户头像

拥抱技术,与开发者携手创造未来! 2018-11-20 加入

我们将持续为人工智能、大数据、云计算、物联网等相关领域的开发者,提供技术干货、行业技术内容、技术落地实践等文章内容。京东云开发者社区官方网站【https://developer.jdcloud.com/】,欢迎大家来玩

评论

发布
暂无评论
一站式统一返回值封装、异常处理、异常错误码解决方案—最强的Sping Boot接口优雅响应处理器 | 京东云技术团队_Spring Boot_京东科技开发者_InfoQ写作社区