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

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

1 统一返回值

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

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

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

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 演示

• 查询信息返回结果：
  

• 删除信息返回结果：
  

2 Swagger2使用（基于SpringBoot）

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

2.1 导入依赖

<!--swagger-->
<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 启动类上扫描

因为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，选择类

②选择不同方法，发起不同请求

③点击try it out即可向服务器发起请求

返回结果:

④如果请求方法中有参数，在下方填写即可

填写参数（此处我要删除id为2的，因此填写2）：

返回结果: