如何优雅的处理Restful

迈不过友情╰ 2023-02-13 03:30 46阅读 0赞

最近公司搭建的项目，前端反映后端返回格式不统一的问题，因此引发小编的思考，如何能够优雅的处理返回值格式呢？在度娘中仔细研读了一番，决定总结一下，于是乎此文便诞生了。

# 一、背景 #

首先，大家都会思考为什么要做统一格式处理呢？

现阶段的开发模式多以前后端分离形式存在，前后端开发人员需要通过大量 API 来进行数据交互，如果在交互过程中前后端人员经常遭遇如下问题：

*  前端人员不能快速理解接口字段含义及接口字段变化
 *  后端人员想复用某些接口，但是不能快速从接口 URL 的定义中明确该接口的含义，需要进一步读代码确认
 *  URL中的英文单词使用五花八门，搜索某个接口不知道具体的关键字
 *  请求方法动词如 POST GET 随意使用
 *  完成当前业务接口对接，前端人员经常会询问下一步业务流程的接口定义在哪里，对接形式是什么样的

以上只是前后端人员通过接口交互的一小部分问题，这些问题就好比"牙痛"，不致命，但是在整个软件开发的生命周期内，天天"牙痛”是很要命的, 需要解决上述的问题，需要前后端人员都能认识与了解接口设计规范的重要性。因此，如何让前端小伙伴可以处理标准的 response JSON 数据结构都至关重要。

通过上面一个问题把大家带入正题，下面我们统一定义一下格式。

# 二、格式定义 #

## 2.1结果格式定义 ##

每一次 RESTful 请求都应该包含以下几个信息：

<table> 
 <tbody> 
 <tr> 
 <td> 名称 </td> 
 <td> 描述 </td> 
 </tr> 
 <tr> 
 <td> success </td> 
 <td> 标识请求成功与否，false、true </td> 
 </tr> 
 <tr> 
 <td> code </td> 
 <td> 状态码，标识错误类型 </td> 
 </tr> 
 <tr> 
 <td> message </td> 
 <td> 提示信息 </td> 
 </tr> 
 <tr> 
 <td> data </td> 
 <td> 返回数据 </td> 
 </tr> 
 </tbody> 
</table>

## 2.2结果枚举类定义 ##

/**
     * @Author:qxy
     * @Date:2020/4/7 13:07
     */
    public enum ResultCodeEnum {
        /*** 通用部分 100 - 599***/
        // 成功请求
        SUCCESS(200, "successful"),
        // 重定向
        REDIRECT(301, "redirect"),
        // 资源未找到
        NOT_FOUND(404, "not found"),
        // 服务器错误
        SERVER_ERROR(500,"server error"),
    
        BUSINESS_EXCEPTION(4000, "business exception"),
        ;
    
        private Integer code;
    
        private String message;
    
        //省略get/set方法
    }

为了日常开发中规范状态码，这里着重参考一下Http定义的规范：

常见的HTTP状态码如：
    200 - 请求成功；
    301 - 资源（网页等）被永久转移到其它URL；
    404 - 请求的资源（网页等）不存在；
    500 - 内部服务器错误。
    message：错误信息
    在发生错误时，如何友好的进行提示？
    1.根据code 给予对应的错误码定位；
    2.把错误描述记录到message中，便于接口调用者更详细的了解错误。

<table> 
 <tbody> 
 <tr> 
 <td> 状态码类型 </td> 
 <td> code区间 </td> 
 <td> 类型 </td> 
 <td> 含义 </td> 
 </tr> 
 <tr> 
 <td> 1 </td> 
 <td> 100-199 </td> 
 <td> 信息 </td> 
 <td> 服务器接收到请求，需要请求者继续执行操作 </td> 
 </tr> 
 <tr> 
 <td> 2 </td> 
 <td> 200-299 </td> 
 <td> 成功 </td> 
 <td> 请求被成功接收并处理 </td> 
 </tr> 
 <tr> 
 <td> 3 </td> 
 <td> 300-399 </td> 
 <td> 重定向 </td> 
 <td> 需要进一步的操作以完成请求 </td> 
 </tr> 
 <tr> 
 <td> 4 </td> 
 <td> 400-499 </td> 
 <td> 客户端错误 </td> 
 <td> 请求包含语法错误或无法完成请求 </td> 
 </tr> 
 <tr> 
 <td> 5 </td> 
 <td> 500-599 </td> 
 <td> 服务端错误 </td> 
 <td> 服务器在处理的时候发生错误 </td> 
 </tr> 
 </tbody> 
</table>

2.3统一结果类

/**
 * @Author:qxy
 * @Date:2020/4/7 13:11
 */
 public class HttpResult<T> implements Serializable {
 
 private Boolean success;
 
 private Integer code;
 
 private String message;
 
 private T data;
 //省略get/set
 
 /**
 * 无参构造
 */
 public HttpResult() {
 this.success = true;
 this.code = ResultCodeEnum.SUCCESS.getCode();
 this.message = ResultCodeEnum.SUCCESS.getMessage();
 }
 
 /**
 * 有参构造：返回成功
 * @param object
 */
 public HttpResult(T object) {
 this.success = true;
 this.code = ResultCodeEnum.SUCCESS.getCode();
 this.message = ResultCodeEnum.SUCCESS.getMessage();
 this.data = object;
 }
 
 /**
 * 有参构造：返回失败
 * @param resultCode
 */
 public HttpResult(ResultCodeEnum resultCode) {
 this.success = false;
 this.code = resultCode.getCode();
 this.message = resultCode.getMessage();
 }
 
 }

## 2.4定义业务场景返回类 ##

/**
 * @Author:qxy
 * @Date:2020/4/7 13:57
 */
 public class ResultResponse {
 /**
 * 通用返回成功（没有返回结果）
 * @param
 * @return
 */
 public static HttpResult success(){
 return new HttpResult();
 }
 
 /**
 * 返回成功（有返回结果）
 * @param data
 * @return
 */
 public static<T> HttpResult success(T data){
 return new HttpResult<T>(data);
 }
 
 /**
 * 通用返回失败
 * @param resultCode
 * @param <T>
 * @return
 */
 public static<T> HttpResult<T> failure(ResultCodeEnum resultCode){
 return new HttpResult<T>(resultCode);
 }
 
 /**
 * 捕获异常类型设置状态和提示信息
 * @param code
 * @param message
 * @param <T>
 * @return
 */
 public static<T> HttpResult<T> failure(Integer code, String message) {
 ResultCodeEnum resultCodeEnum = ResultCodeEnum.BUSINESS_EXCEPTION;
 resultCodeEnum.setCode(code);
 resultCodeEnum.setMessage(message);
 return failure(resultCodeEnum);
 }
 }

# 三、测试 #

/**
     * @Author:qxy
     * @Date:2020/4/7 9:45
     */
    @RestController
    public class StudentController {
    
        @Autowired
        private StudentService studentService;
    
        @GetMapping("/getStudentList")
        public HttpResult getStudentList(){
            return ResultResponse.success(studentService.getStudentList());
        }
    }

详细代码请移步github下载：[https://github.com/stream-source/stream-source/tree/master/informal-essay/src/main/java/com/qxy/response][https_github.com_stream-source_stream-source_tree_master_informal-essay_src_main_java_com_qxy_response]

参考资料：[风尘博客][Link 1]

[https_github.com_stream-source_stream-source_tree_master_informal-essay_src_main_java_com_qxy_response]: https://github.com/stream-source/stream-source/tree/master/informal-essay/src/main/java/com/qxy/response
[Link 1]: https://www.cnblogs.com/vandusty/p/12557551.html