你写的代码真的符合RESTful风格的设计吗?

前言

之前一直认为接口按照增删改查的功能,使用GET POST PUT DELETE这几个HTTP方法,并且URL符合对应对象,比如书籍的增删改查用book,用户的增删改查用user就算是RESTUful风格了,这和实际上的RESTful要求的相去甚远。

本文会介绍一些关于RESTful风格的设计要求,比如语义化版本控制规范、常用消息格式、成熟度模型等等。

语义化版本控制规范(Semvers)

Semvers要求API版本号由三个部分组成

  • MAJOR 当你对API进行不兼容的更改时
  • MINOR 当你对API进行向后兼容的增强时
  • PATCH 当你进行向后兼容的错误修复时

有几个地方可以在API中使用版本号,比如实现REST API,则可以使用主要版本作为URL路径的第一个元素;或者如果要实现使用消息机制的服务,则可以在发布的消息中包含版本号。这些做法都是为了正确地为API设置版本,并以受控的方式更改它们

例如 RESTAPI路径为 /v1/...为前缀 就是进行主要并且不向后兼容的改变

两类消息格式

消息的格式大体可以分为文本和二进制两大类

文本:JSON和XML,好处是它们的可读性很高,同事也是自描述的。XML和JSON都可以允许消息的接收方只挑选它们感兴趣的值,而忽略掉其他。因此,对消息的修改可以做到很强的后向兼容性

弊端主要是消息往往会冗余过长,特别是XML。消息的每一次传递都必须反复包含除了值意外的属性名称,这样会造成额外的开销。另一个弊端是解析文本引入的额外开销,尤其是消息比较大的时候,因此在对性能和效率比较敏感的场景下,更得倾向于基于二进制格式的消息 一个典型的XML数据如下

xml 复制代码
<root>
  <person>
    <name>John</name>
    <age>30</age>
    <address>
      <street>123 Street</street>
      <city>New York</city>
      <country>USA</country>
    </address>
  </person>
</root>

一个典型的JSON数据如下

json 复制代码
{
  "person": {
    "name": "John",
    "age": 30,
    "address": {
      "street": "123 Street",
      "city": "New York",
      "country": "USA"
    }
  }
}

二进制消息:有几种不同的二进制格式,比如Protocol buffers 和 Thrift,这两种格式都提供了一个强类型定义的IDL(接口描述文件),用于定义消息的格式。编译器会自动根据这些格式生成序列化和反序列化的代码。因此你不得不采用API优先的方法来进行服务设计

Protocol Buffers使用tagged filed(带标记的字段)来标记数据和格式

REST成熟度模型

REST成熟度模型

  • LEVEL 0 客户端只是向服务端发起POST 请求 进行服务调用 所有操作都通过POST进行实现
  • LEVEL 1 引入了资源的概念。要执行对资源的操作,客户端需要发出执行要执行的操作,和包含任何参数的POST请求 也是所有操作都通过POST实现
  • LEVEL 2 使用HTTP动词来执行操作,譬如GET 获取 POST创建 PUT更新,这也是大部分接口实现的等级
  • LEVEL 3 在由GET请求返回的资源中包含链接,这些链接能够执行该资源允许的操作。例如客户端通过订单资源的链接取消某一个订单,或者发送GET请求去获取该订单。这样也可以避免在客户端代码中写入硬链接的URL

REST优缺点

优点:

  • 简单 开发者熟悉
  • 可以使用浏览器拓展或者命令行进行测试 比如postman和curl
  • 直接支持请求/响应方式的通信
  • HTTP对防火墙友好
  • 不需要中间代理 简化结构

缺点:

  • 只支持请求/响应方式的通信
  • 可能导致可用性降低 由于客户端和服务直接通信而没有使用代理来缓冲 因此它们必须在REST API调用期间都保持在线
  • 客户端必须知道服务实例的位置 (URL) 这是现代应用程序中的一个重要问题
  • 在单个请求中获取多个资源具有挑战性
  • 有时很难将多个更新操作映射到http动词

总结

通过本文的分享,相信能够加深各位对语义化版本控制和RESTful API设计的了解,遵循这些设计规范是确保项目推进、迭代的关键环节。

创作不易,如果有收获欢迎点赞、评论、收藏,您的支持就是我最大的动力。


相关推荐
GetcharZp1 小时前
彻底告别数据焦虑!这款开源神器 RustDesk,让你自建一个比向日葵、ToDesk 更安全的远程桌面
后端·rust
jack_yin2 小时前
Telegram DeepSeek Bot 管理平台 发布啦!
后端
小码编匠2 小时前
C# 上位机开发怎么学?给自动化工程师的建议
后端·c#·.net
库森学长2 小时前
面试官:发生OOM后,JVM还能运行吗?
jvm·后端·面试
转转技术团队2 小时前
二奢仓店的静默打印代理实现
java·后端
蓝易云2 小时前
CentOS 7上安装X virtual framebuffer (Xvfb) 的步骤以及如何解决无X服务器的问题
前端·后端·centos
秋千码途3 小时前
小架构step系列07:查找日志配置文件
spring boot·后端·架构
蓝倾3 小时前
京东批量获取商品SKU操作指南
前端·后端·api
开心就好20254 小时前
WebView远程调试全景指南:实战对比主流工具优劣与适配场景
后端
用户21411832636024 小时前
AI 一键搞定!中医药科普短视频制作全流程
后端