别再用 Postman 了！IntelliJ IDEA 自带的 .http 文件到底有多强？

别再用 Postman 了！IntelliJ IDEA 自带的 .http 文件到底有多强？

一个被严重低估的 IDEA 内置功能，纯文本写 HTTP 请求，版本控制友好，团队共享零成本。

作为后端开发，日常免不了要和 API 打交道。调试接口、验证返回值、给前端写调用示例——这些活儿你用什么工具？

Postman？Apifox？Swagger？还是直接在终端里敲 curl？

如果你的主力 IDE 是 JetBrains 全家桶（IntelliJ IDEA、WebStorm、PyCharm、GoLand 等），那你可能一直忽略了一个内置神器——.http 文件。

今天就来聊聊这个被严重低估的功能，看看它能不能在你的日常开发中替代掉 Postman。

---

一、什么是 .http 文件？

.http 文件是 JetBrains IDE 内置的 HTTP Client 插件所支持的一种文件格式。它允许你在纯文本文件中编写 HTTP 请求，一键发送，响应结果直接在 IDE 内展示。

本质上，它把"写请求 → 发送 → 看响应"这个流程从外部工具搬回了你的代码编辑器。

格式遵循社区提出的 HTTP 请求档案格式规范，语义直观，上手几乎零门槛。

---

二、快速上手：3 分钟写出你的第一个请求

2.1 创建文件

在项目任意位置新建一个文件，后缀命名为 .http，比如 test.http 或 api.http。IDE 会自动识别并启用语法高亮。

2.2 写一个最简单的 GET 请求

### 获取所有用户
GET http://localhost:8080/api/users
Accept: application/json

就是这么简单。行号左侧会出现一个绿色的 ▶ 运行按钮，点击即可发送请求。

2.3 写一个 POST 请求

### 创建新用户
POST http://localhost:8080/api/users
Content-Type: application/json

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

注意：请求头和请求体之间必须有一个空行，这是 HTTP 协议的规范要求，.http 文件严格遵守这一点。

2.4 一个文件写多个请求

用 ### 分隔符将多个请求写在同一个文件中：

### 1. 登录获取 Token
POST http://localhost:8080/api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456"
}

### 2. 获取用户信息
GET http://localhost:8080/api/users/1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

### 3. 更新用户信息
PUT http://localhost:8080/api/users/1
Content-Type: application/json

{
  "name": "李四",
  "age": 30
}

### 4. 删除用户
DELETE http://localhost:8080/api/users/1

每个 ### 后面的文字是可选的注释标题，会在运行时显示在 Run Configuration 名称中，方便你区分请求。

---

三、环境变量：一套请求，多套环境

实际开发中，我们通常有 dev、test、pre、prod 等多套环境。.http 文件通过环境变量文件来优雅解决这个问题。

3.1 创建环境配置文件

在项目根目录创建 http-client.env.json（IDE 也支持 http-client.private.env.json，这个文件应该加入 .gitignore，存放敏感信息）：

{
  "dev": {
    "host": "http://localhost:8080",
    "username": "admin",
    "password": "123456",
    "token": "dev-token-12345"
  },
  "test": {
    "host": "http://test.example.com",
    "username": "tester",
    "password": "test123",
    "token": "test-token-67890"
  },
  "prod": {
    "host": "https://api.example.com",
    "username": "prod-admin",
    "password": "prod-secure",
    "token": "prod-token-xxxxx"
  }
}

3.2 在请求中引用变量

### 登录（使用环境变量）
POST {{host}}/api/login
Content-Type: application/json

{
  "username": "{{username}}",
  "password": "{{password}}"
}

### 获取用户列表
GET {{host}}/api/users
Accept: application/json
Authorization: Bearer {{token}}

3.3 切换环境

在 .http 文件编辑器的顶部工具栏，会有一个下拉菜单，显示当前选中的环境（dev / test / prod）。切换后，所有 {{变量}} 引用会自动替换为对应环境的值。

3.4 内置变量

IDE 还提供了一些内置变量，无需在环境文件中定义：

• {{$timestamp}} — 当前时间戳（毫秒）
• {{$randomInt}} — 随机整数
• {{$uuid}} — 随机 UUID
• {{$globalSalt}} — 全局盐值（用于加密场景）

### 使用内置变量
POST {{host}}/api/orders
Content-Type: application/json

{
  "orderId": "ORD-{{$timestamp}}",
  "requestId": "{{$uuid}}",
  "itemCount": {{$randomInt}}
}

---

四、请求链：让请求之间"联动"起来

这是 .http 文件最强大的功能之一——上一个请求的响应结果可以作为下一个请求的输入。

4.1 从响应中提取变量

### 1. 登录
POST {{host}}/api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456"
}

> {%
    client.global.set("auth_token", response.body.token);
    client.global.set("user_id", response.body.user.id);
%}

### 2. 使用提取的 Token 请求受保护接口
GET {{host}}/api/users/{{user_id}}
Authorization: Bearer {{auth_token}}

### 3. 更新该用户的信息
PUT {{host}}/api/users/{{user_id}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "name": "新名字",
  "email": "new@example.com"
}

关键点在于 > {% ... %} 这段脚本：

• response.body 是响应解析后的 JSON 对象
• response.headers 是响应头
• response.status 是 HTTP 状态码
• client.global.set(key, value) 将值存入全局变量，后续请求可用
• client.assert(condition, message) 可以做断言校验

4.2 响应断言：轻量级接口自动化测试

### 登录并断言
POST {{host}}/api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456"
}

> {%
    client.assert(response.status === 200, "登录接口应返回 200");
    client.assert(response.body.token != null, "响应体应包含 token");
    client.assert(response.body.user.role === "admin", "登录用户应为管理员");
%}

如果断言失败，IDE 会在响应面板中显示错误信息。这已经具备了轻量级 API 自动化测试的能力。

---

五、请求文件拆分与复用

当 .http 文件越来越大时，可以通过 @ 语法引用其他 .http 文件中定义的变量。

5.1 在另一个 .http 文件中定义请求

// auth.http

### 登录
# @name login
POST {{host}}/api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456"
}

> {%
    client.global.set("auth_token", response.body.token);
%}

5.2 在其他文件中引用

// orders.http

### 创建订单（复用登录的 Token）
POST {{host}}/api/orders
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "productId": 100,
  "quantity": 2
}

# @name 注解给请求命名，其他文件可以通过响应处理脚本间接引用。对于更复杂的场景，也可以使用 http-client.env.json 集中管理变量。

---

六、文件上传与下载

6.1 文件上传

### 上传文件
POST {{host}}/api/upload
Content-Type: multipart/form-data; boundary=WebAppBoundary

--WebAppBoundary
Content-Disposition: form-data; name="file"; filename="report.pdf"
Content-Type: application/pdf

< ./documents/report.pdf
--WebAppBoundary
Content-Disposition: form-data; name="description"

月度报告
--WebAppBoundary--

• < 文件路径 语法表示从本地读取文件内容作为请求体
• 路径支持相对路径（相对于 .http 文件所在位置）和绝对路径
• multipart/form-data 需要手动指定 boundary

6.2 下载文件到本地

### 下载报表
GET {{host}}/api/reports/download

> {%
    client.test("下载成功", function() {
        client.assert(response.status === 200);
    });
    
    // 保存响应体到本地文件
    const fs = require('fs');
    const path = require('path');
    fs.writeFileSync(path.join(__dirname, 'report.pdf'), response.body);
%}

---

七、GraphQL 支持

.http 文件同样支持 GraphQL 请求：

### GraphQL 查询
POST {{host}}/graphql
Content-Type: application/json

{
  "query": "query GetUser($id: ID!) { user(id: $id) { id name email } }",
  "variables": {
    "id": "1"
  }
}

---

八、响应展示：在 IDE 内直接看结果

发送请求后，IDE 会在右侧或下方打开一个响应面板，展示：

1. HTTP 状态码和响应头
2. 响应体（自动格式化 JSON、XML、HTML）
3. 请求耗时
4. 响应大小

支持多种视图模式：

• Text — 原始文本
• JSON / XML — 语法高亮 + 树形结构
• HTML Preview — 渲染 HTML 响应
• Binary — 下载/保存二进制响应

---

九、.http 文件 vs Postman / Apifox：详细对比

下面从实际开发场景出发，逐项对比。

9.1 对比总览

维度	.http 文件	Postman	Apifox
安装成本	IDE 内置，零安装	需单独安装桌面端	需单独安装
学习曲线	极低，纯文本	中等，需熟悉 UI	中等，功能多
版本控制	天然支持（纯文本）	有限（依赖 Workspace 同步）	有限
团队协作	随代码库共享，Git 管理	需付费团队版	支持，但需在线
环境切换	环境配置文件	Environment 变量	环境管理
请求联动	响应脚本提取变量	Tests 脚本 / Visualize	后置操作
自动化测试	轻量断言（client.assert）	Collection Runner + Newman	自动化测试模块
Mock 服务	不支持	支持（Mock Server）	支持（内置 Mock）
API 文档	不支持	支持	支持（自动生成）
WebSocket	支持（.ws 文件）	支持	支持
离线使用	完全离线	部分功能需联网	部分功能需联网
性能	轻量，几乎无开销	较重，内存占用高	较重
调试集成	与 IDE 调试器无缝联动	需要手动切换	需要手动切换

9.2 什么时候该用 .http 文件？

适合 .http 文件的场景：

• 个人开发调试：写代码的过程中快速验证接口，不需要离开 IDE
• 团队 API 示例共享：把 .http 文件随项目一起提交，新成员 clone 下来就能直接运行
• CI/CD 集成：纯文本文件可以用脚本批量执行（通过 IDE 命令行工具）
• Git 代码审查：接口的变更可以作为代码 diff 的一部分被 review
• 轻量自动化测试：简单的接口断言和链路测试

适合 Postman / Apifox 的场景：

• API 文档自动生成和分享：需要对外提供接口文档
• Mock 服务：前后端分离开发时，需要模拟接口响应
• 复杂的集合测试：大量接口的回归测试、定时执行
• 非开发人员使用：测试人员、产品经理需要参与接口调试
• API 监控和告警：持续监控线上接口状态

9.3 它们不是替代关系，而是互补

说实话，.http 文件不会完全替代 Postman。但它确实能覆盖开发者日常 70%~80% 的接口调试需求。

我的建议是：

开发阶段用 .http 文件，文档和协作阶段用 Apifox / Postman。

两者配合使用，效率最大化。

---

十、实战示例：完整的电商 API 调试文件

下面是一个完整的 .http 文件示例，涵盖了大多数日常场景：

### ============================================
### 电商系统 API 调试集
### 环境: 在 http-client.env.json 中配置
### ============================================

### 1. 用户登录
POST {{host}}/api/auth/login
Content-Type: application/json

{
  "username": "{{username}}",
  "password": "{{password}}"
}

> {%
    client.assert(response.status === 200, "登录应成功");
    client.global.set("token", response.body.data.token);
    client.global.set("userId", response.body.data.userId);
    console.log("登录成功，Token: " + response.body.data.token);
%}

### 2. 获取商品列表
GET {{host}}/api/products?page=1&pageSize=10&category=electronics
Accept: application/json
Authorization: Bearer {{token}}

> {%
    client.assert(response.status === 200);
    client.assert(response.body.data.items.length > 0, "商品列表不应为空");
    client.global.set("firstProductId", response.body.data.items[0].id);
%}

### 3. 获取商品详情
GET {{host}}/api/products/{{firstProductId}}
Accept: application/json
Authorization: Bearer {{token}}

### 4. 添加到购物车
POST {{host}}/api/cart/items
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "productId": {{firstProductId}},
  "quantity": 2
}

> {%
    client.assert(response.status === 201, "添加购物车应返回 201");
    client.global.set("cartItemId", response.body.data.id);
%}

### 5. 查看购物车
GET {{host}}/api/cart
Authorization: Bearer {{token}}

### 6. 创建订单
POST {{host}}/api/orders
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "items": [
    {
      "productId": {{firstProductId}},
      "quantity": 2
    }
  ],
  "address": {
    "province": "北京市",
    "city": "北京市",
    "district": "朝阳区",
    "detail": "某某街道 100 号"
  }
}

> {%
    client.assert(response.status === 201);
    client.global.set("orderId", response.body.data.orderId);
%}

### 7. 查询订单状态
GET {{host}}/api/orders/{{orderId}}
Authorization: Bearer {{token}}

### 8. 上传商品图片
POST {{host}}/api/products/{{firstProductId}}/images
Content-Type: multipart/form-data; boundary=UploadBoundary
Authorization: Bearer {{token}}

--UploadBoundary
Content-Disposition: form-data; name="image"; filename="product.jpg"
Content-Type: image/jpeg

< ./images/product.jpg
--UploadBoundary--

配套的环境配置文件 http-client.env.json：

{
  "dev": {
    "host": "http://localhost:8080",
    "username": "admin",
    "password": "admin123"
  },
  "test": {
    "host": "https://test-shop.example.com",
    "username": "test_user",
    "password": "test_pass"
  }
}

把这个 shop-api.http 和 http-client.env.json 提交到 Git 仓库，任何 clone 了项目的团队成员都可以直接在 IDE 中运行这些请求，不需要任何额外的配置或文档。

---

十一、常见问题与技巧

11.1 请求没有发送按钮？

确保文件后缀是 .http（或 .rest，两者等效）。如果是新建文件，可能需要重启 IDE 或手动关联文件类型。

11.2 变量没有生效？

检查以下几点：

• 环境变量文件是否命名为 http-client.env.json 或 http-client.private.env.json
• 环境变量文件是否在项目的根目录或 .http 文件所在目录
• 顶部工具栏是否选择了正确的环境
• 变量名拼写是否正确（区分大小写）

11.3 请求超时怎么设置？

在 IDE 设置中：Settings → Tools → HTTP Client → Request timeout，默认通常是 30000ms（30 秒）。

11.4 忽略 SSL 证书验证

在测试环境中经常遇到自签名证书问题，可以在 IDE 设置中勾选：Settings → Tools → HTTP Client → Accept non-trusted certificates。

11.5 快捷键

• Ctrl+Shift+F10（Windows/Linux）或 Control+Shift+R（Mac）— 运行光标所在位置的请求
• Ctrl+Shift+F9 — 运行所有请求

11.6 请求历史记录

IDE 会自动保存请求历史，在 Services → HTTP Requests 面板中查看。

---

十二、总结

.http 文件是 JetBrains IDE 中一个低调但强大的功能。它用纯文本 + 简单语法的方式解决了接口调试的核心需求，而且天然支持版本控制和团队协作。

核心优势一句话总结：

写请求就像写代码一样自然，版本控制、代码审查、团队共享全部零成本。

如果你已经在用 IDEA 写代码，不妨在下次调试接口时试试 .http 文件——也许你会发现，那个熟悉的 Postman 图标，已经很久没点过了。

---

你的团队还在用 Postman 调试接口吗？欢迎在评论区聊聊你的 API 调试工作流。