企业开发规范 — — 统一返回值及Swagger2的使用
企业开发规范 — — 统一返回值及Swagger2的使用
1 统一返回值
很多时候，我们在开发的时候会遇到很多不同的返回值。比如：我们查询的话就会返回列表集合，我们删除数据库中的某个元素的话就会是boolean。
但是，对于前端来说，希望我们返回都是同一类型的返回值，不然的话很难处理，也会给前端人员和后端带来沟通上的问题。
通常我们会将通用返回值写在common包下，然后让我们的服务模块去依赖common（如：service-hosp）
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
* @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
* @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.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", "[email protected]"))
.build();
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("后台管理系统-API文档")
.description("本文档描述了后台管理系统微服务接口定义")
.version("1.0")
.contact(new Contact("zi", "http://zi.com", "[email protected]"))
.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）：
返回结果:
