新手测试必学的 API 接口文档知识

短命女 2024-03-23 12:16 88阅读 0赞

### 什么是接口文档？ ###

当你第一次需要将电脑连接至屏幕时，可能会被各种接口和线缆弄得一头雾水。HDMI、VGA、DVI、DisplayPort……这些名词听起来都十分专业，高深莫测。但实际上它们就像是电脑和外接设备之间的“桥梁”，帮助它们互相沟通和交流。

其中，HDMI 接口可谓是应用范围最广的一种。它不仅可以将电脑与电视连接，也可以连接显示器和投影仪等其他设备。当小 A 购买了一台新的电脑后，他想要将显示画面投射至一块色准极佳的屏幕上加以扩展。此时，他只需要使用 HDMI 线将屏幕与电脑的 HDMI 接口连接，然后像魔术般，黑漆的屏幕瞬间有了灵动的画面。

![01fb5a5919286df5b8e5ddc71dde71b1.png][]

真的好像变魔术一样，小 A 并不需要知道屏幕与电脑之间的画面是靠着什么参数进行传递的，也无需理解屏幕色彩显示的逻辑原理，只需掌握简单 HDMI 接口的使用方法就能够满足自己的需求。**这也说明了现代科技的一个重要特点：用户无需了解技术实现细节，只需要简单、方便地使用就能够达到自己的目的。**

另一方面，与 HDMI 类似，[API][]（Application Programming Interface，应用程序接口）也是一种“桥梁”。它让不同的软件程序之间互相沟通和交流，从而实现更加复杂的功能。两个产品相互遵循同一套信息通讯协议，配对成功后将多个功能相互集成，协同发挥作用，起到 1+1 > 2 的效果。

虽然现代科技十分方便，但是当用户第一次接触应用中的复杂功能时，通常需要一份清晰、详细的功能说明书来帮助了解接口的工作方式。这就是 API 接口文档的作用。**它不仅可以帮助用户了解接口的工作原理，还提供了使用 API 所需的所有信息，让用户能够更加方便、快速地使用软件功能。**

### 测试工程师为什么需要了解接口文档？ ###

了解接口文档对于开发人员和测试人员来说都非常重要，它可以帮助他们更好地进行开发和[测试][Link 1]工作，提高开发和测试效率和质量。一个能够承载大量用户访问的现代应用程序，其架构复杂性好比物理世界中的一幢摩天大楼。它的功能通常是由多个功能组件组成，包括前端界面、后端逻辑等。接口作为不同组件之间的桥梁，负责将不同组件的功能组合起来，实现整个应用程序的功能。

这些接口对于整个系统的稳定性和可靠性非常重要，测试工程师需要深入了解接口的设计和实现细节，以便能够有效地设计和执行测试用例，保证接口的正确性和可靠性。毫不夸张的说，测试工程师的大部分工作时间不是在验证接口功能的完整性上，就是在对着接口文档设计相关测试用例。

常用的功能接口通常是不稳定和易受外部影响的部分，需要经常进行测试和监控。测试工程师需要密切关注接口的变化和演化，及时更新测试用例和测试策略，以确保系统的稳定性和可靠性。

测试工程师对于团队协作而言也同样重要，他们需要与开发人员和其他团队成员密切合作，共同保证接口的正确性和可靠性；及时报告和跟踪接口缺陷，确保开发人员能够及时修复缺陷并进行验证。

### 测试工程师如何阅读 API 接口文档？ ###

一份设计得当的接口文档通常包含以下要点：

1.  **接口简介（接口干嘛用？）**
2.  **接口请求协议（接口怎么用？）**
3.  **请求地址源**
4.  **请求方式**
5.  **请求参数**
6.  **返回参数示例（使用接口后得到的返回结果是什么？）**
7.  **状态码**

#### 1. **接口简介** ####

接口可以帮助开发者更好地理解接口，提高开发效率和代码质量，接口的维护者应在文档首页准确说明该接口的用途。

![71979622b4ac9df3630751156e4c88aa.png][]

#### **2. 接口请求协议** ####

请求协议本质上是互联网的通讯协议，用以规范各服务间的数据传输与交流方式。在 API 接口中，常见的请求协议有 HTTP、HTTPS、FTP。请求协议是各项 API 接口进行通讯的基础，只有双方共同遵循同一套语言规则才有沟通的可能。

![078a5ecb8d5275007e84cd8812b1c7da.png][]

#### **3. 请求地址源** ####

上街买东西需要找到商铺地址定位。同理，请求地址源就是用来告诉用户在哪个地点可以找到接口的服务方，常见的接口地址为域名或 IP 地址。

![ec375d6489349a510ba2548d9b8b6d50.png][]

#### **4. 请求方式** ####

面对接口的功能，应该采取何种方式进行使用？数据的处理无外乎增删查改四种方法，常见的 API 请求方法包括：新增 (POST)、修改 (PUT)、删除 (DELETE) 和获取 (GET)。

![1b5f0de3c740b8090fc96020bf34b349.png][]

#### **5. 请求参数** ####

了解接口大致的功能与使用方法后，现在需要请求方按照特定的格式填写请求内容。API 接口的本质是预先定义好的函数逻辑，例如某项接口主要提供计算功能，此时需求方希望得到输入 1+1 后的计算结果，其中 1+1 就是请求参数。

![7b01ad262dd97e76ae6a397ce393d365.png][]

#### **6. 返回参数示例** ####

需求方根据接口文档发起请求后，如何判断接口是否收到了请求，并且返回了正确的结果？此时便需要接口提供方提供返回参数示例，它可以帮助使用者更好地理解接口的使用方法和参数格式，减少请求参数填写错误的可能性。

![0906abc65903b10d90d04a85d20aa80f.png][]

#### **7. 状态码** ####

状态码在 API 接口中用于快速向请求方反馈当前请求的处理结果。状态码常见于接口功能异常的场景，好比未接通手机时出现的统一回应模板。

状态码是一个三位数字，第一位数字表示响应类别，后面两位数字是一个自定义的代码，用于具体表示响应的状态。例如，200 表示请求成功，404 表示请求的页面不存在等等。状态码是 API 接口文档中的重要部分，它们可以帮助开发者更好地调试和测试自己的应用程序。

![61a38a80b99953ca1a178cc1e442abda.png][]

### 测试工程师如何基于接口文档开展工作？ ###

如果你作为一个测试工程师正在着手于为你的项目编写接口测试用例，你需要注意以下几点：

#### 1. **仔细阅读接口文档** ####

在编写测试用例之前，你需要仔细阅读接口文档，了解接口的功能、参数、响应等信息，以便准确地编写测试用例。如果你对接口文档中的某些信息存在疑问，可以随时向开发人员或产品经理进行询问。

#### 2. **设计全面的测试用例** ####

在编写测试用例时，你需要设计全面的测试用例，覆盖接口的各种情况，包括正常情况、异常情况、边界情况等。这样可以确保接口的正确性和稳定性。

#### 3. **使用专业的接口测试工具** ####

在进行接口测试时，你需要使用专业的接口测试工具，例如 [Apifox][]、SoapUI 等。这些工具可以帮助你快速地构建请求、检查响应、进行断言等操作，提高测试效率。

#### 4. **及时记录测试结果** ####

在进行接口测试时，你需要及时记录测试结果，包括测试用例的执行情况、接口的响应情况等。这些记录可以帮助你更好地追踪问题，及时定位和解决接口问题。

了解接口文档对测试工程师来说非常重要，它可以帮助你更好地进行接口测试，提高测试效率和测试质量。如果你还不熟悉接口测试，你还可以额外学习一些接口测试的基本知识，例如 HTTP 协议、**[RESTful API][]** 等。

### 知识扩展： ###

关于 API 知识，可点击下方链接了解更多。

*  **[高效实用的方法，让程序员爱上写接口文档][Link 2]**
 *  **[如何写一份合格的 API 文档？][API 1]**

[01fb5a5919286df5b8e5ddc71dde71b1.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/1a5282e4ec0749629485dc5b28a091cf.png
[API]: https://apifox.com/apiskills/understanding-apis/
[Link 1]: https://apifox.com/apiskills/introduction-to-api-testing/
[71979622b4ac9df3630751156e4c88aa.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/4fb2ebe71623435f9bd7a5bf5f5080e0.png
[078a5ecb8d5275007e84cd8812b1c7da.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/05b680149b4947ce91d1196874023a85.png
[ec375d6489349a510ba2548d9b8b6d50.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/c2924b2830374b7dae88121dd451ae94.png
[1b5f0de3c740b8090fc96020bf34b349.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/a13f0155664a4fb992d68f183deb4b52.png
[7b01ad262dd97e76ae6a397ce393d365.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/7327e7e2c8b6459fb4e5106586add846.png
[0906abc65903b10d90d04a85d20aa80f.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/86030fa95d2640cfb79656e4a686e53b.png
[61a38a80b99953ca1a178cc1e442abda.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/40292f3a8dce40e085b26d648818d823.png
[Apifox]: https://apifox.com/
[RESTful API]: https://apifox.com/apiskills/rest-api/
[Link 2]: https://apifox.com/apiskills/love-writing-api-documents/
[API 1]: https://apifox.com/apiskills/qualified-api-documentation/