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

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

请求与响应

请求与响应参数是前后端开发人员对接的重要关注点，如果后端 API 不能向前端（甚至是自己）清晰的传达我接收什么，我返回什么的问题，那么对于双方来说，这都是一种灾难。

通用的 ApiResult

@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扩展一些常用的方法，使得接口在构建响应参数时更加方便。

状态码枚举

@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 工具去处理。这是非常愚蠢的操作。当然，爽是真的爽，但是这样的爽非常自私。对于调用者₁来说，这样的的接口就像是一个黑盒子，必须翻阅具体的代码才能看到它接收什么、返回什么。可是他只想调用一下这个接口，至于里边怎么做的他不需要关心。这合理吗？这一点都不合理！

使用实体类声明就能很好的避免这个问题，因为它能够严格规定这个接口的请求与返回，不是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
        • UserAddReq.java
  • entity
  • properties
  • redis
• service
• utils

---

先别急着骂！这样去管理这些实体类的确目录层级较多，比较麻烦。但是规范与效率两件事本来就是不可兼得的，在很多时候，我自己还是比较偏向于规范的。

这样做有什么好处呢，首先实体类的名称变得有迹可循、有规可依。其次接口参数实体类所在dto包下的目录和接口是一一对应的，有利于你看到接口参数实体类就能很快定位到使用它的接口，看到接口就能很快定位到它的参数实体类。所以今日所谓的麻烦是为了以后不会遇到更多的麻烦。

推荐使用 Swagger

Swagger 能够自动生成接口文档，可以交给前端同事 Swagger 地址作为接口对接依据，开展工作。也可以使用其进行快速的接口调用，进行接口自测。

基本使用

添加依赖并启用

<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 配置文件警告。

@Data
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {

    /**
     * 是否启用 Swagger，默认关闭
     */
    private Boolean enabled = Boolean.FALSE;
}

创建 SwaggerConfig

@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版本不同，可能需要添加相应的依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

以上文的保存用户信息接口请求参数的年龄属性为例，你可以这样做：

接口

@PostMapping("/add")
@ApiOperation(value = "保存用户信息")
public ApiResult<?> add(@RequestBody @Validated UserAddReq req) {
    userService.add(req);
    return ApiResult.success();
}

请求参数实体类

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，除此之外，还有很多的校验注解可以使用，可以点击跳转查阅更多

校验不通过时，程序将会抛出异常来阻止继续运行！将在下文中说明如何优雅的处理校验不通过时的错误。

全局异常处理

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中进行处理。