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来使用这些接口的例子。

 

Logo

权威|前沿|技术|干货|国内首个API全生命周期开发者社区

更多推荐