摆脱单打独斗的束缚：学习与 Postman 合作进行 API 开发

API 开发是我热爱软件的一个重要部分。无论是构建集成还是为解耦的 Web 应用程序制作 API，通常只有我和代码。

大多数时候，我是一名独立的 API 开发人员。单独行动有其好处：快速决策和完全控制。但这是一把双刃剑，因为把所有事情都记在我的脑子里会让交接和授权变得棘手。单独行动限制了我可以从事的项目的规模和复杂性。毕竟我只是一个人。

Postman 是我用于 API 工作的主要工具——发送请求、管理环境和运行测试。我熟悉我的独奏工作流程。但我开始想：在团队环境中，Postman 还能提供什么？它如何加强协作并简化开发流程？

为了探索这些问题，我开始研究一个示例 API，我将其称为“X Nihilo”。

API 示例：X Nihilo

X Nihilo 可帮助您根据您存储或发送的参数生成 280 个字符的推文。您提供一个主题、一个目标、对语气的描述以及对受众的描述。在后台，API 将向 OpenAI 的 API 发送文本补全请求，这将有助于生成推文。

此外，您可以保存用于语气和受众的字符串，然后在后续推文请求中重复使用它们。

让我们来看看我的基本 API 开发工作流程。

单独行动：我的单独工作流程

我工作流程的第一步是设计 API并编写 OpenAPI 规范。在 Postman 中，我创建了一个新的 API，然后开始了一个新的 API 定义。

经过一番思考（并直接使用 ChatGPT，这对于根据我的描述生成初始 OpenAPI 规范非常有用），我编写了规范：

当我的 OpenAPI 规范就位后，我来到了岔路口。我是否应该设置一个模拟服务器以及一些示例请求和响应来展示与此 API 交互的情况？或者我应该开始编写实现代码？

作为一名独立开发人员，我在任何给定时间只能是 API 生产者或 API 消费者。所以我决定：不需要构建模拟——我的消费者必须等待。让我们写一些代码吧！

几分钟后……

使用 Node.js 和 Express 并与 PostgreSQL 数据库通信，我实现了基本的 API。以下是我需要构建的所有内容的概要：

• POST /signin接受username和password ，根据数据库中的记录进行身份验证，然后返回签名的 JWT，该 JWT 可在所有后续请求中使用。
• POST /generateTweet生成一条（最多 280 个字符）的推文。它需要一个topic （字符串）和一个goal （字符串）。它还采用tone （字符串）或toneId （存储的音调的整数ID），以及audience （字符串）或audienceId （存储的受众的整数ID）。每当提供tone和/或audience字符串时，API 都会将它们保存到数据库中。
• GET /tones返回音调 ID 和相应字符串的列表。 GET /audiences对可重用受众字符串执行相同的操作。
• DELETE /tones获取音调 ID 并删除该音调记录。 DELETE /audiences对观众记录执行相同的操作。

初始实现完成后，是时候返回 Postman 开始运行一些请求了。

创建一个带有变量的环境。

首先，我创建了一个名为“测试”的新环境。我添加了变量来存储我的root_url以及有效的username和password 。

创建集合和请求

然后，我创建了一个新集合并添加了我的第一个请求：对/signin POST请求，以尝试身份验证。

当我的 API 服务器在终端窗口中运行时，我发送了第一个请求。

成功！我得到了我的令牌，我在以后的任何请求中都需要它。

我创建了一个新请求，这次是为了生成一条推文。

我确保将授权设置为使用“承载令牌”，并且提供了刚刚从上一个请求收到的令牌。

这是回应：

有用！

总结单独方法

这是我个人工作流程的基本概览。当然，在此过程中我还会做一些其他的事情：

• 编写预请求脚本来执行/signin请求，然后根据响应中的令牌设置环境变量。
• 为 OpenAPI 规范中的所有其他端点创建请求。
• 为每个端点编写测试，确保涵盖我的边缘情况。

如果我独自工作，这个基本工作流程让我非常接近终点线。虽然这很好，但我知道我可能只是触及了 Postman 中可用功能的表面。我知道，如果我在一个团队中工作，我需要 Postman 提供更多帮助。

顿悟时刻：为什么要考虑团队使用 Postman？

如果我不再是 X Nihilo 的独立 API 开发人员怎么办？发生这种情况的原因有多种：

• X Nihilo 的规模和复杂性不断增长，单个 API 开发人员已不足以支持它。
• X Nihilo 只是涉及多个 API 开发人员甚至多个 API 团队的大型 API 项目的一小部分。

并非我为客户提供的所有 API 项目都是可以自己构建的小型项目。有时，我需要成为构建 API 的团队的一员。我什至可能需要领导 API 团队。

当这种情况发生时，我需要放弃我单独的思维方式，并放弃我在 Postman 中单独做事的方式。这促使我研究 Postman 的团队相关功能。

探究Postman的团队（企业）特点

Postman 有一个免费套餐，它提供了一些有限的协作功能，如果您是一个小团队（意味着不超过三个开发人员），这可能就足够了。作为其 Enterprise Essentials 层的一部分，Postman 还具有其他功能。这些对于全面使用 Postman 的大型组织中的 API 团队来说非常有用。

工作空间共享

工作区可让您的团队在多个 API 项目上进行协作。如果您有不同的团队处理不同的 API，但这些 API 相互交互（这在大型软件组织中通常是这种情况），那么这非常有用。

工作空间非常适合实现实时协作。团队成员可以编辑 API 文档，共同处理请求或编写测试，并构建整个团队都可以使用的模拟服务器。进行编辑后，它们会实时与整个团队同步。

版本控制

虽然我关心代码的版本控制，但作为一名独立 API 开发人员，我不太关心 Postman 集合或环境的版本控制。如果我更改某些内容（修改请求、更新测试、删除环境变量），我是唯一受影响的人。没什么大不了。

当你在团队中工作时，你肯定想知道事情何时发生变化。有时您需要回滚更改。幸运的是，对于使用 Postman Enterprise 的团队， Postman允许您访问集合、工作区和 API 的变更日志。您可以将集合回滚到较早的时间点。作为团队中的 API 开发人员，您将需要这个。大多数时候，这是因为鲍勃搞砸了收藏。但有时，你就是鲍勃。

基于角色的访问和用户组织

并非 Postman 工作区中的每个人都应该具有相同级别的权限。一些团队成员是测试人员，他们只需要能够发送请求和运行测试，而不需要修改它们。其他人可能是只允许修改 API 定义的设计人员。

在 Postman 中，您可以为团队成员分配角色。这会影响每个团队成员在团队或工作区中拥有的访问类型和权限级别。

团队还可以拥有私人工作空间，限制团队外部其他人的访问。

我还注意到 Postman Enterprise 支持“域捕获”。这基本上意味着您可以通过向来自（例如） mycompany.biz域的每个人授予访问权限来设置组织中的所有用户。

内嵌评论和讨论

Postman 确实有一项协作功能，该功能在其所有计划中都可用，而不仅仅是其 Enterprise Essentials。这是团队成员向集合（文件夹、请求、示例或拉取请求）添加评论的能力。能够直接在 Postman 中发表评论和讨论对于团队 API 开发来说非常重要。由于团队的大部分 API 开发工作将在 Postman 中进行，因此在那里进行讨论（而不是在 GitHub 或其他外部服务中）是有意义的。

团队 API 开发：Postman 致胜

每当我加入团队时，我都会带来我喜欢使用的工具，但我不会真正将它们强加给我的队友。我想他们有自己的工具。所以，对于每个人来说。但我有一种感觉，大多数 API 开发人员的工具箱里都有 Postman。如果一个团队中的多个 API 开发人员都以单独的心态单独使用 Postman，并且没有利用其中的一些团队功能，那将是一种耻辱。如果他们利用 Postman Enterprise 功能，他们将获得……

提高效率

在共享工作区中，您可以从共享 API 定义开始。每当团队成员编辑定义（或文档、测试或环境）时，编辑都会同步，每个人都拥有最新和最好的。

每个人都处理集合中的同一组请求，并且每个人都可以访问将使用的所有测试。所有这些便利都将提高团队的效率，进而提高他们的开发速度。

减少误会

当每个人都在同一个事实来源（您的工作空间）工作时，他们可以在他们用于开发的工具中发表评论和交谈，这将减少误解。您的团队不会浪费时间来混淆该端点是否应该接受查询参数或路径参数。一切都会清楚的。

要点

我不知道Postman是为团队和企业服务的。现在我知道了，这是我的一大收获：团队合作者使用对团队有利的工具。

当我是一名单独的 API 开发人员时，Postman 对我来说非常有用。幸运的是，它还有一些功能，当我在 API 开发团队工作时，它对我来说非常有用。对我来说，这就是集合、变更日志和版本控制中编辑的实时同步，以及细粒度的访问权限。现在，我很高兴能够与更大的团队一起承担更大的 API 项目。

快乐编码！

也发布在这里。