前言

对应软件客户端与服务端的通信, 大多公司有自己的自定义RPC协议, 通用的如GRPC近几年更是受到了广泛的追捧。

但是, 对于web领域, 由于HTTP的原因, 浏览器是无法实现完整的低损耗RPC协议通信的, 一切几乎都要建立在HTTP之上。

即使HTTP2.0已经出现很久的今天, 即使GRPC也是按照HTTP2.0来实现的如今, 在web领域, 依旧是无法完整的使用GRPC的。

因此RESTful作为web领域唯一的最广泛应用的协议, 仍旧是具有无可替代和无可撼动的地位的。

此篇, 就是为了简单说明RESTful Web API 在设计过程中, 应该遵循的基本规则以及设计技巧。

基本规则

状态码

响应体

基本设计原则

这里不对默认200的API设计做介绍。

  • GET 方法
    成功的 GET 方法通常返回 HTTP 状态代码 200（正常）。 如果找不到资源，该方法应返回 404（未找到）。

    如果请求已完成，但 HTTP 响应中没有包含响应正文，则应返回 HTTP 状态代码 204（无内容）；例如，不产生匹配项的搜索操作可能会通过此行为实现。

  • POST 方法
    如果 POST 方法创建了新资源，则会返回 HTTP 状态代码 201（已创建）。 新资源的 URI 包含在响应的 Location 标头中。 响应正文包含资源的表示形式。

    如果该方法执行了一些处理但未创建新资源，则可以返回 HTTP 状态代码 200，并在响应正文中包含操作结果。 或者，如果没有可返回的结果，该方法可以返回 HTTP 状态代码 204（无内容）但不返回任何响应正文。

    如果客户端将无效数据放入请求，服务器应返回 HTTP 状态代码 400（错误的请求）。 响应正文可以包含有关错误的其他信息，或包含可提供更多详细信息的 URI 链接。

至于PUT PATCH DELETE 方法, 我的项目中并未对其使用, 原因是尽可能简化规范, 避免引用过度的设计造成的开发周期延长问题。

其实这里面的东西很多, 比如异步设计等等…

本文就不再一一介绍了。 具体细节, 可以参考下方链接中的文档予以学习:

异步设计, 参考下面链接中的文档:

双向流的解决方案

前言中提到, 无法在web领域使用完成的GRPC, 可是RESTful并不支持双向流。 因此, 我们要想实现实时同步功能(比如依赖服务端主动下发给客户端消息), 只能通过websocket来实现了。

对于socket及tcp我们都很熟悉, 因此websocket也就不言而喻了, 本质也是基于tcp的应用层协议。

可以看一下现阶段web领域的grpc对比websocket的选型文章: