SpringBoot RESTful API返回统一数据格式还不懂?

关于 Spring 的全局处理,有两方面要说:

统一数据返回格式
统一异常处理
为了将两个问题说明清楚,将分两个章节分别说明,本章主要说第一点
有童鞋说,我们项目都做了这种处理,就是在每个 API 都单独工具类将返回值进行封装,但这种不够优雅;我想写最少的代码完成这件事,也许有童鞋说,加几个注解就解决问题了,说的没错,但这篇文章主要是为了说明为什么加了几个注解就解决问题了,目的是希望大家知其所以然。

为了更好的说明问题,本文先说明如何实现,然后再详细剖析实现原理(这很关键)

为什么要做统一数据返回格式

前后端分离是当今服务形式的主流,如何让前端小伙伴可以处理标准的 response JSON 数据结构都至关重要,为了让前端有更好的逻辑展示与页面交互处理,每一次 RESTful 请求都应该包含以下几个信息:

名称

描述

status

状态码,标识请求成功与否,如 [1:成功;-1:失败]

errorCode

错误码,给出明确错误码,更好的应对业务异常;请求成功该值可为空

errorMsg

错误消息,与错误码相对应,更具体的描述异常信息

resultBody

返回结果,通常是 Bean 对象对应的 JSON 数据, 通常为了应对不同返回值类型,将其声明为泛型类型 实现

通用返回值类定义

根据上面的描述,用 Java Bean 来体现这个结构就是这样:

@Data

public final class CommonResult<T> {

private int status = 1;

private String errorCode = "";

private String errorMsg = "";

private T resultBody;

public CommonResult() {

}

public CommonResult(T resultBody) {

SpringBoot RESTful API返回统一数据格式还不懂?
SpringBoot RESTful API返回统一数据格式还不懂?

}

}

配置

没错,我们需要借助几个关键注

@EnableWebMvc

@Configuration

public class UnifiedReturnConfig {

@RestControllerAdvice("com.example.unifiedreturn.api")

static class CommonResultResponseAdvice implements ResponseBodyAdvice<Object>{

@Override

public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {

return true;

}

@Override

public Object beforeBodyWrite(Object body, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {

if (body instanceof CommonResult){

return body;

}

return new CommonResult<Object>(body);

}

}

}

dy);

}

}

}

到这里就结束了,我们就可以纵情的写任何 RESTful API 了,所有的返回值都会有统一的 JSON

@RestController

@RequestMapping("/users")

public class UserController {

@GetMapping("")

public List<UserVo> getUserList(){

List<UserVo> userVoList = Lists.newArrayListWithCapacity(2);

userVoList.add(UserVo.builder().id(1L).name("一米八的一小伙").age(18).build());

userVoList.add(UserVo.builder().id(2L).name("tan").age(19).build());

return userVoList;

}

}

lder().id(2L).name("tan").age(19).build());

return userVoList;

}

}

}

@GetMapping("/{id}")

public UserVo getUserByName(@PathVariable Long id){

return UserVo.builder().id(1L).name("一米八的一小伙").age(18)

getUserByName(@PathVariable Long id){

return UserVo.builder().id(1L).name("一米八的一小伙").age(18).

e("一米八的一小伙").age(18).

@GetMapping("/testResponseEntity")

public ResponseEntity getUserByAge(){

return new ResponseEntity(UserVo.builder().id(1L).name("一米八的一小伙").age(18).build(), H

ty getUserByAge(){

return new ResponseEntity(UserVo.builder().id(1L).name("一米八的一小伙").age(18).build(), HttpStatus.OK);

}

d(), HttpStatus.OK);

}

打开浏览器输入地址测试: http://localhost:8080/users/testR

@Retention(RetentionPolicy.RUNTIME)

@Target(ElementType.TYPE)

@Documented

@Import(DelegatingWebMvcConfiguration.class)

public

icy.RUNTIME)

@Target(ElementType.TYP

ME)

@Target(ElementType.TYPE)

@Doc

TYPE)

@Doc

@Configuration

public class DelegatingWebMvcConfiguration extends WebMvcConfigurationSupport {

...

}

引入了 DelegatingWebMvcConfiguration.class,那来看这个类吧:

@Configurat

@Bean

public RequestMappingHandlerAdapter requestMappingHandlerAdapter() {

RequestMappingHandlerAdapter adapter = createRequestMappingHandlerAdapter();

...

return adapter;

}

lic RequestMappingHandlerAdapte

public class RequestMappingHandlerAdapter extends AbstractHandlerMethodAdapter

implements BeanFactoryAware, InitializingBean {

...

}

RequestMappingHandlerAdapter 是每一次请求处理的关键,来看该类的定义:

public class RequestMappingHandlerAdapter extends AbstractHandle

@Override

public void afterPropertiesSet() {

// Do this first, it may add ResponseBody advice beans

initControllerAdviceCache();

if (this.argumentResolvers == null) {

List<HandlerMethodArgumentResolver> resolvers = getDefaultArgumentResolvers();

this.argumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);

}

if (this.initBinderArgumentResolvers == null) {

List<HandlerMethodArgumentResolver> resolvers = getDefaultInitBinderArgumentResolvers();

this.initBinderArgumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);

}

if (this.returnValueHandlers == null) {

List<HandlerMethodReturnValueHandler> handlers = getDefaultReturnValueHandlers();

this.returnValueHandlers = new HandlerMethodReturnValueHandlerCompos

ull) {

L

andlers(handle

ull) {

L

}

ull) {

L

private void initControllerAdviceCache() {

...

if (logger.isInfoEnabled()) {

logger.info("Looking for @ControllerAdvice: " + getApplicationContext());

}

List<ControllerAdviceBean> beans = ControllerAdviceBean.findAnnotatedBeans(getApplicationContext());

AnnotationAwareOrderComparator.sort(beans);

List<Object> requestResponseBodyAdviceBeans = new ArrayList<Object>();

for (ControllerAdviceBean bean : beans) {

...

if (ResponseBodyAdvice.class.isAssignableFrom(bean.getBeanType())) {

requestRespon

(beans);

List<Object> requestRe

ns);

List<Object> requestResponseBodyAdviceBean

sponseBodyAdviceBean

@Target(ElementType.TYPE)

@Retention(RetentionPolicy.RUNTIME)

@Documented

@ControllerAdvice

@Response

stResponseBodyAdviceBeans.add(bean);

stResponseBodyAdviceBeans.add(bean);

}

}

ceBeans.add(bean);

}

}

}

}

}

通过 ControllerAdviceBean 静态方法扫描

@Target(ElementType.TYPE)

@Retention(RetentionPolicy.RUNTIME)

@Documented

@ControllerAdvice

@ResponseBo

@ControllerAdvice

@ResponseBody

public @interfa

eBody

public @interface RestControllerAd

ce RestControllerAd

if (messageConverter instanceof GenericHttpMessageConverter) {

if (((GenericHttpMessageConverter) messageConverter).canWrite(

declaredType, valueType, selectedMediaType)) {

outputValue = (T) getAdvice().beforeBodyWrite(outputValue, returnType, selectedMediaType,

(Class<? extends HttpMessageConverter<?>>) messageConverter.getClass(),

inputMessage, outputMessage);

...

return;

}

}

nericHttpMessageConve

pro

{

outputValue = (T) getAdvice().bef

{

outputValue = (T) getAdvice().beforeBodyWrite(outputValue, retur

) getAdvice().beforeBodyWrite(outputValue, retur

class RequestResponseBodyAdviceChain implements RequestBodyAdvice, ResponseBodyAdvice<Object> {

@Override

public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType contentType,

Class<? extends HttpMessageConverter<?>> converterType,

ServerHttpRequest request, ServerHttpResponse response) {

return processBody(body, returnType, contentType, converterType, request, response);

}

@SuppressWarnings("unchecked")

private <T> Object processBody(Object body, MethodParameter returnType, MediaType contentType,

Class<? extends HttpMessageConverter<?>> converterType,

ServerHttpRequest request, ServerHttpResponse response) {

for (ResponseBodyAdvice<?> advice : getMatchingAdvice(returnType, ResponseBodyAdvice.class)) {

if (advice.supports(returnType, converterType)) {

body = ((ResponseBodyAdvice<T>) advice).beforeBodyWrite((T) body, returnType,

e,

ServerHttpRequest request, ServerHttpResponse response) {

for (ResponseBodyAdvice<?> advice : getMatchingAdvice(returnType, ResponseBodyAdvice.class)) {

if (advice.supports(returnType, converterType)) {

body = ((ResponseBodyAdvice<T>) advice).beforeBodyWrite((T) body, returnType,

contentType, converterType, reques

body, returnType,

contentType, converterType, request, response);

}

}

re

verterType, request, response);

}

}

return body;

}

}

);

}

}

return body;

}

}

}

@Override

public void handleReturnValue(Object returnValue, MethodParameter returnType,

ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {

HandlerMethodReturnValueHandler handler = selectHandler(returnValue, returnType);

if (handler == null) {

throw new IllegalArgumentException("Unknown return value type: " + returnType.g

Value, MethodParameter returnType,

ModelAndViewContainer mavContaine

meter returnType,

ModelAndViewContainer mavContainer, NativeWebRequest webRequest)

iner, NativeWebRequest webRequest) throws Exception {

t) throws Exception {

HandlerMethodReturnVal

HandlerMethodReturnVal

@Override

public boolean supportsParameter(MethodParameter parameter

;

}

handler.handleReturnValue(returnValue, retur

;

}

handler.handleReturnValue(retu

;

}

handler.handleReturnValue(returnValue, returnType, mavContainer, webRequ

ue(returnValue, returnType, mavContainer, webRequ

@Override

public void handleReturnValue(Object returnValue, MethodParameter returnType,

ModelAndViewContainer mavContainer, NativeWebRequest webRequest) throws Exception {

...

if (responseEntity instanceof ResponseEntity) {

int returnStatus = ((ResponseEntity<?>) responseEntity).getStatusCodeValue();

outputMessage.getServletResponse().setStatus(returnStatus);

if (returnStatus == 200) {

if (SAFE_METHODS.contains(inputMessage.getMethod())

&& isResourceNotModified(inputMessage, outputMessage)) {

// Ensure headers are flushed, no body should be written.

outputMessage.flush();

// Skip call to converters, as they may update the body.

return;

}

}

}

// Try even with null body. ResponseBodyAdvice could get involved.

writeWithMessageConverters(responseEntity.getBody()

od())

&& isResourceNotModified(inputMessage, outputMessage)) {

// Ensure headers are flushed, no body should be written.

outputMessage.flush();

// Skip call to converters, as they may update the body.

return;

}

}

}

// Try even with null body. ResponseBodyAdvice could get involved.

writeWithMessageConverters(responseEntity.getBody(), returnType, inputMessage, outputMessage);

// Ens

ty.getBody(), returnType, inputMessage, outputMessage);

// Ensure headers are flushed even i

);

// Ensure headers are flushed even if no body was written.

outp

ed even if no body was written.

outputMessage.flush();

}

.

outputMessage.flush();

}

该方法提取出 responseEntity.getBody(),并传递个 MessageConverter,然后再继续调用 beforeBodyWrite 方法,这才是真相!!!

这是 RESTful API 正常返回内容的情况

原文地址:https://blog.51cto.com/14783151/2486048

时间: 2024-11-05 22:53:10

SpringBoot RESTful API返回统一数据格式还不懂?的相关文章

SpringBoot RESTful API 架构风格实践

如果你要问 Spring Boot 做什么最厉害,我想答案就在本章标题 RESTful API 简称 REST API . 1 RESTful API 概述 1.1 什么是 RESTful API Rest 是一种规范,符合 Rest 的 Api 就是 Rest Api.简单的说就是可联网设备利用 HTTP 协议通过 GET.POST.DELETE.PUT.PATCH 来操作具有URI标识的服务器资源,返回统一格式的资源信息,包括 JSON.XML.CSV.ProtoBuf.其他格式. 1.2

springboot返回统一数据格式及其原理浅析

大家都知道,前后分离之后,后端响应最好以统一的格式的响应. 譬如: 名称 描述   status 状态码,标识请求成功与否,如 [1:成功:-1:失败]   errorCode 错误码,给出明确错误码,更好的应对业务异常:请求成功该值可为空   errorMsg 错误消息,与错误码相对应,更具体的描述异常信息   resultBody 返回结果,通常是 Bean 对象对应的 JSON 数据, 通常为了应对不同返回值类型,将其声明为泛型类型  话不多说,直接上代码 1. 定义一个统一响应结果类Co

SpringBoot 为API添加统一的异常处理(一)

首先我把异常分为两种,一种是可控制的,或者是由我们发现条件不正确主动抛出的异常,就像前城市编号不存在那个粟子:另一种是不可控制的,或者说是程序存在bug引起的异常,但这种异常也不想变态的就直接给前端抛出个500异常. 实现步骤如下: 第1步,新建一个Exception类 新建一个RESTException类,在主动招聘异常时,就抛出一个RESTException类实例.它包含两个属性,code和message.code是要抛出的异常代码用http状态码来表示,message是想要告诉前端的信息,

基于Django RESTframework设计Restful API

导语 ? 关于RESTful的问题,在最近的面试中遇到很多,之前有过一定的了解,但没有系统性的总结分析.所以现在结合Django RESTframework来加深对RESTful的理解,同时梳理这过程的一些知识点. 什么是RESTful? ?这个问题是最容易想到的,首先要分析这个问题,网上的其他文章都会讲到有关REST(Representational State Transfer),中文翻译:"表述性状态传递",再白话一点就是对资源的表述性状态传递.刚开始,看到这里头都大了,那我们来

RESTful API 最佳实践(转)

原文:http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html 阮一峰老师的文章,他的文章把难懂的东西讲的易懂 RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计. 它的大原则容易把握,但是细节不容易做对.本文总结 RESTful 的设计细节,介绍如何设计出易于理解和使用的 API. 一.URL 设计 1.1 动词 + 宾语 RESTful 的核心思想就是,客户端发出的数据操作指令都是

使用ASP.NET Core 3.x 构建 RESTful API - 3.4 内容协商

现在,当谈论起 RESTful Web API 的时候,人们总会想到 JSON.但是实际上,JSON 和 RESTful API 没有半毛钱关系,只不过 JSON 恰好是RESTful API 结果的表述格式.也就是说 RESTful API 还可以使用其它的表述格式,例如 xml 或私有的格式.这也就意味着,我们需要让 RESTful API 知道我们想要返回的格式.而这就是HTTP请求和响应的核心内容之一: Content Negotiation 内容协商 内容协商是这样一个过程:针对一个响

【从0到1,搭建Spring Boot+RESTful API+Shiro+Mybatis+SQLServer权限系统】03、创建RESTful API,并统一处理返回值

1.POM文件引入fastJson依赖 <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.38</version> </dependency> 2.添加几个关于HTTP和JSON的工具类 package com.ltsolution.framework.util; import j

SpringBoot入门系列(二)如何返回统一的数据格式

前面介绍了Spring Boot的优点,然后介绍了如何快速创建Spring Boot 项目.不清楚的朋友可以看看之前的文章:https://www.cnblogs.com/zhangweizhong/category/1657780.html. 今天来说一说Spring的@Controller和@RestController控制器, 他们是如何响应客户端请求,如何返回json数据. 一.@Controller和@RestController 两种控制器 Spring中有Controller,Re

springboot集成swagger2构建RESTful API文档

在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可以在访问接口上,直接添加注释 先介绍一下开发环境: jdk版本是1.8 springboot的版本是1.4.1 开发工具为 intellij idea 我们先引入swagger2的jar包,pom文件引入依赖如下: <dependency> <groupId>io.springfox&