标准规范的接口可以降低前后端开发人员之间的沟通成本,并且能够降低后端服务自身的后期维护难度。
请求与响应
请求与响应参数是前后端开发人员对接的重要关注点,如果后端 API 不能向前端(甚至是自己)清晰的传达我接收什么,我返回什么的问题,那么对于双方来说,这都是一种灾难。
通用的 ApiResult
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
| @Data @AllArgsConstructor @NoArgsConstructor public class ApiResult<T> implements Serializable { private static final long serialVersionUID = 2747440445733983051L;
private Integer status;
private String msg;
private T payload;
private String exception; }
|
这是一个简单的ApiResult
示例,你所开发的每一个接口响应参数都应该是它,它是处于顶层的响应参数结构,通过指定不同的泛型适应各个接口的需求。各个参数作用如下:
- status 状态码,用不同的数字表示当前接口处理完成后的结果状态。请不要与 Http 的状态混为一谈,我们不希望直接使用 Http 的状态来表示。 Http 的状态每次请求都应该是 200 的,处理的结果应由响应参数来体现。
- msg 信息,后端服务提示用户消息的主要途径,因为许多的提示信息(正确或错误)都是在后端程序执行过程中才会出现。一般这个信息前端需要使用弹窗、横幅或其他手段去传达给用户。
- payload 响应数据,这个参数可以是任何数据类型,它是接口响应的具体业务数据。
- exception 程序异常信息,结合自己的开发经验,觉得需要这样一个参数来帮助开发者更快的定位问题。例如发生某个异常,这个参数可以是该异常的具体信息
e.getMessage()
,所以开发人员只需通过浏览器开发者工具就能找到发生异常的原因。注意这个信息是不能传达给用户的!
可以根据自己的习惯去命名这些参数,也可以为ApiResult
扩展一些常用的方法,使得接口在构建响应参数时更加方便。
状态码枚举
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
| @Getter @AllArgsConstructor public enum ApiStatusEnum {
SUCCESS(200, "处理成功"),
UNAUTHORIZED(401, "未授权(登录信息有误 需要重新登录)"),
NO_PERMISSIONS(403, "无操作权限"),
FAIL(500, "处理失败");
private final Integer status;
private final String msg; }
|
这是一个状态码枚举示例,它的status
最终会体现在ApiResult
的status
中,前端得以根据不同的状态码进行逻辑处理,可以根据业务需要进行添加。可以参考 http 标准的状态码列举,但是一般与业务相近的 http 状态码少之又少,所以按照数字顺序不断自增列举的方式也是可取的。
使用实体类声明请求与响应参数
一个优秀的 API 接口,是不需要翻阅具体代码就能知道它的请求与响应参数的。
不知道有多少人喜欢使用Map
或者类似于Map
的类去接收和响应数据,甚至是使用String
搭配一些 Json 工具去处理。这是非常愚蠢的操作。当然,爽是真的爽,但是这样的爽非常自私。对于调用者1来说,这样的的接口就像是一个黑盒子,必须翻阅具体的代码才能看到它接收什么、返回什么。可是他只想调用一下这个接口,至于里边怎么做的他不需要关心。这合理吗?这一点都不合理!
使用实体类声明就能很好的避免这个问题,因为它能够严格规定这个接口的请求与返回,不是Map
、String
这样的“来者不拒“。
[1] 调用者:在微服务架构下,许多接口不仅向前端提供,也会向其他服务提供,此处的调用者指后端开发人员。
如何管理这些实体类
个人经验,觉得每一个接口都应该拥有自己独立的参数实体类。
一些人喜欢使用DTO
和VO
作为后缀命名接口的参数,我个人更喜欢使用Req
和Res
作为后缀,也向你推荐使用这种方式,因为它更加的贴切、一目了然。
举一个栗子🌰,有一个分页查询用户信息的接口、还有一个新增用户信息的接口,那么它的参数实体类位置以及命名应该像下面这个样子:
- controller
- UserController.java
/user
/pageList
接口,方法名为pageList
/add
接口,方法名为add
- mapper
- pojo
- dto
- user
- pagelist
- UserPageListReq.java
- UserPageListRes.java
- add
- entity
- properties
- redis
- service
- utils
先别急着骂!这样去管理这些实体类的确目录层级较多,比较麻烦。但是规范与效率两件事本来就是不可兼得的,在很多时候,我自己还是比较偏向于规范的。
这样做有什么好处呢,首先实体类的名称变得有迹可循、有规可依。其次接口参数实体类所在dto
包下的目录和接口是一一对应的,有利于你看到接口参数实体类就能很快定位到使用它的接口,看到接口就能很快定位到它的参数实体类。所以今日所谓的麻烦是为了以后不会遇到更多的麻烦。
推荐使用 Swagger
Swagger 能够自动生成接口文档,可以交给前端同事 Swagger 地址作为接口对接依据,开展工作。也可以使用其进行快速的接口调用,进行接口自测。
基本使用
添加依赖并启用
1 2 3 4 5
| <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
|
SpringBoot 启动类上添加 @EnableOpenApi
注解
创建 SwaggerProperties
通过配置在yml
文件中的enabled
参数来控制不同环境下Swagger是否开启。关于yml
文件与@ConfigurationProperties
可以参考另一篇文章解决 Spring 配置文件警告。
1 2 3 4 5 6 7 8 9 10
| @Data @ConfigurationProperties(prefix = "swagger") public class SwaggerProperties {
private Boolean enabled = Boolean.FALSE; }
|
创建 SwaggerConfig
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
| @Configuration @RequiredArgsConstructor public class SwaggerConfig {
private final SwaggerProperties swaggerProperties;
@Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .enable(swaggerProperties.getEnabled()) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.xxxxx.xxxx.controller")) .paths(PathSelectors.any()) .build(); }
private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("xxx项目") .description("") .termsOfServiceUrl("") .version("1.0") .build(); } }
|
项目启动后就可以通过 {服务根路径}/swagger-ui/
去访问文档了,一定要注意,最后的反斜杠是必须的,否则无法访问。
@Api
@Api
是放置在Controller
类上的,例如用户的UserController
可以这样去写:@Api(tags = "User-用户信息相关接口")
@ApiOperation
@ApiOperation
是放置在具体接口上的,例如用户的/pageList
接口可以这样去写:@ApiOperation(value = "分页查询用户信息")
@ApiModel
@ApiModel
是放置在请求或响应实体类上的,例如分页查询用户信息接口请求参数可以这样写:@ApiModel(description = "分页查询用户信息接口请求参数")
@ApiModelProperty
@ApiModelProperty
是放置在请求或响应实体类的属性上的,例如保存用户信息接口请求参数的年龄属性可以这样写: @ApiModelProperty(value = "年龄", required = true)
其中的required
可以指定是否为必传字段,为 true
时文档中会为该属性添加红色星号,为 true
时可以忽略不写,例如@ApiModelProperty("年龄")
,注意,他并不会帮你进行参数校验!
既然用了就落实下去
为什么会说既然用了就落实下去?我遇到很多的项目,用到了 Swagger,一些接口有他的影子,一些接口又没有他,前后端对接还是跟之前一样口头传达。所以,你要它有何用?
请求参数校验
使用org.springframework.validation.annotation
包下的@Validated
对请求参数进行合法性校验。
因SpringBoot版本不同,可能需要添加相应的依赖
1 2 3 4
| <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency>
|
以上文的保存用户信息接口请求参数的年龄属性为例,你可以这样做:
接口
1 2 3 4 5 6
| @PostMapping("/add") @ApiOperation(value = "保存用户信息") public ApiResult<?> add(@RequestBody @Validated UserAddReq req) { userService.add(req); return ApiResult.success(); }
|
请求参数实体类
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
| import javax.validation.constraints.NotNull;
@Data @ApiModel(description = "保存用户信息请求参数") public class UserAddReq implements Serializable { private static final long serialVersionUID = -2749806305785349883L;
@NotNull(message = "年龄不允许为空") @ApiModelProperty(value = "年龄", required = true) private Integer age;
}
|
通过@NotNull
来指定age
字段不允许为null
,除此之外,还有很多的校验注解可以使用,可以点击跳转查阅更多
校验不通过时,程序将会抛出异常来阻止继续运行!将在下文中说明如何优雅的处理校验不通过时的错误。
全局异常处理
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
| package com.sincland.insurance.partner.config;
import com.sincland.insurance.partner.exception.BusinessException; import com.sincland.insurance.partner.pojo.other.ApiResult; import org.apache.commons.lang3.ObjectUtils; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.http.converter.HttpMessageNotReadableException; import org.springframework.validation.BindingResult; import org.springframework.validation.FieldError; import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice;
import javax.servlet.http.HttpServletRequest;
@RestControllerAdvice public class ExceptionHandlerConfig {
private final Logger log = LoggerFactory.getLogger(this.getClass());
@ExceptionHandler(value = Exception.class) public ApiResult<?> exceptionHandler(HttpServletRequest req, Exception e) { String msg; if (ObjectUtils.isNotEmpty(e.getCause())) { msg = e.getCause().getMessage(); } else { msg = e.getMessage(); } log.error("接口:{} 发生运行时异常:{}", req.getRequestURI(), msg); e.printStackTrace(); return ApiResult.exception(msg); }
@ExceptionHandler(value = MethodArgumentNotValidException.class) public ApiResult<?> handleMethodArgumentNotValidException(HttpServletRequest req, MethodArgumentNotValidException e) { BindingResult bindingResult = e.getBindingResult(); StringBuilder msg = new StringBuilder("请求参数校验不通过: "); for (FieldError fieldError : bindingResult.getFieldErrors()) { msg.append(fieldError.getField()).append(":").append(fieldError.getDefaultMessage()).append(","); } msg.replace(msg.length() - 1, msg.length(), ""); log.error("接口:{} {}", req.getRequestURI(), msg); return ApiResult.exception(msg.toString()); }
@ExceptionHandler(value = BusinessException.class) public ApiResult<?> businessExceptionHandler(HttpServletRequest req, BusinessException e) { log.error("接口:{} 发生业务性异常:{}", req.getRequestURI(), e.getMessage()); return e.getApiResultIsException() ? ApiResult.exception(e.getStatus(), e.getMessage()) : ApiResult.fail(e.getStatus(), e.getMessage()); }
@ExceptionHandler(value = NullPointerException.class) public ApiResult<?> nullPointerExceptionHandler(HttpServletRequest req, NullPointerException e) { log.error("接口:{} 发生空指针异常:{}", req.getRequestURI(), e.getStackTrace()[0]); e.printStackTrace(); return ApiResult.exception("发生空指针异常:" + e.getStackTrace()[0]); }
@ExceptionHandler(value = HttpMessageNotReadableException.class) public ApiResult<?> httpMessageNotReadableExceptionHandler(HttpServletRequest req, HttpMessageNotReadableException e) { log.error("接口:{} 请求消息无法解析异常:{}", req.getRequestURI(), e.getMessage()); e.printStackTrace(); return ApiResult.fail("请检查请求体格式"); }
}
|
可以通过@ExceptionHandler
指定各式各样的异常处理,包括自定义的异常、Java 内置的异常、校验参数异常MethodArgumentNotValidException
。通过与ApiResult
联动,达到即使程序异常,也会按照正常的数据格式进行响应。
也可以实现在服务层需要返回一些业务性错误,但你的方法返回值却不是ApiResult
,那么你可以抛出一些自定义异常,再在ExceptionHandlerConfig
中进行处理。