Spring Boot实际应用讲解（四）：RESTful API

作者: ZYRzyr | 来源:发表于2017-11-21 11:36 被阅读777次

文/ZYRzyr
原文链接:http://www.jianshu.com/p/e907595e9d1d

本文提纲
一、RESTful API通俗解释
二、为什么选择它
三、实例
四、最后

本文运行环境

Ubuntu 16.04 LTS
JDK 8 +
IntelliJ IDEA ULTIMATE 2017.2
Maven 3.5.0
Spring Boot 1.5.8.RELEASE

一、RESTful API通俗解释

RESTful API即具有REST风格的API，那什么是REST呢？
网上有很多介绍什么是REST的，但大多都是长篇大论的理论，即使有耐心读完，也不一定能真正理解其意。比如下面这一小句：

REST全称Representational State Transfer，中文翻译【表述性状态传递】。

所以这个【表述性状态传递】到底是什么鬼？反正我是不明白。
经过自己长时间的使用与对标准化的追求，再加上平时的网络交互中，使用最多的是HTTP协议，所以自己总结出的在HTTP协议基础下的REST即：

客户端与服务器交互过程中，客户端用URL定位服务器资源，用一些动词（POST、GET、PUT、PATCH、DELETE等）描述对资源的操作，得到状态码判断操作结果如何。

实际项目中，很难写出完全满足REST标准的API，所以此处只说一般情况下需要满足的点：

1.1 资源的定义

一般使用名词而不是动词来定义URL，比如：
api.example.com/version/products而不是api.example.com/version/getProducts表示获取商品。

1.2 使用合适的动词

GET——获取资源
POST——新建资源（很少情况下也可用于更新）
PUT——更新资源（对整个资源的更新）
PATCH——更新资源（对部分资源的更新，很少使用，某些类库不支持）
DELETE——删除资源

1.3 使用标准的HTTP状态码

假设一种场景：有一个API是POST请求，请求参数是name和age，其中age有一个后台验证，小于18则不添加并返回错误信息，当客户端调用此API时，age=11，此时不满足后台验证，返回了错误信息必须是成年人，状态码是200.

到此，看似一切都很正常：请求成功，并且也有错误信息。但熟悉HTTP状态码的话就会发现：明明已经返回错误信息了，说明出错了，但还是返回了表示成功的200，这让客户端在做处理时面临一种比较尴尬的情况：需要在success中写错误处理逻辑。

因此，RESTful API中要求：当客户端请求时，达到预期目的才能返回200，其它时候，根据具体的情况返回具体的状态码，这样既标准，又能反应出问题出在何处。上面这种情况应该返回错误信息的同时，返回状态码400，这样，客户端就能从自身找原因。

1.4 适当的表示

REST并没有规定有何种方式来表示资源，但在HTTP协议下，一般的选择就是JSON或XML，因此本文将以JSON表示这些资源。通俗点讲，就是请求一个API时得到的返回值中的数据的表现形式是JSON还是XML。

一般情况下，满足以上4点，即可称为RESTful API，需要强调的是REST并不仅仅以上4点，想了解比较全面的REST，可以看看这篇比较长的文章

二、为什么选择它

服务器提供的API可以有很多种形式，但为什么选择RESTful API呢？主要有以下两点：

2.1 统一的接口

在面对各种客户端存在的情况下：Web、Android，iOS等，RESTful API可以提供一套统一的接口为它们服务，另外，对于一些可以提供第三方服务的平台，如微信登录，支付宝支付等，它们并不需要显示的客户端存在，只需要一套提供服务的接口，RESTful API就是很好的选择，并且RESTful API在微服务架构中也是常用的服务间通信方式。

2.2 对代码质量的追求

就像上一点说的统一接口，其它形式的API也能做到，比如：
只要服务器没有出系统问题，所有的请求都返回下面这种格式：

POST请求成功—无返回值
{
    "code": "1",
    "data": null,
    "message": "客户端请求成功"
}

GET请求成功—返回
{
    "code": "1",
    "data": [
        {
            "name": "Tom",
            "age": 12,
            "money": 100.5
        },
        {
            "name": "Bob",
            "age": 13,
            "money": 200.5
        }
    ],
    "message": "客户端请求成功"
}

请求失败—无返回值
{
    "code": "101",
    "data": null,
    "message": "密码错误"
}

这种形式，看起来似乎很标准，很合理，但其实它有几个坑：

所有的code需要与客户端重新定义，哪个值表示什么意思，一旦有修改，需要重新规定，而RESTful API使用现成的HTTP状态码；
如果data中的形式复杂，解析起来很麻烦，而RESTful API直接返回需要的数据，即使麻烦，始终少一层解析；
客户端的所有响应逻辑全都写在success中，对于追求代码质量的人来说，不能容忍这种尴尬的局面，而RESTful API只要有错，就能在error中操作；
看起来很专业，其实一点也不。

三、实例

Spring Boot对于RESTful API也有很好的支持，本次实例继续使用前篇的项目，依次演示GET、POST、PUT、DELETE，4种请求方式。由于还没讲到数据库，所以暂时不涉及数据库的操作，只需关注上面第一大点中提到的4小点。

3.1 UserController

在上一篇文章中的UserController中新增以下方法，分别对应GET、POST、PUT、DELETE，4种请求方式：

    @GetMapping("/users")
    public ResponseEntity<List<User>> getUsers() {
        List<User> users = new ArrayList<>();
        User user1 = new User();
        user1.setName("Bob");
        user1.setAge(20);
        user1.setPassword("123456");

        User user2 = new User();
        user2.setName("Tom");
        user2.setAge(22);
        user2.setPassword("654321");

        //模拟从数据库取出数据
        users.add(user1);
        users.add(user2);
        return new ResponseEntity<>(users, HttpStatus.OK);
    }

    @PostMapping("/register")
    public ResponseEntity<String> register(@Valid User user, BindingResult bindingResult) {
        if (bindingResult.hasErrors()) {
            //如果验证出错，则返回错误信息，状态码400
            return new ResponseEntity<>(bindingResult.getFieldError().getDefaultMessage(), HttpStatus.BAD_REQUEST);
        }

        return new ResponseEntity<>("success", HttpStatus.OK);
    }

    @PutMapping("/profile")
    public ResponseEntity<User> updateUser(User newUser) {
        User oldUser = new User();
        oldUser.setName("old");
        oldUser.setAge(20);
        oldUser.setPassword("123456");

        //假设oldUser为数据库中已存在数据，用newUser更新oldUser
        if (!TextUtil.isEmpty(newUser.getName())) {
            oldUser.setName(newUser.getName());
        }

        if (newUser.getAge() != null) {
            oldUser.setAge(newUser.getAge());
        }

        if (!TextUtil.isEmpty(newUser.getPassword())) {
            oldUser.setPassword(newUser.getPassword());
        }

        return new ResponseEntity<>(oldUser, HttpStatus.OK);
    }

    @DeleteMapping("/user")
    public ResponseEntity deleteUser(String name) {
        //省略数据库删除数据操作
        return new ResponseEntity(HttpStatus.OK);
    }

在UserController的类名上除了@RestController，还有一个@RequestMapping("/user")，表示URL是localhost:8080/user；
@GetMapping，@PostMapping，@PutMapping，@DeleteMapping：对应的该方法的访问方式分别是GET、POST、PUT、DELETE，其括号中的值接在上一点的后面，如：localhost:8080/user/users；
ResponseEntity<T>：响应实体，其中可包含数据与状态码，或只包含状态码。

3.2 测试

3.2.1 单元测试

在UserControllerTest中添加如下测试用例：

    @Test
    public void testRegister_success() throws Exception {
        mockMvc.perform(MockMvcRequestBuilders.post("/user/register")
                .param("name", "Bob")
                .param("age", "20")
                .param("password", "123456"))
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andExpect(MockMvcResultMatchers.content().string("success"));
    }

    @Test
    public void testRegister_age_error() throws Exception {
        mockMvc.perform(MockMvcRequestBuilders.post("/user/register")
                .param("name", "Bob")
                .param("age", "10")
                .param("password", "123456"))
                .andExpect(MockMvcResultMatchers.status().isBadRequest())//age=10，验证不通过，返回状态码400
                .andExpect(MockMvcResultMatchers.content().string("必须是成年人"));
    }

    @Test
    public void testGetUsers() throws Exception {
        mockMvc.perform(MockMvcRequestBuilders.get("/user/users"))
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andExpect(MockMvcResultMatchers.content().json("[{\"name\":\"Bob\",\"age\":20,\"password\":\"123456\"},{\"name\":\"Tom\",\"age\":22,\"password\":\"654321\"}]"));
    }

    @Test
    public void testUpdateUser() throws Exception {
        mockMvc.perform(MockMvcRequestBuilders.put("/user/profile")
                .param("name", "new")
                .param("age", "30")
                .param("password", "555555"))
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andExpect(MockMvcResultMatchers.content().json("{\"name\":\"new\",\"age\":30,\"password\":\"555555\"}"));
    }

    @Test
    public void testDelete() throws Exception {
        mockMvc.perform(MockMvcRequestBuilders.delete("/user/user"))
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andExpect(MockMvcResultMatchers.content().string(""));
    }

运行，全部通过

3.2.2 IDEA REST Client

IDEA自带API测试工具，打开Tools->Test RESTful Web Service:

REST Client.png

分别输入HTTP method，Host/port，Path，若有请求参数，在Request的Request Parameters中添加参数，完成之后，点左边绿色第一个播放按钮，即可运行。
运行之后，可在Response中查看返回数据，在Response Headers中第一行查看状态码。

四、最后

本文先介绍了RESTful API的一些基本概念，后又在Spring Boot中实例演示。本次代码为了演示需要，在UserController中有很多重复代码，并且代码耦合严重，这些问题将会随着本系列文章的推出而逐步消除。

本文代码已上传至我的GitHub仓库，进入以后将branches切换为4-RESTful即可看见。

前篇：
Spring Boot实际应用讲解（一）：Hello World
Spring Boot实际应用讲解（二）：配置详解
 Spring Boot实际应用讲解（三）：表单验证

后续将推出以下文章，敬请关注！

Spring Boot实际应用讲解（五）：AOP之请求日志
 Spring Boot实际应用讲解（六）：MySQL + Spring-data-jpa(Hibernate)
Spring Boot实际应用讲解（七）：统一异常处理
Spring Boot实际应用讲解（八）：MySQL + Mybatis
Spring Boot实际应用讲解（九）：MySQL + Mybatis + Redis

文中若有错之处，还请各位批评指正，谢谢！

原文作者/ZYRzyr
原文链接:http://www.jianshu.com/p/e907595e9d1d

请进入这里获取授权：https://101709080007647.bqy.mobi

Spring Boot实际应用讲解（四）：RESTful API

一、RESTful API通俗解释

1.1 资源的定义

1.2 使用合适的动词

1.3 使用标准的HTTP状态码

1.4 适当的表示

二、为什么选择它

2.1 统一的接口

2.2 对代码质量的追求

三、实例

3.1 UserController

3.2 测试

3.2.1 单元测试

3.2.2 IDEA REST Client

四、最后

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

Spring-Boot

java进阶干货

Spring Boot