企业开发规范 — — 统一返回值及Swagger2的使用（通用Reulst）

傷城~ 2024-04-06 12:39 30阅读 0赞

## 企业开发规范 — — 统一返回值及Swagger2的使用 ##

### 1 统一返回值 ###

> 很多时候，我们在开发的时候会遇到很多不同的返回值。比如：我们查询的话就会返回列表集合，我们删除数据库中的某个元素的话就会是boolean。

但是，对于前端来说，希望我们返回都是同一类型的返回值，不然的话很难处理，也会给前端人员和后端带来沟通上的问题。

通常我们会将通用返回值写在common包下，然后让我们的服务模块去依赖common（如：service-hosp）

![在这里插入图片描述][c102a907dc3b40599dcb1b3130fb8c06.png]

#### 1.1 定义通用类 ####

##### 1.1.1 定义通用结果类 #####

/**
     * 全局统一返回结果类
     */
    @Data
    @ApiModel(value = "全局统一返回结果")
    public class Result<T> {
        
    
        @ApiModelProperty(value = "返回码")
        private Integer code;
    
        @ApiModelProperty(value = "返回消息")
        private String message;
    
        @ApiModelProperty(value = "返回数据")
        private T data;
    
        public Result() {
        
        }
    
        protected static <T> Result<T> build(T data) {
        
            Result<T> result = new Result<T>();
            if (data != null) {
        
                result.setData(data);
            }
            return result;
        }
    
        public static <T> Result<T> build(T body, ResultCodeEnum resultCodeEnum) {
        
            Result<T> result = build(body);
            result.setCode(resultCodeEnum.getCode());
            result.setMessage(resultCodeEnum.getMessage());
            return result;
        }
    
        public static <T> Result<T> build(Integer code, String message) {
        
            Result<T> result = build(null);
            result.setCode(code);
            result.setMessage(message);
            return result;
        }
    
        public static <T> Result<T> ok() {
        
            return Result.ok(null);
        }
    
        /**
         * 操作成功
         *
         * @param data
         * @param <T>
         * @return
         */
        public static <T> Result<T> ok(T data) {
        
            Result<T> result = build(data);
            return build(data, ResultCodeEnum.SUCCESS);
        }
    
        public static <T> Result<T> fail() {
        
            return Result.fail(null);
        }
    
        /**
         * 操作失败
         *
         * @param data
         * @param <T>
         * @return
         */
        public static <T> Result<T> fail(T data) {
        
            Result<T> result = build(data);
            return build(data, ResultCodeEnum.FAIL);
        }
    
        public Result<T> message(String msg) {
        
            this.setMessage(msg);
            return this;
        }
    
        public Result<T> code(Integer code) {
        
            this.setCode(code);
            return this;
        }
    
        public boolean isOk() {
        
            if (this.getCode().intValue() == ResultCodeEnum.SUCCESS.getCode().intValue()) {
        
                return true;
            }
            return false;
        }
    }

##### 1.1.2 定义分页查询通用 #####

*  分页查询请求

@Data
    @ToString
    public class PageParams {
        
    
      //当前页码默认值
      public static final long DEFAULT_PAGE_CURRENT = 1L;
      //每页记录数默认值
      public static final long DEFAULT_PAGE_SIZE = 10L;
    
      //当前页码
      @ApiModelProperty("当前页码")
      private Long pageNo = DEFAULT_PAGE_CURRENT;
    
      //每页记录数默认值
      private Long pageSize = DEFAULT_PAGE_SIZE;
    
      public PageParams(){
        
    
      }
    
      public PageParams(long pageNo,long pageSize){
        
       this.pageNo = pageNo;
       this.pageSize = pageSize;
      }
    }

*  分页查询返回

@Data
    @ToString
    public class PageResult<T> {
        
        // 数据列表
        private List<T> items;
    
        //总记录数
        private long counts;
    
        //当前页码
        private long page;
    
        //每页记录数
        private long pageSize;
    
        public PageResult(List<T> items, long counts, long page, long pageSize) {
        
            this.items = items;
            this.counts = counts;
            this.page = page;
            this.pageSize = pageSize;
        }
    
    }

#### 1.2 定义返回结果状态信息（code+msg） ####

/**
     * 统一返回结果状态信息类
     */
    @Getter
    public enum ResultCodeEnum {
        
    
        SUCCESS(200,"成功"),
        FAIL(201, "失败"),
        PARAM_ERROR( 202, "参数不正确"),
        SERVICE_ERROR(203, "服务异常"),
        DATA_ERROR(204, "数据异常"),
        DATA_UPDATE_ERROR(205, "数据版本异常"),
    
        LOGIN_AUTH(208, "未登陆"),
        PERMISSION(209, "没有权限"),
    
        CODE_ERROR(210, "验证码错误"),
    //    LOGIN_MOBLE_ERROR(211, "账号不正确"),
        LOGIN_DISABLED_ERROR(212, "改用户已被禁用"),
        REGISTER_MOBLE_ERROR(213, "手机号已被使用"),
        LOGIN_AURH(214, "需要登录"),
        LOGIN_ACL(215, "没有权限"),
    
        URL_ENCODE_ERROR( 216, "URL编码失败"),
        ILLEGAL_CALLBACK_REQUEST_ERROR( 217, "非法回调请求"),
        FETCH_ACCESSTOKEN_FAILD( 218, "获取accessToken失败"),
        FETCH_USERINFO_ERROR( 219, "获取用户信息失败"),
        //LOGIN_ERROR( 23005, "登录失败"),
    
        PAY_RUN(220, "支付中"),
        CANCEL_ORDER_FAIL(225, "取消订单失败"),
        CANCEL_ORDER_NO(225, "不能取消预约"),
    
        HOSCODE_EXIST(230, "医院编号已经存在"),
        NUMBER_NO(240, "可预约号不足"),
        TIME_NO(250, "当前时间不可以预约"),
    
        SIGN_ERROR(300, "签名错误"),
        HOSPITAL_OPEN(310, "医院未开通，暂时不能访问"),
        HOSPITAL_LOCK(320, "医院被锁定，暂时不能访问"),
        ;
    
        private Integer code;
        private String message;
    
        private ResultCodeEnum(Integer code, String message) {
        
            this.code = code;
            this.message = message;
        }
    }

#### 1.3 演示 ####

*  查询信息返回结果：  
    ![在这里插入图片描述][7aaec8c6cde346d48ca4543cb39bcc00.png]
 *  删除信息返回结果：  
    ![在这里插入图片描述][9d251179b96b42d99863ca8a3da4289c.png]

### 2 Swagger2使用（基于SpringBoot） ###

> 在开发过程中，我们有时候不仅仅是要向服务器发起GET、PUT请求，还有其他很多请求，比如DELETE请求。但是这个时候我们又没有其他访问工具（像PostMan那种），这个时候我们就可以基于Swagger2向服务器发送不同请求。

#### 2.1 导入依赖 ####

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
    </dependency>

#### 2.2 编写配置类Swagger2Config ####

/**
     * @author 夏末
     * @description Swagger2配置信息
     * @date 2022/9/24 11:23
     */
    
    @Configuration
    @EnableSwagger2
    public class Swagger2Config {
        
        @Bean
        public Docket webApiConfig(){
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("webApi")
                    .apiInfo(webApiInfo())
                    .select()
                    //只显示api路径下的页面
                    .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                    .build();
        }
    
        @Bean
        public Docket adminApiConfig(){
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("adminApi")
                    .apiInfo(adminApiInfo())
                    .select()
                    //只显示admin路径下的页面
                    .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                    .build();
        }
    
        private ApiInfo webApiInfo(){
        
            return new ApiInfoBuilder()
                    .title("网站-API文档")
                    .description("本文档描述了网站微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("zi", "http://zi.com", "493211102@qq.com"))
                    .build();
        }
    
        private ApiInfo adminApiInfo(){
        
            return new ApiInfoBuilder()
                    .title("后台管理系统-API文档")
                    .description("本文档描述了后台管理系统微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("zi", "http://zi.com", "49321112@qq.com"))
                    .build();
        }
    }

#### 2.3 Controller层中使用 ####

/**
     * @author 夏末
     * @description TODO
     * @date 2022/9/24 10:52
     * Swagger访问地址：http://localhost:8201/swagger-ui.html
     */
    @Api("医院设置管理")
    @RestController
    @RequestMapping("/admin/hosp/hospitalSet")
    public class HospitalSetController {
        
    
        @Autowired
        private HospitalSetService hospitalSetService;
    
        /**
         * 获取所有医院列表
         *
         * @return
         */
        @ApiOperation("获取所有医院设置")
        @GetMapping("/findAll")
        public Result findAllHospitalSet() {
        
            List<HospitalSet> list = hospitalSetService.list();
            return Result.ok(list);
        }
    
    
        /**
         * 逻辑删除医院
         *
         * @param id
         * @return
         */
        @ApiOperation("逻辑删除医院设置")
        @DeleteMapping("/{id}")
        public Result deleteHospById(@PathVariable("id") Integer id) {
        
            boolean result = hospitalSetService.removeById(id);
            if (result) {
        
                //删除成功
                return Result.ok();
            } else {
        
                return Result.fail();
            }
        }
    }

> @Api(“医院设置管理”)标识类  
> @ApiOperation(“逻辑删除医院设置”)标识方法

#### 2.4 启动类上扫描 ####

![在这里插入图片描述][3a646b49ea8e4ed1ba16d40f541e50b8.png]  
因为Swagger2的配置类与服务启动的相同包结构为com.zi，所以使用@ComponentScan扫描com.zi(也可以为com.zi.yygh)

> @ComponentScan

/**
     * @author 夏末
     * @description TODO
     * @date 2022/9/24 10:34
     */
    @SpringBootApplication
    @ComponentScan(basePackages = "com.zi")
    public class ServiceHospApplication {
        
    
        public static void main(String[] args) {
        
            SpringApplication.run(ServiceHospApplication.class);
        }
    }

#### 2.5 利用Swagger2发起不同请求 ####

Swagger默认访问地址：

http://ip:port/swagger-ui.html

①访问Swagger，选择类  
![在这里插入图片描述][ed049bf981f8442ebee7e2d4d435b7b3.png]  
②选择不同方法，发起不同请求  
![在这里插入图片描述][d5c52aee194347e1a5d0f0875ac6e453.png]  
③点击try it out即可向服务器发起请求  
![在这里插入图片描述][391335eb616143f6891b5fde81971af8.png]  
`返回结果:`  
![在这里插入图片描述][6acd1560fa7f4a688b8873cc35cd6bb6.png]

④如果请求方法中有参数，在下方填写即可  
![在这里插入图片描述][51d9a180dcb2429cba7d1c0fef4c33da.png]  
填写参数（此处我要删除id为2的，因此填写2）：  
![在这里插入图片描述][3e043918e8524e35804b8a61da86be98.png]  
`返回结果:`  
![在这里插入图片描述][7ca4ee5ea6aa4fbda8dd768cda390633.png]

[c102a907dc3b40599dcb1b3130fb8c06.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/3b177fa66085489da4f5b8dfeb333480.png
[7aaec8c6cde346d48ca4543cb39bcc00.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/23b76365455d4e80b04c919fbacd2000.png
[9d251179b96b42d99863ca8a3da4289c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/07cd8047f7b7451697ad64c99a2b04cc.png
[3a646b49ea8e4ed1ba16d40f541e50b8.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/dd29e4129ced402b8f135ceb84b7ebcf.png
[ed049bf981f8442ebee7e2d4d435b7b3.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/a82072c924944111b8867d50aca4b42c.png
[d5c52aee194347e1a5d0f0875ac6e453.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/6aefe5d3c0fc49c6813741e6d8cf1605.png
[391335eb616143f6891b5fde81971af8.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/7ec1d0f0d7dd4a418aa7d1017ef4e932.png
[6acd1560fa7f4a688b8873cc35cd6bb6.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/feae262c33f1495dbea56187e8a1c34e.png
[51d9a180dcb2429cba7d1c0fef4c33da.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/4e6d2d0e3f644597bcd4eb3d4aca167b.png
[3e043918e8524e35804b8a61da86be98.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/7003b6d3982a431482488b0235f6a657.png
[7ca4ee5ea6aa4fbda8dd768cda390633.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/934e31b0b4c3481b86330e67fa7ac29e.png