美文网首页网络相关
restful-API设计规范

restful-API设计规范

作者: 哥斯拉啊啊啊哦 | 来源:发表于2019-08-14 08:52 被阅读0次

    RESTful是一种软件架构风格、设计风格,而不是标准,只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制,也便于调用者理解接口的作用

    REST 系统的5个特征

    客户-服务器(Client-Server),提供服务的服务器和使用服务的客户需要被隔离对待。

    无状态(Stateless),来自客户的每一个请求必须包含服务器处理该请求所需的所有信息。换句话说,服务器端不能存储来自某个客户的某个请求中的信息,并在该客户的其他请求中使用。

    可缓存(Cachable),服务器必须让客户知道请求是否可以被缓存。(Ross:更详细解释请参考 理解本真的REST架构风格 以及 StackOverflow 的这个问题 中对缓存的解释。)

    分层系统(Layered System),服务器和客户之间的通信必须被这样标准化:允许服务器和客户之间的中间层(Ross:代理,网关等)可以代替服务器对客户的请求进行回应,而且这些对客户来说不需要特别支持。

    统一接口(Uniform Interface),客户和服务器之间通信的方法必须是统一化的。(Ross:GET,POST,PUT.DELETE, etc)

    支持按需代码(Code-On-Demand,可选),服务器可以提供一些代码或者脚本(Ross:Javascrpt,flash,etc)并在客户的运行环境中执行。这条准则是这些准则中唯一不必必须满足的一条。(Ross:比如客户可以在客户端下载脚本生成密码访问服务器。)

    详细解释

    无状态(Stateless)

       所谓无状态的,即所有的资源,都可以通过URI定位,而且这个定位与其他资源无关,也不会因为其他资源的变化而改变。有状态和无状态的区别,举个简单的例子说明一下。如查询员工的工资,如果查询工资是需要登录系统,进入查询工资的页面,执行相关操作后,获取工资的多少,则这种情况是有状态的,因为查询工资的每一步操作都依赖于前一步操作,只要前置操作不成功,后续操作就无法执行;如果输入一个url即可得到指定员工的工资,则这种情况是无状态的,因为获取工资不依赖于其他资源或状态,且这种情况下,员工工资是一个资源,由一个url与之对应,可以通过HTTP中的GET方法得到资源,这是典型的RESTful风格。

    统一接口(Uniform Interface)

      RESTful架构风格规定,数据的元操作,即CRUD(create, read, update和delete,即数据的增删查改)操作,分别对应于HTTP方法:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源,这样就统一了数据操作的接口,仅通过HTTP方法,就可以完成对数据的所有增删查改工作

    GET(SELECT):从服务器取出资源(一项或多项)。

    POST(CREATE):在服务器新建一个资源。

    PUT(UPDATE):在服务器更新资源(客户端提供完整资源数据)。

    DELETE(DELETE):从服务器删除资源。

    URI 的设计只要负责把资源通过合理方式暴露出来就可以了。对资源的操作与它无关,操作是通过 HTTP动词来体现,所以REST 通过 URI 暴露资源时,会强调不要在 URI 中出现动词

    左边是错误示范,右边是正确示范

    GET /rest/api/getDogs --> GET /rest/api/dogs 获取所有小狗狗

    GET /rest/api/addDogs --> POST /rest/api/dogs 添加一个小狗狗

    GET /rest/api/editDogs/:dog_id --> PUT /rest/api/dogs/:dog_id 修改一个小狗狗

    GET /rest/api/deleteDogs/:dog_id --> DELETE /rest/api/dogs/:dog_id 删除一个小狗狗

    HTTPCode返回码,要符合规范,比如200表示成功,404表示找不到资源等等,不要用404表示成功,不要这样的乱用,要符合HTTP规范

    分层系统

    另一个重要的 REST 原则是分层系统,这表示组件无法了解它与之交互的中间层以外的组件。通过将系统知识限制在单个层,可以限制整个系统的复杂性,促进了底层的独立性。

    如request,db调用,response,均分层,只对外暴露接口,这样后期在增减功能都更方便。如果都集合在一起,后期在增减功能会很复杂

    相关文章

      网友评论

        本文标题:restful-API设计规范

        本文链接:https://www.haomeiwen.com/subject/ysswjctx.html