[

Hossein Mousavi

6月20日

13分钟阅读

[

拯救

API-First Approach的完整指南

在你的软件开发生涯中，你可能会采取许多方法来开发一个应用程序，其中之一就是API-First Approach。在这篇文章中，我们将深入了解它的核心概念，学习更多关于这种方法的知识，我们也将熟悉在整个这个方法中你可能需要的一些工具。

照片：Marvin MeyeronUnsplash

背景介绍

从一个人的脑海中突然出现一个产品的想法，到产品完成并推出的那一刻，需要采取数百（甚至数千）个步骤；因此，尽管有一个优秀的想法和商业计划，许多团队还是无法建立一个应用程序。因此，如果有一个设计、开发、发布和营销产品的准则，对所有这些团队都会有很大的帮助。此外，团队可以从扩大他们的应用规模和提高他们最终完成产品的速度中受益。许多引入的方法之一是API-First方法。然而，在我们深入研究API-First方法之前，让我们首先建立一些关于先决条件概念的基础知识。

对什么是API的回顾

你们可能都听说过API与服务员的相似之处，但这次让我们从技术上更深入地挖掘API。首先，让我们一起回顾一些核心概念，然后我们将展开API有用的原因。

API是Application Programming Interface 的缩写**，** 它是两个机器甚至两个程序之间的连接。因此，你可以把API想象成两个端点之间的中间件，用于传输数据和在特定时间用特定数据调用一些功能。API对于安全原因也是至关重要的。因为几乎每个应用程序都有需要存储在数据库中的数据，如果让用户直接连接到数据库来手动获取、更新、创建和删除他们的数据是不安全的。在这里，API从应用程序中接收必要的信息并将其发送给服务器，一旦服务器为API提供了响应，API将把响应返回给客户端。为了复述，下面是API的工作方式。

客户端发起一个调用API的请求。该请求中必须有几样东西。请求REST动词，URI（统一资源标识符），请求的标题，如果动词需要一个主体，请求主体也是必要的。
API会向程序伸出援手。收到请求后，API将到达服务器并与之连接。然后，服务器开始处理数据，也许做一些计算，为API准备适当的响应。
服务器会向API发送一个响应。在处理并最终确定请求后，一旦服务器准备好数据，它就会将数据传输给API（我们称之为响应）。
API向客户端发送响应。一 旦API从服务器上收集到响应，它将准备好用HTTP协议将响应发送给应用程序。

API功能的四个步骤

尽管我们的开发者为我们的应用程序实现了一个友好的用户界面，使其能够有效地工作，但API并不是为了让人类直接使用的，它们是为计算机准备的。因此，为了拥有出色的工作API，我们应该始终考虑性能优化和机器限制。此外，我们需要以一种方式来实现它们，这样我们就可以在未来扩展我们的产品，而在开发产品的过程中，对我们帮助很大的一点是编写可预测的代码，如 Andrei Neagoie，在他的一门课程中说的。

"我们应该编写可预测的代码，不仅对人类，而且对机器都是如此。你的代码的可预测性越高，就越好，因为它没有任何的意外"

-Andrei Neagoie

另一个我们需要关注的基本问题是安全问题。例如，用户可能会在我们的应用程序上输入他们的重要信息（例如，他们的银行账户信息），我们需要使用我们的API将这些数据传输到我们的服务器。此外，我们的API应该防止黑客从我们的API中嗅到数据。最后，数据应该在每个端点进行加密和解密，以防止黑客在发生数据泄露时接触到数据。

照片：NASAonUnsplash

不同类型的API

网络API是由HTTP协议提供的。你可以在网络API中找到存储等服务（如本地存储和会话存储），或者你可能想控制浏览器的通知。网络API通常使用JavaScript，尽管这并不是必须的。如果你做过前端开发，当你想找到当前页面的URL**（window**）或想设置一个定时器以便稍后做某事**（setTimeout**）等时，你肯定接触过它们。最常用的API是网络API，包括四个主要类型。

开放（公共）API。 它们对每个人都是可用的。它可能需要注册，但它们是公开的，是为外部用户准备的。例如，你可以在这里看一下谷歌的API的完整列表。
内部API。如 果你有敏感信息，只想在公司内部（或商业伙伴）发布，内部API就是你要看的。
合作伙伴API。 它们与开放API基本相同，但，你可以使用API网关将你的API的访问限制在特定用户。在软件开发中，这种方法盛行于控制对付费API和有敏感信息的API的访问。
复合API。如 果你需要在一次调用中发送多个请求，你可以使用这种API。这些API的好处之一是，你可以将一个API的输出作为另一个API的输入。

不同类型的API协议

尽管API的主要职责是在两个端点（机器或程序）之间建立一个安全可靠的连接，但这只是它的一般概念。我们需要实现我们的API来解决我们的问题，优化我们产品的性能。因此，多年来程序员们引入了不同类型的API，而且每一种API都有一些优势。此外，还引入了不同的API架构和协议来指定我们要建立的数据类型和规则。有三种主要的API协议。REST、SOAP和RPC。我们将学习它们各自的基础知识，然后我们将深入研究REST，因为我们想利用REST概念学习API-First方法。

RPC（远程程序性调用）

这种协议使用客户-服务器模型，在不知道网络细节的情况下，在两个程序之间建立通信。RPC的整个想法是，我们想从另一台电脑或机器上调用我们服务器中的一个函数。例如，假设我们有两个服务器（服务器A和服务器B），我们想从服务器B调用服务器A上的一个函数。当然，这些服务器有可能不使用相同的编程语言，所以我们需要实现一些即使在不同语言中也能调用的功能，这就是RPC的用武之地。

你可以在XML或JSON 之间选择数据类型格式**。** 最流行的RPC框架是GRPC （G代表谷歌！），你可以在JSON、Protobuf、Thrift或XML之间选择你的数据类型。

SOAP（简单对象访问协议）

SOAP是一个基于XML的无平台应用通信协议，用于发送和接收信息，在21世纪初被广泛使用。它是一个具有以下结构的XML文档。

**SOAP信封：
**它是每个SOAP消息的包装器，由两个子元素组成。头和正文。这一部分负责表明一个XML文档是一个SOAP。
**SOAP header
**SOAP header是SOAP信封的一个子元素。与The Body不同，Header不是强制性的，它包含了消息的元数据和应用相关的信息。它被用来在两个端点之间进行更好的通信。它可以让你分散地在SOAP消息中添加功能，而不需要通信双方事先达成协议。
**SOAP正文
**每条SOAP消息的重要部分是它的正文（这是必须的）。它包含请求和响应信息。
**SOAP故障
**在失败的情况下，SOAP为我们提供了一种特殊的Body来报告和处理错误，这是SOAP故障的责任。

SOAP消息结构

REST (Representational State Transfer)

Roy T. Fielding的博士论文提出了REST的概念，导致了API在应用程序（客户端）和服务器之间建立可靠连接的巨大使用。此外，REST 易于实现，易于理解，并在语言和框架中被广泛接受。考虑到我们大量的系统是基于客户端-服务器的，REST的表现形式就像下面的图片。

基于REST的环境的模式。为了简单起见，我们没有考虑数据库。

我们有一个服务器，里面有我们的应用程序所需的所有必要资源（比如加载页面的所有文件、媒体和我们需要的数据，以便应用程序正常运行）。我们在应用程序中用REST API访问这些资源（客户端）。我们用于在客户端和服务器之间建立连接的协议是HTTP。

REST API请求和响应

在REST环境中，我们可以做四个动作。创建、读取、更新、删除（又称CRUD），我们有一个或多个REST动词分配给它们（GET、POST、PUT、DELETE，等等）。为了操作服务器中的资源，我们可以使用这些动词，但首先，我们需要为它们中的每一个实现一个API。

REST动词的列表和它们的动作

现在我们已经对API有了扎实的了解，让我们不再多说，直接进入API-First Approach。

什么是API-First Approach？

每个应用程序最关键的部分是它的业务逻辑。业务逻辑是将所有其他组件聚集在一起的一件事，因此你可以拥有一个有意义的应用程序。API-First方法将你所有的API视为一等公民，以类似于业务逻辑的方式来消费它们。在这种方法中，在项目的文档和业务模型准备好之后，我们就可以开始设计API。通过这种方式，我们可以防止因与利益相关者沟通不畅而发生的问题。

与API-First相反的是Code-First方法，一旦项目被定义，开发人员就开始编写代码。在项目初始化之初就实现服务、组件和资源，一开始听起来很有希望，因为你正在取得进展，但事实并非如此!由于重点是实施和编写代码，而不是为你的项目设计和建立一个坚实的结构和架构，所以项目可能不是客户所希望的。这将导致在实施过程中重构和重写你的代码库，这是任何团队都不希望看到的。

API优先方法的好处

开发软件或应用程序几乎都是一个团体活动。你需要成为一个团队成员才能成功。为了保证应用程序的开发过程顺利进行，领导者应该密切关注团队成员，并确保他们在一起工作得当。API-First方法是团队领导可以考虑用来维护项目的方法之一。

因为我们首先设计API，通过从一开始就实现它们的方式，减少重新实现应用程序的成本。这就避免了不必要的会议，这些会议消耗了团队的大量时间和精力。

另一方面，每个团队成员都参与到项目的设计和架构中。这很重要，因为这有助于所有的人获得宝贵的经验，并帮助他们在职业生涯中成长。

另一个重要的事情是平行工作的能力。假设我们想实现一个网络应用。一旦API的结构准备好了，前端开发人员就可以开始实现应用程序的客户端，另一方面，后端团队正在经历实现其他API的过程。同时，整个团队合作，以获得他们可以实现的实现其他API的结构的最佳解决方案。

由于后端团队和从端团队同时工作，他们可以互相告知实施过程中可能出现的问题，并节省大量的时间。

API-First Approach的优势

什么是API-First Approach的必要性？

现在我们已经对什么是API-First以及它的好处有了一定的了解，我们需要弄清楚我们的团队是否有资格开始实施它。
如今，许多大规模的公司都在向API-First方式发展。随着公司规模的扩大，我们面临更多的麻烦，作为一个老的伊朗谚语说。

更大的屋顶可以吸收更多的雪!

我们首先需要担心的不是实施API-First的技术细节，而是建立一种文化，让团队成员和管理者对这种方法有很好的理解。让每个人都站在同一起跑线上是这种方法的主要必要条件之一。建立这种文化不仅仅是项目经理的职责，团队的每一个成员都应该参与其中。

下一步将是为我们的沟通和文件实施一个基础设施。一开始我们可能会面临很多会议，如果我们没有一个合适的会议媒介，事情会很快脱离我们的控制，以至于我们一开始没有意识到这一点。收集所有必要的信息并将它们记录下来供将来使用，这需要一个适当的常规和协议。你无法想象，在一个设计不良的系统中，事情会变得多么快。

照片：Brett JordanonUnsplash

开始实施API-first

好了!现在一切都已经处理好了，我们可以开始在我们的项目中实施API-First方法。

最初的会议

尽管API-First方法减少了你用于会议的时间，但它仍然需要团队聚集在一起进行头脑风暴，特别是在项目的开始阶段。所有的团队成员都需要了解利益相关者的确切需求和他们的期望。请记住，记录所有的会议是至关重要的（也许在每个人允许的情况下可以录音）。

团队成员介绍

如果你的团队有新成员，或者团队成员不认识利益相关者，那么接下来就需要所有团队成员互相认识。拥有一个健康的关系将促进你的团队的表现。这个步骤的另一个基本好处是，每个人都会知道每个人的确切职责，并将减少官僚主义。

建立一个设计和开发的文化

正如我们前面所讨论的，建立一种文化是API-First方法的先决条件之一。它也是实施它的一个关键部分。团队需要有一套关于开发方法、项目的架构和设计、编码风格指南等的坚实规则。作为一个项目经理，你有责任确保你的每一个团队成员都了解这些规则。

使API标准化

你可以使用很多工具来规范你的API。但是，在后端和前端团队之间有一个共同的语言是至关重要的。请不要把这和文档搞错，因为我们在这里谈论的是技术团队之间的相互语言。

尽管这可能有助于医生在实验室报告中写下评论，但他们都能从报告中收集到必要的信息。开发者也应该如此。他们之间应该有一种技术上的共同语言，以便与技术语言直接互动。

自动化、测试和部署

对于项目如何以及何时发布新版本，应该有具体的规定。有很多工具可以用于语义上的版本管理。测试现在是任何应用程序不可分割的一部分，你需要考虑清楚。

照片：Jason GoodmanonUnsplash

还有两件事...

像许多软件开发方法一样，有两条至关重要的规则需要你注意。

没有一种方法适用于所有人。每个公司都应该从一种方法中得到启发，并对其进行定制，以更好地满足他们的愿望。关键的启示是，他们不应该把方法定制得太多，以至于结果与基础方法完全不同。
一个项目就像一个婴儿。它需要不断的照顾才能成长。有时候，似乎有一段时间没有进展，但这是可以的。这就是像敏捷这样的方法论可能派上用场的地方。

与你的朋友们分享!拍手👏，最多50次。

请不要犹豫，与我分享你的想法和意见。你可以在Twitter上联系我，或者你可以通过访问我的作品集找到另一种方式。

[

Hossein Mousavi - 软件开发人员

你们好👋🏻发现Hossein Mousavi的空间并找出我的作品。欢迎与我和更多的人取得联系

www.hmousavi.dev

](www.hmousavi.dev/)

阅读更多来自我的信息。

[

Angular中的多个拦截器

Angular提供的一个惊人的功能是拦截器，但拦截器是做什么的，我们能...

媒介网

](medium.com/codex/multi…)

[

Husky 6 Lint（prettier + eslint）和JavaScript项目的commitlint

编程是一项团队工作，所以我们必须保证我们的代码库是干净的，并且可以为团队中的每个人提供...

媒介网

](medium.com/angular-in-…)

[

Angular表单（Reactive Form）包括Angular Material和自定义验证器

表单是每个Angular项目的主要部分，在这篇文章中，我们要实现一个反应式Angular表单，包括Angular Material和自定义验证器。

媒介网