/graceful-response

Spring Boot接口响应处理解决方案,提供统一返回值封装、全局异常处理、自定义异常错误码、参数校验增强、断言增强等功能

Primary LanguageJavaMIT LicenseMIT

Featured|HelloGitHub

GitHub stars GitHub forks Maven Central

1. 项目介绍

Graceful Response 是 Spring Boot 技术体系下的响应处理解决方案,可以帮助开发者优雅地完成包括统一响应格式数据封装、全局异常处理、错误码填充、异常消息国际化等处理过程,提高开发效率,提高代码质量。欢迎 star!

代码现状

项目及案例代码仓库如下:

Spring Boot 版本 项目 案例
3.x https://github.com/feiniaojin/graceful-response https://github.com/feiniaojin/graceful-response-example
2.x https://github.com/feiniaojin/graceful-response2 https://github.com/feiniaojin/graceful-response2-example

学习资源:

2. 核心功能

  • 统一返回值封装
  • void 返回类型封装
  • 全局异常处理
  • 自定义响应体:适应不同项目的响应格式需求
  • 参数校验错误码:为参数校验的异常指定错误码,支持全局的参数校验错误码
  • 断言增强:执行断言时填充错误码和异常信息到 Response
  • 异常别名:适配外部异常,通过注解或者配置文件的方式,为外部异常指定错误码
  • 例外请求放行:支持根据路径、返回值、注解、配置等多种方式进行放行,无须担心框架冲突
  • 第三方组件适配:目前已完成 Swagger、springdoc、actuator、FastJson 等框架或者组件的适配
  • RESTful 支持:可以指定异常的 HTTP 状态码,并且支持统一指定
  • 错误码枚举:支持定义错误码枚举,避免创建过多的异常类

更多功能,请到文档中心进行了解。

3. 感谢

感谢以下公众号或者自媒体对本项目的推广。

自媒体名称 类型 链接
芋道源码 公众号 https://mp.weixin.qq.com/s/VG6n5IsIDez8iZkY8JK6QQ
Java 面试那些事 公众号 https://mp.weixin.qq.com/s/V9MhNVj3uQRrmnrfy9KkAQ
编程奇点 公众号 https://mp.weixin.qq.com/s/cQWgivkpuXGEijRR1WRt0g
macrozheng 公众号 https://mp.weixin.qq.com/s/XAHBzVRFuMJTEh8Y1Xvv4g
Java 后端技术 公众号 https://mp.weixin.qq.com/s/4ssfZftGUqq0l9nW9lShLA
Java 高性能架构 公众号 https://mp.weixin.qq.com/s/XImjkUExBHEklgrLnrINyw
技术老男孩 公众号 https://mp.weixin.qq.com/s/6gafudNaNTK1FRIdvNMXXw
Java 知音 公众号 https://mp.weixin.qq.com/s/ZNmpTZnL2XqsPN2ayq0_4Q
Java123 公众号 https://mp.weixin.qq.com/s/MF0PaawFILzNBMM78O_Pnw
程序员追风 公众号 https://mp.weixin.qq.com/s/wlY0phnXEiO7E_basxsWJw
Spring源码项目进行时 掘金 https://juejin.cn/post/7367195057559371788
京东云开发者 掘金 https://juejin.cn/post/7405158247592427560

4. 快速入门

4.1 引入 Graceful Response

通过 Maven 依赖进行引入,GAV如下:

<dependency>
    <groupId>com.feiniaojin</groupId>
    <artifactId>graceful-response</artifactId>
    <version>{latest.version}</version>
</dependency>

版本选择:请到**仓库选择最新的版本,boot2 和 boot3 有不用的 GAV。

仓库链接:https://central.sonatype.com/artifact/com.feiniaojin/graceful-response

4.2 开启 Graceful Response

在启动类中引入@EnableGracefulResponse 注解,即可启用 Graceful Response 组件。

@EnableGracefulResponse
@SpringBootApplication
public class ExampleApplication {
    public static void main(String[] args) {
        SpringApplication.run(ExampleApplication.class, args);
    }
}

4.4 代码编写

4.4.1 Controller层

引入 Graceful Response 后,不需要再手工进行查询结果的封装,直接返回实际结果即可,Graceful Response 会自动完成封装的操作。

Controller 层示例如下。

@Controller
public class Controller {
    @RequestMapping("/get")
    @ResponseBody
    public UserInfoView get(Long id) {
        return UserInfoView.builder().id(id).name("name" + id).build();
    }
}

在示例代码中,Controller 层的方法直接返回了 UserInfoView 对象,没有进行封装的操作,但经过 Graceful Response 处理后,还是得到了以下的响应结果。

{
  "code": "0",
  "msg": "ok",
  "data": {
    "id": 1,
    "name": "name1"
  }
}

而对于命令操作(Command,即写操作)尽量不返回数据,因此写操作的方法的返回值应该是 void,Graceful Response 对于对于返回值类型 void 的方法,也会自动进行封装。

public class Controller {
    @RequestMapping("/command")
    @ResponseBody
    public void command() {
        //业务操作
    }
}

成功调用该接口,将得到:

{
  "code": "0",
  "msg": "ok",
  "data": {}
}

不再需要在Controller中手工封装Result/Response进行返回。

4.4.2 Service 层

在引入 Graceful Response 前,有的开发者为了在接口中返回异常码,直接将 Service 层方法定义为 Response,淹没了方法的正常返回值,非常不优雅。

例如以下伪代码:

/**
 * 直接返回Response的Service
 * 不规范
 */
public interface Service {
    Reponse commandMethod(Command command);
}

Graceful Response 通过多种机制,可以异常和错误码关联起来,这样 Service层方法就不需要再维护 Response 的响应码了,直接抛出业务异常即可。

  • 方法一

使用@ExceptionMapper 注解修饰业务异常,提供错误码和错误提示,再由业务方法直接抛出该异常。

业务异常定义:

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

}

Service 接口直接抛异常:

public class QueryServiceImpl implements QueryService {
    @Resource
    private UserInfoMapper mapper;

    public UserInfoView queryOne(Query query) {
        UserInfo userInfo = mapper.findOne(query.getId());
        if (Objects.isNull(userInfo)) {
            //这里直接抛自定义异常
            throw new NotFoundException();
        }
        //……后续业务操作
    }
}

当 Service 层的 queryOne 方法抛出 NotFoundException 时,Graceful Response 会进行异常捕获,并将 NotFoundException 对应的异常码和异常信息封装到统一的响应对象中,最终接口返回以下 JSON。

{
  "code": "1404",
  "msg": "找不到对象",
  "data": {}
}
  • 方法二

方法一有可能导致定义过多的业务异常类,还可以通过使用GracefulResponse工具类进行异常抛出。

@GetMapping("/raiseException0")
public void raiseException0() {
    //直接指定错误码和提示信息
    GracefulResponse.raiseException("520", "测试手工异常0");
}


@GetMapping("/raiseException1")
public void raiseException1() {
    try {

    } catch (Exception e) {
        //包装异常并继续抛出
        GracefulResponse.raiseException("1314", "测试手工异常1", e);
    }
}


@GetMapping("/test0")
public void test0() {
    //抛出异常枚举
    GracefulResponse.raiseException(ExceptionEnum.CUSTOM_EXCEPTION);
}

5. 使用文档

链接如下:

https://doc.feiniaojin.com/graceful-response/home.html

点击访问文档中心

6. 交流和反馈

欢迎通过以下二维码联系作者、并加入 Graceful Response 用户交流群,申请好友时请备注“GR”。

公众号: 悟道领域驱动设计

7. 贡献者