对于相对规范的服务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 工具去处理。这是非常愚蠢的操作。当然，爽是真的爽，但是这样的爽非常自私。对于调用者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
      - UserAddReq.java
- entity
- properties
- redis
service
utils

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

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

请求参数校验

使用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("请检查请求体格式");
    }

}