👇🏽 🐰 👏🏽 REST API建议-Java和Spring中的Web服务设计示例 ☝🏻 📟 🥋

在本系列的最后一篇文章中，您将学习Java和Spring Web Services的REST API建议和开发示例。

开发良好的REST API时，拥有良好的微服务很重要。
您如何开发REST API？最佳做法是什么？

您将学到：

如何开发一个好的REST API？
开发REST API时应该考虑些什么？
开发RESTful Web服务的最佳实践是什么？

REST API

这是有关REST API的系列文章中的最后一篇：

使用消费者至上的方法

谁来使用您的服务？消费者服务。

您从消费者的角度看服务吗？

如果您正在开发API，那么您的消费者可以理解您的API吗？
如果发布资源，那么消费者可以找到并访问它们吗？
消费者可以理解您的URI吗？
您提供什么类型的服务？
这是移动应用程序还是Web应用程序？
您期望什么消费者，这些类型的消费者将来会改变吗？
如果您要实现HATEOAS之类的东西，请在实现之前考虑客户如何使用它。

最重要的是要拥有出色的文档
让客户更轻松地节省时间。
消费者可以自己做的越多，为您工作的次数就越少。

每当您进行讨论或进行服务审核时，都将客户要求放在首位。

使用合同优先方法

什么是合约？

Web服务的创建者被认为是服务提供者 。使用Web服务的应用程序是该服务的使用者 。合同是提供者和消费者之间关于服务的协议。

为了正确使用服务，服务的使用者必须完全了解合同。该合同包括服务的许多方面的详细信息，例如：

如何调用网络服务？
使用哪种交通工具？
请求和响应结构是什么？

这也称为服务定义 。

在“合同优先”方法中，首先定义服务合同，然后仅实施服务。

与WSDL首先签订合同

例如，当您定义SOAP Web服务时，您将使用WSDL来定义合同。

WSDL确定什么是服务端点，您发布的操作以及请求和响应结构。

首先使用Swagger / Open API签约

当您使用RESTful Web服务时，Swagger是用于记录Web服务的流行工具。

Swagger可让您确定作为API一部分提供的资源。它包括每个操作的详细信息，例如，是否使用XML，JSON或同时使用两者。答案大纲也在那里。

它还提供了有关其支持的响应代码的详细信息。您还可以看到/ jpa / users这个特定资源：

支持GET操作。实际上，它还支持POST操作：

如果此资源可用，则响应方案将是：

Swagger协议中对User对象的定义如下：

它包括属性： birthDate ， id ， name和帖子消息数组。一些字段在其中还包含描述字段。

在合同优先方法中，在实施服务之前，您可以手动或使用应用程序创建Swagger创建的定义。

合同优先法的好处

使用“合同优先”方法，您会考虑客户以及他们如何使用此服务。您最初并不担心实现细节。

如果您在早期阶段就非常重视实现，那么技术细节会渗透到服务的定义中。

您需要确保服务的定义不依赖于所使用的平台（Java，.NET或任何其他平台）。

定义REST API的组织标准

YARAS是组织标准的重要指南。

YARAS代表的是另一个RESTful API标准 。 YARAS提供了开发RESTful Web服务时必须遵循的标准，准则和约定。他针对以下事项提供建议：

您应该给服务起什么名字
您应该如何组织您的请求和响应
您应如何实施过滤，排序，分页和其他操作
您应该如何进行版本控制
您如何处理API文档

统一的服务开发方法

在开始设计RESTful Web服务之前，您需要解决许多复杂的问题。以上所有，您需要找出。

您组织的领导层不会希望处理不同资源的团队对这些事情采用不同的方法。

例如，不希望Team-A根据查询参数组织版本控制，而Team-B使用基于URI的版本控制。

因此，为RESTful Web服务方法明确定义组织标准非常重要。

根据组织需求定制YARAS

YARAS的优点在于可以对其进行自定义以满足组织特定的需求。例如，您可以：

配置请求和响应主体的外观。
选择特定的版本控制系统

由于YARAS具有相当全面的覆盖范围，因此可以确保您没有错过任何重要的决定。

选择标准的企业框架REST API框架

在Java世界中用于创建RESTful Web服务的典型框架是Spring MVC，Spring REST和JAX-RS。

如果您在首选的REST API平台之上创建符合通用组织标准的特定于组织的框架/原型/参考应用程序，这将使团队可以轻松遵守通用标准。

典型功能包括：

请求和响应结构
错误处理
过滤
搜寻
版本控制
错误答案支持
Hateoas

标准框架为在整个组织中设计和实施服务提供了统一的方法。

分散式REST API管理

从创建REST API的团队中创建专家组，并组成管理团队。团队负责

改善REST API标准
构建/设计REST API框架

HTTP的广泛使用

每当您想到RESTful Web服务时，就想到HTTP。

HTTP具有帮助您创建出色的Web服务的所有功能。

使用正确的HTTP请求方法

考虑一下您需要使用的HTTP请求方法。考虑实现一项操作时，请确定应在其上执行的资源，然后找到适当的HTTP请求方法。您是检索详细信息，创建内容，更新现有内容还是删除现有内容？

使用HTTP方法：

得到得到
开机自检创建
放置更新
删除删除
修补程序以进行部分更新

使用适当的HTTP响应状态

执行操作时，请确保返回正确的响应状态。

例如，当找不到特定资源时，请勿引发服务器异常。而是在响应消息中发送适当的响应代码，例如404 。

如果确实存在服务器异常，则将代码500发送回去。

如果验证失败，请发送无效请求的代码。

专注于表现

每个资源可以有几种表示形式-XML或JSON格式。服务使用者可以选择自己选择的表示形式。

当我们发送GET请求时，该服务将返回3个用户。在这种情况下，我们获取/ users资源的JSON表示形式。

当使用者未指示首选视图时，我们使用JSON。

使用者可以发送Accept标头来指示视图。

响应主体现在具有XML内容：

使用复数

在命名资源时，请始终使用复数形式。

让我们看一个简单的例子。假设我们有一个托管用户资源的服务。下面介绍如何访问它们：

创建用户： POST /用户
删除用户： DELETE /个用户/ 1
获取所有用户： GET /用户
获取一个用户： GET / users / 1

多个用户优先于用户用户使URI更具可读性。

例如，如果我们使用/ user而不是/ user来获取，则GET / user不会将正确的消息传递给阅读器。

创建好的文档

消费者需要了解如何充分利用服务，而帮助他们的最佳方法是创建良好的文档。

SOAP Web服务可以使用WSDL功能，而RESTful Web服务具有Swagger选项（现在是Open API文档标准）。

选择格式只是创建好的文档的一部分。同样重要的是提供适量的信息来帮助消费者。

该文档应完整，并包括以下几点：

什么是请求和响应结构？
消费者应如何认证自己？
使用限制是什么？
指出服务可能期望的所有类型的响应消息和相应的状态代码。

创建一个通用的REST API文档门户

为整个组织使用通用的REST API文档门户会很有帮助。看一看这样的门户：

这样的门户汇集了组织中所有可用的资源。拥有Swagger UI之类的用户界面将带来更多好处。使用Swagger UI，您可以更详细地查看文档：

即使非技术用户也可以使用此功能。此处提供的信息包括：

预期回应格式
内容类型
支持的答案代码

实时请求/响应样式的文档格式也可能是您感兴趣的。

版本支持

版本控制给Web服务带来了极大的复杂性。维护同一Web服务的多个不同版本非常困难。尽可能避免这种情况。

但是，在某些情况下，版本控制是不可避免的。

让我们从一个示例服务开始。假设我们最初定义了一个具有PersonV1类的服务，如下所示：

该类的版本不考虑名称可以包含许多子节，例如名字和姓氏。检查一下：

源类的第二个版本已更新，可以解决此异常问题：

我们无法立即将整个服务转让给使用PersonV2 ！可能还有其他消费者正在等待PersonV1格式的响应。

这是需要版本控制的地方。

现在，让我们看一下对这两种资源进行版本控制的选项。

使用不同的URI

我们有一个选择-对这些不同的资源使用不同的URI。在下面的考试代码中，我们使用URI v1 / person和v2 / person来区分它们：

如果您对资源v1 / person执行GET请求：

您将收到与v1相对应的信息。对于另一资源：

使用查询参数

第二种版本控制方法使用查询参数：

在URI / person / param中 ，如果我们发送version = 1的参数，则会返回PersonV1类型的资源：

对于相同的URI， version = 2的参数返回类型为PersonV2的资源：

该方法称为使用查询参数的版本控制。

使用标题（标题）

可以执行此操作的另一种方法是通过指定标题来进行版本控制。在这里，我们使用名为X-API-VERSION的标头，并将URI标记为/ person / header 。当标头值为1时， 返回PersonV1类型的资源：

当其值为2时，将检索类型为PersonV2的资源：

我们使用请求标头中的属性为我们执行版本控制。

使用接受标题

创建版本的最终方法是使用“接受标头”。如果使用者在GET请求的“接受标头”中包含第一个版本信息，则返回以下资源：

否则， 返回PersonV2类型的资源：

此版本控制方法称为“ 接受标头版本控制”或“ 媒体类型版本控制” ，因为MIME类型通常是Accept标头的内容。

版本控制方法的比较

到目前为止，我们已经在版本中看到了四种类型的方法：

使用不同的URI
使用查询参数
标头的使用
使用接受标题/媒体类型

哪一个最好？事实是，这个问题没有单一答案。事实是，不同的互联网巨头光顾了不同类型的版本。

使用不同的URI-Twitter
使用查询参数-Amazon
使用标题-Microsoft
使用接受标题/媒体类型-GitHub

您需要根据您的特定需求评估这四个选项。有许多重要因素需要考虑：

URI污染 ：通过使用URI和查询参数控制版本，我们最终污染了URI空间。这是因为我们在URI的主字符串中添加了前缀和后缀。使用标头进行版本控制可以避免这种情况。
HTTP标头的滥用 。在使用标头和媒体类型进行版本控制的情况下，会误用HTTP标头，因为它们最初并不是用于版本控制的。
缓存：资源由其URI标识。但是，如果您不使用URI来确定其版本，而是使用基于标头的机制，则无法缓存版本信息。如果HTTP缓存对您很重要，请使用基于URI或request参数的版本控制。
浏览器请求可执行性 ：基于标题和媒体类型的版本控制需要Postman之类的工具。但是，如果服务使用者在技术上并不精通，则最好使用基于URI或查询参数的版本控制。
API文档 ：您还需要考虑如何记录API。与其他两种类型的版本控制相比，基于URI和查询参数的版本控制更易于记录。

了解没有单一的理想解决方案！