REST API返回结果对象设计

超、凢脫俗 2023-01-20 12:55 163阅读 0赞

基于REST API的项目返回的数据结构题都是统一的，这样方便接口对接和使用。因此，对结果对象的设计会有一定的要求：

*  一个结果对象要能够同时支持成功和失败的数据结构；
 *  要能够处理多种类的返回结果对象；
 *  能够很轻易的判断出结果是成功还是失败；
 *  能够存储错误编码和错误信息；

下面就基于Spring Boot项目来设计一下对应的统一结果返回对象。这里定义对应的类为ApiResponse：

import com.fasterxml.jackson.annotation.JsonCreator;
    import com.fasterxml.jackson.annotation.JsonProperty;
    import com.fasterxml.jackson.annotation.JsonValue;
     
    public final class ApiResponse<T> {
     
        private ErrorResponse error;
        private T data;
        private Status status;
     
        private ApiResponse(Status status, ErrorResponse error) {
            this.error = error;
            this.status = status;
        }
     
        private ApiResponse(Status status, T data) {
            this.data = data;
            this.status = status;
        }
     
        @JsonCreator
        public static <T> ApiResponse<T> success(
                @JsonProperty("status") Status status,
                @JsonProperty("data") T data) {
            return new ApiResponse<>(status, data);
        }
     
        @JsonCreator
        public static <T> ApiResponse<T> error(
                @JsonProperty("status") Status status,
                @JsonProperty("error") ErrorResponse error) {
            return new ApiResponse<>(status, error);
        }
     
        public enum Status {
            SUCCESS("success"), ERROR("error");
     
            private final String status;
     
            Status(String status) {
                this.status = status;
            }
     
            @JsonValue
            public String getStatus() {
                return this.status;
            }
        }
     
        public ErrorResponse getError() {
            return this.error;
        }
     
        public T getData() {
            return this.data;
        }
     
        public Status getStatus() {
            return this.status;
        }
    }

上面的类有以下关键点：

*  Status枚举类用来保存状态，这样可以方便的看出请求是成功还是失败；
 *  data变量使用了泛型，可以存储任何类型的对象；
 *  错误信息可以通过error属性来获得；

ErrorResponse类内容如下：

import com.fasterxml.jackson.annotation.JsonCreator;
    import com.fasterxml.jackson.annotation.JsonProperty;
     
    public final class ErrorResponse {
        public final String code;
        public final String message;
     
        @JsonCreator
        public ErrorResponse(
                @JsonProperty("code") String code,
                @JsonProperty("message") String message) {
            this.code = code;
            this.message = message;
        }
    }

ErrorResponse有code和message两个字段，code可以是http的返回编码也可以是任何业务编码。message变量用描述错误的信息。

基于上述对象，返回的JSON报文格式如下：

{
        "status": "success",
        "data": {
            "task": "Write a post",
            "taskStatus":"in_progress",
            "tags":["writing"]
        }
    }

错误的报文如下：

{
        "status": "error",
        "error": {
            "code" "409",
             "message" : "User with username xyz already exists"
        }
    }

需要注意的是JSON序列化时，需要排除结果为null的值。比如，在发生错误时，可能不希望data为null，如果使用的是Spring Boot框架，可以通过如下方式进行配置：

spring.jackson.default-property-inclusion=NON_NULL

如果使用的是Java 8或Gauva，想要要排除可选类型，则应使用NON\_ABSENT值。

spring.jackson.default-property-inclusion=NON_ABSENT

--------------------

**程序新视界**  
公众号“ **程序新视界**”，一个让你软实力、硬技术同步提升的平台，提供海量资料

![微信公众号：程序新视界][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dvNTQxMDc1NzU0_size_16_color_FFFFFF_t_70_pic_center]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dvNTQxMDc1NzU0_size_16_color_FFFFFF_t_70_pic_center]: /images/20221021/a1ce4057682d4577a017857e83f7184d.png