相对规范的服务API应如何实现

标准规范的接口可以降低前后端开发人员之间的沟通成本,并且能够降低后端服务自身的后期维护难度。

请求与响应

请求与响应参数是前后端开发人员对接的重要关注点,如果后端 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最终会体现在ApiResultstatus中,前端得以根据不同的状态码进行逻辑处理,可以根据业务需要进行添加。可以参考 http 标准的状态码列举,但是一般与业务相近的 http 状态码少之又少,所以按照数字顺序不断自增列举的方式也是可取的。

使用实体类声明请求与响应参数

一个优秀的 API 接口,是不需要翻阅具体代码就能知道它的请求与响应参数的。

不知道有多少人喜欢使用Map或者类似于Map的类去接收和响应数据,甚至是使用String搭配一些 Json 工具去处理。这是非常愚蠢的操作。当然,爽是真的爽,但是这样的爽非常自私。对于调用者1来说,这样的的接口就像是一个黑盒子,必须翻阅具体的代码才能看到它接收什么、返回什么。可是他只想调用一下这个接口,至于里边怎么做的他不需要关心。这合理吗?这一点都不合理!

使用实体类声明就能很好的避免这个问题,因为它能够严格规定这个接口的请求与返回,不是MapString这样的“来者不拒“。

[1] 调用者:在微服务架构下,许多接口不仅向前端提供,也会向其他服务提供,此处的调用者指后端开发人员。

如何管理这些实体类

个人经验,觉得每一个接口都应该拥有自己独立的参数实体类

一些人喜欢使用DTOVO作为后缀命名接口的参数,我个人更喜欢使用ReqRes作为后缀,也向你推荐使用这种方式,因为它更加的贴切、一目了然。

举一个栗子🌰,有一个分页查询用户信息的接口、还有一个新增用户信息的接口,那么它的参数实体类位置以及命名应该像下面这个样子:


  • controller
    • UserController.java /user
      • /pageList接口,方法名为pageList
      • /add 接口,方法名为add
  • mapper
  • pojo
    • dto
      • user
        • pagelist
          • UserPageListReq.java
          • UserPageListRes.java
        • add
          • UserAddReq.java
    • 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 {

/**
* 是否启用 Swagger,默认关闭
*/
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()
//指定需要被 Swagger 扫描到的包名
.apis(RequestHandlerSelectors.basePackage("com.xxxxx.xxxx.controller"))
.paths(PathSelectors.any())
.build();
}

/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
*
* @return ApiInfo
*/
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());

/**
* 处理其他所有异常
*
* @param req 请求参数
* @param e 异常信息
* @return ApiResult
*/
@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);
}


/**
* 校验参数异常
*
* @param req HttpServletRequest
* @param e 异常信息
* @return ApiResult
*/
@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());
}

/**
* 处理业务异常
*
* @param req 请求参数
* @param e 异常信息
* @return ApiResult
*/
@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());
}

/**
* 处理空指针异常
*
* @param req 请求参数
* @param e 异常信息
* @return ApiResult
*/
@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]);
}

/**
* 请求消息无法解析异常
*
* @param req 请求参数
* @param e 异常信息
* @return ApiResult
*/
@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中进行处理。