SpringBoot实战 - 接口返回体

目录

目前API返回格式主流的应该只有XML、JSON两种吧,这里我们不做对比,我们使用JSON作为接口的返回格式进行演示

数据返回格式

数据的返回格式其实是个比较纠结的问题,在 Restful 风格中很多文章都讲解使用的是 http 状态码控制请求的结果状态,例如:http 状态码为200~300的时候,为正常状态,response 响应体即为所需要返回的数据,404时代表没有查询到数据,响应体即为空,500为系统错误,响应体也为空等等,但是这种方式也是存在很大问题的,http 状态码是有限的,而且每个状态码都已经被赋予特殊的含义,在企业开发中当接口遇到错误的时候,我们可能更希望将结果状态码标记的更为详细,更利于前端开发者使用,毕竟写接口的目的也是方便前端使用,这样也可以降低前后端开发人员沟通成本。

下面给出我们在实际开发中使用的返回值统一格式:

@Data
public class Result implements Serializable {

    private static final long serialVersionUID = -3948389268046368059L;

    private Integer code;

    private String msg;

    private Object data;

    public Result() {}

    public Result(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
    }

    public static Result success() {
        Result result = new Result();
        result.setResultCode(ResultCode.SUCCESS);
        return result;
    }

    public static Result success(Object data) {
        Result result = new Result();
        result.setResultCode(ResultCode.SUCCESS);
        result.setData(data);
        return result;
    }

    public static Result failure(ResultCode resultCode) {
        Result result = new Result();
        result.setResultCode(resultCode);
        return result;
    }

    public static Result failure(ResultCode resultCode, Object data) {
        Result result = new Result();
        result.setResultCode(resultCode);
        result.setData(data);
        return result;
    }

    public void setResultCode(ResultCode code) {
        this.code = code.code();
        this.msg = code.message();
    }
}

说明

上面代码我们注意到其中引入了一个 ResultCode 枚举类,该类也是我们后面紧接着要说的,全局统一返回状态码。

这里说明下字段 data 不是在 code=1 为成功的时候才会有值哦,比如当 code 为参数无效错误时,data 可以放入更详细的错误描述,用于指明具体是哪个参数为什么导致的无效的。

全局状态码

当你发现你的系统中错误码随意定义,没有任何规范的时候,你应该考虑下使用一个枚举全局管理下你的状态码,这对线上环境定位错误问题和后续接口文档的维护都是很有帮助的。

下面我们在给出一个完整版代码示例,用于参考:

/**
 * API 统一返回状态码
 */
public enum ResultCode {

    /* 成功状态码 */
    SUCCESS(1, "成功"),

    /* 参数错误:10001-19999 */
    PARAM_IS_INVALID(10001, "参数无效"),
    PARAM_IS_BLANK(10002, "参数为空"),
    PARAM_TYPE_BIND_ERROR(10003, "参数类型错误"),
    PARAM_NOT_COMPLETE(10004, "参数缺失"),

    /* 用户错误:20001-29999*/
    USER_NOT_LOGGED_IN(20001, "用户未登录"),
    USER_LOGIN_ERROR(20002, "账号不存在或密码错误"),
    USER_ACCOUNT_FORBIDDEN(20003, "账号已被禁用"),
    USER_NOT_EXIST(20004, "用户不存在"),
    USER_HAS_EXISTED(20005, "用户已存在"),

    /* 业务错误:30001-39999 */
    SPECIFIED_QUESTIONED_USER_NOT_EXIST(30001, "某业务出现问题"),

    /* 系统错误:40001-49999 */
    SYSTEM_INNER_ERROR(40001, "系统繁忙,请稍后重试"),

    /* 数据错误:50001-599999 */
    RESULE_DATA_NONE(50001, "数据未找到"),
    DATA_IS_WRONG(50002, "数据有误"),
    DATA_ALREADY_EXISTED(50003, "数据已存在"),

    /* 接口错误:60001-69999 */
    INTERFACE_INNER_INVOKE_ERROR(60001, "内部系统接口调用异常"),
    INTERFACE_OUTTER_INVOKE_ERROR(60002, "外部系统接口调用异常"),
    INTERFACE_FORBID_VISIT(60003, "该接口禁止访问"),
    INTERFACE_ADDRESS_INVALID(60004, "接口地址无效"),
    INTERFACE_REQUEST_TIMEOUT(60005, "接口请求超时"),
    INTERFACE_EXCEED_LOAD(60006, "接口负载过高"),

    /* 权限错误:70001-79999 */
    PERMISSION_NO_ACCESS(70001, "无访问权限");

    private Integer code;

    private String message;

    ResultCode(Integer code, String message) {
        this.code = code;
        this.message = message;
    }

    public Integer code() {
        return this.code;
    }

    public String message() {
        return this.message;
    }

    public static String getMessage(String name) {
        for (ResultCode item : ResultCode.values()) {
            if (item.name().equals(name)) {
                return item.message;
            }
        }
        return name;
    }

    public static Integer getCode(String name) {
        for (ResultCode item : ResultCode.values()) {
            if (item.name().equals(name)) {
                return item.code;
            }
        }
        return null;
    }

    @Override
    public String toString() {
        return this.name();
    }

    //校验重复的code值
    public static void main(String[] args) {
        ResultCode[] ApiResultCodes = ResultCode.values();
        List<Integer> codeList = new ArrayList<Integer>();
        for (ResultCode ApiResultCode : ApiResultCodes) {
            if (codeList.contains(ApiResultCode.code)) {
                System.out.println(ApiResultCode.code);
            } else {
                codeList.add(ApiResultCode.code());
            }
        }
    }
}

说明

上述例子中我们对状态码做了一个大的类型上的划分,在实际开发中你可以在后面写你更加详细的错误状态

Controller 该怎么写呢?

那我们已查询、更新用户为例,看看现在我们写一个完整的 controller 都需要做什么呢?

@RestController
@RequestMapping("/user")
public class UserController {

    private static final Logger LOGGER = LoggerFactory.getLogger(UserController.class);

    private final UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/{userId}")
    Result getUser(@PathVariable("userId") Long userId) {
        User user = userService.getUserById(userId);
        return Result.success(user);
    }

    @PutMapping("/{userId}")
    public Result updateUser(@PathVariable("userId") Long userId, @RequestBody User user) {
        LOGGER.info("Call updateUser start, params:{}", JsonUtil.object2Json(user));//注意此处打印日志有不合理的地方,user里可能带有pwd密码等明文敏感信息,需要做过滤打印。

        Result result = new Result();

        //参数校验
        if (user.getId() == null || user.getName == null) {
            result.setResultCode(ResultCode.PARAM_IS_INVALID);
            LOGGER.info("Call updateUser end, result:{}", JsonUtil.object2Json(result));
            return result;
        }

        try {
            //更新数据
            User dbUser = userService.getUserById(user.getId());
            if (dbUser == null) {
                result.setResultCode(ResultCode.USER_NOT_EXIST);
            } else {
                User updatedUser = userService.updateDbAndCache(user);
                result.setData(updatedUser);
                result.setResultCode(ResultCode.SUCCESS);
            }
        } catch (Exception e) {
            LOGGER.info("Call updateUser occurs exception, caused by: ", e);
            result.setResultCode(ResultCode.SYSTEM_INNER_ERROR);
        }

        LOGGER.info("Call updateUser end, result:{}", JsonUtil.object2Json(result));
        return result;
    }

}

一个极大的问题

我们看下上面的例子,这似乎已经可以满足对用户管理操作的需求,但是对于一个查询用户方法来讲代码量还是可以接受的,但是对于一个简单的更新用户操作,我们却写了一大堆的逻辑,其中包括:

1.请求参数、响应结果日志打印

2.基础参数的校验

3.更新用户业务主逻辑

4.全局异常的捕获

5.对Result结果的封装。

这其中貌似一个步骤也不能省略,但却导致我们写代码效率低下,其实最重要的一步仅仅是③,那么我们改如何改进呢?

1.请求参数、响应结果日志打印 -> 使用在 controller 方法外对做切面统一打印日志(非GET方法都会打印)

2.基础参数的校验 -> 使用 hibernate validate/javax.validation 做操作校验

4.全局异常的捕获 -> 使用 @ControllerAdvice 写全局异常处理类控制异常展现方式

5.对Result结果的封装 -> 实现 ResponseBodyAdvice 接口,对接口响应体统一处理

上面我们只是提供的一个解决问题的思路,但是还没有实际的代码,后面的文章中我们会依次给出解决方案。

解决方案

1.请求参数、响应结果日志打印 -> SpringBoot实战 - AOP统一打印日志

2.基础参数的校验 -> SpringBoot实战 - 拦截器实现统一参数校验

4.全局异常的捕获 -> SpringBoot实战 - 增强器实现全局异常处理器

5对Result结果的封装 -> SpringBoot实战 - 接口响应体统一封装

最后我们期望着写controller方法变为:

@PutMapping("/{userId}")
public User updateUser(@PathVariable("userId") Long userId, @Valid @RequestBody User user) {

    //更新数据
    User dbUser = userService.getUserById(user.getId());
    if (dbUser == null) {
        throw new BusinessException(ResultCode.USER_NOT_EXIST);
    }

    return userService.updateDbAndCache(user);
}

无效数据不返回,必要数据返回

什么叫无效数据不返回,必要数据返回呢?

无效数据清理:对于 json 响应接口,我们需要遵守对所有值为 null 的字段不做返回,对前端不关心的数据不做返回(合理的定义 VO 是很有必要的)。

对于 spring boot 我们可以用下配置,实现字段值为null时不做返回。

spring.jackson.date-format=yyyy-MM-dd HH:mm:ss
spring.jackson.time-zone=Asia/Shanghai
spring.jackson.default-property-inclusion= non_null

必要数据返回:对于添加(POST)、修改(PUT | PATCH)这类方法我们需要立即返回添加或更新后的数据以备前端使用(这是一个约定需要遵守)。

GitHub地址:https://github.com/FlickerMi/notemi-demo

标签: spring spring boot 企业实战

声明:本博客如无特殊说明皆为原创,转载请注明来源:SpringBoot实战 - 接口返回体谢谢!

相关文章

发表评论:

icon_question.pngicon_razz.pngicon_sad.pngicon_evil.pngicon_exclaim.pngicon_smile.pngicon_redface.pngicon_biggrin.pngicon_surprised.pngicon_eek.pngicon_confused.pngicon_cool.pngicon_lol.pngicon_mad.pngicon_twisted.pngicon_rolleyes.pngicon_wink.pngicon_idea.pngicon_arrow.pngicon_neutral.pngicon_cry.pngicon_mrgreen.png