Spring Boot 快速入门系列（VI）—— 接口规范篇

​前言

《Spring Boot 快速入门系列》上一节「事务管理篇」讲完了，小伙伴们是否已经掌握了声明式事务管理。

真实的项目，我们必须要考虑数据规范、数据校验、数据安全、权限控制等。如今，前后端分离模式架构已经非常常见，已然成为项目开发标配，后台开发人员专心负责数据接收、业务逻辑处理和响应，前端技术人员负责数据展示和数据传输。一般前后端数据传输的报文交互格式有 json、xml 两种。具体使用哪一种交互格式，以实际情况而定。

在互联网企业中，根据业务会划分很多部门，而每个部门又会开发维护多个微服务，部门内服务之间存在相互调用，不同的业务部门之间的服务也可能有依赖，最后形成了一个庞大而复杂的系统，对于开发和运维人员的要求，公司会统一定义自己的数据规范，一个统一且标准的数据规范对于系统开发和维护来说是至关重要的，也在很大程度上提升了开发和运维效率。

 

接口规范（以 Json 格式为例）

1. 响应报文数据格式

一般来说，响应报文至少需要告诉接口调用方三项信息：

• 响应状态码（code）

• 响应描述信息（msg）

• 响应数据（data）

其中，响应数据不是每个接口必须的，如果只是一个简单更新删除的操作，可能就没有必要返回 data 了。

下面接着之前的项目，我们在 domain 包下定义一个 ResponseDataVO<T> 类来封装我们的响应报文，代码如下所示。

 

package cn.giserway.helloworld.domain;

/**
 * @program: helloworld
 *
 * @author: giserway
 *
 **/
// 响应体
public class ResponseDataVO<T> {
    /**
     * 响应状态码
     */
    private String code;
    /**
     * 响应描述信息
     */
    private String msg;
    /**
     * 响应数据
     */
    private T data;

    /**
     * 无data的返回构造方法
     * @param responseStatusCode
     */
    public ResponseDataVO(ResponseStatusCode responseStatusCode) {
        this.code = responseStatusCode.getCode();
        this.msg = responseStatusCode.getMsg();
    }

    /**
     * 有data的返回构造方法
     * @param responseStatusCode
     * @param data
     */
    public ResponseDataVO(ResponseStatusCode responseStatusCode, T data) {
        this(responseStatusCode);
        this.data = data;
    }

    // 省略 get/set 方法
}

其中 ResponseStatusCode 是一个维护响应状态码的枚举类，代码如下所示：

package cn.giserway.helloworld.domain;

/**
 * @program: helloworld
 *
 * @author: giserway
 *
 **/
// 自定义返回状态码
public enum ResponseStatusCode {
    SUCCESS("0000","请求成功"),
    FAIL("0001","请求失败"),
    CUSTOMEXCEPTION("9999","请求异常");

    private String code;
    private String msg;

    ResponseStatusCode(String code, String msg) {
        this.code = code;
        this.msg = msg;
    }

    // 省略 get/set 方法
}

2. 请求报文数据格式

前后端分离开发模式中，在开发之前，需要定义好接口的数据格式、参数类型、数据校验、请求方式等，使得前后端并行开发，如果接口有改动须及时的进行前后端沟通，提高开发的效率。

一般系统都有登录功能，以此为例，请求数据的格式如下（json）：

{
  "userName":"giserway",
  "password":"123456"
}

在 domain 包下，新建请求数据的后台封装对象 UserLoginReqVO类，代码如下所示：

package cn.giserway.helloworld.domain;

/**
 * @program: helloworld
 *
 * @author: giserway
 *
 **/
// 登录请求体
public class UserLoginReqVO {
    /**
     * 用户名
     */
    private String userName;
    /**
     * 密码
     */
    private String password;

    // 省略 get/set 方法
}

控制层新建 UserController 类，代码如下所示：

package cn.giserway.helloworld.controller;

import cn.giserway.helloworld.domain.ResponseDataVO;
import cn.giserway.helloworld.domain.ResponseStatusCode;
import cn.giserway.helloworld.domain.UserLoginReqVO;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @program: helloworld
 *
 * @author: giserway
 **/
@RestController
@RequestMapping("/user")
public class UserController {

    @PostMapping("/login")
    public ResponseDataVO login(@RequestBody UserLoginReqVO userLoginReqVO) {
        // 具体业务处理省略
        return new ResponseDataVO(ResponseStatusCode.SUCCESS, userLoginReqVO);
    }

}

启动 Spring Boot 项目（注：保证 mysql 数据库已经启动，可以连接，虽然本次测试不需要数据库相关操作，但是沿用了之前的工程项目），用 Postman 模拟请求如下：

请求接口地址：http://localhost:9999/user/login
请求方式：POST
请求数据格式：json
请求数据：
{
  "userName":"giserway",
  "password":"123456"
}

# 响应的报文体格式如下：
{    
  "code": 0,    
  "msg": "请求成功",    
  "data": {        
    "userName": "giserway",        
    "password": "123456"    
  }
}

其中返回的 password 有值不太安全，因此需要将请求对象和响应对象分离，定义一个返回对象 UserRespVO，由于 Spring Boot 默认使用 Jackson 作为 Json 序列化工具，如果想要过滤掉响应体中的某些字段，只需在过滤字段对应的 get 方法上加上 @JsonIgnore 注解即可。下面我们在 password 字段对应的get方法上加上 @JsonIgnore 注解即可忽略该字段的序列化，代码如下所示。

package cn.giserway.helloworld.domain;

import com.fasterxml.jackson.annotation.JsonIgnore;

/**
 * @program: helloworld
 *
 * @author: giserway
 *
 **/
// 登录响应体
public class UserRespVO {
    private String userName;
    @JsonIgnore
    private String password;

    // 省略 get/set 方法
}

控制层 UserController 类的代码修改如下所示：

package cn.giserway.helloworld.controller;

import cn.giserway.helloworld.domain.ResponseDataVO;
import cn.giserway.helloworld.domain.ResponseStatusCode;
import cn.giserway.helloworld.domain.UserLoginReqVO;
import cn.giserway.helloworld.domain.UserRespVO;
import org.springframework.beans.BeanUtils;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @program: helloworld
 *
 * @author: giserway
 **/
@RestController
@RequestMapping("/user")
public class UserController {

    @PostMapping("/login")
    public ResponseDataVO login(@RequestBody UserLoginReqVO userLoginReqVO) {
        // 具体业务处理省略
        UserRespVO userRespVO = new UserRespVO();
        BeanUtils.copyProperties(userLoginReqVO,userRespVO);
        return new ResponseDataVO(ResponseStatusCode.SUCCESS, userRespVO);
    }

}

重新启动项目，Postman 测试同上。

 

小结

通过今天的学习，相信大家对接口规范有了大致的了解，对于目前流行的前后端分离模式开发或者服务端开发，接口规范就显得尤为重要。统一且标准的返回报文，可以减少不同部门系统之间对接的难度，降低沟通成本，也减少部门内前后端同事之间沟通的时间，大大的提高了开发的效率。

 

# 精彩推荐 #

Spring Boot 快速入门系列（II）—— 数据操作篇之 Spring Data JPA

Spring Boot 快速入门系列（III）—— 数据操作篇之 JdbcTemplate

Spring Boot 快速入门系列（IV）—— 数据操作篇之 MyBatis

Spring Boot 快速入门系列（V）—— 事务管理篇之 @Transactional