feiniaojin/graceful-response
Fork: 168 Star: 1111 (更新于 2024-10-21 14:05:14)
license: MIT
Language: Java .
Spring Boot接口响应处理解决方案,提供统一返回值封装、全局异常处理、自定义异常错误码、参数校验增强、断言增强等功能
最后发布版本: 5.0.1 ( 2024-09-06 23:22:09)
1. 项目介绍
Graceful Response 是 Spring Boot 技术体系下的响应处理解决方案,可以帮助开发者优雅地完成包括统一响应格式数据封装、全局异常处理、错误码填充、异常消息国际化等处理过程,提高开发效率,提高代码质量。欢迎 star!
项目及案例代码仓库如下:
学习资源:
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. 贡献者
最近版本更新:(数据更新于 2024-09-23 08:29:43)
2024-09-06 23:22:09 5.0.1
2024-04-27 16:33:46 4.0.1
2024-04-27 09:59:42 4.0.0
2024-02-28 01:27:07 3.5.2
2024-02-20 00:56:14 3.5.0
2023-12-21 01:01:40 3.4.0
2023-12-07 12:08:10 3.3.1
2023-12-06 16:05:57 3.3.0
2023-11-23 19:24:01 3.2.1-boot3
2023-11-15 19:23:17 3.2.0-boot3
主题(topics):
api, globalexceptionhandler, java, restfull, spring-boot
feiniaojin/graceful-response同语言 Java最近更新仓库
2024-11-05 19:32:42 xiaojieonly/Ehviewer_CN_SXJ
2024-11-05 04:13:47 Stirling-Tools/Stirling-PDF
2024-11-04 02:03:13 exzhawk/EhViewer
2024-11-03 00:43:09 PBH-BTN/PeerBanHelper
2024-10-31 18:52:00 CodePhiliaX/Chat2DB
2024-10-31 11:19:43 mybatis-flex/mybatis-flex