RESTful的正确姿势

最新推荐文章于 2021-10-09 16:04:52 发布
最新推荐文章于 2021-10-09 16:04:52 发布
阅读量3.1k 收藏 3
点赞数 2
分类专栏： 心得 文章标签： rest restful java 接口 http
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/boroborome/article/details/104449640
版权

RESTfull定义

很多人都有这样的疑问：

  • 什么是RESTful API/RESTful接口？
  • RESTful接口规范是什么样子的？

下面是摘抄自百度百科词条RESTful。

REST（英文：Representational State Transfer，简称REST）描述了一个架构样式的网络系统，比如 web 应用程序。它首次出现在 2000 年 Roy Fielding 的博士论文中，Roy Fielding是 HTTP 规范的主要编写者之一。在目前主流的三种Web服务交互方案中，REST相比于SOAP（Simple Object Access protocol，简单对象访问协议）以及XML-RPC更加简单明了，无论是对URL的处理还是对Payload的编码，REST都倾向于用更加简单轻量的方法设计和实现。值得注意的是REST并没有一个明确的标准，而更像是一种设计的风格。

REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。

RESTFUL特点包括：
1、每一个URI代表1种资源；
2、客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；
3、通过操作资源的表现形式来操作资源；
4、资源的表现形式是XML或者HTML；
5、客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。

RESTful标准用法实践

这里以一个物流系统为例定义一组接口，这里需要完成的功能如下

  • 维护物流运单。用户需要对物流运单进行增删改查操作。每个运单上都有单号，承运商，运输方式等信息。
  • 维护发票信息。用户需要管理发票，每个发票都有重量，金额和相关物流运单号。
  • 统计不同运输方式、承运商在给定时间的费用信息。

通过需求可以清晰的看到两个资源，物流运单和发票，分别定义为delivery和invoice，根据REST风格的特点，定义如下接口

  • 创建物流运单

    REST建议使用POST创建资源

    创建物流运单接口
URL:[POST]/delivery
Request: {
	"doNum": "12345678",
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}
Response: {
	"doNum": "12345678",
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}

错误码：

  • 200: 正常创建

    • 409:单号冲突了
    • 422:参数不正确。仅靠错误码那难以给出更为准确的提示，类似：运输方式kongyun错误，有效运输方式为[Air,Sea,Truck]。

  • 查询物流运单

    REST建议使用GET来获取资源。

    查询所有：
URL:[GET]/delivery
Response: [ {运单信息}, {运单信息} ]

根据ID查询
URL:[GET]/delivery/{delivery-id}
Response: {运单信息}

多条件查询
URL:[GET]/delivery/?mot={运输方式}&carrier={承运商}...
Response: [ {运单信息}, {运单信息} ]

    错误码：

    • 200: 正常查询
    • 404: 查询的资源不存在
    • 422: 查询参数不正确

    在实际应用中，这个查询被挑战的最多

    • 参数太多难以传递

      GET传递参数的常规方式就是URL参数，但URL长度是受限的，难以完成类似一次查询1万单号这种需求。

    • 复杂参数难以传递

      GET传递参数的常规方式就是URL参数，但是URL上的参数只能传递结构简单的数据，难以处理对象数组参数，类似[{“carrier”=“c1”, “mot”=“Sea”}, {“carrier”=“c2”, “mot”=“Air”}]这种复杂参数需要特殊处理。对于把文件当做过滤条件的就更处理不了了。

    • 工作量多

      后台在处理复杂查询请求时，一般都会有一个表示请求条件的结构，通过URL参数构造这个结构需要额外工作量，前台在发送请求时，将所有参数拼接到URL中也需要工作量，还面临着各种编码问题。

  • 修改物流运单

    REST建议使用PUT来获取资源。

    修改物流运单接口
URL:[PUT]/delivery/{delivery-id}
Request: {
	"doNum": "12345678",
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}
Response: {
	"doNum": "12345678",
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}

    错误码：

    • 200: 正常修改
    • 422: 参数错误。和创建一样无法报告更为准确的错误。

    在实际应用中，这个修改操作还面临着批量修改和部分修改的挑战

    • 批量修改

      用户希望修改满足条件的所有运单的某些属性为固定值。这个需求很常见，但是REST没说怎么办，当前基本上是开发人员在自由发挥。

    • 部分修改

      复杂的业务数据经常涉及到部分修改功能。比如每抵达一站，都会有一个称重员对货物称重，记录称重结果，这个人不关系目的地一类的信息，他只是在这个运单上增加一个称重记录

  • 删除物流运单

    REST建议使用DELETE来获取资源。

    删除物流运单接口
URL:[DELETE]/delivery/{delivery-id}
Response: {
	"doNum": "12345678",
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}

    实际操作还有批量删除的场景

  • 批量上传物流运单

    REST没建议

  • 批量下载物流运单

    REST没建议

  • 发票管理接口。参照物流运输单来一套就好了。

  • 统计接口

    统计信息是发票和运单的综合数据，我们称他为分摊后发票，是每个发票在单个运单上的金额信息，记为delivery-invoice。在后台可以有一个组件在自动更新。虽然这个接口是一个查询接口，但是查询的内容不是原始数据，是统计数据，不知道应该叫什么URL了。

REST enhance

技术和规范都是服务于业务的，在业务需求的推动下，所有的技术和规范必须与时俱进。针对上面提到的问题，做做了一些调整。

基本规则

  • 不使用HTTP Code返回错误信息

    HTTP Code肩负着传输层的功能，让它兼职业务逻辑，其实很为难它。所有的业务返回信息，都放在Response中更为合理。所以定义了一个通用的返回结构

    {
  "error": [],		// 使用字符串返回所有严重的影响业务继续执行的错信息
  "warning": [],	// 使用字符串返回所有警告类业务信息
  "message": ...	// 根据业务需要返回需要的信息
}

  • 扩展URI指定的资源

    URI仍然用于定位资源，现在资源的范围扩展到原有资源的属性

    /delivery											// 表示运单资源
/delivery/123									// 表示某一个具体的运单资源
/delivery/123/weight-check		// 运单123相关的重量检测记录
/delivery/123/weight-check/1  // 运单123上id为1的重量检测记录
/delivery/mot									// 这个不是资源，不能这么写

  • 通过Head扩展不同的Command

    在原来的4个Method无法表达的情况下，通过Head中增加REST_Command来扩展功能

    REST_Command=BATCH_CREATE		// 表示批量创建请求
REST_Command=SEARCH       	// 表示当前操作是一个查询请求
REST_Command=SEARCH_SUMMARY	// 表示查询摘要信息，根据业务需要返回比较少的内容，类似只返回运单基本信息，没有重量检测信息
REST_Command=PART_UPDATE		// 部分修改。此时修改操作仅仅修改运单数据，不影响重量检测列表
REST_Command=BATCH_UPDATE		// 批量修改。
REST_Command=BATCH_DELETE		// 批量删除
REST_Command=GENERATE				// 对于没有持久化，而是实时计算出来的结果，使用这个命令

  • Request为业务参数

    业务参数必须和业务相关才是业务参数，类似用户登录信息，用于标记查询、修改一类的命名，都不是业务信息。

Demo

  • 创建物流运单

    • 创建运单

      URL:[POST]/delivery
Request: {
	"doNum": "12345678",
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}
Response: {
  "error": [],
  "warning": [],
  "message": {
	  "doNum": "12345678",
	  "carrier": "shunfeng",
	  "mot": "kongyun",
	  "weight": 234  
  }
}

    • 创建运单子对象

      URL:[POST]/delivery/{delivery-id}/weight-check
Request: {
	"id": 1,
	"time": "2020-02-02 02:02:02",
	"weight": 234
}
Response: {
  "error": [],
  "warning": [],
  "message": {
    "id": 1,
    "time": "2020-02-02 02:02:02",
    "weight": 234
  }
}

      子对象是必须已存与运单的信息，如果没有了运单，这个信息也没有了。运单的重量检测记录，属于子对象，但是分摊到运单的发票不是，没有运单，发票还在呀。

  • 批量创建

    创建物流运单接口
URL:[POST]/delivery
Head: REST_Command=BATCH_CREATE
Request: {	// 这个request可以根据需求做一些定制
	"doNum": ["12345678", "1234569"],
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}
Response: {
  "error": [],
  "warning": [],
  "message": [{
	  "doNum": "12345678",
	  "carrier": "shunfeng",
	  "mot": "kongyun",
	  "weight": 234  
  }, ...]
}

  • 查询物流运单

    • 查询所有

      URL:[GET]/delivery
Head: REST_Command=SEARCH;SEARCH_SUMMARY;		// 不同的命令返回数据不同
Response: {
  "error": [],
  "warning": [],
  "message": [{运单信息}, {运单信息}]
}

    • 根据ID查询单个

      URL:[GET]/delivery/{delivery-id}
Head: REST_Command=SEARCH;SEARCH_SUMMARY;		// 不同的命令返回数据不同
Response: {
  "error": [],
  "warning": [],
  "message": {
    "doNum": "12345678",
    "carrier": "shunfeng",
    "mot": "kongyun",
    "weight": 234,
    "weightCheck": [{
      "id": 1,
      "time": "2020-02-02 02:02:02",
      "weight": 234
      }
    ]
  }
}

    • 复杂条件查询

      URL:[POST]/delivery
Head: REST_Command=SEARCH;SEARCH_SUMMARY;		// 不同的命令返回数据不同
Request: {
	"mot": ["haiyun", "kongyun"],
	"carrier": ["承运商1", "承运商2"]
}
Response: {
  "error": [],
  "warning": [],
  "message": [{运单信息}, {运单信息}]
}

    • 查询子对象列表

      URL:[GET]/delivery/{delivery-id}/weight-check/{check-id}
Response: {
  "error": [],
  "warning": [],
  "message": [{重量检测信息}, {重量检测信息}]
}

  • 修改物流运单

    • 全量修改运单

      URL:[PUT]/delivery/{delivery-id}
Request: {
	"doNum": "12345678",
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}
Response: {
  "error": [],
  "warning": [],
  "message": {运单信息}
}

    • 部分修改运单

      URL:[PUT]/delivery/{delivery-id}
Head: REST_Command=PART_UPDATE
Request: {
	"doNum": "12345678",
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}
Response: {
  "error": [],
  "warning": [],
  "message": {运单信息}
}

    • 修改运单子对象

      URL:[PUT]/delivery/{delivery-id}/weight-check/1
Request: {
	"id": 1,
	"time": "2020-02-02 02:02:02",
	"weight": 234
}
Response: {
  "error": [],
  "warning": [],
  "message": {
    "id": 1,
    "time": "2020-02-02 02:02:02",
    "weight": 234
  }
}

    • 批量修改运单

      URL:[PUT]/delivery/
Head: REST_Command=BATCH_UPDATE
Request: {	// 业务自定义请求内容
	"doNum": ["12345678", "12345679"]
	"carrier": "shunfeng",
	"mot": "kongyun",
	"weight": 234
}
Response: {
  "error": [],
  "warning": [],
  "message": [{运单信息}]
}

  • 删除物流运单

    删除操作在删除对象不存在时直接返回，因为期望结果和当前结果一致的。

    • 删除运单

      URL:[DELETE]/delivery/{delivery-id}
Response: {
  "error": [],
  "warning": [],
  "message": [{运单信息}]
}

    • 删除运单子对象

      URL:[DELETE]/delivery/{delivery-id}/weight-check/{check-id}
Response: {
  "error": [],
  "warning": [],
  "message": [{重量检测信息}]
}

    • 批量删除

      URL:[POST]/delivery
Head: REST_Command=BATCH_DELETE
Request: {
	"mot": ["haiyun", "kongyun"],
	"carrier": ["承运商1", "承运商2"]
}
Response: {
  "error": [],
  "warning": [],
  "message": [{运单信息}, {运单信息}]
}

  • 批量上传物流运单

    批量上传可以按照批量创建的接口做。更新REST_Command=BATCH_UPLOAD。

  • 批量下载物流运单

    批量下载可以按照批量查询的接口做。更新REST_Command=DOWNLOAD。

  • 统计接口

    统计信息是发票和运单的综合数据，我们称他为分摊后发票，是每个发票在单个运单上的金额信息，记为delivery-invoice。在后台可以有一个组件在自动更新。虽然这个接口是一个查询接口，但是查询的内容不是原始数据，是统计数据，所以命名为delivery-invoice-report。

    URL:[POST]/delivery-invoice-report
Head: REST_Command=GENERATE
Request: {	// 自定义查询条件
	"mot": ["haiyun", "kongyun"],
	"carrier": ["承运商1", "承运商2"]
}
Response: {
  "error": [],
  "warning": [],
  "message": {统计结果}
}

总结

  • URI固定表示资源，子对象也算资源，实时计算的内容使用虚拟资源
  • HTTP Code是传输层的内容，不再参与业务逻辑
  • 使用公共的Response结构来返回各种错误信息
  • 扩展Head，增加REST_Command完成各种多样功能
BoRoBoRoMe
关注
  • 2
    点赞
  • 踩
  • 3
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
Restful 操作
wwhhff11
06-14 839
Rest模式有四种操作，POST /uri 创建 DELETE /uri/xxx 删除 PUT /uri/xxx 更新或创建 GET /uri/xxx 查看GET操作是安全的。所谓安全是指不管进行多少次操作，资源的状态都不会改变。比如我用GET浏览文章，不管浏览多少次，那篇文章还在那，没有变化。当然，你可能说每浏览一次文章，文章的浏览数就加一，这不也改变了资源的状态么？这并不矛盾，因为这个改变不是G
restful crud_CRUD和7个RESTful动作
编程故事的地方
05-13 346
restful crud 当我学习新东西时，我喜欢和自己谈谈，直到我感到自己明白为止。 当您隐藏在没有其他人在问您的事实的背后时，您会感觉到，您实际上只是在对自己撒谎。 “是的，REST，CRUD，非常简单……” 这是我尝试掌握一个概念的时候之一，这实际上很简单，但是只有当我说出来一些时候。 让我以及其他许多人感到困惑的是，CRUD是4个不同的操作，并且有七个RESTful操作，因此我们...
Restful服务
懒散的蜗牛
10-16 1282
Restful Web API应该严格遵守Http的四个操作：             1、GET对应查询操作；             2、POST对应创建操作；             3、PUT对应更新操作；             4、DELETE对应删除操作。 从HttpClient发过来的Request类型只能是上述四种之一。 下面是我做的一个例子，这样可以更快的理解 ...
RESTful API 常用动作以及状态码（Status Codes）
chimo9943的博客
04-30 574
RESTful API 动作: GET /zoos：列出所有动物园 POST /zoos：新建一个动物园 GET /zoos/ID：获取某个指定动物园的信息 PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息） PATCH /zoos/ID：更...
RESTfull与URL设计之收集那些卖萌的URL(持续更新中)
weixin_33875564的博客
03-19 114
为什么80%的码农都做不了架构师？>>> ...
Restful 接口规范
最新发布
01-04
* 正确设置 http 状态码，不要自定义 * Response body 提供错误的描述文本（展示给用户） API 可能抛出两类异常：业务异常和非业务异常。业务异常由自己的业务代码抛出，表示一个用例的前置条件不满足、业务规则...
restful 测试工具
06-18
Restful测试工具是一种...总的来说，这个RESTful测试工具是开发和测试RESTful API不可或缺的辅助软件，它简化了接口测试流程，提高了工作效率，让开发者能够更加专注于服务的逻辑和功能验证，而不是测试环境的搭建。
RESTful架构介绍
01-02
RESTful架构介绍
restful.rar
05-02
这些测试可以帮助开发者确保RESTful接口和JWT验证逻辑的正确性。 总的来说，本项目实践了RESTful接口设计，结合JWT进行安全验证，使用Eclipse进行开发，并依赖Tomcat作为服务器。这涵盖了Web服务设计、身份验证、...
SaToken实现Restful风格
02-27
在IT行业中，RESTful风格的API设计已经成为现代Web服务的标准，因为它强调了资源的独立性和统一的接口。然而，这种风格在实现权限控制时可能会带来挑战，特别是在使用SaToken这样的权限管理框架时。SaToken是一个轻...
RESTful-RESTful GET，如果存在大量参数，是否有必要变通一下？
Eistert
10-09 2960
问题 比如设计一个GET接口，用来获取满足条件的商品 GET shop/1/goods? 参数可能是五花八门的，name，create_time，description, status, owner… 通常这种情况，如果不考虑RESTful，就会设计成POST。 但是现在RESTful风格要求做成GET，如何处理会比较合适？ 张立理回答 首先承认超过GET的URL总长度的情况确实可能存在的，一个比较典型的场景就是多选id，鬼知道一个变态能选出多少个来当然一个合理的应用不应该让这种情况出现，毕竟用手勾选到能超
RESTFUL API 常用动作以及状态码
FishLearning的博客
03-23 1237
RESTFUL API 动作: GET /zoos：列出所有动物园 POST /zoos：新建一个动物园 GET /zoos/ID：获取某个指定动物园的信息 PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息） PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息） DELETE /zoos/ID：删除某个动物园 GET /zoos/ID/anim...
RESTful API接口设计标准及规范；
热门推荐
时光偏执的博客
01-12 28万+
RESTful发展背景及简介 网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面电脑、其他专用设备…）。因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行，甚至出现"APIFirst"的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。 REST（Representational Stat...
Restful API 的设计规范
youhan26的专栏
10-20 3152
http://www.tuicool.com/articles/bUZNZbZ Restful API 的设计规范 1. URI URI规范资源集合 vs 单个资源避免层级过深的URI对Composite资源的访问 2. Request HTTP方法安全性和幂等性复杂查询BookmarkerFormatContent Negotiation 6. Response 分
用实践做总结，Restful API风格仅适用于业务逻辑简单的小型应用
阿吉的技术总结博客
06-06 1068
很苦恼编程界目前的一个现状：有很多人都说Restful不行或者不好，最后大多数人都被Restful的支持和拥簇者怼了回来，说你根本就不懂得什么是Restful，因为在Restful的世界里，一切你要操作的对象都可以抽象成资源，你们这些说Restful不好的人，根本就没有理解Restful的精髓，在这种情况下，甚至很多人深受Restful为害之苦，却不敢站出来发声； 为...
Restful风格的常用方法
uddwffgll的博客
05-06 517
1.Restful 风格的介绍 Restful 一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。 REST（英文：Representational State Transfer，简称REST）描述了一个架构样式的网络系统，比如 web 应用程序。它首次出现在 2000 ...
Restful的理解，Restful 优缺点
u012045045的博客
07-19 4477
先看看什么叫restful： REST的名称"表现层状态转化"中，省略了主语。"表现层"其实指的是"资源"（Resources）的"表现层"。 所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。 客户端用到的手段，只能是HTTP协议。具体来说，就是.
REST和RESTful有什么区别
p15097962069的博客
01-16 658
REST系统和RESTful系统之间有什么区别？ 从我最常阅读的几件事中，所谓的REST服务实际上就是RESTful服务。 那么两者之间有什么区别。
【小家java】 Restful风格的API设计中，怎么实现批量删除？
架构师：通透，才能写出好代码！
07-27 2万+
如题，指的是在restful风格的url设计中，怎么实现批量删除呢？ 这里指的删除是真删除，不是逻辑删除。如果是逻辑删除，其实就是update，使用put方法即可 如果是需要删除一个条目，可以直接将需要删除的条目的id放进url里面，比如http://example.com/posts/2016，但是如果需要再一次请求里面删除多个条目，应该如何设计比较合理呢？我现在想到的是以下两种方法...
RESTful架构实战.docx
11-03
"RESTful架构实战" 本文深入探讨了RESTful架构风格，这是一种基于网络的软件架构设计，强调信息在系统架构中的核心地位。REST（Representational State Transfer）的核心理念在于通过无状态的方式处理、访问和操作...

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值