告别Postman——用VSCode优雅地发起Http请求

为什么你需要扔掉Postman

后端开发日常工作中，最频繁的操作之一就是调试接口。打开Postman，找到对应的Collection，点击Send，查看返回结果。这听起来没什么问题，但实际做起来，痛点却不少。

接口文档写在了Swagger或者YApi上，每次要手动复制URL、参数到Postman。项目换了人交接，Postman的Collection要么没导出，要么导出的JSON格式乱作一团。团队几个人共用一个Postman账号，请求列表互相覆盖，你改了我的接口参数，我找不到了昨天的测试数据。Postman的请求数据散落在各自的电脑里，无法用Git管理，更谈不上Code Review。

更让人抓狂的是，当你从Postman复制一段请求示例到Issue或Wiki时，那是一段难以阅读的JSON，别人拿到之后还得手动导入Postman才能用。如果要共享一个接口调用场景，你需要导出成文件，发送给对方，对方再导入。这个过程重复几十次后，你会开始怀疑人生。

有没有一种方式，让Http请求像写代码一样简单？让请求文件能纳入版本控制，能Review，能开箱即用地共享？

答案是：有的。VSCode的REST Client插件，配合 .http 文件，就是答案。

.http 文件的诞生背景

故事要从 2016 年说起。那一年，VSCode 正在迅速崛起，凭借轻量、免费、插件生态丰富的特点，吸引了大量开发者。然而，在接口调试这个高频场景上，VSCode 却几乎是空白------开发者要么切到独立的 Postman 窗口，要么在终端里手敲 cURL 命令，体验割裂。

一位来自中国的开发者毛华超（Huachao Mao）注意到了这个问题。他的思考方向很独特：Http请求本质上就是一段文本------请求行、请求头、请求体，这些都是可读的纯文本。既然如此，为什么要把它封装成图形界面里的表单字段？为什么不直接用文本来定义一个请求？

这个想法的根基是 Http 协议本身。Http 协议（RFC 2616，后来被 RFC 7230 取代）规定了请求的标准结构：第一行是请求行（方法 + URL + 协议版本），随后是若干行请求头，中间用空行分隔，最后是请求体。这本身就是一份结构清晰的文本。毛华超要做的，就是把这种文本结构变成一个可执行的文件格式。

2016 年，REST Client 插件在 VSCode Marketplace 上正式发布。它引入了 .http 和 .rest 两种文件扩展名，用纯文本描述 Http 请求。文件的语法忠实地还原了 Http 协议的结构：用 POST /api/xxx 定义请求行，用 Content-Type: application/json 定义请求头，空行之后就是请求体。为了在一个文件中容纳多个请求，毛华超设计了 ### 作为请求分隔符------三个连续的井号，简洁且不会与请求内容冲突。

这个看似简单的设计，背后解决的是一个长期被忽视的矛盾：接口调试工具的"易用性"和"可维护性"难以兼得。Postman 用图形界面换来了易用性，但请求数据被锁在专有格式里，无法纳入版本控制；cURL 命令是纯文本，可维护，但参数长了之后可读性极差，且缺乏响应的可视化。REST Client 找到了第三条路------用结构化的纯文本描述请求，既保留了可读性和可维护性，又通过 VSCode 的插件能力提供了语法高亮、自动补全、响应可视化等图形化体验。

插件发布后，社区反响热烈。从 2016 年至今，REST Client 经历了数十个版本的迭代，功能逐步丰富：

2018 年，引入了文件变量（file variables），支持变量之间的互相引用，让环境配置更加灵活。

2019 年，加入了 GraphQL 请求支持和 .env 文件变量，紧跟当时的技术趋势。

2020 年，AWS Signature v4 认证、Microsoft Identity Platform 认证相继加入，覆盖了主流云服务的鉴权场景。

2022 年，prompt variables 功能上线，允许在发送请求时交互式地输入变量值。

如今，REST Client 在 VSCode Marketplace 上的安装量已超过 740 万次，成为后端开发者工具箱中的常驻插件。

值得一提的是，很多人以为 .http 文件格式是 JetBrains 发明的，因为 Java 开发者大多是在 IntelliJ IDEA 里第一次接触到它。但事实恰好相反：JetBrains 的 HTTP Client 直到 2018.1 EAP（2018 年 1 月）才正式推出，比 VSCode 的 REST Client 晚了将近两年。JetBrains 官方博客在那篇介绍文章中将其称为"the new REST client"。当然，两者的格式并非互相抄袭------它们都源于同一个根基：Http 协议标准（RFC 2616）本身就规定了请求行、请求头、请求体的文本结构。与其说是谁发明了 .http 格式，不如说大家都意识到：Http 请求天然就是文本，用文本来描述它是最自然的选择。这个理念，正在成为整个行业的共识。

.http 文件格式带来的改变是深层的：

它让接口请求成为项目代码的一部分。.http 文件和 .java、.go 文件一样，躺在同一个代码仓库里，参与同样的 Git 流程。接口怎么调用、传什么参数、返回什么结构，Reviewer 在 Code Review 时一目了然。

它让接口文档"活"了起来。传统的接口文档是静态的------Swagger 页面、Wiki 页面，更新往往滞后于代码。而 .http 文件是可执行的，开发者写完接口顺手在文件里加一个请求示例，文档和代码天然同步。

它让团队协作变得透明。一个 .http 文件就是一个可执行的接口契约。新人入职，拉下代码，安装插件，打开文件，点击发送，接口就能跑通。前端同事拿到 .http 文件，无需任何额外配置，直接在 VSCode 中调试后端接口。

它让回归测试有了载体。同一个接口的不同参数组合，用多个 ### 分隔的请求块描述，从上到下依次点击，就是一次完整的接口回归。

从最简单的GET请求开始

安装好 VSCode 的 REST Client 插件后，新建一个 test.http 文件，输入以下内容即可发起你的第一个请求。

http 复制代码

### 获取用户列表
GET https://api.example.com/users

在 GET 行上方会出现一个 "Send Request" 按钮，点击它，右侧就会打开响应面板，展示返回的 JSON 数据。没错，一个请求只需要三行：一个注释描述、一个 GET 行。这就是全部。

如果接口需要查询参数，直接在 URL 上拼接就好：

http 复制代码

### 搜索用户
GET https://api.example.com/users?keyword=张三&page=1&size=20

携带请求头

很多接口需要认证信息，比如 Token 或 Cookie。请求头写在 URL 下方，每行一个：

http 复制代码

### 获取当前用户信息
GET https://api.example.com/user/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

也常见携带 Accept、X-Requested-With 等自定义头：

http 复制代码

### 分页查询订单
GET https://api.example.com/orders?page=1&size=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Accept: application/json
X-Requested-With: XMLHttpRequest

POST 请求与 JSON 请求体

这是后端开发中最常用的场景。POST 请求的请求体放在空行之后：

http 复制代码

### 创建用户
POST https://api.example.com/users
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

{
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 25
}

注意 POST 行和请求头之间没有空行，而请求头和请求体之间必须有一个空行。这是Http协议的标准格式，REST Client只是忠实地呈现了它。

使用变量管理环境和敏感信息

实际项目中，开发环境、测试环境、生产环境的 URL 和 Token 都不一样。每次复制粘贴？当然不。

REST Client 支持变量引用，通过 @ 关键字定义变量：

http 复制代码

@baseUrl = http://localhost:8080
@authToken = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

### 查询用户列表
GET {{baseUrl}}/users
Authorization: Bearer {{authToken}}

变量定义放在文件头部，请求中用 {``{变量名}} 引用即可。更优雅的做法是抽出一个 settings.http 文件存放环境变量，再用 @import 引入：

http 复制代码

# settings.http
@devBaseUrl = http://localhost:8080
@prodBaseUrl = https://api.example.com
@devToken = dev-token-xxx
@prodToken = prod-token-xxx

http 复制代码

# test.http
@import ./settings.http

### 开发环境-查询用户列表
GET {{devBaseUrl}}/users
Authorization: Bearer {{devToken}}

### 生产环境-查询用户列表
GET {{prodBaseUrl}}/users
Authorization: Bearer {{prodToken}}

文件上传请求（multipart/form-data）

上传文件的场景在传统接口调试工具中往往比较繁琐，需要选择文件、设置表单字段。在 .http 文件中，这一切通过文本描述来完成：

http 复制代码

### 上传文件
POST https://api.example.com/file/upload
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Content-Type: multipart/form-data; boundary=MyBoundary

--MyBoundary
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg

< D:/workspace/test-data/photo.jpg
--MyBoundary
Content-Disposition: form-data; name="description"

这是一张测试图片
--MyBoundary--

通过 < 符号引用本地文件路径，REST Client 会自动读取文件内容作为请求体的一部分。文件路径可以使用正斜杠 / 或双反斜杠 \\。

一个复杂的真实案例

下面是一个综合案例，展示了一个项目实际开发中 .http 文件的使用方式。涉及多个接口、不同参数组合的测试场景。

http 复制代码

@baseUrl = http://localhost:8080
@token = your-token-here

### 导入数据
# 注意：文件路径要用双反斜杠 \\ 或正斜杠 /
POST {{baseUrl}}/admin-api/data/import
Content-Type: multipart/form-data; boundary=WebKitFormBoundary
Authorization: Bearer {{token}}

--WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="data_template.xlsx"
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

< D:/workspace/test-data/data_template.xlsx
--WebKitFormBoundary
Content-Disposition: form-data; name="type"

5
--WebKitFormBoundary--

### 分页查询（带筛选条件）
POST {{baseUrl}}/admin-api/order/page
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "pageNo": 1,
  "pageSize": 10,
  "keyword": "测试订单"
}

### 分页查询（不带筛选，验证基础分页）
POST {{baseUrl}}/admin-api/order/page
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "pageNo": 1,
  "pageSize": 10
}

### 统计查询（全量）
POST {{baseUrl}}/admin-api/order/statistics
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "pageNo": 1,
  "pageSize": 10
}

### 统计查询（按时间范围筛选）
POST {{baseUrl}}/admin-api/order/statistics
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "pageNo": 1,
  "pageSize": 10,
  "startTime": "2025-01-01",
  "endTime": "2025-12-31"
}

### APP端-订单列表（含统计）
POST {{baseUrl}}/app-api/order/statistics/page
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "pageNo": 1,
  "pageSize": 10
}

### APP端-统计查询（按编号筛选）
POST {{baseUrl}}/app-api/order/statistics
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "pageNo": 1,
  "pageSize": 10,
  "certificateNo": "GH"
}

这个案例展现的正是 .http 文件的魅力：多个请求分层排列，注释清晰标注每个请求的用途，变量统一管理环境信息，文件本身就是一份可执行的测试计划。

日常开发工作流

在实际项目中使用 .http 文件，推荐的工作流程是这样的：

在项目的 temp/test 或 docs 目录下新建 api-test.http 文件。文件头部声明变量，之后按模块或功能分段组织请求。每开发一个新接口，先在 .http 文件中写好请求示例，再编写代码。这样做的好处是，接口写好时，测试请求已经就绪，点击一下就能验证。

当接口出现 Bug 时，在 .http 文件中新增一个请求块，复现问题场景。修复代码后，再次点击验证。这个复现步骤可以保留在文件中，成为回归测试的一部分。

需要和前端联调时，把 .http 文件发送给前端同事。对方不需要安装任何额外工具（VSCode 开发者都有 REST Client 插件），打开就能直接调用接口。如果前端发现了接口问题，直接在 .http 文件中修改参数，把文件发回给你，你打开就能复现。

为什么团队应该拥抱 .http

简单来说，.http 文件让接口调试从"工具操作"回归到了"文本编辑"。它不依赖任何图形界面，不依赖任何云服务，不需要联网，不存储任何专有格式的数据。一个文件、一个插件，完整替代了 Postman 90% 的日常功能。

正因为它只是文本，所以可以用 Git 管理，可以 Diff，可以 Code Review。正因为它只是文本，所以可以用任何编辑器打开查看，不存在"打不开Collection文件"的问题。正因为它只是文本，所以分享就是复制粘贴，接收方看到的就是可执行的请求。

Postman 是一个优秀的工具，但它解决的是"接口调试"问题，而不是"接口协作"问题。.http 文件恰好填补了后者。对于后端开发团队而言，将 .http 文件纳入项目代码库，带来的不是工具的更替，而是协作效率的一次提升。

从今天开始，在你的项目里创建一个 .http 文件，把第一个接口写进去，点击 Send Request，体验一下这种"像写代码一样调接口"的感觉吧。