REST API返回结果对象设计

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

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

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

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

  1. import com.fasterxml.jackson.annotation.JsonCreator;
  2. import com.fasterxml.jackson.annotation.JsonProperty;
  3. import com.fasterxml.jackson.annotation.JsonValue;
  5. public final class ApiResponse<T> {
  7.     private ErrorResponse error;
  8.     private T data;
  9.     private Status status;
  11.     private ApiResponse(Status status, ErrorResponse error) {
  12.         this.error = error;
  13.         this.status = status;
  14.     }
  16.     private ApiResponse(Status status, T data) {
  17.         this.data = data;
  18.         this.status = status;
  19.     }
  21.     @JsonCreator
  22.     public static <T> ApiResponse<T> success(
  23.             @JsonProperty("status") Status status,
  24.             @JsonProperty("data") T data) {
  25.         return new ApiResponse<>(status, data);
  26.     }
  28.     @JsonCreator
  29.     public static <T> ApiResponse<T> error(
  30.             @JsonProperty("status") Status status,
  31.             @JsonProperty("error") ErrorResponse error) {
  32.         return new ApiResponse<>(status, error);
  33.     }
  35.     public enum Status {
  36.         SUCCESS("success"), ERROR("error");
  38.         private final String status;
  40.         Status(String status) {
  41.             this.status = status;
  42.         }
  44.         @JsonValue
  45.         public String getStatus() {
  46.             return this.status;
  47.         }
  48.     }
  50.     public ErrorResponse getError() {
  51.         return this.error;
  52.     }
  54.     public T getData() {
  55.         return this.data;
  56.     }
  58.     public Status getStatus() {
  59.         return this.status;
  60.     }
  61. }

上面的类有以下关键点：

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

ErrorResponse类内容如下：

  1. import com.fasterxml.jackson.annotation.JsonCreator;
  2. import com.fasterxml.jackson.annotation.JsonProperty;
  4. public final class ErrorResponse {
  5.     public final String code;
  6.     public final String message;
  8.     @JsonCreator
  9.     public ErrorResponse(
  10.             @JsonProperty("code") String code,
  11.             @JsonProperty("message") String message) {
  12.         this.code = code;
  13.         this.message = message;
  14.     }
  15. }

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

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

  1. {
  2.     "status": "success",
  3.     "data": {
  4.         "task": "Write a post",
  5.         "taskStatus":"in_progress",
  6.         "tags":["writing"]
  7.     }
  8. }

错误的报文如下：

  1. {
  2.     "status": "error",
  3.     "error": {
  4.         "code" "409",
  5.          "message" : "User with username xyz already exists"
  6.     }
  7. }

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

  1. spring.jackson.default-property-inclusion=NON_NULL

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

  1. spring.jackson.default-property-inclusion=NON_ABSENT

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

微信公众号：程序新视界

发表评论

表情：
评论列表 （有 0 条评论，255人围观）

还没有评论，来说两句吧...

相关阅读

    相关 REST API返回结果对象设计

    基于REST API的项目返回的数据结构题都是统一的，这样方便接口对接和使用。因此，对结果对象的设计会有一定的要求： 一个结果对象要能够同时支持成功和失败的数据结构；

    超、凢脫俗超、凢脫俗/ 0 赞/ 256 阅读

    相关 Rest API 设计

    【问题】 在以前的项目经验中，接口请求都是GET或者POST方式；接口定义都是以动词开头，比如，按名称查询某用户信息，都是写成queryByUserName；接口不管对内还是

    淡淡的烟草味﹌淡淡的烟草味﹌/ 0 赞/ 456 阅读

    相关 restful api接口设计

    技术由来： 互联网早期，页面请求和并发量不高，且移动端未盛行时对接口要求不高，使用动态页面(jsp)就能满足绝大多数的使用需求。但是随着互联网和移动设备的发展，人们对We

    た 入场券た 入场券/ 0 赞/ 666 阅读