后端项目-自定义接口响应结果设计JsonResult

文章接上文：后端接口增删改查

上文中返回的值是string格式，明显是不合适。
一般情况下，我们返回给前台的都是对象格式，结合添加在类上添加@RestController注解，标记此类中所以的处理请求的方法都是响应正文的（Json格式，原因是@RestController类中添加@ResponseBody注解）。
同样的，我们需要规范返回给前台的数据样式，以便前台规范响应。

一、自定义服务器响应类-如JsonResult

在项目的根包下创建web.JsonResult类（类名自定义），并在类中声明需要响应到客户端的数据属性，也可以理解为声明期望响应的JSON数据中的属性：

/**
 * 响应json
 *
 * @author luoyang
 * @date 2023/12/16
 */
@Data
@Slf4j
@NoArgsConstructor
@AllArgsConstructor
//@JsonInclude(JsonInclude.Include.NON_NULL) //配置在类上，所以属性为空是都不展示该属性
public class JsonResult implements Serializable {
    private Integer code;
    // @JsonInclude用于配置“此属性什么时候会包含在JSON结果中”
    // NON_NULL 表示 不为null的时候
//    @JsonInclude(JsonInclude.Include.NON_NULL)
    private String message;

    public static JsonResult ok() {
        JsonResult jsonResult = new JsonResult();
        jsonResult.setCode(ServiceCode.OK.getValue());
        return jsonResult;
    }

    public static JsonResult fail(ServiceCode serviceCode, String message) {
        JsonResult jsonResult = new JsonResult();
        jsonResult.setCode(serviceCode.getValue());
        jsonResult.setMessage(message);
        log.error("JsonResult fail  serviceCode {}, message{}", serviceCode, message);
        return jsonResult;
    }

    public static JsonResult fail(CustomServiceException e) {
        return fail(e.getServiceCode(), e.getMessage());
    }
}

其中，为了进一步更好的管理状态码，应该将这些状态码定义在专门的类型中，
使用枚举对象，注意：每一个枚举值，其实都是当前枚举类型的对象
例如，在项目的根包下创建web.ServiceCode类，用于管理各个可能使用到的业务状态码：

package com.luoyang.small.web;


/**
 * @author luoyang
 * @date 2023/12/16
 */
public enum ServiceCode {

    // 注意：每一个枚举值，其实都是当前枚举类型的对象
    // 注意：请将以下语法理解为“通过带参数的构造方法创建枚举类型的对象”
    // 注意：由于通过构造方法传入了值，所以，每个枚举类型的对象都带有一个数字值，后续可以getValue()取出
    OK(200),
    ERR_NOT_FOUND(404),
    ERR_CONFLICT(409),
    ERR_CUSTOM(1000);

    // 以下属性，表示每个枚举类型的对象都有一个Integer value属性，此属性的值将通过构造方法传入
    private Integer value;

    // 显式的声明枚举的带Integer参数的构造方法，用于创建枚举类型的对象时，为其Integer value属性赋值
    // 注意：枚举的构造方法的访问权限固定是私有的（Java语法特征）
    //      不写访问权限，并不表示“默认的”，而是“私有的”
    //      写public / protected是错误的
    //      写private是多余的
    ServiceCode(Integer value) {
        this.value = value;
    }

    // 用于通过枚举对象获取Integer value属性的值
    public Integer getValue() {
        return value;
    }
}

二、使用JsonResult自定义响应类

    //在线文档注解
    @ApiOperation("根据相册对象删除相册")//接口名注解
    @ApiImplicitParam(name = "albumName", value = "相册对象", required = true,
            example = "小米9相册", dataType = "String")//参数名注解
    @ApiOperationSupport(order = 1)//接口展示排序
    //直接网络请求删除
    //http://localhost:8080/album/delete?name=TestAlbum001
    @RequestMapping(value = "/delete", method = RequestMethod.GET)
    public JsonResult deleteAlbum(String albumName) {
        log.debug("开始处理【根据相册名删除】的请求，参数：{}", albumName);
        if (albumName == null || albumName.isEmpty()) {
            return JsonResult.fail(ServiceCode.ERR_CUSTOM, "删除相册的名称为空");
        }
        try {
            albumService.deleteAlbum(albumName);
            return JsonResult.ok();
        } catch (Exception e) {
            String message = e.getMessage();
            log.error("deleteAlbum Exception {}", message);
            return JsonResult.fail(ServiceCode.ERR_CUSTOM, message);
        }
    }

三、Json所有属性为空，就不展示对应属性

客户端响应JSON格式的结果，某些情况下，会有一些属性的值为null

{
  "code": 200,
  "message": null
}

以上message属性是没有必要响应的，此属性的值一定是null值,
可以在响应结果对应的属性上配置@JsonInclude注解，例如：

@Data
public class JsonResult implements Serializable {

    private Integer code;
    
    // @JsonInclude用于配置“此属性什么时候会包含在JSON结果中”
    // NON_NULL 表示 不为null的时候
    @JsonInclude(JsonInclude.Include.NON_NULL)
    private String message;  
}

或者，也可以将此注解添加在类上，则类中每个属性都是此配置：

@Data
@JsonInclude(JsonInclude.Include.NON_NULL) // 在类上配置，每个属性都遵循此配置
public class JsonResult implements Serializable {

    private Integer code;
    private String message;
    
}

或者，在application.yml中添加：

# Spring相关配置
spring:
  # jackson框架的相关配置
  jackson:
    # 服务器端响应JSON结果时，JSON结果中默认包含哪些属性
    default-property-inclusion: non_null

创造价值，乐哉分享！
一起入门后端 204146007