企业开发规范 — — 统一返回值及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", "@.com")) .build(); } private ApiInfo adminApiInfo(){ 
    return new ApiInfoBuilder() .title("后台管理系统-API文档") .description("本文档描述了后台管理系统微服务接口定义") .version("1.0") .contact(new Contact("zi", "http://zi.com", "@.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(); } } } 

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）：

返回结果: