X5 Protocol REST Client - VS Code 插件

专为小米 X5 协议设计的 VS Code API 测试插件，提供便捷的请求编辑、发送和响应查看功能。

功能特性

安装

方式一：从 VSIX 安装（推荐）

1. 下载 vs-x5-plugin-*.vsix 文件
2. 打开 VS Code，按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows）
3. 输入 "VSIX"，选择 "Extensions: Install from VSIX..."
4. 选择下载的 .vsix 文件
5. 重启 VS Code

方式二：命令行安装

code --install-extension /path/to/vs-x5-plugin-*.vsix

快速开始

第一步：配置环境变量

在项目根目录创建 .x5env 文件（JSON 格式）：

{
  "development": {
    "DEV_APPID": "your_app_id_here",
    "DEV_APPKEY": "your_app_key_here",
    "DEV_BASE_URL": "http://localhost:8080"
  },
  "production": {
    "PROD_APPID": "your_prod_app_id",
    "PROD_APPKEY": "your_prod_app_key",
    "PROD_BASE_URL": "https://api.example.com"
  }
}

提示：APPID 和 APPKEY 由服务器端提供

第二步：创建请求文件

新建 test.x5 文件，写入以下内容：

### 创建任务
@name = 创建任务
@appid = {{DEV_APPID}}
@appkey = {{DEV_APPKEY}}
@url = {{DEV_BASE_URL}}/x5/task/create

POST @url
X5-Method: createTask

{
  "taskName": "测试任务",
  "priority": "high",
  "assignee": "user123"
}

第三步：发送请求

点击请求上方的 "Send Request" 链接，或在命令面板中选择 "X5: Send X5 Request"

请求文件格式

.x5 格式

### 请求描述（可选）
@name = 请求名称
@appid = {{DEV_APPID}}
@appkey = {{DEV_APPKEY}}
@url = {{DEV_BASE_URL}}/api/endpoint

POST @url
X5-Method: methodName

{
  "key1": "value1",
  "key2": "value2"
}

指令说明：

自定义请求头：

可以在 X5-Method: 后添加任意 HTTP 请求头：

### 带自定义请求头的请求
@name = 测试请求
@appid = {{DEV_APPID}}
@appkey = {{DEV_APPKEY}}
@url = {{DEV_BASE_URL}}/api/endpoint

POST @url
X5-Method: methodName
X-Custom-Header: custom-value
Authorization: Bearer your-token-here
X-Request-ID: 12345

{
  "key": "value"
}

多请求文件

一个文件可以包含多个请求，用 ### 分隔：

### 请求1：创建资源
@name = 创建资源
@appid = {{DEV_APPID}}
@appkey = {{DEV_APPKEY}}
@url = {{DEV_BASE_URL}}/x5/resource/create

POST @url
X5-Method: createResource
{"name": "test"}

### 请求2：查询资源
@name = 查询资源
@appid = {{DEV_APPID}}
@appkey = {{DEV_APPKEY}}
@url = {{DEV_BASE_URL}}/x5/resource/query

POST @url
X5-Method: queryResource
{"resourceId": "123"}

环境管理

.x5env 文件格式

使用单个 .x5env 文件管理所有环境，JSON 格式：

{
  "development": {
    "DEV_APPID": "dev_app_id",
    "DEV_APPKEY": "dev_app_key",
    "DEV_BASE_URL": "http://localhost:8080"
  },
  "production": {
    "PROD_APPID": "prod_app_id",
    "PROD_APPKEY": "prod_app_key",
    "PROD_BASE_URL": "https://api.example.com"
  },
  "test": {
    "TEST_APPID": "test_app_id",
    "TEST_APPKEY": "test_app_key",
    "TEST_BASE_URL": "http://test.example.com"
  }
}

切换环境

1. 按 Cmd+Shift+P 打开命令面板
2. 输入 "X5: Switch Environment"
3. 选择目标环境

状态栏右下角会显示当前环境：$(server) development

添加新环境

直接编辑 .x5env 文件，添加新的环境配置：

{
  "staging": {
    "STAGING_APPID": "staging_app_id",
    "STAGING_APPKEY": "staging_app_key",
    "STAGING_BASE_URL": "https://staging.example.com"
  }
}

保存后切换环境时会自动识别新环境。

常用命令

配置选项

在 VS Code 设置中搜索 x5，或手动编辑 settings.json：

{
  // 默认环境
  "x5.defaultEnvironment": "development",

  // 是否启用请求历史
  "x5.historyEnabled": true,

  // 历史记录最大数量
  "x5.maxHistorySize": 100,

  // 请求超时时间（毫秒）
  "x5.requestTimeout": 30000
}

响应面板

请求发送后，右侧会显示响应面板，包含：

• 状态指示：成功（绿色）/ 失败（红色）
• HTTP 状态码：200、400、500 等
• 请求时间：显示请求发送的日期和时间（YYYY-MM-DD HH:MM:SS）
• 请求耗时：显示请求执行时间（毫秒）
• 响应大小：响应数据的字节数
• Content-Type：响应内容类型
• 请求详情：包含自定义请求头（如果有）
• 响应头：Content-Type、Content-Length 等
• 响应体：JSON 格式化高亮显示

实际示例

示例1：创建容器

### 创建空容器
@name = 创建容器
@appid = {{DEV_APPID}}
@appkey = {{DEV_APPKEY}}
@url = {{DEV_BASE_URL}}/x5/task/callEmptyContainer/create

POST @url
X5-Method: callEmptyContainer

{
  "containerName": "test-container",
  "region": "cn-north-1"
}

示例2：查询任务

### 查询任务状态
@name = 查询任务
@appid = {{DEV_APPID}}
@appkey = {{DEV_APPKEY}}
@url = {{DEV_BASE_URL}}/x5/task/query

POST @url
X5-Method: queryTask

{
  "taskId": "12345",
  "includeDetails": true
}

示例3：带自定义请求头

### 带认证的请求
@name = 认证请求
@appid = {{DEV_APPID}}
@appkey = {{DEV_APPKEY}}
@url = {{DEV_BASE_URL}}/x5/api/secure

POST @url
X5-Method: secureMethod
X-User-ID: user123
X-Session-Token: abc123xyz

{
  "data": "value"
}

常见问题

Q1: 点击 "Send Request" 没反应？

A: 检查以下几点：

1. 确认插件已正确安装
2. 确认 .x5env 文件中的变量已正确配置
3. 查看 VS Code 输出面板的错误信息

Q2: 提示 "Variable {{DEV_APPID}} is not defined"？

A: 需要在项目根目录创建 .x5env 文件并配置对应变量。

Q3: 请求发送失败？

A: 检查：

1. 网络连接是否正常
2. URL 是否正确
3. APPID 和 APPKEY 是否有效
4. 服务器是否正常运行

Q4: 如何查看请求历史？

A:

1. 按 Cmd+Shift+P 打开命令面板
2. 输入 "X5: Show Request History"
3. 选择历史请求查看详情或重新发送

Q5: 修改 .x5env 文件后环境列表没有更新？

A: 切换环境时会自动重新读取配置文件，显示最新的环境列表。

X5 协议说明

请求结构

{
  "header": {
    "appid": "应用ID",
    "sign": "MD5签名（大写）",
    "method": "API方法名"
  },
  "body": "业务数据的JSON字符串"
}

签名计算

sign = md5(appid + body + appkey).toUpperCase()

示例：

appid = "my_app"
body = "{\"userId\":\"123\"}"
appkey = "my_key"

sign = md5("my_app{\"userId\":\"123\"}my_key").toUpperCase()

请求编码

1. 将整个请求体（header + body）序列化为 JSON
2. 进行 Base64 编码
3. 作为 data 参数发送 POST 请求

项目结构

vs-x5-plugin/
├── src/
│   ├── extension.ts              # 插件入口
│   ├── x5Protocol/               # X5 协议核心实现
│   │   ├── requestParser.ts      # 请求解析器
│   │   ├── signatureGenerator.ts # 签名生成
│   │   ├── requestEncoder.ts     # Base64 编码
│   │   ├── requestSender.ts      # HTTP 请求发送
│   │   └── responseProcessor.ts  # 响应处理
│   ├── views/                    # 视图组件
│   │   ├── responsePanel.ts      # 响应展示面板
│   │   └── x5CodeLensProvider.ts # CodeLens 支持
│   └── management/               # 管理模块
│       ├── environmentManager.ts # 环境管理（.x5env）
│       ├── variableResolver.ts   # 变量解析
│       └── historyManager.ts     # 历史记录
├── syntaxes/x5.tmLanguage.json   # 语法高亮定义
├── examples/                     # 示例文件
├── .x5env.example               # 环境变量示例
└── README.md                     # 说明文档

开发

# 安装依赖
npm install

# 编译
npm run compile

# 监听模式编译
npm run watch

# 运行测试
npm run test

# 打包
npm run vscode:prepublish && vsce package

许可证

MIT License

Copyright (c) 2025 ianguanghui