全网最详细的Postman使用指南（2024最新版）_postman使用手册

一、前言：为什么选择Postman？

在当今前后端分离的开发模式下，API 已成为不同系统间通信的核心纽带。而 Postman 作为全球超过 2500 万开发者信赖的工具，早已成为 API 开发测试领域的“瑞士军刀”。以下是它脱颖而出的关键原因：

---

1. API 开发测试的行业标准工具

• 开发者生态统治力
  Stack Overflow 调查显示，83% 的开发者将 Postman 作为首选 API 工具，其地位如同 Java 界的 IntelliJ IDEA、前端界的 VS Code。从硅谷科技巨头到初创团队，Postman 的身影无处不在。

• 全链路覆盖能力
  从早期接口调试到自动化测试，从文档生成到 Mock 服务，甚至 API 性能监控——Postman 提供从设计到运维的全生命周期支持，完美替代传统的 curl + jq 命令行组合。

• 社区资源丰富性
  拥有超过 10 万个公开 API 集合（如 Twitter、GitHub 官方接口模板），开发者可直接导入使用，无需从零造轮子。

---

2. 适合多角色协作的终极武器

• 前端开发者
  无需等待后端接口完成，通过 Mock Server 模拟响应数据，并行开发页面逻辑。例如：

// 提前定义 Mock 规则pm.mock({ \"data\": { \"user\": \"{{$randomUserName}}\", // 动态生成测试数据 \"avatar\": \"https://picsum.photos/200\" // 随机图片地址 }});

• 后端工程师
  一键生成代码片段（Python/Java/Go 等），快速验证接口逻辑。调试时可直接查看请求头、Cookie、响应时间等细节，告别 System.out.println 的原始调试方式。

• 测试工程师
  通过 Collection Runner 批量执行测试用例，结合 Newman CLI 工具集成到 CI/CD 流水线，实现自动化回归测试。例如电商场景：

✅ 用户登录 → 获取 Token  
✅ 查询商品 → 验证分页逻辑  
✅ 提交订单 → 检查库存扣减  
✅ 支付回调 → Mock 第三方支付 

3. 跨平台无缝体验

• 全平台覆盖
  原生支持 Windows/macOS/Linux 系统，配合 Postman Web 版 实现浏览器端操作。团队中混合使用不同操作系统的开发者无需适应新工具。

• 多端数据同步
  通过 Workspace 功能实时同步测试集合、环境变量，在办公室的 Windows 台式机与家里的 MacBook 之间无缝切换，工作进度永不丢失。

• 移动端支持
  提供 iOS/Android 客户端，支持在手机上快速查看 API 文档或执行简单测试，满足移动办公需求。

---

4. 为什么不是其他工具？（对比竞品）

工具 痛点 Postman 优势 cURL 命令行操作繁琐，无可视化 图形化界面直观，支持一键生成 cURL 命令 Swagger UI 仅能测试已部署的 API 支持本地调试，无需部署即可测试 Insomnia 团队协作功能薄弱 完善的权限管理和版本控制 JMeter 侧重性能测试，接口调试笨重 专为 API 调试优化，学习曲线平缓

---

5. 从新手到专家的成长路径

无论您是：

• 🟢 入门者：通过自动补全和智能提示快速上手

• 🟡 进阶用户：利用 Pre-request Script 实现动态签名

• 🔴 专家级：通过 Postman API 开发自定义插件

Postman 都提供了对应的能力支持，其 分层学习体系 让每个开发者都能找到适合自己的使用场景。

---

🚀 现在开始，跟着本文的步骤，您将在 30 分钟内掌握 Postman 的核心操作，从此告别“前后端扯皮”，让 API 开发效率提升 200%

二、基础篇：快速上手

1. 安装与配置

各平台安装方法（含汉化技巧）

• Windows：
  • 访问 Postman 的官方下载页面（Download Postman | Get Started for Free ）。
  • 选择适用于 Windows 的安装包（32 位或 64 位）进行下载。
  • 下载完成后，双击安装包文件，按照安装向导的提示完成安装，一般只需不断点击 “下一步” 直至安装结束。
• macOS：
  • 同样在官方下载页面，选择 macOS 版本的安装包进行下载。
  • 下载完成后，打开下载的.dmg 文件，将 Postman 图标拖移到 “应用程序” 文件夹即可完成安装。
• Linux：
  • Debian/Ubuntu：可以使用以下命令通过命令行安装。

bash

sudo apt updatesudo apt install postman

• Fedora：使用如下命令。

bash

sudo dnf install postman

• 汉化技巧：打开 Postman，点击右上角的齿轮图标，选择 “Settings”，在 “General” 选项卡中找到 “Language”，选择 “中文 (简体)”，然后重启 Postman，界面就会变成中文。

界面布局详解（请求区 / 响应区 / 历史记录）

• 请求区：通常位于界面的上半部分或者左侧。这里是构建 API 请求的核心区域，你可以在此选择请求方法（如 GET、POST、PUT、DELETE 等），输入请求的 URL 地址。还能对请求头（Headers）、查询参数（Params）、请求体（Body）等进行设置。例如，若要在请求中添加自定义的请求头信息，可在 Headers 区域添加键值对。
• 响应区：一般在界面的下半部分或者右侧。当你发送请求后，响应区会显示服务器返回的结果。它包含响应的状态码、响应头和响应体。状态码能让你快速了解请求的结果状态，响应头包含了服务器返回的一些元信息，响应体则是服务器返回的具体数据内容。
• 历史记录：通常在界面的侧边栏或者下方区域。它记录了你之前发起的所有请求，方便你快速重复之前的请求操作。你可以对历史记录中的请求进行编辑、重新发送等操作，还能根据时间、请求方法等进行筛选。

账号体系说明（本地模式 vs 云同步）

• 本地模式：不登录账号也能使用 Postman 的基本功能。在本地模式下，你创建的请求、环境变量等数据都保存在本地计算机上。适合个人开发者在单机环境下进行简单的 API 调试，数据不会与云端进行交互。
• 云同步：注册并登录 Postman 账号后，开启云同步功能。此时，你在 Postman 中创建的所有请求、集合、环境配置等信息都会同步到云端。这意味着你可以在不同的设备上登录账号后继续使用之前的配置，方便跨设备开发。同时，云同步还支持团队协作，团队成员可以共享工作区和相关的 API 资源。

2. 发起第一个 API 请求

GET 请求实战（查询天气 API 示例）

以下以使用心知天气的 API 查询天气为例（使用前需在心知天气官网注册获取 API Key）。
步骤如下：

1. 打开 Postman，在请求区的请求方法下拉框中选择 “GET”。
2. 输入 API 的 URL，例如：https://api.seniverse.com/v3/weather/now.json?key=your_api_key&location=beijing&language=zh-Hans&unit=c，将your_api_key替换为你自己的 API Key。
3. 点击 “Send” 按钮发送请求。
4. 在响应区查看响应结果，能看到北京当前的天气状况等信息。

POST 请求实战（模拟用户注册）

假设我们有一个简单的用户注册 API，地址为http://example.com/api/register。
步骤如下：

1. 在请求区选择请求方法为 “POST”。
2. 输入 API 的 URL：http://example.com/api/register。
3. 切换到 “Body” 选项卡，选择 “raw” 格式，并选择 “JSON (application/json)” 类型。
4. 在输入框中输入如下 JSON 格式的用户注册信息：

json

{ \"username\": \"testuser\", \"password\": \"testpassword\", \"email\": \"test@example.com\"}

1. 点击 “Send” 按钮发送请求。
2. 在响应区查看服务器返回的注册结果。

解读响应结果（状态码 / Body/Headers）

• 状态码：是三位数字的代码，用于表示请求的结果状态。常见的状态码及含义如下：
  • 200：表示请求成功，服务器正常处理了请求并返回了数据。
  • 400：表示客户端请求有语法错误，不能被服务器所识别。
  • 401：表示请求未经授权，需要进行身份验证。
  • 404：表示请求的资源不存在。
  • 500：表示服务器内部错误，无法完成请求。
• Body：服务器返回的具体数据内容。其格式可能是 JSON、XML、文本等。例如，在上述天气查询的响应体中，可能包含天气状况、温度等信息；在用户注册的响应体中，可能包含注册是否成功的提示信息。
• Headers：包含了服务器返回的一些元信息，如Content-Type表示响应体的内容类型，Cache-Control用于控制缓存策略等。通过查看 Headers，可以了解服务器的一些配置和响应的相关特性。

3. 请求参数全解析

Query Params：/users?page=1

• 定义与用途：查询参数（Query Params）是附加在 URL 后面的键值对，用于向服务器传递额外的信息，通常用于筛选、分页等操作。它们以问号 ? 开始，多个参数之间用 & 分隔。
• 示例：在请求 /users?page=1 中，page 是参数名，1 是参数值，表示请求第一页的用户数据。如果还需要指定每页显示的记录数，可以添加 limit 参数，如 /users?page=1&limit=10。
• 在 Postman 中的设置：在 Postman 的请求区，输入 URL 后，点击 “Params” 按钮，在弹出的表格中添加参数名和参数值，Postman 会自动将其添加到 URL 后面。

Path Variables：/products/{id}

• 定义与用途：路径变量（Path Variables）是 URL 路径中的一部分，用于表示特定的资源标识。它们通常用花括号 {} 括起来，在请求时需要替换为实际的值。
• 示例：在请求 /products/{id} 中，{id} 是路径变量，表示要请求的产品的 ID。当请求具体的产品时，需要将 {id} 替换为实际的产品 ID，如 /products/123 表示请求 ID 为 123 的产品信息。
• 在 Postman 中的设置：在 Postman 的请求区输入包含路径变量的 URL，如 /products/{id}，然后在 “Params” 中添加 id 参数并设置其值，Postman 会自动将路径变量替换为实际的值。

Headers：Content-Type/Authorization

• 定义与用途：请求头（Headers）是包含在 HTTP 请求中的额外信息，用于向服务器提供关于请求的元数据，如请求的内容类型、授权信息等。
• 常见请求头示例：
  • Content-Type：用于指定请求体的内容类型。常见的值有 application/json 表示请求体是 JSON 格式的数据，application/x-www-form-urlencoded 表示请求体是表单编码的数据，multipart/form-data 用于上传文件等。例如，当发送 JSON 格式的请求体时，需要设置 Content-Type: application/json。
  • Authorization：用于提供身份验证信息，常见的认证方式有基本认证（Basic Authentication）、Bearer Token 认证等。例如，使用 Bearer Token 认证时，请求头可以设置为 Authorization: Bearer your_token，其中 your_token 是实际的令牌。
• 在 Postman 中的设置：在 Postman 的请求区，点击 “Headers” 按钮，在弹出的表格中添加请求头的键和值。

Body 类型对比

• raw：
  • 特点：可以发送任意格式的文本数据，如 JSON、XML、纯文本等。需要手动指定内容类型。
  • 适用场景：当需要发送 JSON、XML 等结构化数据时，使用 raw 类型并指定相应的内容类型（如 application/json、application/xml）。
  • 示例：在发送 JSON 格式的用户注册信息时，选择 raw 类型，指定 Content-Type: application/json，然后输入 JSON 数据：

json

{ \"username\": \"newuser\", \"password\": \"123456\", \"email\": \"newuser@example.com\"}

• x-www-form-urlencoded：
  • 特点：将请求体编码为表单数据，键值对之间用 & 分隔，键和值使用 URL 编码。
  • 适用场景：常用于传统的 HTML 表单提交。
  • 示例：在 Postman 中选择 x-www-form-urlencoded 类型，在表格中添加键值对，如 username=newuser&password=123456。
• form-data：
  • 特点：支持上传文件和表单数据，每个字段可以有不同的内容类型。
  • 适用场景：当需要上传文件时，使用 form-data 类型。
  • 示例：在 Postman 中选择 form-data 类型，添加字段时可以选择字段类型为 “File”，然后选择要上传的文件。
• binary：
  • 特点：用于发送二进制数据，如图片、视频等。
  • 适用场景：当需要直接发送二进制文件而不进行编码时，使用 binary 类型。
  • 示例：在 Postman 中选择 binary 类型，点击 “Select File” 按钮选择要发送的二进制文件。

三、进阶篇：高效工作流

1. 环境变量管理

多环境配置（Dev/Test/Prod）

在 API 开发与测试过程中，通常会涉及开发（Dev）、测试（Test）和生产（Prod）等不同环境。每个环境的 API 地址、数据库连接信息等可能不同，使用环境变量可以方便地在不同环境之间切换。

在 Postman 里，你可以创建多个环境，例如：

• 开发环境（Dev）：设置 API 的基础 URL 为 http://dev-api.example.com。
• 测试环境（Test）：设置 API 的基础 URL 为 http://test-api.example.com。
• 生产环境（Prod）：设置 API 的基础 URL 为 http://api.example.com。

这样在不同的环境下进行测试或开发时，只需切换环境，请求的 URL 等信息就会自动更新。

全局变量 vs 环境变量

• 全局变量：在 Postman 的任何环境中都可以使用，其作用域是整个 Postman 工作区。适用于那些在所有环境中都保持不变的信息，比如某个固定的 API 密钥。
• 环境变量：仅在特定的环境中有效。不同的环境可以有相同名称但不同值的环境变量，这对于区分不同环境下的配置非常有用。例如，不同环境的数据库连接字符串就可以通过环境变量来设置。

脚本动态修改变量

在 Postman 中，可以使用 JavaScript 脚本来动态修改变量。以下是设置变量的示例代码：

javascript

// 设置变量pm.environment.set(\"token\", responseJson.access_token);

这段代码的作用是将响应 JSON 数据中的 access_token 值赋给环境变量 token。之后在后续的请求中，就可以使用这个 token 进行身份验证等操作。

2. 自动化测试

Tests 标签页实战

在 Postman 中，每个请求都有一个 Tests 标签页，你可以在这个标签页中编写测试脚本，对请求的响应结果进行验证。

• 状态码断言：

javascript

pm.response.to.have.status(200);

此代码用于验证响应的状态码是否为 200。若状态码不是 200，测试将失败。

• 响应时间检测：

javascript

pm.expect(pm.response.responseTime).to.be.below(500);

该代码用于检查响应时间是否小于 500 毫秒。若响应时间超过 500 毫秒，测试将不通过。

• JSON 数据验证：

javascript

pm.expect(jsonData.user).to.be.an(\'object\');

此代码用于验证响应的 JSON 数据中 user 字段是否为一个对象。若不是对象，测试会失败。

测试集合运行

• 批量执行测试用例：可以把多个相关的请求组织成一个测试集合，然后批量执行集合中的所有请求及其对应的测试脚本。在 Postman 的左侧导航栏中选择测试集合，点击 “Run” 按钮，就可以开始批量执行测试用例。
• 生成 HTML 测试报告：使用 Newman（Postman 的命令行工具）可以生成详细的 HTML 测试报告。首先需要安装 Newman，命令如下：

bash

npm install -g newman

然后使用以下命令运行测试集合并生成 HTML 报告：

bash

newman run collection.json -e environment.json -r html --reporter-html-export report.html

其中，collection.json 是测试集合的文件，environment.json 是环境配置文件，report.html 是生成的 HTML 报告文件名。

3. Mock 服务搭建

5 分钟创建 Mock API

在 Postman 中创建 Mock API 非常简单，只需按照以下步骤操作：

1. 打开 Postman，在左侧导航栏中选择要创建 Mock API 的集合。
2. 点击集合名称旁边的三个点，选择 “Create Mock Server”。
3. 配置 Mock Server 的名称、描述等信息，选择要模拟的请求。
4. 点击 “Create Mock Server” 按钮，Postman 会自动生成一个 Mock API 的 URL。

之后，你就可以使用这个 URL 来模拟 API 的响应，而无需依赖实际的后端服务。

动态响应模板

Mock API 支持使用动态响应模板来生成随机数据。以下是一个示例：

json

{ \"id\": {{$randomInt}}, \"name\": \"{{$randomFirstName}}\"}

在这个模板中，{{$randomInt}} 会生成一个随机整数，{{$randomFirstName}} 会生成一个随机的名字。每次请求 Mock API 时，都会返回包含不同随机数据的响应。这样可以模拟各种不同的响应情况，方便进行测试。

四、实战篇：Spring MVC 接口测试

1. 测试 RESTful 接口

带认证的请求

在 Spring MVC 应用里，RESTful 接口常需认证才能访问，常见认证方式有基于 JWT（JSON Web Token）、OAuth、Session/Cookie 等。这里着重介绍基于 Session/Cookie 的认证测试。

Session/Cookie 测试技巧：

• 登录请求：先发送登录请求到 /login 接口，用 form-data 或者 raw（JSON 格式）传递用户名和密码。示例请求如下：

• 后续请求：登录成功后，服务器会返回包含 Session 信息的 Cookie，后续请求会自动携带该 Cookie 完成认证。在 Postman 里，它会自动管理 Cookie，所以后续请求无需额外配置。若用代码实现，在后续请求中设置 withCredentials: true 即可。示例如下：

// 假设使用 Axios 发送请求const axios = require(\'axios\');const loginData = { username: \'testUser\', password: \'testPassword\'};axios.post(\'http://localhost:8080/login\', loginData) .then(response => { console.log(\'登录成功\', response.headers); // 这里可获取 Cookie 信息 }) .catch(error => { console.error(\'登录失败\', error); });

javascript

axios.get(\'http://localhost:8080/protectedResource\', { withCredentials: true }) .then(response => { console.log(\'访问受保护资源成功\', response.data); }) .catch(error => { console.error(\'访问受保护资源失败\', error); });

2. 文件上传测试

form-data 文件字段设置

在 Spring MVC 中，文件上传一般使用 form-data 格式。在 Postman 里进行文件上传测试，步骤如下：

1. 选择请求方法为 POST。
2. 输入文件上传接口的 URL，如 http://localhost:8080/upload。
3. 切换到 Body 选项卡，选择 form-data 类型。
4. 添加一个字段，把字段类型设为 File，然后选择要上传的文件。
5. 若还有其他表单字段，接着添加并设置对应的值，如 description 字段。

批量上传测试脚本

可借助 Postman 的集合运行器和脚本功能实现批量文件上传测试。示例脚本如下：

javascript

// 假设文件存储在本地一个目录中const filePaths = [ \'path/to/file1.txt\', \'path/to/file2.txt\', \'path/to/file3.txt\'];filePaths.forEach((filePath) => { pm.sendRequest({ url: \'http://localhost:8080/upload\', method: \'POST\', header: { \'Content-Type\': \'multipart/form-data\' }, body: { mode: \'formdata\', formdata: [ {  key: \'file\',  value: pm.variables.replaceIn(`{{${filePath}}}`),  type: \'file\' }, {  key: \'description\',  value: \'Test file upload\' } ] } }, (err, res) => { if (err) { console.log(err); } else { console.log(res.json()); } });});

将上述脚本放在 Postman 的 Pre-request Script 中，就能实现批量文件上传测试。

3. 数据库联动测试

前置脚本连接 MySQL 验证数据

在测试接口前，可使用 Postman 的前置脚本连接 MySQL 数据库，验证数据是否符合预期。示例脚本如下：

javascript

const mysql = require(\'mysql\');// 创建数据库连接const connection = mysql.createConnection({ host: \'localhost\', user: \'root\', password: \'password\', database: \'testdb\'});// 连接数据库connection.connect((err) => { if (err) { console.error(\'Error connecting to database: \', err); } else { console.log(\'Connected to database\'); // 执行查询语句验证数据 const query = \'SELECT * FROM users WHERE username = ?\'; connection.query(query, [\'testUser\'], (err, results) => { if (err) { console.error(\'Error executing query: \', err); } else { console.log(\'Query results: \', results); pm.environment.set(\'userCount\', results.length); } // 关闭数据库连接 connection.end(); }); }});

将上述脚本放在 Postman 的 Pre-request Script 中，在发送请求前会先连接数据库并验证数据。

接口调用后断言数据库变更

接口调用后，再次连接数据库，查询相关数据并断言，验证数据库是否有预期变更。示例脚本如下：

javascript

const mysql = require(\'mysql\');// 创建数据库连接const connection = mysql.createConnection({ host: \'localhost\', user: \'root\', password: \'password\', database: \'testdb\'});// 连接数据库connection.connect((err) => { if (err) { console.error(\'Error connecting to database: \', err); } else { console.log(\'Connected to database\'); // 执行查询语句验证数据库变更 const query = \'SELECT COUNT(*) as count FROM users WHERE username = ?\'; connection.query(query, [\'newUser\'], (err, results) => { if (err) { console.error(\'Error executing query: \', err); } else { const count = results[0].count; const previousCount = parseInt(pm.environment.get(\'userCount\')); pm.expect(count).to.be.greaterThan(previousCount); } // 关闭数据库连接 connection.end(); }); }});

将上述脚本放在 Postman 的 Tests 标签页中，接口调用后会执行该脚本，验证数据库是否有预期变更。

五、团队协作篇

1. 共享 API 集合

生成可分享链接

在 Postman 中，你可以很方便地为 API 集合生成可分享的链接。具体步骤如下：

1. 打开你想要分享的 API 集合。
2. 点击集合名称旁边的三个点，选择 “Share collection”。
3. 在弹出的窗口中，选择 “Link” 选项。
4. 可以根据需要设置链接的有效期和权限（如只读或可编辑）。
5. 点击 “Generate link” 按钮，Postman 会生成一个唯一的链接。
   你可以将这个链接分享给团队成员或其他相关人员，他们通过点击链接就能访问该 API 集合。

权限控制（查看 / 编辑）

在生成分享链接时，你可以对链接的访问权限进行设置：

• 查看权限：设置为只读权限后，获得链接的人只能查看 API 集合的内容，无法对其进行修改。这适用于只想让他人了解 API 信息，而不希望他们随意更改的情况。
• 编辑权限：如果赋予编辑权限，获得链接的人可以对 API 集合进行修改、添加或删除请求等操作。这适合团队成员之间共同协作开发和维护 API 集合。

2. 生成在线文档

自动排版 Markdown

Postman 支持自动将 API 集合转换为 Markdown 格式的文档。操作步骤如下：

1. 打开要生成文档的 API 集合。
2. 点击集合名称旁边的三个点，选择 “View documentation”。
3. Postman 会自动为 API 集合生成文档，文档采用 Markdown 格式进行排版，包括请求的 URL、方法、参数、响应示例等信息。
4. 你可以在文档页面进行预览和编辑，确保文档内容准确无误。

添加代码示例

在生成的 API 文档中，你可以添加代码示例，帮助其他开发者更好地理解和使用 API。具体方法如下：

1. 在 API 文档页面，找到要添加代码示例的请求。
2. 点击请求下方的 “Code” 按钮，选择你想要展示的代码语言（如 Python、JavaScript、Java 等）。
3. Postman 会自动生成该请求的代码示例，你可以将其复制到文档中相应的位置。
4. 还可以对代码示例进行编辑和调整，使其更符合实际需求。

3. 监控与 CI 集成

定时监控 API 可用性

Postman 提供了 API 监控功能，可以定时对 API 进行请求，检查其可用性和性能。设置步骤如下：

1. 打开要监控的 API 集合。
2. 点击集合名称旁边的三个点，选择 “Monitor collection”。
3. 在监控设置页面，设置监控的频率（如每分钟、每小时、每天等）和要监控的环境。
4. 可以设置监控的通知方式，如邮件、Slack 等，当 API 出现问题时及时收到通知。
5. 点击 “Create monitor” 按钮，Postman 会按照设置的频率定时对 API 进行请求，并记录请求的结果和性能指标。

与 Jenkins/GitLab CI 对接

将 Postman 与 Jenkins 或 GitLab CI 集成，可以实现 API 测试的自动化。以下是集成的一般步骤：

与 Jenkins 集成

1. 安装 Newman 插件：Newman 是 Postman 的命令行工具，用于在命令行中运行 Postman 集合。可以使用以下命令进行安装：

bash

npm install -g newman

1. 在 Jenkins 中创建一个新的任务。
2. 在任务的配置中，添加一个 “Execute shell” 步骤（对于 Linux 系统）或 “Execute Windows batch command” 步骤（对于 Windows 系统）。
3. 在命令行中使用 Newman 运行 Postman 集合，示例命令如下：

bash

newman run /path/to/collection.json -e /path/to/environment.json

其中，/path/to/collection.json 是 Postman 集合的文件路径，/path/to/environment.json 是环境配置文件的路径。
5. 可以根据需要设置 Jenkins 的构建触发器，如定时构建或代码变更触发构建。

与 GitLab CI 集成：

1. 在项目的根目录下创建一个 .gitlab-ci.yml 文件。
2. 在 .gitlab-ci.yml 文件中添加以下内容：

yaml

stages: - testapi_test: stage: test image: node:latest script: - npm install -g newman - newman run /path/to/collection.json -e /path/to/environment.json

同样，需要将 /path/to/collection.json 和 /path/to/environment.json 替换为实际的文件路径。
3. 提交 .gitlab-ci.yml 文件到 GitLab 仓库，GitLab CI 会根据配置自动运行 API 测试。

六、postman常见问题排查

返回 401 Unauthorized（未授权）

核心原因：认证信息缺失、格式错误或 Token 失效

Postman 专属排查步骤：

1.检查认证头格式（以 Bearer Token 为例）

正确操作：
① 点击请求面板的 Authorization 标签页，选择 Bearer Token。
② 在 Token 输入框中填写完整的 JWT 令牌（无需手动添加 Bearer 前缀，Postman 会自动生成）。

常见错误：

• 误在 Headers 标签页手动填写 Authorization: （缺少 Bearer 前缀）。
• 令牌包含空格或特殊字符（需确保 Token 正确无误，可通过 JWT 解析工具 验证）。

2.确认 Token 有效期

• JWT 解析：复制 Token 到 jwt.io，检查 exp 字段（Unix 时间戳）是否已过期。
• 环境变量管理：若 Token 需定期刷新，建议将其存储在 Postman 环境变量 中，通过脚本自动更新（示例脚本见下方）：

// 预请求脚本（Pre-request Script）中刷新 Token if (pm.environment.get(\"tokenExpires\") < Date.now() / 1000) { // 发送刷新 Token 的请求 pm.sendRequest({ url: \"https://api.com/auth/refresh\", method: \"POST\", body: { raw: \'{\"refreshToken\": \"\' + pm.environment.get(\"refreshToken\") + \'\"}\' } }, function (err, response) { const newToken = response.json().accessToken; pm.environment.set(\"accessToken\", newToken); pm.environment.set(\"tokenExpires\", response.json().expiresIn); }); } 

1. 其他认证方式排查

   • Basic Auth：在 Authorization 标签页选择 Basic Auth，填写用户名和密码，Postman 会自动生成 Base64 编码的头。
   • OAuth 2.0：使用 Postman 的 OAuth 2.0 配置向导，填写令牌端点、客户端 ID 等信息，避免手动拼接 Authorization 头。

Q2：跨域请求失败（Cross-Origin Request Blocked）

核心原因：Postman 模拟浏览器行为时缺少必要头，或服务端未配置 CORS

Postman 专属排查步骤：

1. 手动添加 Origin 头模拟浏览器

   • Postman 默认不会自动发送 Origin 头，需手动添加：
     ① 在 Headers 标签页添加键 Origin，值为前端域名（如 http://localhost:3000）。
     ② 发送请求后，查看响应头是否包含 Access-Control-Allow-Origin（需与 Origin 匹配或为 *）。
   • 预检请求（OPTIONS）：
     • 若请求方法为 PUT/DELETE 或包含自定义头（如 Authorization），Postman 会先发送 OPTIONS 请求。
     • 在 History 中找到 OPTIONS 请求，查看服务端是否返回允许的方法和头：

       http

• • • Access-Control-Allow-Methods: POST, GET, OPTIONS Access-Control-Allow-Headers: Authorization, Content-Type 

• Postman 特殊设置（临时调试）

  • 关闭 SSL 验证（仅用于测试，非真实环境）：
    Settings → General → SSL Certificate Validation 关闭开关。
  • 使用 Postman Interceptor 插件（浏览器版）：
    安装后可模拟真实浏览器发送请求，携带 Cookie 并触发 CORS 机制（需搭配 Postman 桌面版使用）。

• 服务端 CORS 配置示例

  • Express 示例（需安装 cors 包）：

    javascript

1. • const cors = require(\'cors\'); app.use(cors({ origin: \'http://localhost:3000\', // 允许的前端域名 credentials: true // 允许携带 Cookie（需与 Postman 发送的 Cookie 一致） })); 

   • Spring Boot 示例：
     在控制器方法或类上添加 @CrossOrigin(origins = \"http://localhost:3000\")。

Q3：响应数据乱码（中文显示为 � 或乱码）

核心原因：Postman 未正确识别响应编码，或服务端未返回 charset 头

Postman 专属排查步骤：

1. 检查响应头的 Content-Type

   • 在响应区 Headers 标签页查看是否包含 charset=utf-8，如：

     http

Content-Type: application/json; charset=utf-8 

• • 若缺少 charset，Postman 可能默认使用 ISO-8859-1 解码，导致乱码。

• 手动设置响应编码（Postman 临时解决方案）

  • 在响应区右键点击 Set Character Encoding，选择 UTF-8（仅对当前请求生效）。

  • 服务端强制设置编码

  • Express 示例：

    javascript

  • res.setHeader(\'Content-Type\', \'application/json; charset=utf-8\'); res.json({ message: \'你好，世界！\' }); 

  • Spring Boot 示例：
    在 application.properties 中添加：

    properties

  • • spring.http.encoding.charset=UTF-8 spring.http.encoding.enabled=true spring.http.encoding.force=true 

  • 二进制数据处理

    • 若返回图片 / 文件，切换响应区到 Binary 模式（避免以文本模式解析二进制数据）。

  • Postman 进阶排查工具

  • 控制台日志（Console）
    • 打开 Postman 底部的 Console，查看请求 / 响应原始数据、脚本错误（快捷键：Ctrl+Alt+I）。
  • 沙盒脚本（Sandbox Scripts）
    • 在 Tests 标签页添加断言，验证响应编码或认证状态：

      javascript

  • • // 验证响应是否为 UTF-8 编码 pm.test(\"Response is UTF-8\", () => { const charset = pm.response.headers.get(\"Content-Type\").match(/charset=([^;]+)/); pm.expect(charset[1]).to.eql(\"utf-8\"); }); 

  • 环境与全局变量
    • 将常用配置（如 API 地址、认证头）存储在环境变量中，避免重复设置，降低出错概率。

  • 总结

  • 401 问题：优先使用 Postman 内置的 Authorization 标签页 配置认证，避免手动拼接头；通过环境变量管理动态 Token。
  • 跨域问题：手动添加 Origin 头模拟浏览器，利用 Postman History 查看 OPTIONS 请求；服务端配置时避免 Access-Control-Allow-Origin: *（生产环境需限制具体域名）。
  • 乱码问题：确保服务端返回 Content-Type 包含 charset=utf-8，Postman 中可临时手动设置编码，或通过脚本断言强制验证。
  •  

    通过以上步骤，可高效解决 Postman 使用中 90% 以上的常见问题，后续可结合 Postman 官方文档 深入学习脚本、自动化测试等进阶功能。

七、扩展资源

一、官方学习中心推荐

1. Postman 官方学习平台

• 地址：Documentation | Postman Docs
  • 核心资源：
    • 入门教程：从基础请求到自动化测试的全流程视频课程（如 \"First API Call\"）。
    • 进阶专题：涵盖 GraphQL 测试、API 监控、团队协作等高级功能（如 \"GraphQL with Postman\"）。
    • 实战案例：提供电商、金融等行业的 API 开发与测试案例库。
  • 特色功能：
    • 交互式学习：支持边学边练，直接在浏览器中运行示例请求。
    • 认证体系：完成课程后可获得 Postman 官方认证（如 \"API Development Fundamentals\"）。

2. Postman 官方文档

• 地址：Postman documentation overview | Postman Docs
  • 核心内容：
    • 操作手册：详细说明界面布局、请求配置、脚本编写等基础操作。
    • API 参考：提供 Postman API、Mock Server、Newman 等工具的技术文档。
    • 最佳实践：包括性能优化、安全测试、团队协作等场景化指南。

3. Postman 社区论坛

• 地址：Postman Community
  • 核心价值：
    • 技术问答：与全球开发者交流，解决实际使用中的疑难问题（如 \"CORS 配置失败\"）。
    • 经验分享：获取团队协作、自动化测试等场景的实战经验（如 \"如何用 Newman 实现 CI/CD 集成\"）。
    • 插件开发：学习如何编写自定义插件（如 \"用 Postman Interceptor 模拟浏览器行为\"）。

二、热门插件清单（Swagger/GraphQL 支持）

1. Swagger 相关插件

• Postman Swagger 导入（内置功能）：

  • 操作路径：File → Import → OpenAPI/Swagger。
  • 优势：直接导入 Swagger 文档（JSON/YAML），自动生成请求集合，支持动态参数填充。
  • 示例：导入电商 API 的 Swagger 文档后，可快速生成商品查询、订单创建等请求模板。

• Swagger UI 插件（第三方）：

  • 地址：Chrome 应用商店
  • 功能：在浏览器中可视化 Swagger 文档，支持在线调试（需配合 Postman 使用）。

2. GraphQL 支持插件

• Postman GraphQL 客户端（内置功能）：

  • 操作路径：New → GraphQL Request。
  • 优势：支持编写 GraphQL 查询、变量绑定及自动补全（如 \"query { user(id: 1) { name email } }\"）。
  • 示例：导入 GitHub 的 GraphQL Schema 后，可快速查询用户信息、仓库列表等。

• GraphQL Playground（第三方）：

  • 地址：https://github.com/graphql/graphql-playground
  • 功能：提供更友好的 GraphQL 查询界面，支持变量管理和历史记录（需配合 Postman 发送请求）。

3. 其他实用插件

• Apipost Helper（IDEA 插件）：

  • 地址：IDEA 插件市场
  • 功能：在 IDE 中直接调试接口，一键生成 Swagger 文档（支持 Spring、Python 等框架）。

• Postman Interceptor（浏览器插件）：

  • 地址：Chrome 应用商店
  • 功能：模拟真实浏览器发送请求，支持 Cookie 同步和 CORS 验证（需配合 Postman 桌面版使用）。

三、快捷键速查表（附 PDF 下载）

1. 常用快捷键

操作 Windows/Linux Mac 发送请求 Ctrl + Enter Cmd + Enter 保存请求 Ctrl + S Cmd + S 清除响应结果 Ctrl + R Cmd + R 切换请求类型 Ctrl + 1 ~ Ctrl + 9 Cmd + 1 ~ Cmd + 9 打开历史记录 Ctrl + H Cmd + H 新建标签页 Ctrl + T Cmd + T

2. 高级快捷键

操作 Windows/Linux Mac 运行集合 Ctrl + Shift + R Cmd + Shift + R 切换到测试脚本 Ctrl + Alt + T Cmd + Alt + T 打开控制台 Ctrl + Alt + I Cmd + Alt + I 切换环境变量 Ctrl + Alt + E Cmd + Alt + E

3. PDF 速查表下载

• 官方速查表：Postman 快捷键 PDF（需官网注册）。
• 社区整理版：GitHub 速查表（包含更多自定义快捷键）。

四、汉化资源与替代工具

1. Postman 汉化教程

• 操作步骤：
  1. 下载汉化包：访问 GitHub 汉化仓库，选择对应版本的 app.zip。
  2. 替换文件：
     • Windows：进入 C:\\Users\\用户名\\AppData\\Local\\Postman\\app-版本号\\resources，解压 app.zip 替换原文件。
     • Mac：右键 Postman 应用 → 显示包内容 → Contents/Resources，替换 app 文件夹。
  3. 禁用自动更新：修改系统 hosts 文件，添加 0.0.0.0 dl.pstmn.io。

2. 替代工具推荐

• Apifox：集 API 设计、调试、文档、测试于一体，支持 Swagger 导入和团队协作（官网）。
• Hoppscotch：开源、免费的 API 客户端，支持 GraphQL 和 WebSocket（官网）。
• Insomnia：跨平台 API 工具，支持 GraphQL 和 RESTful API（官网）。

五、进阶学习资源

1. Postman 官方博客：https://blog.postman.com/

   • 内容涵盖 API 开发趋势、工具新功能解读（如 \"Postman Flows 工作流设计\"）。

2. YouTube 频道：Postman

   • 定期发布教程视频，如 \"GraphQL 测试实战\"、\"API 安全最佳实践\"。

3. 电子书：《Postman 权威指南》

   • 由 Postman 官方团队编写，涵盖从入门到高级的全流程技术细节。

通过以上资源，你可以深入掌握 Postman 的核心功能，结合插件生态和快捷键技巧，大幅提升 API 开发与测试效率。建议优先使用官方资源，并根据团队需求选择第三方工具补充。

结语：从工具到生态，开启 API 开发新征程

至此，我们已从 Postman 的基础操作聊到进阶实战，从请求调试深入到团队协作，从常见问题排查延伸到生态资源整合。这不仅是一份工具使用指南，更是一次围绕 API 开发效率与质量 的深度探索。希望你能通过 Postman 这个支点，轻松撬动 API 世界的无限可能。

为什么选择 Postman？—— 不止是工具，更是效率引擎

• 全流程覆盖：从接口设计（导入 Swagger/GraphQL）到调试、文档生成、自动化测试，再到团队协作与监控，Postman 提供了闭环解决方案，避免在多工具间频繁切换。
• 生态赋能：通过插件（如 Newman 集成 CI/CD）、环境变量（适配多环境）、脚本沙盒（自定义逻辑），它能无缝融入你的开发工作流，成为团队协作的 “API 中枢”。
• 社区与官方支持：千万开发者的实战经验、官方持续更新的学习资源（如交互式教程、认证课程），让你在遇到问题时永不孤单。

给读者的三点建议：从 “会用” 到 “精通”

1. 在实战中沉淀：

   • 建立自己的 请求集合库（如按项目 / 模块分类），积累常用接口模板（登录、分页、文件上传等），减少重复劳动。
   • 用 测试脚本 固化断言逻辑（如校验响应状态码、字段完整性），每次调试即自动验证，提前暴露接口问题。

2. 探索 “隐藏” 的高阶功能：

   • Mock Server：在后端未就绪时，用模拟数据驱动前端开发，实现前后端并行。
   • API 监控：设置定时任务监控关键接口，实时接收异常通知（如 Slack / 邮件），让 “被动排错” 变 “主动预防”。
   • Newman 自动化：将 Postman 集合转化为命令行脚本，集成到 Jenkins/GitHub Actions 中，实现持续测试（CI/CD 必备）。

3. 跳出工具，理解 API 设计本质：

   • Postman 是 “显微镜”，帮你看清每个请求细节；而真正的能力提升，在于理解 API 设计原则（如 RESTful 规范、GraphQL 最佳实践）、性能优化（如分页、缓存）、安全策略（JWT/OAuth 2.0）。
   • 尝试从 “工具使用者” 转变为 “API 设计者”：思考如何让接口更简洁、健壮、易维护，这才是技术进阶的核心。

致开发者：技术的价值在于连接与创新

API 是数字世界的 “桥梁”，连接着前端与后端、服务与服务、甚至不同系统与平台。Postman 则是搭建这座桥梁的 “脚手架”—— 它让繁琐的调试变得轻松，让复杂的协作变得有序，让隐藏的问题无所遁形。

但请记住：工具的上限，由使用者的认知决定。当你熟练掌握 Postman 的高阶玩法，尝试将它与团队流程、业务场景深度结合时，才会真正体会到 “工欲善其事，必先利其器” 的含义。

后续学习资源：持续成长的阶梯

• 官方资源：定期浏览 Postman 学习中心 和 博客，紧跟功能更新（如 AI 辅助生成请求、可视化工作流设计）。
• 社区交流：加入 Postman 中文社区，分享你的实战经验，向同行请教复杂场景解决方案。
• 技术实践：选择一个真实项目（如开源 API 接口调试、微服务联调），将所学知识落地，在踩坑中积累 “肌肉记忆”。

最后的话

技术的魅力，在于它永远为 “效率” 和 “创新” 让路。Postman 只是起点，未来你还会遇到更多强大的工具（如 Apifox、Hoppscotch）、更前沿的技术（如 Web3 API、AI 驱动接口测试）。但无论何时，保持对 “如何把事情做得更好” 的好奇心，才是持续进步的源动力。

祝愿你在 API 开发的道路上，步步生花，代码皆成诗。如果这份指南曾为你点亮过某个瞬间，欢迎分享给更多同行 —— 技术的价值，在传播中才能实现更大的意义。

我们下次技术探索再见！

—— 始终与你同行的技术人
2025 年 4 月 7 日