SpringBoot学习笔记——统一的接口response格式

对于接口的返回结果，需要有统一的结构，因为对于不用考虑流量费用的内部系统，对接口数据长度往往不太介意

开源项目的接口规范案例：

1.阿里云：

阿里云健康码引擎的response结构 ResponseResult

ResponseResult代码 参考：

https://github.com/aliyun/alibabacloud-whiteboard-callbackservice-demo/blob/master/src/main/java/com/aliyun/rtc/whiteboard/models/ResponseResult.java

返回体结构

/**
* 自动生成的请求ID，建议回传互动白板服务，以便日志跟踪
*/
private String requestId;

/**
* 响应状态
*/
private boolean responseSuccess;

/**
* 响应成功结果体
*/
private T result;

/**
* 响应失败错误信息
*/
private String errorCode;
private String errorMsg;

/**
* 成功响应
*/
public static <T> ResponseResult<T> getSuccessResult(String requestId, T v) {
	ResponseResult<T> result = new ResponseResult<>();
	result.setRequestId(requestId);
	result.setResponseSuccess(true);
	result.setResult(v);
	return result;
}

/**
* 错误响应
*/
public static <T> ResponseResult<T> getErrorResult(String requestId, String errorCode, String errorMsg) {
	ResponseResult<T> result = new ResponseResult<>();
	result.setRequestId(requestId);
	result.setResponseSuccess(false);
	result.setErrorCode(errorCode);
	result.setErrorMsg(errorMsg);
	return result;
}

线上阿里云的dataworks的某接口API的response字段：

data是返回的数据，errCode是错误码，errMsg是错误信息，requestId是请求的uuid

2.apache dolphinscheduler

参考：

https://github.com/apache/dolphinscheduler/blob/master/dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/utils/Result.java

3.antd design pro

antd design pro作为一个前端框架，也对后端的接口规范给出了建议，参考：https://v5-pro.ant.design/zh-CN/docs/request

我设计的后端接口规范：

对于接口的response，目前设计了3个字段：code，msg和data

code是状态码，msg是返回消息，data的返回数据

http status是200的时候，code默认是200

http status是4xx的时候，code会是4xxxx，比如http status为403的时候，code会是40301、40302、40303...标识 Forbidden 的具体原因

http status是5xx的时候，code会是5xxxx，比如http status为500的时候，code会是50001、50002、50003...标识 Internal Server Error 的具体原因

import lombok.*;

import java.io.Serializable;
import org.springframework.http.HttpStatus;

@Data
@ToString
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class ControllerResponseT<T> implements Serializable {

    /**
     * 状态码
     */
    private int code;

    /**
     * 消息
     */
    private String msg;

    /**
     * 数据内容，比如列表，实体
     */
    private T data;

    public static <T> ControllerResponseT<T> ofSuccess() {
        return ControllerResponseT.<T>builder()
                .code(HttpStatus.OK.value())
                .msg(HttpStatus.OK.getReasonPhrase())
                .build();
    }

    public static <T> ControllerResponseT<T> ofSuccess(String message) {
        return ControllerResponseT.<T>builder()
                .code(HttpStatus.OK.value())
                .msg(message)
                .build();
    }

    public static <T> ControllerResponseT<T> ofSuccess(String message, T data) {
        return ControllerResponseT.<T>builder()
                .code(HttpStatus.OK.value())
                .msg(message)
                .data(data)
                .build();
    }

    public static <T> ControllerResponseT<T> ofFail(int code, String message, T data) {
        return ControllerResponseT.<T>builder()
                .code(code)
                .msg(message)
                .data(data)
                .build();
    }

}

controller

import com.example.demo.common.ControllerResponseT;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@Slf4j
@RestController
public class HelloController {

    @RequestMapping(path = "/hello", method = RequestMethod.GET)
    public ControllerResponseT hello() {
        return ControllerResponseT.ofSuccess("hello");
    }

    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @RequestMapping(path = "/fail", method = RequestMethod.GET)
    public ControllerResponseT fail() {
        return ControllerResponseT.ofFail(50001, "error", null);
    }

}

返回

参考：Spring Boot 无侵入式 实现API接口统一JSON格式返回