当前位置: 首页>后端>正文

你真的会写Restful API吗?

现在服务端向前端暴露的API一般都称自己为Restful API,肉眼可见的最明显特征就是application/json。但是json这个东西只能说是一个数据格式,它的好处就是表达数据清晰简单,但是要把restful和json画个等号就大错特错了。

也许你听说过Rest是面向资源的,但没有这样认真实践过,不知道怎样做才是最符合标准的。其实Rest有一个成熟度模型,最高的等级是超媒体控制,这有个专业的名词:HATEOAS(The Hypermedia As The Engine Of Application Statue)。如果你使用Java,可能看到过Spring HATEOAS,它就是用来实现这个最高等级的,不过用的人应该不多,这是为什么呢?下面会谈到这个问题。

我们先看一下成熟度模型的其它几个等级:

第0级:仅使用http作为通道。

我看见的很多API都停留在这个阶段,接口的形式还是RPC的形式,典型的特征就是get、set、add、delete等命名的接口满天飞,在这些接口中看不到任何基于资源的影子。get和post方法也是混用的,哪个方便用哪个。

第1级:以资源为中心。

我认为做到这一点才算真正的是Restful API了。形式如下:

/products/
/products/?name=foo
/products/1
/orders/

接口编写者提供的是资源,接口调用者访问的也是资源,而不再是执行某个动作。

有时候怎么定义资源需要琢磨一下,比如用户登录和退出,用restful API怎么写?

以前可能会这样写:

user/login
user/logout

现在想一下用户登录和退出操作的是什么资源?是会话。

所以登录可以是:Post /Session ,退出就是:Delete /Session

什么时候用Post?什么时候用Delete?下面马上讲。

第2级:利用http动作的语义。

这个有点难理解,看一个例子:

GET /products/1

GET语义上有幂等的意思,这里的幂等怎么理解?这个操作的意思是获取一个编号为1的产品,它不会更改资源的状态,如果调用API的时候超时了或者出错了,它可以安全地重试多次。

如果是POST动作,则语义上不是幂等的。它会改变资源的状态,比如银行转账,简单重试可能导致多扣一次钱。所以对于非幂等的操作,重试之前需要先检查资源的最新状态,否则可能会造成一些业务问题。

常用的Http动作还有Put、Delete等等,注意它们语义上都是幂等的,也就说可以安全重试,应用这两个动作的时候千万需要注意,实现上不要破坏这种幂等性。

绝大部分情况下,能够做到这一步就够了,算是标准合格的Restful API了。

第3级,终极等级,也就是前边提到的超媒体控制。做到这一步,客户端无需提前知道API的Path定义,服务端会返回资源的当前状态,以及下一步可以执行的各种标准动作。具体的就是通过link来给出各种处理资源的Path。这个有点像书的目录,具体样子请看附图。

你真的会写Restful API吗?,你真的会写Restful API吗?_json,第1张

你真的会写Restful API吗?,你真的会写Restful API吗?_幂等_02,第2张

应用到这一级的API比较少见,我认为是有点过于复杂了,编写服务端和客户端都比较麻烦,技术上有点理想化,实际的应用场景也比较少,我想不出来,欢迎补充。

另外还想说的是,restful和json不是绑定的,json只是一种最为流行的编码格式,在restful架构风格下,还可以使用xml、protobuf或者其它一些格式,经常见到的就是很多API支持根据http header中的accept返回json或者xml。

最后我们一般在对外提供服务的时候使用restful的接口,对内基于效率和习惯,还是使用RPC框架居多。RPC就不是面向资源的了,可以认为它面向的是业务模型,调用的是各种业务动作。不过RPC也可以基于Http协议,只使用其中的Post动作,比如大名鼎鼎的grpc就使用Http,这里Http协议被作为了一种传输协议,RPC协议则是上层业务协议。


好了,这篇文章就到这里。

你是怎么看待这个问题的?欢迎留言。

(封面图来源:Richardson Maturity Model (martinfowler.com))


https://www.xamrdz.com/backend/3t51931187.html

相关文章: