Springboot项目中如何设计一个规范的统一的Restful API 响应框架？

旧城等待， 2023-09-27 20:37 74阅读 0赞

#### 设计Restful API 响应框架 ####

*   *   *  一、设计
         *  二、响应枚举
         *  三、统一结果类
         *  四、控制层调用返回

#### 一、设计 ####

> **目前项目开发,都是基于前后端分离模式开发的,基于后端模板引擎那一套,可能已经不适用一些项目开发流程,和当下开发模式了,尤其在要写比较大型项目,前后端项目拆分,团队共同开发那是必不可少的**

目前的前后端开发大部分数据的传输格式都是json，因此定义一个统一规范的数据格式有利于前后端的交互与UI的展示。

> 返回的统一接口形式应该包含这些内容

> 1.  是否响应成功
> 2.  响应状态码
> 3.  状态码描述
> 4.  响应数据
> 5.  接口调用时间
> 6.  其他标识符

按照这些我们可以定义统一的标准结果返回

#### 二、响应枚举 ####

> 前三者可以定义为 success,code,message

package com.tigerhhzz.springbootmybatisplusdemo.domain;
    
    import lombok.Getter;
    
    /**
     * @author tigerhhzz
     * @date 2023/5/10 9:28
     * 响应结果枚举
     */
    @Getter
    public enum ResultCodeEnum {
        
        SUCCESS(true, 200, "成功"),
        FAIL(false, 400, "请求失败"),
    
        NOT_FOUND(false, 404, "接口不存在"),
        FORBIDDEN(false, 403, "资源拒绝访问"),
        UNAUTHORIZED(false, 401, "未认证（签名错误）"),
    
        INTERNAL_SERVER_ERROR(false, 500, "服务器内部错误"),
    
    
        NULL_POINT(false, 200002, "空指针异常"),
        PARAM_ERROR(false, 200001, "参数错误");
    
        /**
         * 响应是否成功
         */
        private Boolean success;
        /**
         * 响应状态码
         */
        private Integer code;
        /**
         * 响应信息
         */
        private String message;
    
    
        ResultCodeEnum(Boolean success, Integer code, String message) {
        
            this.success = success;
            this.code = code;
            this.message = message;
        }
    }

#### 三、统一结果类 ####

>  *  外部返回调用类统一的结果方法 success,failure 因此构造器私有
>  *  内置静态方法，直接返回对象
>  *  便于自定义统一结果信息，使用链式编程，返回对象类本身 return this
>  *  响应数据为json格式，可定义为JsonObject或Map形式

package com.tigerhhzz.springbootmybatisplusdemo.domain;
    
    
    import java.util.HashMap;
    import java.util.Map;
    
    /**
     * @author tigerhhzz
     * @date 2023/5/10 9:31
     * 统一响应结果处理  使用链式编程 返回类本身
     */
    public class CommonRespResult {
        
        private Boolean success;
    
        private Integer code;
    
        private String message;
    
        /**
         * 接口请求时间戳
         */
        private Long timestamp;
    
        private Map<String, Object> data = new HashMap<>();
    
    
        private CommonRespResult setSuccess(Boolean success) {
        
            this.success = success;
            return this;
        }
    
    
        private CommonRespResult setMessage(String message) {
        
            this.message = message;
            return this;
        }
    
        private CommonRespResult setData(Map<String, Object> data) {
        
            this.data = data;
            return this;
        }
    
        private CommonRespResult setCode(Integer code) {
        
            this.code = code;
            return this;
        }
    
        private CommonRespResult() {
        
        }
    
        private CommonRespResult(Long timestamp) {
        
            this.timestamp = timestamp;
        }
    
    
        /**
         * 通用返回成功
         *
         * @return
         */
        public static CommonRespResult success() {
        
            return new CommonRespResult(System.currentTimeMillis())
                    .setSuccess(ResultCodeEnum.SUCCESS.getSuccess())
                    .setCode(ResultCodeEnum.SUCCESS.getCode())
                    .setMessage(ResultCodeEnum.SUCCESS.getMessage());
    
        }
    
        /**
         * 通用返回失败
         *
         * @return
         */
        public static CommonRespResult failure() {
        
            return new CommonRespResult(System.currentTimeMillis())
                    .setSuccess(ResultCodeEnum.FAIL.getSuccess())
                    .setCode(ResultCodeEnum.FAIL.getCode())
                    .setMessage(ResultCodeEnum.FAIL.getMessage());
    
        }
    
        /**
         * 设置结果，形参为结果枚举
         *
         * @param result
         * @return
         */
        public static CommonRespResult setResult(ResultCodeEnum result) {
        
            return new CommonRespResult(System.currentTimeMillis())
                    .setSuccess(result.getSuccess())
                    .setCode(result.getCode())
                    .setMessage(result.getMessage());
    
        }
    
    
        // 自定义返回数据
        public CommonRespResult data(Map<String, Object> map) {
        
            return this.setData(map);
    
        }
    
        // 通用设置data
        public CommonRespResult data(String key, Object value) {
        
            this.data.put(key, value);
            return this;
        }
    
        // 自定义状态信息
        public CommonRespResult message(String message) {
        
            return this.setMessage(message);
    
        }
    
        // 自定义状态码
        public CommonRespResult code(Integer code) {
        
            return this.setCode(code);
    
        }
    
        // 自定义返回结果
        public CommonRespResult success(Boolean success) {
        
            return this.setSuccess(success);
    
        }
    }

#### 四、控制层调用返回 ####

package com.tigerhhzz.springbootmybatisplusdemo.controller;
    
    
    import com.tigerhhzz.springbootmybatisplusdemo.domain.CommonRespResult;
    import com.tigerhhzz.springbootmybatisplusdemo.domain.MBlog;
    import org.springframework.web.bind.annotation.GetMapping;
    
    
    import org.springframework.web.bind.annotation.RestController;
    
    import java.util.HashMap;
    import java.util.Map;
    
    /**
     * <p>
     *  前端控制器
     * </p>
     *
     * @author tigerhhzz
     * @since 2023-04-28
     */
    @RestController
    public class MBlogController {
        
    
        @GetMapping("/index")
        public CommonRespResult index() {
        
            Map m = new HashMap();
            m.put("name", "Tom");
            m.put("age", 25);
            m.put("sex", "男");
            return CommonRespResult.success().data(m);
        }
    
        @GetMapping("/home")
        public CommonRespResult home() {
        
    
            MBlog mBlog = new MBlog();
            mBlog.setContent("DFSDFSDFSDFSD");
            mBlog.setTitle("FFDSFD");
    
            return CommonRespResult.success().data("mBlog",mBlog).message("查询用户详情信息");
        }
    
        /**
         * 异常返回模拟
         *
         * @return
         */
        @GetMapping("/exception")
        public CommonRespResult exception() {
        
            Map m = null;
            m.put("name", "Jack");
            return CommonRespResult.success().data("user", m).message("查询用户详情信息");
        }
    
    }

统一结果类的使用参考了mybatis-plus中Result对象的设计。