JetBrains HTTP Client 调试最佳实践

JetBrains 系列 IDE（IntelliJ IDEA / PyCharm 等 Ultimate 版）内置 HTTP Client，可直接编写 *.http 文件调试接口，无需 Postman。

文件组织

1
2
3

xxx.http                       # 请求定义
http-client.env.json           # 公共环境变量
http-client.private.env.json   # 私密环境变量（含 token）

环境（Environment）机制

变量按环境分组，公共变量放 http-client.env.json，敏感变量放同名 *.private.env.json，两者按环境名合并。

1
2
3
4
5

// http-client.env.json
{
  "local": { "base_url": "http://127.0.0.1:8080" },
  "prod":  { "base_url": "https://api.example.com" }
}

1
2
3
4
5

// http-client.private.env.json
{
  "local": { "access_token": "<本地 token>" },
  "prod":  { "access_token": "<正式 token>", "auth_project": "demo" }
}

请求里用 {{变量名}} 引用：

1
2
3
4

GET {{base_url}}/v1/resources?page=1&size=20
X-Access-Token: {{access_token}}
X-Auth-Project: {{auth_project}}
Accept: application/json

使用步骤

1. 用 IDE 打开任意 *.http 文件。
2. 在 http-client.private.env.json 中填好对应环境的敏感变量。
3. 点请求左侧的 ▶️ 绿色三角，弹出环境选择，选目标环境。
4. 响应在底部 Run 面板查看，历史响应存于 .idea/httpRequests/。
5. 切换环境：右上角环境下拉框，或运行时弹窗选择。

Token 安全

• token 只放 *.private.env.json，确认该文件已被 .gitignore 忽略，切勿提交。
• token 通常有有效期（如 JWT 的 exp），过期需重新获取。
• 切勿把 token 写进 *.http 或 http-client.env.json，否则会随仓库泄露。

常用技巧

• 分隔多个请求：同一文件内用 ### 分隔，每段是独立请求，可加注释标题。
• 响应提取：请求后接 > {% client.global.set("xxx", response.body.xxx); %} 脚本块，把响应字段存为全局变量供后续请求复用（如登录拿 token）。
• 变量优先级：请求内联 > private env > 公共 env > 全局变量。
• 查询参数多值：用逗号分隔（如 _embed=a,b,c），IDE 会自动做 URL 编码，无需手写 %2C。
• 复制为 cURL：右键请求 → Convert to cURL，便于在终端复现。

请求模板

1
2
3
4
5

### <环境>：<接口说明>
GET {{base_url}}/<path>?<query>
X-Access-Token: {{access_token}}
X-Auth-Project: {{auth_project}}
Accept: application/json