• 阅读笔记整理:RestFul && Swagger编程规范


    RestFul && Swagger编程规范

    先前扫地生对RestFule编程规范只要零散的了解,最近在项目中发现,自己编写的接口在对接的过程中显得是那么的独树一帜。为了找了时间规范整理了一下有关RestFule的编程规范。发现以下几篇文章写的挺好,就将它们整合在今日的阅读笔记中。

    1、web服务交互

    我们在浏览器中能看到的每个网站,都是一个web服务。那么我们在提供每个web服务的时候,都需要前后端交互,前后端交互就一定有一些实现方案,我们通常叫web服务交互方案。

    目前主流的三种web服务交互方案:

    • REST ( Representational State Transfer)表述性状态转移

    • SOAP (Simple Object Access Protocol) 简单的对象访问协议

    • XML-RPC (XML Remote Procedure Call)基于XML的远程过程调用

    XML-RPC是通过XML将调用函数封装,并使用HTTP协议作为传送机制。后来在新的功能不断被引入下,这个标准慢慢演变成为今日的SOAP协定。

    SOAP服务则是以本身所定义的操作集,来访问网络上的资源。SOAP也是基于XML的,但是它不只限于HTTP协议的传输,包括TCP协议,UDP协议都可以传输。

    REST是Roy Thomas Fielding博士于2000年在他的博士论文里提出来的。REST相比SOAP更加简洁,性能和开发效率也有突出的优势。

    以下主要说一下这个REST,现在越来越多的web服务开始采用REST风格设计和实现。

    例如,amazon.com提供接近REST风格的Web服务进行图书查找;雅虎提供的Web服务也是REST风格的。

    那么我们来看下它到底是个什么样的风格,了解了它是什么后,我们看下它的优点是什么,我们为什么用它。

    2、理解REST

    如果我们想要理解restful,就要理解Representational State Transfer这个词组的意思,表征性状态转移。这里所说的表征性,其实指的就是资源。通常我们称为资源状态转移。

    2.1 什么是资源

    任何事物,只要有被引用到的必要,它就是一个资源。我们在浏览器中看到的文本,视频,图片等等都是资源。这些都是实实在在存在的实体。资源可以是一个实体,也可以是抽象概念。

    比如说:

    • xxx的个人信息

    • xxx的手机号

    img

    • xxx跟qqq的潜在关系

    这些都是资源,可以是实体比如个人信息,手机号。也可以是抽象的概念,比如两个人的关系......那么在我们的网络中,我们要引用资源,资源一定要有一个标识,在web中的唯一标识就是URI,URI我们不常听说,我们经常用URL,那么两者区别是什么呢~

    2.2 什么是URI,URL

    URI 统一资源标志符。URL 统一资源定位符。URI是给我们的资源进行标识的,URL是描述我们资源地址的。

    比如说我们每个人都有名字和身份证,名字可能重名,但是身份证是唯一的,那么身份证号就可以是我们的URI,标识我们每个人,也可以说标识我们每个资源。我们可以通过身份证号找到xxx,也可以通过下面这种方式找到他.....

      xxx的住址协议://地球/中国/屌丝省/屌丝市/寡妇村/250号街道/250号/xxx

    这个就是我们的URL,我们通过这两种方式都可以找到我们的资源,其实我们的URL可以说是URI的子集,通过定位的方式实现的URI。这是我们资源的定位有了资源的地址后,我们要去访问资源,那么我们要通过什么方式去访问呢

    2.3 统一资源接口

    现在我们可以通过URL去访问到资源,那么我们对资源会有很多不同的操作,增删改查,以前我们可能会为了这个增加新设计一个URL,然后这个URL就是对数据进行增加的,还会为了更新和删除分别设计一个URL,现在我们不用了,我们只有一个URL,然后根据HTTP请求方式的不同,对资源进行不同的操作,这个就是是统一资源接口。我们一定要遵循HTTP请求方法的语义,也就是说POST请求就在新增数据等....

    2.4 资源的表述

    资源的表述其实就是资源的展现形式,我们客户端和服务端传输的都是资源的表述,而不是资源本身。例如文本资源可以采用html、xml、json等格式,图片可以使用PNG或JPG展现出来。

    那么客户端如何知道服务端提供哪种表述形式呢?可以通过HTTP内容协商,客户端可以通过Accept头请求一种特定格式的表述,服务端则通过Content-Type告诉客户端资源的表述形式。这些资源的表述呈现在页面上,就是我们说的资源状态。

    2.5 状态转移

    我们在看页面的时候,从当前资源的表述(也可以说状态或者表现层)会跳转到其他的资源状态。服务端通过超媒体告诉客户端当前状态有哪些后续状态可以进入。这些类似"下一页"之类的链接起的就是这种推进状态的作用——指引你如何从当前状态进入下一个可能的状态。

    2.6 总结

    可以得知REST风格的特点如下:

    • 在web中,只要有被引用的必要都叫资源。
    • 每个URI代表一个资源,独一无二的。
    • 客户端通过HTTP的方法,对服务器端资源进行操作;
    • 客户端和服务器之间,传递这种资源的某种表现层;
    • 通过超链接的指引,实现"表现层状态转移"。

    3、restful规范

    如果一个架构符合REST的约束条件和原则,我们就称它为RESTful架构。

    一种软件的架构风格,设计风格, 为客户端和服务端的交互提供一组设计原则和约束条件。

    3.1 面向资源编程

    每个URL代表一种资源,URL中尽量不要用动词,要用名词。针对不同的操作,服务器向用户返回的结果应该符合以下规范:

    GET/collection:返回资源对象的列表(数组)

    GET/collection/resource:返回单个资源对象

    POST/collection:返回新生成的资源对象

    PUT/collection/resource:返回完成的资源对象

    PATCH/collection/resource:返回完整的资源对象

    DELETE/collection/resource:返回一个空文档

    3.2 根据method不同,进行不同的操作

    方式 描述
    GET(select) 从服务器取出一个/多个资源
    POST(create) 在服务器新建一个资源
    PATCH(update) 在服务器更新资源(客户端提供改变的属性)
    PUT(update) 在服务器更新资源(客户端提供改变后的完整资源)
    DELETE(delete) 从客户端删除资源

    3.3 在URL中体现版本

    https://www.bootcss.com/v1/mycss

    https://v1.bootcss.com/mycss

    3.4 在URL中体现是否是API

    https://www.bootcss.com/api/mycss

    https://api.bootcss.com/mycss

    3.5 在URL中的过滤条件

    如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果,以下是一些常用的参数:

    https://api.example.com/v1/zoos?limit=10 :指定返回记录的数据量

    https://api.example.com/v1/zoos?offset=10 :指定返回记录的开始位置

    https://api.example.com/v1/zoos?page=2&per_page=100 :指定第几页以及每页的记录数

    https://api.example.com/v1/zoos?sortby=name&order=asc :指定返回结果按照哪个属性排序,以及排序顺序

    https://api.example.com/v1/zoos?animal_type_id=10 :指定筛选条件

    参数的设计允许存在冗余,即允许API路径和URL参数偶尔重复。比如GET/zoo/ID/animals与GET/animals?zoo_id=ID的含义是相同的

    3.6 尽量使用HTTPS

     https://www.bootcss.com/v1/mycss

    3.7 响应时设置状态码

    1** 信息,服务器收到请求,需要请求者继续执行操作

    2** 成功,操作被成功接收并处理

    • 200 OK -[GET]:服务器成功返回用户请求的数据,该操作是幂等的(idempotent)
    • 201 CREATED -[POST/PUT/PATCH]:用户新建或修改数据成功
    • 202 Accepted -[*]:表示一个请求已经进入后台排序(异步任务)
    • 204 NO CONTENT -[DELETE]:用户删除数据成功
    • ...

    3** 重定向,需要进一步的操作以完成请求

    • ...

    4** 客户端错误,请求包含语法错误或无法完成请求

    • 401 INVALID REQUEST -[POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的
    • 403 Unauthorized -[*]:表示用户没有权限(令牌,用户名或密码错误)
    • 404 NOT FOUND -[*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的
    • 406 Not Acceptable -[GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)
    • 410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的
    • 422 Unprocesable entity -[POST/PUT/PATCH]:当创建一个对象时,发生一个验证错误
    • ...

    5** 服务器错误,服务器在处理请求的过程中发生了错误

    • 500 INTERNAL SERVER ERROR -[*]:服务器发生错误,用户无法判断发出的请求是否成功
    • ...

    3.8 返回值

    GET请求 返回查到所有或单条数据

    POST请求 返回新增的数据

    PUT请求 返回更新数据

    PATCH请求 局部更新 返回更新整条数据

    DELETE请求 返回值为空

    3.9 返回错误信息

    返回值携带错误信息

    3.10 Hypermedia API

    如果遇到需要跳转的情况 携带调转接口的URL

    ret = {
     code: 1000,
     data:{
     	id:1,
     	name:'saodisheng',
     	depart_id:http://www.xxxxx.com/api/v1/depart/8/
      }
     }
    

      

    4、swagger规范

    主要的Swagger工具有:

    • swagger编辑器:基于浏览器的编辑器,便于构建和使用rest api
    • swagger UI:让OpenAPI规范以交互式API文档呈现
    • swagger Codegen:让OpenAPI规范生成服务器静态文件(stubs)和客户端库

    4.1 常用注解

    注解 对象范围 使用位置 详细参数 例子
    @Api 协议集描述 controller类上 value:URL路径值,description:对api资源的详细描述 @Api(value = "User-API", descroption = "这是用户接口详细信息的描述")
    @ApiOperation 协议描述 controller方法上 value:接口操作简介,notes:接口描述 @ApiOperation(value = "获取用户列表", notes = "根据url来获取用户详细信息,返回List类型的JSON用户信息")
    @ApiResponses response集 controller方法上
    @ApiResponse response @ApiResponses里面用于表示一组响应,一般用于表达错误的响应信息;
    @ApiParam 参数描述 在Rest接口上、Rest接口参数前面
    @ApiImplicitParams 非对象参数集 controller方法上
    @ApiImplicitParam 非对象参数,对容器的描述 @ApiImplicitParams方法里面 name:属性名称,value:属性介绍,required:是否属性必填,dataType:数据类型,paramType:参数类型 @ApiImplicitParam(name = "user", value = "用户详细实体User", required = true, dataType = "User")
    @ApiModel 描述返回对象的意义 出入对象上 value:实体类的描述
    @ApiModelProperty 对象属性 出入对象的字段上 value:字段介绍,required:属性是否必填

    注:@ApiImplicitParam比@ApiParam使用范围更广,非JAX-RS场合,只能使用@ApiImplicitParam。

    5、阅读文章

    文章1

    文章2

    文章3

    文章4

    持续更新中...

    向大神看齐
  • 相关阅读:
    sync 解释
    USB枚举详细过程剖析(转)
    内核早期内存分配器:memblock
    LTE:eMBMS架构
    对linux内核中jiffies+Hz表示一秒钟的理解
    android的USB MTP && USB CDC/USBnet(ECM, NCM, ACM) && USB gardget
    Install Shield中调用devcon自动安装硬件驱动程序
    利用 devcon.exe实现自动安装驱动(转)
    linux系统IO调度算法
    ZooKeeper原理详解及常用操作
  • 原文地址:https://www.cnblogs.com/Liu-xing-wu/p/15039467.html
Copyright © 2020-2023  润新知