Restful API实践（二）SpringBoot项目接口设计示例

1 概述

通过上一遍文章（Restful API实践（一）设计要点）我们对Restful API的设计要点进行了详细地介绍，面对现在SpringCloud框架和微服务的火爆，现在我将SpringBoot中常用到的接口类型的设计进行总结。

2 GET接口

get请求通常表达获取某种资源。

（1）获取多个资源。针对多个资源的获取我们可以使用url中的名词为复数形式进行标记为获取多个，具体示例如下：

    //获取多个用户信息
    @GetMapping(value="/users")
    public List<User> getUsers(){
        ... ...
    }

（2）获取单个资源，并且按照田间进行筛选。这里我们就需要使用到url参数来传递筛选条件。具体示例如下：

    //获取单个用户信息
    @GetMapping("/user")
    public User getUser(
            @RequestParam(value = "name",defaultValue = "liutao")String name,
            @RequestParam(value = "age",defaultValue = "10") int age) {

            ... ...
    }

上面例子的name和age就为筛选条件,具体url类似http://locahost:8888/api-demo/user?name=XXXX&age=10。

当我们想要参数的合法性，如果不合法的时候，我们就返回错误状态码及错误信息。这里需要注意，我们不直接在响应内容中返回错误信息，这样会加重对响应内容的封装负担。我们直接在响应头中添加错误信息，具体如下：

if(age < 0){
            HttpServletResponse response = ((ServletRequestAttributes)RequestContextHolder.getRequestAttributes()).getResponse();
            response.setStatus(10004);
            response.addHeader("Error-Message","Parameter is invalid");
            return null;
        }

这个时候如果请求传入的age < 0，响应的结果就会如下：

我们就可以根据响应状态码来获取请求状态，如果请求错误，我们就可以从请求头获取Error-Message来得到错误信息。

（3）如果我们想要限定用户所属部门，但是这个时候我们又不想要使用路径参数，咋办呢？这个时候就应该能想到Spring中有一个注解PathVariable，具体示例如下：

    /**
     * 获取某个部门下的某个用户
     * 这里针对部门的限制使用了路径参数，使用PathVariable标签来获取部门信息
     *
     * @param dept
     * @param name
     * @return
     */
    @GetMapping("/{dept}/user")
    public User getUserOfDept(
            @PathVariable("dept") String dept,
            @RequestParam(value = "name")String name,
            HttpServletRequest request
    ){
            ... ...
     }

这个时候请求路径可以是这样的 http://locahost:8888/api-demo/finance/user?name=XXXX。

然后我们就可以获取到部门信息（dept）为finance。

在我们通常的API中涉及到权限认证token的问题，我们可以直接将token存放在请求头里面，然后在接口里面获取请求头里面的token，进行权限认证，如下：

String token = request.getHeader("token");

当然针对上面这一步建议直接在拦截器里面做处理。

3 POST接口

post请求表达对某种资源的创建。

（1）针对Restful API我们建议数据传递使用json格式。示例如下：

    //添加用户信息
    @PostMapping("/json/user")
    public int addUserToSpecialDepart(
            @RequestParam("dept") String dept,
            @RequestBody User user
    ){
        ... ... 
    }

RequestBody标签会自动将json格式的数据转换成对象。

（2）上面我们看了post接口如何接收json格式，那么如果我们要接收form表单数据呢？这个时候就需要将RequestBody注解换成ModelAttribute,示例如下：

    /**
     * 添加用户信息
     * 请求参数支持表单数据
     * @param user
     * @return
     */
    @PostMapping("/form/user")
    public int addUserByForm(@ModelAttribute User user){
        ... ... 
    }

4 PUT接口

put请求表示对某种资源的修改，但是我们需要注意put的修改与patch相比，put需要传入修改对象的全部数据，二patch仅仅需要传递部分数据。


    //修改用户信息（传入被修改对象的全部）
    @PutMapping("user")
    public int updateUser(@RequestBody User user){
        ... ...
    }

5 PATCH接口

patch接口表示修改，需要传入修改对象的部分内容。

    /**
     * 修改用户名（传入被修改对象的部分信息）
     * @param id
     * @param name
     * @return
     */
    @PatchMapping("user/{id}")
    public int updateUserName(
            @PathVariable("id")String id,
            @RequestParam("name") String name
    ){
        ... ...
    }

6 DELETE接口

delete请求表示删除某个资源，其实delete请求和get请求的使用方式是相同的，不同的仅仅是请求动词。

    /**
     * 删除用户信息
     * @return
     */
    @DeleteMapping("user")
    public int getUser(
            @RequestParam(value = "name",defaultValue = "liutao")String name,
            @RequestParam("age") int age) {
        ... ...
    }

上面就是对SpringBoot中常遇到的Restful API的接口类型的总结，当然在我们接口设计时还会涉及到接口数据传递的安全性问题，这个时候我们就需要对接口数据进行加密，目前最安全的加密方式时RSA加密，针对RSA解密接口数据和加密返回数据，博主利用SpringBoot写了一个自动加密工具，可以参考TOOL_SpringBootSecurityStater 查看源码。

针对这些接口我们如何使用Java代码消费可以参考博主的下一篇文章（Restful API实践（三）RestTemplate使用详解）。

详尽的设计及使用示例可以参考SpringBoot--Restful API设计示例。里面包含了这些接口的设计，以及在单元测试中使用RestTemplate来使用这些接口的例子。