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

文/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": "密码错误"
}

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

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

三、实例

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);
    }
  1. 在UserController的类名上除了@RestController，还有一个@RequestMapping("/user")，表示URL是localhost:8080/user；
  2. @GetMapping，@PostMapping，@PutMapping，@DeleteMapping：对应的该方法的访问方式分别是GET、POST、PUT、DELETE，其括号中的值接在上一点的后面，如：localhost:8080/user/users；
  3. 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

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 212,029评论 6赞 492
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 90,395评论 3赞 385
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 157,570评论 0赞 348
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 56,535评论 1赞 284
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 65,650评论 6赞 386
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 49,850评论 1赞 290
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 39,006评论 3赞 408
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 37,747评论 0赞 268
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 44,207评论 1赞 303
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,536评论 2赞 327
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,683评论 1赞 341
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 34,342评论 4赞 330
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 39,964评论 3赞 315
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,772评论 0赞 21
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,004评论 1赞 266
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 46,401评论 2赞 360
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 43,566评论 2赞 349