首页 » 漏洞 » RESTful:RESTful API 设计的理解

RESTful:RESTful API 设计的理解

 
文章目录

前言

最近依旧在忙公司 KM 的项目,我负责的是部分核心模块的开发,已经实现了Servcie - DAO 层的开发,紧接开始着手实现 Controller 层,因为是基于 RESTful,所以必须定义好 RESTful API 的接口,才能进行功能的实现。

因为对 RESTful 理解的比较少,所以参考了GitHub的设计开发原则,以下的内容是我根据对 RESTful 的理解,针对公司项目设计接口。

项目-部分核心模块-部分功能

  • Disk : 网盘

    • 网盘列表

  • Folder : 目录 (即网盘下的文件夹)

    • 目录列表

    • 目录重命名

    • 目录移动

    • 目录批量移动

    • 目录下载

    • 目录批量下载

  • File :文件(只能存在于目录下,不能存在网盘下)

    • 文件列表(展示该目录下的子目录和文件)

    • 文件收藏

    • 文件分享

    • 文件批量下载

跟着 Github 学习 Restful

  • RESTful 的关键

    • RESTful 定义可表示流程元素/资源的对象。在 REST 中,每一个对象都是通过URL来表示的,对象用户负责将状态信息打包进每一条消息内,以便对象的处理总是无状态的

    • 资源分为单个文档和集合,尽量使用复数来表示资源,单个资源通过添加 id 或者 name 等来表示

    • 一个资源可以有多个不同的 URL

    • 资源可以嵌套,通过类似目录路径的方式来表示,以体现它们之间的关系

    • 注意:根据RFC3986定义,URL是大小写敏感的。所以为了避免歧义,尽量使用小写字母

  • Method

    • 举例:GitHub上对仓库的增删查改

      GET /repos/:owner/:repo/issues GET /repos/:owner/:repo/issues/:number POST /repos/:owner/:repo/issues PATCH /repos/:owner/:repo/issues/:number DELETE /repos/:owner/:repo
Method 描述
GET 获取资源
POST 创建资源,会返回创建的资源
PATCH 更新资源的部分属性。因为 PATCH 比较新,而且规范比较复杂,所以真正实现的比较少,一般都是用 POST 替代,会返回更新的资源
PUT 替换资源,客户端需要提供新建资源的所有属性。如果新内容为空,要设置 Content-Length 为 0,以区别错误信息,会返回更新的资源
DELETE 删除资源
  • 把动作转换为资源

    在设计的过程中,会发现,除了 CRUD 这四种操作,我们还会遇到其他的操作,这样就给我们在 API 的设计带来很大的麻烦,然而,RESTful 是一种设计风格而不是标准,只是提供了一组设计原则和约束条件,所以我们可以对接口进行灵活的设计,从而满足我们的业务需求。最常规的做法是为需要的动作增加一个 endpoint,选择一个 Method 来执行动作,比如 POST /email/:emailId/resend 重新发送邮件

    • 举例:GitHub上对仓库的加星操作

    PUT /gists/:id/star  DELETE /gists/:id/star
  • Query 实现更自由的查询

    在对接口进行操作的时候,除了一些必要的参数,有时候需要一些非必要的参数进行条件控制,是用 query 参数进行控制,避免了在接口设计的硬性规定,实现更大的自由度。

    举例: 查询某个 repo 下面 issues 的时候,可以通过以下参数来控制返回哪些结果:

    • state:issue 的状态,可以是 open,closed,all

    • since:在指定时间点之后更新过的才会返回

    • assignee:被 assign 给某个 user 的 issues

    • sort:选择排序的值,可以是 created、updated、comments

    • direction:排序的方向,升序(asc)还是降序(desc)

    • per_page:每页返回多少资源,如果没提供会使用预设的默认值

    • page:要获取哪一页的资源,默认是第一页

  • 批量操作实现

    • 设计方法有很多种,借用Backbone.js 的说法:There's More Than One Way To Do It,不要太纠结

    • 举例:多种设计方案

      //简约的设计   GET /ec2/instance/batch?id=aa,bb,cc:   //健壮的设计   GET /ec2/instance?batch={"ids":["aa","bb","cc"]}:   //   GET /ec2/instance?batch=[{"method":"DELETE","id":"aa"},{"method":"DELETE","id":"bb"},{"method":"DELETE","id":"cc"}]:

功能的RESTful API 设计

  • Disk : 网盘

    • 网盘列表 :/disks

  • Folder : 目录 (即网盘下的文件夹)

    • 目录列表 :GET: /disks/:diskId/folders

    • 目录重命名 :PATCH:/disks/:diskId/folders/:folderId/rename/:name

    • 目录移动 :PATCH:disks/:diskId/folders/:folderId/moveto/folderId/:folderId

    • 目录下载 :GET:disks/:diskId/folders/:foderId/download

  • File :文件(只能存在于目录下,不能存在网盘下)

    • 文件列表 :GET:disks/:diskId/folders/:folders/files

    • 文件收藏 :PATCH:disks/:diskId/folders/:folderId/files/:fileId/collect

    • 文件分享 :PATCH:disks/:diskId/folders/:folderId/files/:fileId/share

  • 批量操作:

    • 多个fileObj移动:PATCH:disks/:diskId/fileobjs/moveto/folderId/:folderId?请求包体

    • 多个fileObj删除:DELETE:disks/:diskId/fileobjs?请求包体

    • 多个fileObj下载:GET:disks/:diskId/fileobjs/download?请求包体

      • 请求包体:

    请求包体:"fileObjects": [         {             "fileObjectId": fileId,             "isFolder": true / false         }     ]

    以上的设计其实还没得到上级的通过,其实还需要继续改进,不过这一轮的设计让我对 RESTful 的使用有了一定的了解,虽然还没深入研究 RESTful 核心的部分,但是,通过 URL 操作资源这种设计思路,的确是让人眼前一亮。

原文链接:RESTful:RESTful API 设计的理解,转载请注明来源!

0