SpringBoot全局Controller返回值格式统一处理
一、Controller返回值格式统一
1、WebResult类
在 Controller对外提供服务的时候，我们都需要统一返回值格式。一般定义一个 WebResult类。
统一返回值（WebResult类）格式如下：
{
"success": true,
"code": 200000,
"message": null,
"data": {
"pageList": [
"张三",
"ccc"
],
"paginator": {
"currentPage": 1,
"pageSize": 2,
"total": 3,
"pages": 4
}
}
}
WebResult类信息：
@Data
@ApiModel(value = "Web结果集")
public class WebResult<T> implements Serializable {
private static final long serialVersionUID = -4350499690382193884L;
/**
* 是否成功, 默认false
*/
@ApiModelProperty(value = "是否成功, 默认false")
private Boolean success = false;
/**
* 返回状态码
*/
@ApiModelProperty(value = "返回状态码")
private Integer code;
/**
* 返回信息
*/
@ApiModelProperty(value = "返回信息")
private String message;
/**
* 返回数据
*/
@ApiModelProperty(value = "返回数据")
private T data;
public static <T> WebResult<T> ok() {
WebResult<T> webResult = new WebResult<>();
webResult.setSuccess(true);
webResult.setCode(WebHttpCode.SERVICE_SUCCESS);
webResult.setMessage("操作成功");
return webResult;
}
public static <T> WebResult<T> ok(T data) {
WebResult<T> webResult = new WebResult<>();
webResult.setSuccess(true);
webResult.setCode(WebHttpCode.SERVICE_SUCCESS);
webResult.setMessage("操作成功");
webResult.setData(data);
return webResult;
}
public static <T> WebResult<T> error() {
WebResult<T> webResult = new WebResult<>();
webResult.setSuccess(false);
webResult.setCode(WebHttpCode.SERVICE_ERROR);
webResult.setMessage("操作失败");
return webResult;
}
public WebResult message(String message) {
this.setMessage(message);
return this;
}
public WebResult data(T data) {
this.setData(data);
return this;
}
}
如果我们不做全局 Controller统一处理返回时，就出需要业务在每个 Controller类中返回 WebResult类。同时在全局异常中也返回 WebResult类。
有没有一种跟优雅的方式处理呢？当然有
- 业务不需要对所有 Controller都使用一个返回值（WebResult类），Controller可以需要返回原始值或者自定义的基类，然后处理器统一对返回值（WebResult类）进行封装并输出。
- 同时也可以添加自定义注解，此注解用于忽略返回值封装，按照 Controller原始值返回。
下面我们使用 HandlerMethodReturnValueHandler接口来实现。
2、相关类说明
2.1 HandlerMethodReturnValueHandler接口
使用不同策略处理从调用处理程序方法的返回值，策略处理顶层接口，自定义返回值格式需要实现此接口。
org.springframework.web.method.support.HandlerMethodReturnValueHandler
- supportsReturnType：设置支持返回值类型
- handleReturnValue：处理返回值基础参数
2.2 RequestMappingHandlerAdapter类
请求映射处理适配，包含了参数、返回值处理器等信息
org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter
- HandlerMethodReturnValueHandlerComposite内部维护了HandlerMethodReturnValueHandler列表
3.3 RequestResponseBodyMethodProcessor类
属于HandlerMethodReturnValueHandler子类。
org.springframework.web.servlet.mvc.method.annotation.RequestResponseBodyMethodProcessor
- 主要功能是对请求和响应体的做处理的方法，所有属于RequestResponseBodyMethodProcessor的子类都需要替换为自定义返回值处理
全局Controller返回值统一处理实现原理就是：在bean初始化的时候，获取到所有处理器数组，然后将所有是 RequestResponseBodyMethodProcessor处理器子类对返回值处理的过程替换为自定义返回值处理器处理。
这样当调用对应返回值处理器时，将会使用到自定义的返回值处理器，也就是所有返回值都会按照规定的进行处理。
同时，我们也可以自定义注解（作用于Controller类或者方法级别忽略返回值封装），然后在自定义返回值处理器中忽略返回值封装。
二、全局Controller返回值统一处理实战
1、自定义注解
自定义注解，作用于Controller类或者方法级别忽略返回值封装。
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface IgnoreResponseBodyWrap {
}
2、创建自定义返回值处理器类
创建自定义处理器类实现 HandlerMethodReturnValueHandler接口，主要用于实现自定义返回值内容，不需要注入容器。
下面代码中的 BaseXXXResult是业务的基类。你可以自定义或者使用你们约定的基类。
/**
* Controller 返回值格式统一处理
*/
public class ResponseBodyWrapHandler implements HandlerMethodReturnValueHandler {
private final HandlerMethodReturnValueHandler delegate;
public ResponseBodyWrapHandler(HandlerMethodReturnValueHandler delegate) {
this.delegate = delegate;
}
/**
* 设置支持返回值类型
*
* @param returnType
* @return
*/
@Override
public boolean supportsReturnType(MethodParameter returnType) {
return delegate.supportsReturnType(returnType);
}
/**
* 处理返回值基础参数
*
* @param returnValue 方法的返回值对象
* @param returnType 封装方法参数说明的辅助类（方法的返回值类型）
* @param mavContainer 用于设置模型和视图的容器
* @param webRequest 当前的请求对象
* @throws Exception
*/
@Override
public void handleReturnValue(Object returnValue, MethodParameter returnType, ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {
// 如果类或者方法含有不包装注解则忽略包装
IgnoreResponseBodyWrap ignoreResponseBodyWrap = returnType.getDeclaringClass().getAnnotation(IgnoreResponseBodyWrap.class);
if (ignoreResponseBodyWrap != null) {
delegate.handleReturnValue(returnValue, returnType, mavContainer, webRequest);
return;
}
ignoreResponseBodyWrap = returnType.getMethodAnnotation(IgnoreResponseBodyWrap.class);
if (ignoreResponseBodyWrap != null) {
delegate.handleReturnValue(returnValue, returnType, mavContainer, webRequest);
return;
}
// 返回统一格式
Object obj = null;
if (returnValue instanceof WebResult) {
obj = returnValue;
} else if (returnValue instanceof BasePageResult) {
BasePageResult basePageResult = (BasePageResult) returnValue;
ErrorCode errorCode = basePageResult.getErrorCode();
Map<String, Object> pageData = new HashMap<>();
pageData.put(CommonConstants.PAGE_LIST, basePageResult.getPageList());
pageData.put(CommonConstants.PAGINATOR, basePageResult.getPaginator());
obj = WebResult.ok().data(pageData).message(errorCode == null ? null : errorCode.getMessage());
} else if (returnValue instanceof BaseOperateResult) {
BaseOperateResult baseOperateResult = (BaseOperateResult) returnValue;
ErrorCode errorCode = baseOperateResult.getErrorCode();
boolean success = baseOperateResult.isSuccess();
if (success) {
obj = WebResult.ok().data(baseOperateResult.getId()).message(errorCode == null ? null : errorCode.getMessage());
} else {
obj = WebResult.error().message(errorCode == null ? null : errorCode.getMessage());
}
} else if (returnValue instanceof BaseDataResult) {
BaseDataResult baseDataResult = (BaseDataResult) returnValue;
ErrorCode errorCode = baseDataResult.getErrorCode();
boolean success = baseDataResult.isSuccess();
if (success) {
obj = WebResult.ok().data(baseDataResult.getData()).message(errorCode == null ? null : errorCode.getMessage());
} else {
obj = WebResult.error().message(errorCode == null ? null : errorCode.getMessage());
}
} else if (returnValue instanceof BaseResult) {
BaseResult baseResult = (BaseResult) returnValue;
ErrorCode errorCode = baseResult.getErrorCode();
boolean success = baseResult.isSuccess();
if (success) {
obj = WebResult.ok().message(errorCode == null ? null : errorCode.getMessage());
} else {
obj = WebResult.error().message(errorCode == null ? null : errorCode.getMessage());
}
} else {
obj = returnValue;
}
delegate.handleReturnValue(obj, returnType, mavContainer, webRequest);
}
}
3、注册自定义返回值处理器类
将所有 RequestResponseBodyMethodProcessor返回值处理器替换为自定义的返回值处理器。
@Component
public class ResponseBodyWrapFactoryBean implements InitializingBean {
private final RequestMappingHandlerAdapter adapter;
@Autowired
public ResponseBodyWrapFactoryBean(RequestMappingHandlerAdapter adapter) {
this.adapter = adapter;
}
@Override
public void afterPropertiesSet() throws Exception {
List<HandlerMethodReturnValueHandler> returnValueHandlers = adapter.getReturnValueHandlers();
if (returnValueHandlers.size() > 0) {
// 将内置的返回值处理器进行替换
List<HandlerMethodReturnValueHandler> handlers = new ArrayList<>(returnValueHandlers);
decorateHandlers(handlers);
adapter.setReturnValueHandlers(handlers);
}
}
/**
* 将所有RequestResponseBodyMethodProcessor返回值处理器替换为自定义的返回值处理器
*
* @author [email protected]
* @since 2020/10/12
*/
private void decorateHandlers(List<HandlerMethodReturnValueHandler> handlers) {
for (HandlerMethodReturnValueHandler handler : handlers) {
if (handler instanceof RequestResponseBodyMethodProcessor) {
// 替换为自定义返回值处理器
ResponseBodyWrapHandler decorator = new ResponseBodyWrapHandler(handler);
int index = handlers.indexOf(handler);
handlers.set(index, decorator);
break;
}
}
}
}
4、全局异常处理类
一般项目都会有一个全局异常处理类
@Slf4j
@ResponseBody
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(value = Exception.class)
private WebResult handlerException(Exception e) {
log.error("Exception 异常 -> error:", e);
WebResult webResult = new WebResult();
webResult.setSuccess(false);
webResult.setCode(WebHttpCode.SYSTEM_ERROR);
webResult.setMessage("系统异常，请联系管理员");
return webResult;
}
@ExceptionHandler(value = RuntimeException.class)
private WebResult handlerRuntimeException(RuntimeException e) {
log.error("RuntimeException 异常 -> error:", e);
WebResult webResult = new WebResult();
webResult.setSuccess(false);
webResult.setCode(WebHttpCode.SYSTEM_ERROR);
webResult.setMessage("系统异常");
return webResult;
}
@ExceptionHandler(value = ServiceException.class)
private WebResult handlerServiceException(ServiceException e) {
log.error("ServiceException 异常 -> error:", e);
WebResult webResult = new WebResult();
webResult.setSuccess(false);
webResult.setCode(WebHttpCode.SERVICE_ERROR);
webResult.setMessage(e.getMessage());
return webResult;
}
}
5、Controller示例
@RestController
@RequestMapping("/project2")
@Slf4j
@Api(value = "Project2Controller", tags = {"Project2相关操作接口"})
public class Project2Controller {
@GetMapping("/successPage")
@ApiOperation(value = "successPage接口")
public BaseResult successPage() {
log.info("successPage接口");
List list = new ArrayList();
list.add("张三");
list.add("ccc");
BasePageResult basePageResult = new BasePageResult<>();
basePageResult.setSuccess(Boolean.TRUE);
basePageResult.setPageList(list);
basePageResult.setPaginator(new Paginator(1, 2, 3, 4));
return basePageResult;
}
@GetMapping("/get")
@ApiOperation(value = "get接口")
@IgnoreResponseBodyWrap
public List get() {
log.info("get接口");
ProjectDO projectDO = new ProjectDO();
projectDO.setId(10L);
projectDO.setName("项目10");
projectDO.setDepartmentId(0L);
projectDO.setDescr("");
projectDO.setDelFlag(false);
projectDO.setCreateTime(new Date());
projectDO.setUpdateTime(new Date());
List list = new ArrayList();
list.add("张三");
list.add("ccc");
return list;
}
@GetMapping("/get2")
@ApiOperation(value = "get2接口")
public BaseDataResult get2() {
log.info("get2接口");
ProjectDO projectDO = new ProjectDO();
projectDO.setId(10L);
projectDO.setName("项目10");
projectDO.setDepartmentId(0L);
projectDO.setDescr("");
projectDO.setDelFlag(false);
projectDO.setCreateTime(new Date());
projectDO.setUpdateTime(new Date());
BaseDataResult baseDataResult = new BaseDataResult();
baseDataResult.setSuccess(Boolean.TRUE);
baseDataResult.setData(projectDO);
return baseDataResult;
}
/**
* 文件下载接口
*/
@GetMapping("/download")
@ApiOperation(value = "文件下载接口")
public void download(HttpServletResponse response) throws SerialException {
try {
// 获取要下载的文件
File file = new File("D:\\TempFiles\\xxxxxx.xlsx");
String fileName = file.getName();
response.setContentType("application/octet-stream;charset=UTF-8");
response.setHeader("Content-Disposition", "attachment;filename=" + new String(fileName.getBytes("UTF-8"), "iso-8859-1"));
IOUtils.copy(new FileInputStream(file), response.getOutputStream());
} catch (Exception e) {
log.info("文件下载异常 -> e=", e);
throw new ServiceException("文件下载异常");
}
}
@GetMapping("/systemError")
@ApiOperation(value = "systemError接口")
public BaseResult systemError() {
log.info("systemError接口");
int i = 2 / 0;
BaseResult baseResult = new BaseResult();
baseResult.setSuccess(Boolean.TRUE);
return baseResult;
}
}
– 求知若饥，虚心若愚。