对于接口的返回结果，需要有统一的结构，因为对于不用考虑流量费用的内部系统，对接口数据长度往往不太介意
开源项目的接口规范案例：
1.阿里云：
阿里云健康码引擎的response结构
ResponseResult
ResponseResult代码 参考：
1
2
| https://github.com/aliyun/alibabacloud-whiteboard-callbackservice-demo/blob/master/src/main/java/com/aliyun/rtc/whiteboard/models/ResponseResult.java
|
返回体结构
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
| /**
* 自动生成的请求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
参考：
1
2
| 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 的具体原因
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
| 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
| 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格式返回
