rest接口 一种RESTful接口的约定

1概述1.1写作目的

本文用于定义统一的RESTful界面设计方案，希望有参考价值。本文描述的方案是学术性的(刚性)，上一家公司没有采用。在为数有限的声称采用RESTful风格的公司中，发现他们相差甚远。然而，在介绍RESTful的书籍和大多数在线资料中，都是这样的方案(URL命名风格、请求和响应的设计)。他们这样做当然是有原因的，我也明白这只是一个选择的问题。这篇文章其实是一篇老文章，写于2016年底，但一直躺在电脑硬盘上，不想浪费当时的心血，在此公开。

1.2为什么使用REST

目的是将服务器与客户端分离。SOA只是把前端和后端从结构上分开，但实际上数据逻辑还没有解耦，服务器接口的升级往往会影响客户端，所以两者的行为需要严格约定。REST是用HTTP协议约定的，客户端只需要按照HTTP协议理解服务器返回的数据。尽管与业务相关的数据结构仍然需要达成一致，但它确实进一步分离了服务器和客户端。

此外，因为数据是严格按照HTTP协议返回的，所以可以在返回的报头中为安全接口设置缓存策略(接口安全的概念将在后面解释)。

1.3文件结构

第二部分将阐述RESTful的一些关键概念，明确第二部分阐述的概念有利于设计和实现优雅、标准的界面。

第三部分，对URL命名问题进行了约定。

第四部分对信息实体进行约定。

第五部分阐述了“对RESTful接口的请求”，并对实现方法、请求头和请求体的格式进行了约定。

第六部分指定了接口的响应格式，包括响应消息头、状态码和JSON实体。

第七部分涉及版本控制问题。

第八部分对RESTful接口的实现提出了一些建议。

2个关键概念

澄清一些关键概念很重要。RESTful API设计虽然没有统一的标准，但还是需要符合一定的原则，否则不能称为RESTful API。很多人在没有完全理解REST的情况下，就声称自己的API是RESTful风格的API，以至于RESTful的支持者菲尔丁博士都受不了。2008年，他写了一篇博客“REST APIs必须是超文本驱动的”。超文本驱动和HATEOAS是同一个概念的不同表达，后面会解释。

2.1 RESTful

REST不是协议，不是文件格式，也不是开发框架。它是一组设计约束:无状态、超媒体作为应用程序状态的引擎等。REST是表征状态迁移的简称，在汉语中是“表达状态迁移”。这里涉及到资源表示和状态两个概念。

简单来说，资源可以看作是存储在服务器上的所有数据，资源的表示是服务器提供的指向这些资源的方式。JSON，XML等。可以使用，并且一个资源可以有多个表示；资源状态是服务器的数据存储状态。例如，在时间t，服务器存储m条数据，然后客户端向服务器提交创建数据的请求，服务器处理该请求并创建一条数据。然后在t+1时刻，服务器存储m+1条数据，这两个时刻的资源状态是不同的。时间t的请求导致资源状态的改变。

2.2 HATEOAS

超媒体作为应用状态的引擎，超媒体作为应用状态的引擎。这是REST区别于其他SOA风格的主要特征。当客户端与服务器交互时，完全是通过服务器动态提供的超媒体。除了对超媒体的一般了解，客户端不需要知道任何额外的知识。相反，在一些SOA接口的设计中，客户端和服务器端的通信要事先约定好，比如通过文档或者接口设计语言(Interface Deion Language，IDL)。在基于HTTP协议的REST设计中，一般采用请求和响应的报头来体现HATEOAS的原理(详见https://en.wikipedia.org/wiki/HATEOAS)。这也意味着REST应该充分利用HTTP标准中已有的东西，比如Header、标准方法、状态码等。

从标准来看，HTTP标准是世界公认的RFC标准；其他自定义的SOA标准可能是个人标准，也可能是公司标准，最多是互联网草案(这对于大多数公司来说是不可能的)。一个标准被越广泛接受，它的普遍性就越强。个人标准和公司标准多种多样，每个标准要参考其相关文档才能实现相应的行为逻辑，非常麻烦。

2.3安全

调用一次方法和调用0次是一样的。这个方法是安全的，否则就是不安全的。例如，方法A只读取数据，不创建或修改数据。方法A无论调用多少次，对数据记录都没有任何影响，方法A是安全的。但如果有另一种方法B删除数据，方法B被调用一次后，数据会被删除(或者修改标识位)，系统中的数据会发生变化，那么方法B是不安全的。

2.4幂等

一次调用一个方法和多次调用是一样的，即相同的输入会得到相同的输出，所以这个方法是幂等的，否则就不是幂等的。

在2.3节中，方法A和方法B都是幂等的。安全方法必须是幂等的，但幂等方法可能不安全。

假设一个方法C在一个全局计数器上执行自增操作并写入数据库，对方法C的每次调用都会影响系统数据，那么方法C就不是幂等的。

3网址命名

URL是用来标识资源的，所以URL要用名词来命名，比如/users，/users/children等。

常规URL将嵌入参数。比如获取id为313的用户的信息，URL应该是/users/313，前一个用户应该是复数，如果列出了它的所有后代，那么URL应该是/users/313/children，children应该是复数，如果要获取id为499的后代，那么URL应该是/users/313/children/499。

4消息实体

消息实体是请求和响应消息中的实体体(也称为body)，消息实体采用JSON字符串格式。

5项请求

5.1方法

使用HTTP标准定义的请求方法。

5.1.1获取

为了获得资源，通常在网址上写一个参数，而在网址上附加多个参数作为查询参数，例如:

单参数:/user/123，表示id为123的用户

多个参数:/用户？name = tom & amp电话= 13787890987 & amp性别=男性

Get方法应该是幂等的，并且对数据记录没有影响。对于汉字和特殊字符应该使用Urlencode。

5.1.2员额

要创建资源，请在请求的头中将内容类型设置为应用程序/json，参数为json类型。

根据惯例，在成功创建之后，返回的状态代码应该是201(已创建)，并且应该在响应的标头中将位置设置为新创建的资源的URL。例如，如果创建了一个新用户，并且创建后该用户的id是888，那么在标题中应该将位置设置为/users/888。当然，这应该是一个完整的网址，这里只给出一个相对路径URI来说明。这些数据返回后，客户端可以自定义后续行为，或者查看创建的用户，或者刷新当前用户列表，这些都是服务器不关心的。

相同数据重复提交的话，第一次返回201，后面返回409(冲突)。在响应的标题中，位置应设置为指向现有资源，指示冲突的来源。

5.1.3放

更新资源和修改现有资源。请求的标题和post一样，参数也一样。这个方法应该是幂等的。

5.1.4删除

删除资源。这个方法应该是幂等的。

5.2标题

内容类型应该设置为application/json。

此外，应该设置一个版本来指示所使用的接口版本。这不是HTTP协议的一部分，而是自定义的。为了版本控制，详见第7章。

5.3车身

使用JSON字符串，具体结构需要约定，不是HTTP协议的一部分，用户自定义。

这里主要放业务相关的数据。

借用10年前一篇文章中的一幅图:

6回应

6.1标题

根据响应的不同状态码，相应设置表头，详见下一节。

但在我认识的公司里，惯例是统一返回200，然后在返回的JSON字符串中设置消息代码。我无法理解。据某前端学生称，前端代码收到请求后，不方便获取Http状态码。其实前端也是我写的，不深入，但是有一些基础知识。我觉得这样做不难。估计他的代码包没有考虑到这一点。现在改起来比较麻烦，不想大惊小怪伤到骨头。

6.2状态代码

6.3正文采用JSON字符串。

JSON结构有两种:成功和失败。

一般来说，成功的JSON需要在返回200的时候才读，失败的JSON需要在返回406和500的时候才读。对于其他状态代码，客户端不需要服务器提供额外的消息。

一个成功的JSON应该只包含一个结果对象，而一个失败的JSON应该使用这个结构:

{

错误:{

代码:xxx，

信息:“xxx”，

数据:{...}

}

}

失败的JSON只有一个错误对象，包含错误代码、消息和相关数据。消息应该是直接可读的，客户端不需要理解发生了什么错误，只需要显示消息。当接收406时，客户端只需要知道发生的错误是由客户端引起的，而不需要知道是什么类型。消息可以直接显示，让用户知道是什么，所以消息应该是人类可以理解的文本。同理，在接收500的时候，你只需要知道这个错误是服务器的问题，客户端不需要知道具体的错误类型。最多可以显示错误代码和消息，让用户有反馈依据。

7版本控制

考虑到接口可能会升级，有几种类型的升级:

添加功能接口

原始接口返回数据增量字段

现有接口返回数据以更改现有字段的格式或删除现有字段

现有的接口改变了业务逻辑

删除接口

其中前两次升级不会影响客户端，所以没必要处理。后三种情况将导致使用旧接口的客户端无法正常工作。

一般服务器升级和客户端升级不同步，客户端升级往往滞后。所以服务器升级后，旧版本的界面要保持继续运行一段时间，让未升级的客户端继续工作一段时间，同时启动新版本的客户端。一段时间后，将旧版本的界面脱机。

版本控制应该是向后兼容的，也就是假设当前版本是1.2，如果客户端请求1.3版本的服务，就应该提供当前版本的服务。如果未指明要求的版本号，则应提供服务的当前版本。

一般情况下，客户端请求需要携带版本号，而服务器不需要处理，除非是同时运行新旧版本相同的接口，否则需要处理差异。

8个实施工具

8.1春季HATEOAS

Spring HATEOAS可以很容易的和Spring MVC结合起来开发RESTful接口。详见其文档:http://docs . spring . io/spring-hateoas/docs/0 . 20 . 0 . release/reference/html/# foundations . JAXB-JSON

9个缺陷

这个方案其实基本上是互联网上大多数人认可的一些做法的总结，但是缺乏细节，比如分页，但其实这些都可以是灵活的，比如在查询字符串中加入分页参数。“一个没有后端的供应链系统开发实践(上):前端分离的Restful界面设计”这篇文章的设计是全面的，但是两者考虑的问题是不同的。他的设计是无服务器的，把业务逻辑放在前端，后端只充当前端和数据源之间的代理(如果数据源和客户端在自己的控制范围内，就没必要这么做)。在这种情况下，接口要表达的逻辑是复杂的，但本文还是从传统的抽象思想考虑，逻辑封装在后端，所以接口不需要表达逻辑有多复杂。

10篇参考文献

当时没有写下来，就不列举了。这里不保证出处的权威性，请自行鉴定。^_^

原文:https://bungder.github.io/2017/07/24/REST/