Postman Essentials: Exploring the Collection Format

如果你是在使用Postman的2000万用户之一，那么你一定以某种方式使用过Postman集合。集合是组织API请求的绝佳方式，它们允许开发人员轻松创建、共享和协作不同的API。集合几乎可以用于任何API工作流程，无论是模拟、监控、测试还是记录API。但是集合如何能够做这么多事情呢？让我们仔细看看集合到底是什么。

注意：本文中同时使用了“集合”和“集合格式”这两个术语。它们的含义相同，但使它们看起来不同的是我们使用它们的上下文。例如，当在Postman中工作时，我们使用“集合”这个词，但当讨论导出的集合时，我们使用“集合格式”这个短语。

什么是集合格式？

集合格式是一种开源的JSON格式，它让我们能够组织API请求并在API生命周期中无缝工作。集合提供了机器可读和人类可读的API表示，这些表示是可移植、可共享和可执行的。你还可以定义API的不同参数和方面。这类似于你可以使用其他API定义格式（如OpenAPI和RAML）所做的事情，不同之处在于集合格式允许你为API创建工作流程并在其整个生命周期中工作。将集合视为API引擎是有帮助的——一个帮助你在整个生命周期中驱动API的引擎。

大多数时候，我们不需要考虑集合是如何工作的，除非我们需要执行低级任务。例如，如果你曾经从Postman中导出过一个集合，你会注意到导出的JSON文件包含了关于你集合的所有信息。将这个文件重新导入Postman可以帮助你从上次离开的地方继续处理你的请求、文档、环境、变量、模拟、请求头、测试和预请求脚本。

集合结构如下所示：

[按Enter键或单击以全尺寸查看图像]

集合的基本结构

一个非常基本的JSON集合看起来像这样：

1
2
3
4
5
6
7
8

{
  "information": {
    "name": "My Collection",
    "description": "This is a demo collection.",
    "schema": "https://schema.postman.com/collection/json/v2.1.0/draft-07/collection.json"
   },
  "item": []
}

在顶层，集合有两个主要属性：“information”和“item”。“information”属性包含关于集合的通用元数据，例如其名称、描述和模式。“item”是集合的基本构建块。它允许你指定一个请求、其对应的响应以及相关的元数据。一个item可以是一个对象或不同item的数组。当它是一个数组时，它包含一些额外的元数据，并被称为“item-group”。你可以将“item-group”视为一个item文件夹，它可以选择性地拥有自己的名称、描述和事件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "id": "an-item-example",
  "name": "First Folder",
  "description": "This is an ItemGroup(folder) that contains two items",
  "item": [
    {
      "id": "1",
      "name": "Item A",
      "request": "https://postman-echo.com/get"
    },
    {
      "id": "2",
      "name": "Item B",
      "request": "https://postman-echo.com/headers"
    }
  ]
}

在上面的代码片段中，item的“request”属性的值是一个URL。然而，item的“request”属性的值远不止是一个URL；它是一个对象，可用于表示API请求的其他部分，例如请求头、主体以及成功发出API请求所需的任何其他内容。下面的代码片段显示了一个请求的基本结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "description": "This is a sample POST request",
  "url": "https://postman-echo.com/post",
  "method": "POST",
  "header": [
    {
      "key": "Content-Type",
      "value": "Application/JSON"
    },
    {
      "key": "host",
      "value": "postman-echo.com"
    }
  ],
  "body": {
    "mode": "urlencoded",
    "urlencoded": [
      {
        "key": "some-variable",
        "value": "Something awesome!"
      }
    ]
  }
}

我们已经介绍了请求在JSON中的基本示例，但集合可以表示的内容远不止这些，例如API响应、测试和文档。

为什么集合有用？

集合有很多用例，这些用例根据它们运行的环境和运行它们的人的需求而变化。以下是Postman集合对许多开发人员变得至关重要的一些原因：

API合同的基础

API合同是API生产者和消费者之间的正式业务协议。它是关于API预期提供什么的共同理解。集合是Postman中每个API合同的基础，因为它们的简单性、可读性和易用性使它们非常适合用于此目的。

API生命周期管理

如果你曾经使用过API优先方法，你会理解轻松跨越API生命周期的能力对你构建的API质量非常关键。集合赋予你这种能力，并提供一个独特的界面，让你轻松表示API的不同阶段。

集合具有高度可移植性

集合具有直观的结构和极其可移植的格式，可以在不同环境中共享和使用而不会失去功能。集合如此可移植的部分原因是集合中的所有内容都被划分为可以在集合中其他地方重用的子单元。

集合适用于不同的规范

在工具的帮助下，集合具有很好的互操作性。你可以将集合转换为OpenAPI定义，反之亦然。在Postman的API构建器中，你可以以各种格式（如OpenAPI和GraphQL）导入你的API定义，并使用它们生成用于不同目的的集合，包括模拟、文档和测试。

如何运行集合？

我们上面讨论的集合的互操作性和可移植性允许它们在具有各种工具的任何环境中运行。例如，集合可以运行在：

命令行上，使用Newman或Postman CLI

Newman是一个命令行界面（CLI）工具，允许你在命令行环境中运行集合。你可以使用它来运行测试并将其与你的CI/CD流水线集成。Newman也可以作为JavaScript库运行。

或者，你可以使用Postman CLI，它使你能够运行你的集合，执行治理和安全检查，并轻松从命令行测试你的API。它与你的Postman帐户同步，并将你的运行报告上传回Postman，允许你在一个地方完成所有自动化测试和流水线运行。

在你的代码中，使用Postman Runtime

Postman Runtime是Postman内部使用的开源NodeJS库，允许开发人员无缝地与集合一起工作。它比Newman更底层；事实上，Newman是建立在它之上的。Postman Runtime允许你运行集合，同时让你能够指定超时、严格SSL、主机查找、代理、证书列表等参数。Postman中的集合运行器也使用Postman Runtime来运行你的集合。

使用Postman API和webhooks

你可以使用Postman API创建一个webhook，让你通过向其发送请求来启动集合运行。如果你正在运行一些自动化，并且希望响应特定事件触发集合运行，这将特别有用。

集合可以做的远超过大多数人的想象；使用这种格式可以构建和实现很多功能。该模式完全开源，可以在GitHub上找到。

最初发布于 https://blog.postman.com，2022年9月29日。