{T}

REST Client 插件实战

概述

REST Client 是 VS Code 生态中最流行的接口调试插件，通过 .http 纯文本文件定义请求，无需离开编辑器即可完成接口调试。相比 Postman 的 GUI 操作，REST Client 更适合前端开发者：请求文件可纳入 Git 版本管理、支持环境变量、可与项目代码同仓库维护。

前置知识

学习目标

  • 掌握 .http 文件的完整语法
  • 理解环境变量、Prompt 变量、dotenv 的使用方式
  • 掌握 cURL 互转与代码生成能力
  • 能够在项目中建立 api/ 目录进行接口资产管理

一、.http 文件语法

1.1 基本请求

http
### 获取用户列表
GET http://localhost:3000/api/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

### 获取单个用户
GET http://localhost:3000/api/users/1

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

{
  "name": "张伟",
  "email": "zhangwei@example.com",
  "role": "admin"
}

### 更新用户
PUT http://localhost:3000/api/users/1
Content-Type: application/json

{
  "name": "张伟（已更新）"
}

### 删除用户
DELETE http://localhost:3000/api/users/1

1.2 语法要点

元素说明
###请求分隔符，每个 ### 开始一个新请求
第一行方法 URL [协议版本]
后续行请求头（Key: Value）
空行后请求体（Body）
// 或 #注释（仅在行首）

1.3 查询参数

http
### 带查询参数
GET http://localhost:3000/api/courses?_page=1&_limit=10&_sort=price&_order=asc

### 多行参数（可读性更好）
GET http://localhost:3000/api/courses
  ?_page=1
  &_limit=10
  &_sort=price

二、环境变量

2.1 环境配置文件

在项目根目录创建 rest-client.env.json：

json
{
  "development": {
    "baseUrl": "http://localhost:3000",
    "token": "dev-mock-token"
  },
  "staging": {
    "baseUrl": "https://staging.api.example.com",
    "token": "staging-token-xxx"
  },
  "production": {
    "baseUrl": "https://api.example.com",
    "token": "prod-token-xxx"
  }
}

2.2 在请求中引用

http
### 使用环境变量
GET {{baseUrl}}/api/users
Authorization: Bearer {{token}}

2.3 切换环境

VS Code 右下角状态栏显示当前环境名，点击可切换。

2.4 Prompt 变量

运行时弹出输入框，动态填入值：

http
### 登录（运行时提示输入）
POST {{baseUrl}}/api/login
Content-Type: application/json

{
  "username": "{{$prompt 请输入用户名}}",
  "password": "{{$prompt 请输入密码}}"
}

2.5 dotenv 支持

在 .env 文件中定义变量，REST Client 自动读取：

bash
# .env
API_BASE=http://localhost:3000
API_KEY=sk-xxxx
http
GET {{$dotenv API_BASE}}/api/data
X-API-Key: {{$dotenv API_KEY}}

三、响应处理

3.1 响应面板

发送请求后，响应在独立面板展示：

  • 状态码与响应时间
  • 响应头
  • 响应体（JSON 自动格式化）

3.2 响应重定向

将响应保存到文件：

http
### 保存响应到文件
GET {{baseUrl}}/api/users
> ./responses/users.json

3.3 响应脚本

http
### 提取 token 存入变量
POST {{baseUrl}}/api/login
Content-Type: application/json

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

> {%
  const res = response.body
  if (res.code === 0) {
    client.global.set('token', res.data.token)
  }
%}

四、cURL 互转

4.1 cURL → .http

code
命令面板 → REST Client: Import cURL

粘贴 cURL 命令自动转换为 .http 格式：

bash
# 输入 cURL
curl -X POST http://localhost:3000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

转换结果：

http
POST http://localhost:3000/api/login
Content-Type: application/json

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

4.2 .http → 代码生成

右键请求 → "Generate Code Snippet"，支持：

  • JavaScript (fetch / axios)
  • Python (requests)
  • Go (net/http)
  • cURL
  • PHP / Ruby / Java 等

五、项目集成方案

5.1 目录结构

code
project/
├── api/                          # 接口定义目录
│   ├── auth.http                 # 认证相关
│   ├── users.http                # 用户模块
│   ├── courses.http              # 课程模块
│   └── orders.http               # 订单模块
├── rest-client.env.json          # 环境配置
├── .env                          # 敏感变量（gitignore）
└── .vscode/
    └── settings.json             # REST Client 配置

5.2 VS Code 配置

json
{
  "rest-client.environmentVariables": {
    "$shared": {
      "version": "v1"
    }
  },
  "rest-client.defaultHeaders": {
    "User-Agent": "vscode-restclient"
  },
  "rest-client.requestTimeout": 30000,
  "rest-client.followredirect": true
}

5.3 Git 管理策略

文件是否入库说明
api/*.http是接口定义，团队共享
rest-client.env.json是环境结构（不含敏感值）
.env否真实 token/密钥

5.4 团队协作优势

  • 接口定义与代码同仓库，版本一致
  • Code Review 时可审查接口变更
  • 新人 clone 项目即可调试所有接口
  • 无需安装额外客户端工具

六、REST Client vs Postman 对比

维度REST ClientPostman
运行环境VS Code 内独立客户端
文件格式纯文本 .http私有 JSON 格式
版本管理Git 友好需导出/同步
团队协作通过 Git通过 Postman Cloud
学习成本极低中等
功能丰富度基础调试完整平台（Monitor/Flows/Mock）
自动化测试有限Newman CLI
适用人群前端开发者QA / 全栈 / 后端

选择建议：

  • 日常开发调试 → REST Client（零切换成本）
  • 完整测试流程 → Postman（功能全面）
  • 两者可并存：REST Client 管理项目接口，Postman 执行复杂测试

常见问题

问题原因解决方案
变量显示为红色未解析环境未选择或变量名拼写错误检查右下角环境选择
请求体不发送Body 前缺少空行请求头和 Body 之间必须有空行
HTTPS 证书错误自签名证书设置 "rest-client.strictSSL": false
响应中文乱码编码问题响应头确认 charset=utf-8

最佳实践

  1. 按模块拆分文件：每个业务模块一个 .http 文件，避免单文件过长
  2. 注释说明用途：每个请求前用 ### + 中文注释说明业务含义
  3. 环境变量隔离敏感信息：token/密钥放 .env，不入库
  4. 纳入 Code Review：接口变更通过 PR 审查，保持文档与实现同步
  5. 配合 JSON Server 使用：开发期 .http 文件指向本地 Mock 服务

延伸阅读