在我们提供后端 API 给前端时，我们需要告前端，这个 API 调用结果是否成功：

• 如果成功，成功的数据是什么。后续，前端会取数据渲染到页面上。
• 如果失败，失败的原因是什么。一般，前端会将原因弹出提示给用户。

这样，我们就需要有统一的返回结果，而不能是每个接口自己定义自己的风格。一般来说，统一的全局返回信息如下：

• 成功时，返回成功的状态码 + 数据。
• 失败时，返回失败的状态码 + 错误提示。

在标准的 RESTful API 的定义，是推荐使用 HTTP 响应状态码 返回状态码。一般来说，我们实践很少这么去做，主要有如下原因：

• 业务返回的错误状态码很多，HTTP 响应状态码无法很好的映射。例如说，活动还未开始、订单已取消等等。
• 国内开发者对 HTTP 响应状态码不是很了解，可能只知道 200、403、404、500 几种常见的。这样，反倒增加学习成本。

所以，实际项目在实践时，我们会将状态码放在 Response Body 响应内容中返回。

在全局统一返回里，我们至少需要定义三个字段：

• code：状态码。无论是否成功，必须返回。

  • 成功时，状态码为 0 。

  • 失败时，对应业务的错误码。

    关于这一块，也有团队实践时，增加了 success 字段，通过 true 和 false 表示成功还是失败。这个看每个团队的习惯吧。个人还是偏好基于约定，返回 0 时表示成功。

• data：数据。成功时，返回该字段。

• message：错误提示。失败时，返回该字段。

那么，让我们来看两个示例：

// 成功响应
{
 code: 0,
 data: {
 id: 1,
 username: "yudaoyuanma"
 }
}

// 失败响应
{
 code: 233666,
 message: "徐妈太丑了"
}

下面，我们来看一个示例。

2.1 引入依赖

与上篇文章一致。

2.2 Application

与上篇文章一致。

2.3 CommonResult

创建 [CommonResult]类，用于全局统一返回。代码如下：

package com.erbadagang.springboot.springwebflux.globalresponse.core.vo;

import com.fasterxml.jackson.annotation.JsonIgnore;
import org.springframework.util.Assert;

import javax.xml.bind.annotation.XmlRootElement;
import java.io.Serializable;

/**
 * 通用返回结果
 *
 * @param <T> 结果泛型
 */
@XmlRootElement
public class CommonResult<T> implements Serializable {

    public static Integer CODE_SUCCESS = 0;

    /**
     * 错误码
     */
    private Integer code;
    /**
     * 错误提示
     */
    private String message;
    /**
     * 返回数据
     */
    private T data;

    /**
     * 将传入的 result 对象，转换成另外一个泛型结果的对象
     *
     * 因为 A 方法返回的 CommonResult 对象，不满足调用其的 B 方法的返回，所以需要进行转换。
     *
     * @param result 传入的 result 对象
     * @param <T> 返回的泛型
     * @return 新的 CommonResult 对象
     */
    public static <T> CommonResult<T> error(CommonResult<?> result) {
        return error(result.getCode(), result.getMessage());
    }

    public static <T> CommonResult<T> error(Integer code, String message) {
        Assert.isTrue(!CODE_SUCCESS.equals(code), "code 必须是错误的！");
        CommonResult<T> result = new CommonResult<>();
        result.code = code;
        result.message = message;
        return result;
    }

    public static <T> CommonResult<T> success(T data) {
        CommonResult<T> result = new CommonResult<>();
        result.code = CODE_SUCCESS;
        result.data = data;
        result.message = "";
        return result;
    }

    public Integer getCode() {
        return code;
    }

    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }

    @JsonIgnore
    public boolean isSuccess() {
        return CODE_SUCCESS.equals(code);
    }

    @JsonIgnore
    public boolean isError() {
        return !isSuccess();
    }

    @Override
    public String toString() {
        return "CommonResult{" +
                "code=" + code +
                ", message='" + message + '\'' +
                ", data=" + data +
                '}';
    }

}

2.4 GlobalResponseBodyHandler

创建 [GlobalResponseBodyHandler]类，全局统一返回的处理器。代码如下：

package com.erbadagang.springboot.springwebflux.globalresponse.core.web;

import com.erbadagang.springboot.springwebflux.globalresponse.core.vo.CommonResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.core.MethodParameter;
import org.springframework.core.ReactiveAdapterRegistry;
import org.springframework.http.codec.HttpMessageWriter;
import org.springframework.web.reactive.HandlerResult;
import org.springframework.web.reactive.accept.RequestedContentTypeResolver;
import org.springframework.web.reactive.result.method.annotation.ResponseBodyResultHandler;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.List;
import java.util.function.Function;

public class GlobalResponseBodyHandler extends ResponseBodyResultHandler {

    private static Logger LOGGER = LoggerFactory.getLogger(GlobalResponseBodyHandler.class);

    private static MethodParameter METHOD_PARAMETER_MONO_COMMON_RESULT;

    private static final CommonResult COMMON_RESULT_SUCCESS = CommonResult.success(null);

    static {
        try {
            // 获得 METHOD_PARAMETER_MONO_COMMON_RESULT 。其中 -1 表示 `#methodForParams()` 方法的返回值
            METHOD_PARAMETER_MONO_COMMON_RESULT = new MethodParameter(
                    GlobalResponseBodyHandler.class.getDeclaredMethod("methodForParams"), -1);
        } catch (NoSuchMethodException e) {
            LOGGER.error("[static][获取 METHOD_PARAMETER_MONO_COMMON_RESULT 时，找不都方法");
            throw new RuntimeException(e);
        }
    }

    public GlobalResponseBodyHandler(List<HttpMessageWriter<?>> writers, RequestedContentTypeResolver resolver) {
        super(writers, resolver);
    }

    public GlobalResponseBodyHandler(List<HttpMessageWriter<?>> writers, RequestedContentTypeResolver resolver, ReactiveAdapterRegistry registry) {
        super(writers, resolver, registry);
    }

    @Override
    @SuppressWarnings("unchecked")
    public Mono<Void> handleResult(ServerWebExchange exchange, HandlerResult result) {
        Object returnValue = result.getReturnValue();
        Object body;
        // <1.1>  处理返回结果为 Mono 的情况
        if (returnValue instanceof Mono) {
            body = ((Mono<Object>) result.getReturnValue())
                    .map((Function<Object, Object>) GlobalResponseBodyHandler::wrapCommonResult)
                    .defaultIfEmpty(COMMON_RESULT_SUCCESS);
        //  <1.2> 处理返回结果为 Flux 的情况
        } else if (returnValue instanceof Flux) {
            body = ((Flux<Object>) result.getReturnValue())
                    .collectList()
                    .map((Function<Object, Object>) GlobalResponseBodyHandler::wrapCommonResult)
                    .defaultIfEmpty(COMMON_RESULT_SUCCESS);
        //  <1.3> 处理结果为其它类型
        } else {
            body = wrapCommonResult(returnValue);
        }
        return writeBody(body, METHOD_PARAMETER_MONO_COMMON_RESULT, exchange);
    }

    private static Mono<CommonResult> methodForParams() {
        return null;
    }

    private static CommonResult<?> wrapCommonResult(Object body) {
        // 如果已经是 CommonResult 类型，则直接返回
        if (body instanceof CommonResult) {
            return (CommonResult<?>) body;
        }
        // 如果不是，则包装成 CommonResult 类型
        return CommonResult.success(body);
    }

}

• 继承 WebFlux 的 ResponseBodyResultHandler 类，因为该类将 Response 的 body 写回给前端。所以，我们通过重写该类的 #handleResult(ServerWebExchange exchange, HandlerResult result) 方法，将返回结果进行使用 CommonResult 包装。
• <1> 处，获得 METHOD_PARAMETER_MONO_COMMON_RESULT 。其中 -1 表示 #methodForParams() 方法的返回值类型 Mono<CommonResult> 。后续我们在#handleResult(ServerWebExchange exchange, HandlerResult result) 方法中，会使用到 METHOD_PARAMETER_MONO_COMMON_RESULT 。
• 重写 #handleResult(ServerWebExchange exchange, HandlerResult result) 方法，将返回结果进行使用 CommonResult 包装。
  • <1.1> 处，处理返回结果为 Mono 的情况。通过调用 Mono#map(Function<? super T, ? extends R> mapper) 方法，将原返回结果，进行包装成 CommonResult<?> 。
  • <1.2> 处，处理返回结果为 Flux 的情况。先通过调用 Flux#collectList() 方法，将其转换成 Mono<List<T>> 对象，后续就是和 <1.1> 相同的逻辑。
  • <1.3> 处，处理结果为其它类型的情况，直接进行包装成 CommonResult<?> 。
• <2> 处，调用父类方法 #writeBody(Object body, MethodParameter bodyParameter, ServerWebExchange exchange) 方法，实现将结果写回给前端。

在思路上，和 SpringMVC 使用 ResponseBodyAdvice + @ControllerAdvice 注解，是一致的。只是说，WebFlux 暂时没有提供这样的方式，所以咱只好通过继承 ResponseBodyResultHandler 类，重写其 #handleResult(ServerWebExchange exchange, HandlerResult result) 方法，将返回结果进行使用 CommonResult 包装。

2.5 WebFluxConfiguration

创建 [WebFluxConfiguration]配置类。代码如下：

package com.erbadagang.springboot.springwebflux.globalresponse.config;

import com.erbadagang.springboot.springwebflux.globalresponse.core.web.GlobalResponseBodyHandler;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.http.codec.ServerCodecConfigurer;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.reactive.CorsWebFilter;
import org.springframework.web.cors.reactive.UrlBasedCorsConfigurationSource;
import org.springframework.web.reactive.accept.RequestedContentTypeResolver;
import org.springframework.web.reactive.config.WebFluxConfigurer;

import java.util.Collections;

@Configuration
public class WebFluxConfiguration implements WebFluxConfigurer {

    @Bean
    public GlobalResponseBodyHandler responseWrapper(ServerCodecConfigurer serverCodecConfigurer,
                                                     RequestedContentTypeResolver requestedContentTypeResolver) {
        return new GlobalResponseBodyHandler(serverCodecConfigurer.getWriters(), requestedContentTypeResolver);
    }
}

• 在 #responseWrapper(serverCodecConfigurer, requestedContentTypeResolver) 方法中，我们创建了 4.4 GlobalResponseBodyHandler Bean 对象，实现对返回结果的包装。

2.6 UserController

创建 [UserController]类。代码如下：

package com.erbadagang.springboot.springwebflux.globalresponse.controller;

import com.erbadagang.springboot.springwebflux.globalresponse.constants.ServiceExceptionEnum;
import com.erbadagang.springboot.springwebflux.globalresponse.core.exception.ServiceException;
import com.erbadagang.springboot.springwebflux.globalresponse.core.vo.CommonResult;
import com.erbadagang.springboot.springwebflux.globalresponse.vo.UserVO;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.ArrayList;
import java.util.List;

/**
 * 用户 Controller
 */
@RestController
@RequestMapping("/users")
//@CrossOrigin(value = "*")
public class UserController {

    /**
     * 查询用户列表
     *
     * @return 用户列表
     */
    @GetMapping("/list")
    public Flux<UserVO> list() {
        // 查询列表
        List<UserVO> result = new ArrayList<>();
        result.add(new UserVO().setId(1).setUsername("trek"));
        result.add(new UserVO().setId(2).setUsername("specialized"));
        result.add(new UserVO().setId(3).setUsername("look"));
        // 返回列表
        return Flux.fromIterable(result);
    }

    /**
     * 获得指定用户编号的用户
     *
     * @param id 用户编号
     * @return 用户
     */
    @GetMapping("/get")
//    @PostMapping("/get")
    public Mono<UserVO> get(@RequestParam("id") Integer id) {
        // 查询用户
        UserVO user = new UserVO().setId(id).setUsername("username:" + id);
        // 返回
        return Mono.just(user);
    }

    /**
     * 获得指定用户编号的用户
     *
     * @param id 用户编号
     * @return 用户
     */
    @GetMapping("/get2")
    public Mono<CommonResult<UserVO>> get2(@RequestParam("id") Integer id) {
        // 查询用户
        UserVO user = new UserVO().setId(id).setUsername("username:" + id);
        // 返回
        return Mono.just(CommonResult.success(user));
    }

    /**
     * 获得指定用户编号的用户
     *
     * @param id 用户编号
     * @return 用户
     */
    @GetMapping("/get3")
    public UserVO get3(@RequestParam("id") Integer id) {
        // 查询用户
        UserVO user = new UserVO().setId(id).setUsername("username:" + id);
        // 返回
        return user;
    }

    /**
     * 获得指定用户编号的用户
     *
     * @param id 用户编号
     * @return 用户
     */
    @GetMapping("/get4")
    public CommonResult<UserVO> get4(@RequestParam("id") Integer id) {
        // 查询用户
        UserVO user = new UserVO().setId(id).setUsername("username:" + id);
        // 返回
        return CommonResult.success(user);
    }

    /**
     * 测试抛出 NullPointerException 异常
     */
    @GetMapping("/exception-01")
    public UserVO exception01() {
        throw new NullPointerException("没有粗面鱼丸");
    }

    /**
     * 测试抛出 ServiceException 异常
     */
    @GetMapping("/exception-02")
    public UserVO exception02() {
        throw new ServiceException(ServiceExceptionEnum.USER_NOT_FOUND);
    }

//    @PostMapping(value = "/add",
//            // ↓ 增加 "application/xml"、"application/json" ，针对 Content-Type 请求头
//            consumes = {MediaType.APPLICATION_XML_VALUE, MediaType.APPLICATION_JSON_VALUE},
//            // ↓ 增加 "application/xml"、"application/json" ，针对 Accept 请求头
//            produces = {MediaType.APPLICATION_XML_VALUE, MediaType.APPLICATION_JSON_VALUE}
//    )

    @PostMapping(value = "/add",
            // ↓ 增加 "application/xml"、"application/json" ，针对 Content-Type 请求头
            consumes = {MediaType.APPLICATION_XML_VALUE},
            // ↓ 增加 "application/xml"、"application/json" ，针对 Accept 请求头
            produces = {MediaType.APPLICATION_XML_VALUE}
    )
//    @PostMapping(value = "/add")
    public Mono<UserVO> add(@RequestBody Mono<UserVO> user) {
        return user;
    }

}

API 接口虽然比较多，但是我们可以先根据返回结果的类型，分成 Flux 和 Mono 两类。然后，艿艿这里又创建了 Mono 分类的四种情况的接口，就是 /users/get、/users/get2、/users/get3、/users/get4 四个。
在 #get(Integer id) 方法，返回的结果是 UserVO 类型。这样，结果会被 GlobalResponseBodyHandler 拦截，包装成 CommonResult 类型返回。请求结果如下：

{
    "code": 0,
    "message": "",
    "data": {
        "id": 10,
        "username": "username:10"
    }
}

会有"message": ""的返回的原因是，我们使用 SpringMVC 提供的 Jackson 序列化，对于CommonResult此时的message = null的情况下，会序列化它成"message": ""返回。实际情况下，不会影响前端处理。
在# get2(Integer id)方法，返回的结果是Mono<Common<UserVO>>类型。结果虽然也会被GlobalResponseBodyHandler处理，但是不会二次再重复包装成 CommonResult类型返回。

访问http://localhost:8080/users/list，测试结果展示：

返回统一响应消息格式

底线

---

本文源代码使用 Apache License 2.0开源许可协议，这里是本文源码Gitee地址，可通过命令git clone+地址下载代码到本地，也可直接点击链接通过浏览器方式查看源代码。