bigsai

bigsai

关注
发信
关注(28)粉丝(399)

一文搞懂RESTful API

RESTful接口实战

前言

在学习RESTful 风格接口之前，即使你不知道它是什么，但你肯定会好奇它能解决什么问题？有什么应用场景？听完下面描述我想你就会明白：

在互联网并没有完全流行的初期，移动端也没有那么盛行，页面请求和并发量也不高，那时候人们对接口的要求没那么高，一些动态页面(jsp)就能满足绝大多数的使用需求。

一文搞懂RESTful API-LMLPHP

但是随着互联网和移动设备的发展，人们对Web应用的使用需求也增加，传统的动态页面由于低效率而渐渐被HTML+JavaScript(Ajax)的前后端分离所取代，并且安卓、IOS、小程序等形式客户端层出不穷，客户端的种类出现多元化，定位到资源才能去访问，而通常一个完整的URL组成由以下几个部分构成：

URI = scheme "://" host  ":"  port "/" path [ "?" query ][ "#" fragment ]

scheme: 指底层用的协议，如http、https、ftp
host: 服务器的IP地址或者域名
port: 端口，http默认为80端口
path: 访问资源的路径，就是各种web 框架中定义的route路由
query: 查询字符串，为发送给服务器的参数，在这里更多发送数据分页、排序等参数。
fragment: 锚点，定位到页面的资源

我们在设计API时URL的path是需要认真考虑的，而RESTful对path的设计做了一些规范，通常一个RESTful API的path组成如下：

/{version}/{resources}/{resource_id}

version：API版本号，有些版本号放置在头信息中也可以，通过控制版本号有利于应用迭代。
resources：资源，RESTful API推荐用小写英文单词的复数形式。
resource_id：资源的id，访问或操作该资源。

当然，有时候可能资源级别较大，其下还可细分很多子资源也可以灵活设计URL的path，例如：

/{version}/{resources}/{resource_id}/{subresources}/{subresource_id}

此外，有时可能增删改查无法满足业务要求，可以在URL末尾加上action，例如

/{version}/{resources}/{resource_id}/action

其中action就是对资源的操作。

从大体样式了解URL路径组成之后，对于RESTful API的URL具体设计的规范如下：

  1. 不用大写字母，所有单词使用英文且小写。
  2. 连字符用中杠"-"而不用下杠"_"
  3. 正确使用 "/" 表示层级关系,URL的层级不要过深，并且越靠前的层级应该相对越稳定
  4. 结尾不要包含正斜杠分隔符"/"
  5. URL中不出现动词，用请求方式表示动作
  6. 资源表示用复数不要用单数
  7. 不要使用文件扩展名

HTTP动词

在RESTful API中，不同的HTTP请求方法有各自的含义，这里就展示GET,POST,PUT,DELETE几种请求API的设计与含义分析。针对不同操作，具体的含义如下：

GET /collection：从服务器查询资源的列表（数组）
GET /collection/resource：从服务器查询单个资源
POST /collection：在服务器创建新的资源
PUT /collection/resource：更新服务器资源
DELETE /collection/resource：从服务器删除资源

在非RESTful风格的API中，我们通常使用GET请求和POST请求完成增删改查以及其他操作，查询和删除一般使用GET方式请求，更新和插入一般使用POST请求。从请求方式上无法知道API具体是干嘛的，所有在URL上都会有操作的动词来表示API进行的动作，例如：query，add，update，delete等等。

而RESTful风格的API则要求在URL上都以名词的方式出现，从几种请求方式上就可以看出想要进行的操作，这点与非RESTful风格的API形成鲜明对比。

在谈及GET,POST,PUT,DELETE的时候，就必须提一下接口的安全性和幂等性，其中安全性是指方法不会修改资源状态，即读的为安全的，写的操作为非安全的。而幂等性的意思是操作一次和操作多次的最终效果相同，客户端重复调用也只返回同一个结果。

上述四个HTTP请求方法的安全性和幂等性如下：

状态码和返回数据

服务端处理完成后客户端也可能不知道具体成功了还是失败了，服务器响应时，包含状态码和返回数据两个部分。

状态码

我们首先要正确使用各类状态码来表示该请求的处理执行结果。状态码主要分为五大类：

每一大类有若干小类，状态码的种类比较多，而主要常用状态码罗列在下面：

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

返回结果

针对不同操作，服务器向用户返回数据，而各个团队或公司封装的返回实体类也不同，但都返回JSON格式数据给客户端。

第三关 一个RESTful API案例

上面讲了RESTful理论知识，下面动手实现一个小案例吧！

预备

在本案例的实战中，我们访问的RESTful接口都是对数据库真实的操作，新建数据库，创建一个数据库和表(根据自己喜好)。

选择Maven依赖的时候，只需要勾选其中Spring的Web模块、MySQL驱动以及MyBatis框架。

本案例的POJO创建Dog.java实体对象，其具体构造为：

package com.restfuldemo.pojo;

public class Dog {
    private int id;//唯一id标识
    private String name;//名称
    private  int age;//年龄
    //省略get set
}

上面创建好了项目，我们就开始构建RESTful风格的API。在具体构建RESTful API的时候，需要对各种请求有更细致的认知，当然，本案例在实现各种请求的时候为了演示的便捷并没有完全遵循RESTful API规范，例如版本号等信息这里就不添加了，案例更侧重于使用SpringBoot实现这个接口。

本案例实现对dog资源的增删改查，如下是非RESTful 和RESTful接口对比：

另外在使用postman进行发送请求的时候，有三种常用的文件类型传递到后端：

一文搞懂RESTful API-LMLPHP
form-data ： 就是form表单中的multipart/form-data，会将表单数据处理为一条信息，用特定标签符将一条条信息分割开，而这个文件类型通常用来上传二进制文件。

x-www-form-urlencoded：就是application/x-www-form-urlencoded，是form表单默认的encType，form表单会将表单内的数据转换为键值对，这种格式不能上传文件。

raw：可以上传任意格式的文本，可以上传Text，JSON，XML等，但目前大部分还是上传JSON格式数据。当后端需要接收JSON格式数据处理的时候，可以采用这种格式来测试。

因为GET请求查询参数在URL上，其他类型请求使用x-www-form-urlencoded方式向后端传值。

GET POST PUT DELETE请求

GET请求用来获取资源：GET请求会向数据库发索取数据的请求，从而来获取资源，该请求就像数据库的select操作一样，只是用来查询数据，不会影响资源的内容。无论进行多少次操作，结果都是一样的。

并且GET请求会把请求的参数附加在URL后面，但是不同的浏览器对其有不同的大小长度限制。

在本案例中，我们设计两个GET请求的API。
GET /dogs ：用来返回dog资源的列表。
GET /dogs/{dogid} ：用来查询此id的单个dog资源。

POST请求用来新增一个资源 : POST请求向服务器发送数据，但是该请求会改变数据的内容(新添)，就像数据库的insert操作一样，会创建新的内容。且POST请求的请求参数都是请求体中，其大小是没有限制的。

在本案例中，我们设计以下POST请求的API。
POST /dogs ：服务端新增一个dog资源。

PUT请求用来更新资源，PUT请求是向服务器端发送数据的， 与POST请求不同的是，PUT请求侧重于数据的修改 ,就像数据库中update一样，而POST请求侧重于数据的增加。

在本案例中，我们设计以下POST请求的API。
PUT /dogs/{dogid} ：用来更新此id的单个dog资源。

DELETE 请求用来删除资源，DELETE请求用途和它字面意思一致，用来删除资源。和数据库中delete相对应。

在本案例中，我们设计以下DELETE请求的API。
DELETE /dogs/{dogid} ：用来删除此id的单个dog资源。

对应的Mapper文件为：

package com.restfuldemo.mapper;

import com.restfuldemo.pojo.Dog;
import org.apache.ibatis.annotations.*;
import java.util.List;

@Mapper
public interface DogMapper {

    @Select("select * from dog")
    List<Dog> getAllDog();

    @Select("select * from dog where id=#{id}")
    Dog getDogById(@Param("id") int id);

    @Insert("insert into dog (name,age) values (#{name},#{age})")
    boolean addDog(Dog dog);

    @Update("update dog set name=#{name},age=#{age} where id=#{id}")
    boolean updateDog(Dog dog);

    @Delete("delete  from dog where id=#{id}")
    boolean deleteDogById(int id);
}

对应controller文件为：

package com.restfuldemo.controller;

import com.restfuldemo.mapper.DogMapper;
import com.restfuldemo.pojo.Dog;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.Arrays;
import java.util.List;

@RestController
public class TestController {

    @Autowired(required = false)
    DogMapper dogMapper;

    @GetMapping("dogs")
    public List<Dog> getDogs()
    {
        return  dogMapper.getAllDog();
    }

    @GetMapping("dogs/{id}")
    public Dog getDogById(@PathVariable("id") int id)
    {
        Dog dog=dogMapper.getDogById(id);
        return  dog;
    }
    @PostMapping("dogs")
    public boolean addDog(Dog dog)
    {
        return dogMapper.addDog(dog);
    }
    @PutMapping("dogs/{id}")
    public boolean updateDog(@PathVariable("id")int id,@RequestParam("name")String name,@RequestParam("age")int age)
    {

        Dog dog=dogMapper.getDogById(id);
        dog.setName(name);
        dog.setAge(age);
        return  dogMapper.updateDog(dog);
    }

    @DeleteMapping("dogs/{id}")
    public boolean deleteDog(@PathVariable("id") int id)
    {
        return  dogMapper.deleteDogById(id);
    }
}

经过笔者测试一切都是ok的，如果要项目源文件请联系笔者发你哈！

总结

RESTful风格的API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为REST是一种风格，而不是一种约束或规则，过于理想的RESTful API 会付出太多的成本。

比如RESTful API也有一些缺点

  • 比如操作方式繁琐，RESTful API通常根据GET、POST、PUT、DELETE 来区分操作资源的动作，而HTTP Method 本身不可直接见，是隐藏的，而如果将动作放到URL的path上反而清晰可见，更利于团队的理解和交流。
  • 并且有些浏览器对GET,POST之外的请求支持不太友好，还需要特殊额外的处理。
  • 过分强调资源，而实际业务API可能有各种需求比较复杂，单单使用资源的增删改查可能并不能有效满足使用需求，强行使用RESTful风格API只会增加开发难度和成本。

所以，当你或你们的技术团队在设计API的时候，如果使用场景和REST风格很匹配，那么你们可以采用RESTful 风格API。但是如果业务需求和RESTful风格API不太匹配或者很麻烦，那也可以不用RESTful风格API或者可以借鉴一下，毕竟无论那种风格的API都是为了方便团队开发、协商以及管理，不能墨守成规。
一文搞懂RESTful API-LMLPHP
到这里RESTful API的介绍和实战就结束啦，本篇首先从RESTful的一些特点进行介绍，再到SpringBoot实战RESTful API，最后也说了一些RESTful API并不完美的地方，相信睿智的你对RESTful 一定有了很深刻的理解。在以后项目的API设计上定能有所优化。

不同的人对RESTful API可能有着不同的理解，但存在即合理，RESTful API有着其鲜明的优势和特点，目前也是一种API设计的主要选型之一，所以掌握和理解RESTful API还是相当重要的!
一文搞懂RESTful API-LMLPHP

原创不易，bigsai我请你帮两件事帮忙一下:

  1. 点赞支持一下， 您的肯定是我在园子创作的源源动力。

  2. 微信搜索「bigsai」，关注我的公众号(新人求支持)，不仅免费送你电子书，我还会第一时间在公众号分享知识技术。加我还可拉你进力扣打卡群一起打卡LeetCode。

记得关注、咱们下次再见！

一文搞懂RESTful API-LMLPHP

12-08 06:07
Powered by LMLPHP ©2024 bigsai 0.074433