RESTful & “优雅的”API 响应结构设计

摘要：概述一个规范易懂和优雅，以及结构清晰且易于理解的响应结构，完全可以省去许多无意义的沟通和文档。

一个规范、易懂和优雅，以及结构清晰且易于理解的API响应结构，完全可以省去许多无意义的沟通和文档。

操作成功：

{
    "status": true,
    "timestamp": 1525582485337
}

操作成功：返回数据

{
    "status": true,
    "result": {
        "users": [
            {"id": 1, "name": "name1"},
            {"id": 2, "name": "name2"}
        ]
    },
    "timestamp": 1525582485337
}

操作失败：

{
    "status": false,
    "error": {
        "error_code": 5002,
        "error_reason": "illegal_argument_error",
        "error_description": "The String argument[1] must have length; it must not be null or empty"
    },
    "timestamp": 1525582485337
}

@Data
@Accessors(chain = true)
public class JSONEntity implements Serializable {

    public enum Error {
        UNKNOWN_ERROR(-1, "unknown_error", "未知错误"),
        SERVER_ERROR(5000, "server_error", "服务器内部异常"),
        BUSINESS_ERROR(5001, "business_error", "业务错误"),
        ILLEGAL_ARGUMENT_ERROR(5002, "illegal_argument_error", "参数错误"),
        JSON_SERIALIZATION_ERROR(5003, "json_serialization_error", "JSON序列化失败"),
        UNAUTHORIZED_ACCESS(5004, "unauthorized_access", "未经授权的访问"),
        SIGN_CHECK_ERROR(5005, "sign_check_error", "签名校验失败"),
        FEIGN_CALL_ERROR(5006, "feign_call_error", "远程调用失败");

        private int code;
        private String reason;
        private String description;

        Error(int code, String reason, String description) {
            this.code = code;
            this.reason = reason;
            this.description = description;
        }

        public int getCode() {
            return code;
        }

        public Error setCode(int code) {
            this.code = code;
            return this;
        }

        public String getReason() {
            return reason;
        }

        public Error setReason(String reason) {
            this.reason = reason;
            return this;
        }

        public String getDescription() {
            return description;
        }

        public Error setDescription(String description) {
            this.description = description;
            return this;
        }

        public static String toMarkdownTable() {
            StringBuilder stringBuilder = new StringBuilder("error_code | error_reason | error_description");
            stringBuilder.append("
:-: | :-: | :-:
");
            for (Error error : Error.values()) {
                stringBuilder.append(String.format("%s | %s | %s", error.getCode(), error.getReason(), error.getDescription())).append("
");
            }
            return stringBuilder.toString();
        }

        public static String toJsonArrayString() {
            SerializeConfig config = new SerializeConfig();
            config.configEnumAsJavaBean(Error.class);
            return JSON.toJSONString(Error.values(), config);
        }
    }

    @JSONField(ordinal = 0)
    public boolean isStatus() {
        return null == this.error;
    }

    @JSONField(ordinal = 1)
    private Result result;
    @JSONField(ordinal = 2)
    private Map error;

    @JSONField(ordinal = 3)
    public long getTimestamp() {
        return System.currentTimeMillis();
    }

    public static JSONEntity ok() {
        return JSONEntity.ok(null);
    }

    public static JSONEntity ok(Object result) {
        return new JSONEntity