SpringBoot第11讲：SpringBoot 如何统一接口封装

SpringBoot第11讲：SpringBoot 如何统一接口封装

本文是SpringBoot第11讲，在以SpringBoot开发Restful接口时统一返回，方便前端进行开发和封装，以及出现问题时给出响应编码和信息。

1、RESTful API接口?

• 什么是 REST？

Representational State Transfer，翻译是“表现层状态转化”。可以总结为一句话：REST 是所有 Web 应用都应该遵守的架构设计指导原则。

面向资源是 REST 最明显的特征，对于同一个资源的一组不同的操作。资源是服务器上一个可命名的抽象概念，资源是以名词为核心来组织的，首先关注的是名词。REST 要求，必须通过统一的接口来对资源执行各种操作。对于每个资源只能执行一组有限的操作。

• 什么是 RESTful API？

符合 REST 设计标准的 API，即 RESTful API。REST 架构设计，遵循的各项标准和准则，就是 HTTP 协议的表现，换句话说，HTTP 协议就是属于 REST 架构的设计模式。比如，无状态，请求-响应。

• Restful相关文档可以参考 https://restfulapi.net/

2、为什么要统一封装接口

现在大多数项目采用前后分离的模式进行开发，统一返回方便前端进行开发和封装，以及出现时给出响应编码和信息。

以查询某个用户接口而言，如果没有封装, 返回结果如下

{
  "userId": 1,
  "userName": "赵云"
}

如果封装了，返回正常的结果如下：

{
  "timestamp": 11111111111,
  "status": 200,
  "message": "success",
  "data": {
    "userId": 1,
    "userName": "赵云"
  }
}

异常返回结果如下：

{
  "timestamp": 11111111111,
  "status": 10001,
  "message": "User not exist",
  "data": null
}

3、实现案例

如何实现上面的封装呢？

3.1、状态码封装

这里以常见的状态码为例，包含code 和 msg 两个属性。

如果还有其它业务状态码，也可以放到这个类中。

@Getter
@AllArgsConstructor
public enum ResponseStatus {

    /**
     * 未捕获异常统一返回
     */
    SYSTEM_ERROR(-1, "系统处理超时，请稍后重试"),
    /**
     * 正常情况下返回
     */
    SUCCESS(1, "调用服务接口成功"),
    API_SUCCESS(200, "调用服务接口成功"),

    /**
     * 校验异常
     */
    PARAM_IS_NULL_ERROR(150101, "参数为空"),
    PARAM_ILLEGAL_ERROR(150102, "参数非法"),
    DATA_IS_NULL(150120, "数据不存在"),
    DATA_NOT_NULL(150121, "数据已存在"),

    /**
     * 业务异常
     */
    INSERT_ERROR(150000, "新增失败"),
    UPDATE_ERROR(150001, "更新失败"),
    DELETE_ERROR(150002, "删除失败");

    private final int code;
    private final String msg;
}

3.2、返回内容封装

包含公共的接口返回时间，状态status, 消息message，以及数据data。

考虑到数据的序列化（比如在网络上传输），这里data有时候还会 extends Serializable。

@Data
@Builder
public class ServiceResponse<T> {

    /**
     * response timestamp.
     */
    private long timestamp;

    /**
     * response code, 1 -> OK.
     */
    private int code;

    /**
     * response message.
     */
    private String message;

    /**
     * response data.
     */
    private T data;

    /**
     * response success result wrapper.
     *
     * @param  type of data class
     * @return response result
     */
    public static <T> ServiceResponse<T> success() {
        return success(null);
    }

    /**
     * response success result wrapper.
     *
     * @param data response data
     * @param   type of data class
     * @return response result
     */
    public static <T> ServiceResponse<T> success(T data) {
        return ServiceResponse.<T>builder().data(data)
                .message(ResponseStatus.SUCCESS.getMsg())
                .status(ResponseStatus.SUCCESS.getCode())
                .timestamp(System.currentTimeMillis())
                .build();
    }

    /**
     * response error result wrapper.
     *
     * @param message error message
     * @param      type of data class
     * @return response result
     */
    public static <T extends Serializable> ServiceResponse<T> fail(String message) {
        return fail(null, message);
    }

    /**
     * response error result wrapper.
     *
     * @param data    response data
     * @param message error message
     * @param      type of data class
     * @return response result
     */
    public static <T> ServiceResponse<T> fail(T data, String message) {
        return ServiceResponse.<T>builder().data(data)
                .message(message)
                .status(ResponseStatus.FAIL.getCode())
                .timestamp(System.currentTimeMillis())
                .build();
    }
}

3.3、接口返回时调用

在接口返回时调用, 以用户接口为例

@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    private IUserService userService;

    /**
     * @param user user param
     * @return user
     */
    @ApiOperation("Add/Edit User")
    @PostMapping("add")
    public ServiceResponse<User> add(User user) {
        if (user.getId()==null || !userService.exists(user.getId())) {
            user.setCreateTime(LocalDateTime.now());
            user.setUpdateTime(LocalDateTime.now());
            userService.save(user);
        } else {
            user.setUpdateTime(LocalDateTime.now());
            userService.update(user);
        }
        return ServiceResponse.success(userService.find(user.getId()));
    }


    /**
     * @return user list
     */
    @ApiOperation("Query User One")
    @GetMapping("edit/{userId}")
    public ServiceResponse<User> edit(@PathVariable("userId") Long userId) {
        return ServiceResponse.success(userService.find(userId));
    }
}

4、示例源码

todo

5、接口封装在商品中心的使用

1、通用业务逻辑

@Data
@ToString
public class Response<T> implements Serializable {
    /** 必填 是否成功标识 */
    private boolean success;

    /** 非必填 返回结果集 */
    private T result;

    /** 失败时必填 业务码/失败码 全局需唯一 */
    private String code;

    /** 失败时必填 业务文案/失败文案提示 */
    private String message;

    public boolean isSuccess() {
        return this.success;
    }

    public static <T> Response<T> ok(T data) {
        Response resp = new Response();
        resp.setResult(data);
        resp.setSuccess(true);
        return resp;
    }

    public static <T> Response<T> ok() {
        return ok((T)null);
    }

    public static <T> Response<T> fail(String code, String message) {
        Response resp = new Response();
        resp.setCode(code);
        resp.setMessage(message);
        resp.setSuccess(false);
        return resp;
    }

    public static <T> Response<T> failOfMessage(String message) {
        Response resp = new Response();
        resp.setMessage(message);
        resp.setSuccess(false);
        return resp;
    }

    public static <T> Response<T> fail(String code) {
        Response resp = new Response();
        resp.setCode(code);
        resp.setSuccess(false);
        return resp;
    }
}