vscode-httpyac-config

VSCode httpYac 配置

关于此技能

使用 httpYac 将 API 文档转换为可执行、可测试的 .http 文件。此技能提供工作流指导，帮助创建可用于生产环境的 API 集合，涵盖脚本编写、身份验证、环境管理以及 CI/CD 集成。

何时使用此技能

• API 文档 → 可执行文件：将 API 规范（Swagger、Postman、文档）转换为 httpYac 格式
• 身份验证实现：设置 OAuth2、Bearer 令牌或复杂的身份验证流程
• 大型集合：使用多文件结构组织 10 个以上的端点
• 请求串联：在请求之间传递数据（登录 → 使用令牌 → 创建 → 更新）
• 环境管理：切换开发、测试和生产环境
• 团队工作流：使用基于 Git 的协作方式并安全处理凭据
• CI/CD 集成：在 GitHub Actions、GitLab CI 等平台中进行自动化测试

预期结果

• ✅ 使用正确 httpYac 语法编写的可用 .http 文件
• ✅ 基于环境的配置（.env 文件、.httpyac.json）
• ✅ 安全的凭据管理（不将机密信息提交到 Git）
• ✅ 请求串联和响应验证
• ✅ 包含文档、适合团队使用的结构
• ✅ CI/CD 流水线集成（可选）

---

核心工作流

第 1 阶段：调研和规划

目标：了解 API 结构并提出文件组织方案。

关键问题：

1. 有多少个端点？（少于 20 个 = 单文件，20 个以上 = 多文件）
2. 使用哪种身份验证方式？（Bearer、OAuth2、API Key、Basic Auth）
3. 需要哪些环境？（开发、测试、预发布、生产）
4. 是否有现有文档？（Swagger、Postman 集合、文档 URL）

向用户提出结构方案：

Identified API modules:
- Authentication (2 endpoints)
- Users (5 endpoints)
- Articles (3 endpoints)

Recommended: Multi-file structure
- auth.http
- users.http
- articles.http

Proceed with this structure?

📖 详细指南：references/WORKFLOW_GUIDE.md

---

第 2 阶段：基于模板创建文件

🚨 必须：始终从 assets/ 目录中的模板开始。

模板使用顺序：

1. 读取 assets/http-file.template
2. 将结构复制到目标文件
3. 替换 {{PLACEHOLDER}} 变量
4. 添加特定于 API 的请求
5. 根据 references/SYNTAX.md 验证语法

可用模板：

• assets/http-file.template → 完整的 .http 文件结构
• assets/httpyac-config.template → 配置文件
• assets/env.template → 环境变量

要创建的关键文件：

• .http 文件 → API 请求
• .env → 环境变量（已加入 gitignore）
• .env.example → 含占位符的模板（提交到版本库）
• .httpyac.json → 配置（可选）

📖 文件结构指南：references/WORKFLOW_GUIDE.md#phase-2

---

第 3 阶段：实现身份验证

根据 API 类型选择模式：

API 类型	模式	参考位置
静态令牌	简单 Bearer	references/AUTHENTICATION_PATTERNS.md#pattern-1
OAuth2 凭据	自动获取令牌	references/AUTHENTICATION_PATTERNS.md#pattern-2
令牌刷新	自动刷新	references/AUTHENTICATION_PATTERNS.md#pattern-3
API Key	请求头或查询参数	references/AUTHENTICATION_PATTERNS.md#pattern-5-6

快速示例：

# @name login
POST {{baseUrl}}/auth/login
Content-Type: application/json

{
  "email": "{{user}}",
  "password": "{{password}}"
}

{{
  // Store token for subsequent requests
  if (response.statusCode === 200) {
    exports.accessToken = response.parsedBody.access_token;
    console.log('✓ Token obtained');
  }
}}

###

# Use token in protected request
GET {{baseUrl}}/api/data
Authorization: Bearer {{accessToken}}

📖 完整模式：references/AUTHENTICATION_PATTERNS.md 搜索模式：grep -n "Pattern [0-9]:" references/AUTHENTICATION_PATTERNS.md

---

⚠️ 关键语法规则

🎯 变量管理（最常见的错误）

1. 环境变量（来自 .env 文件）

@baseUrl = {{API_BASE_URL}}
@token = {{API_TOKEN}}

✅ 在文件顶部使用 @variable = {{ENV_VAR}} 语法

2. 实用函数（在脚本块中）

{{
  // ✅ CORRECT: Export with exports.
  exports.validateResponse = function(response, actionName) {
    return response.statusCode === 200;
  };
}}

###

GET {{baseUrl}}/api/test

{{
  // ✅ CORRECT: Call WITHOUT exports.
  if (validateResponse(response, 'Test')) {
    console.log('Success');
  }
}}

3. 响应数据（仅在响应后使用）

GET {{baseUrl}}/users

{{
  // ✅ Store for next request
  exports.userId = response.parsedBody.id;
}}

❌ 禁止事项

{{
  // ❌ WRONG: Don't use exports/process.env for env vars
  exports.baseUrl = process.env.API_BASE_URL;  // NO!

  // ❌ WRONG: Don't use exports when calling
  if (exports.validateResponse(response)) { }  // NO!
}}

🔍 创建后检查清单

• 使用模板作为基础
• 请求之间使用 ### 分隔符
• 变量：@variable = {{ENV_VAR}}
• 导出函数：exports.func = function() {}
• 调用函数时不使用 exports
• 创建 .env.example
• .http 文件中没有机密

📖 完整语法：references/SYNTAX.md 📖 常见错误：references/COMMON_MISTAKES.md 📖 速查表：references/SYNTAX_CHEATSHEET.md

---

针对 httpbook UI 的格式优化

清晰易浏览的结构

# ============================================================
# Article Endpoints - API Name
# ============================================================
# V1-Basic | V2-Metadata | V3-Full Content⭐
# Docs: https://api.example.com/docs
# ============================================================

@baseUrl = {{API_BASE_URL}}

### Get Articles V3 ⭐

# @name getArticlesV3
# @description Full content + Base64 HTML | Requires auth | Auto-decode
GET {{baseUrl}}/articles?page=1
Authorization: Bearer {{accessToken}}

格式指南

应该：

• ✅ 使用 60 个字符的分隔符：# =============
• ✅ 使用 | 添加行内说明：Detail 1 | Detail 2
• ✅ 使用 @description 添加悬停详情
• ✅ 使用 Emoji 提供视觉提示：⭐⚠️📄

不应该：

• ❌ 使用 80 个字符以上的分隔符
• ❌ 使用 HTML 注释 ``（会在 UI 中显示）
• ❌ 编写多行文档块
• ❌ 过度使用 ### 装饰

📖 完整指南：请参阅 SKILL.md 第 3.5 阶段中的前后对比示例

---

安全配置

必备的 .gitignore

# httpYac: Protect secrets
.env
.env.local
.env.*.local
.env.production

# httpYac: Ignore cache
.httpyac.cache
*.httpyac.cache
httpyac-output/

安全规则

始终：

• ✅ 使用环境变量存储机密
• ✅ 在 .gitignore 中添加 .env
• ✅ .env.example 中不包含真实机密
• ✅ 在日志中截断令牌：token.substring(0, 10) + '...'

绝不：

• ❌ 在 .http 文件中硬编码凭据
• ❌ 提交 .env 文件
• ❌ 记录完整令牌/机密
• ❌ 在生产环境中禁用 SSL

📖 完整指南：references/SECURITY.md 搜索模式：grep -n "gitignore\|secrets" references/SECURITY.md

---

参考资料加载指南

在以下情况下加载参考资料：

情况	要加载的文件	grep 搜索模式
设置身份验证	references/AUTHENTICATION_PATTERNS.md	grep -n "Pattern [0-9]"
脚本执行错误	references/SCRIPTING_TESTING.md	grep -n "Pre-Request|Post-Response"
切换环境	references/ENVIRONMENT_MANAGEMENT.md	grep -n "\.env|\.httpyac"
安全配置	references/SECURITY.md	grep -n "gitignore|secrets"
团队文档	references/DOCUMENTATION.md	grep -n "README|CHANGELOG"
高级功能	references/ADVANCED_FEATURES.md	grep -n "GraphQL|WebSocket|gRPC"
CI/CD 集成	references/CLI_CICD.md	grep -n "GitHub Actions|GitLab"
完整语法参考	references/SYNTAX.md	grep -n "@|??|{{" references/SYNTAX.md

快速参考（始终可用）：

• references/SYNTAX_CHEATSHEET.md - 常见语法模式
• references/COMMON_MISTAKES.md - 错误预防
• references/WORKFLOW_GUIDE.md - 完整工作流

---

完整工作流阶段

此技能遵循 7 个阶段的工作流。上文已介绍阶段 1-3。其余阶段如下：

阶段 4：脚本编写与测试

• 请求前/后的脚本
• 测试断言
• 请求链
• 📖 参考资料：references/SCRIPTING_TESTING.md

阶段 5：环境管理

• 使用 .env 文件存储变量
• 使用 .httpyac.json 进行配置
• 多环境设置
• 📖 参考资料：references/ENVIRONMENT_MANAGEMENT.md

阶段 6：文档

• 创建 README.md
• 文件内注释
• API 参考
• 📖 参考资料：references/DOCUMENTATION.md

阶段 7：CI/CD 集成（可选）

• 设置 GitHub Actions
• 配置 GitLab CI
• Docker 集成
• 📖 参考资料：references/CLI_CICD.md

---

质量检查清单

完成前，请确认：

结构：

• 文件结构适合集合规模
• 使用模板作为基础
• 使用 ### 分隔请求

语法：

• 变量：@var = {{ENV_VAR}}
• 函数已正确导出和调用
• 没有语法错误（已对照参考资料验证）

安全性：

• .env 已列入 .gitignore
• .env.example 包含占位符
• 没有硬编码凭据

功能：

• 所有请求均可成功执行
• 身份验证流程正常
• 请求链可正确传递数据

文档：

• README.md 包含快速入门指南
• 已记录环境变量
• 注释清晰简洁

---

常见问题

症状	可能原因	解决方案
"Variable not defined"	未使用 @ 声明	在顶部添加 @var = {{ENV_VAR}}
"Function not defined"	未导出	使用 exports.func = function() {}
脚本未执行	语法或位置错误	检查 {{ }} 的位置
Token 未保留	使用了局部变量	改用 exports.token
未加载环境变量	文件位置错误	将 .env 放在项目根目录中

📖 完整故障排除指南：references/TROUBLESHOOTING.md

---

成功标准

满足以下条件时，集合即可用于生产环境：

1. ✅ 所有 .http 文件均可无错误执行
2. ✅ 身份验证流程可自动运行
3. ✅ 已测试环境切换（开发/生产）
4. ✅ 机密信息受到保护（.env 已列入 gitignore）
5. ✅ 团队成员可在 5 分钟内完成克隆和运行
6. ✅ 请求包含断言
7. ✅ 文档完整

---

实施说明

生成文件前：

• 与用户确认结构
• 验证 API 文档是否完整
• 确认身份验证要求

生成过程中：

• 始终使用 assets/ 中的模板
• 写入前验证语法
• 在需要时加入身份验证
• 为关键端点添加断言

生成后：

• 向用户展示创建的结构
• 至少测试一个请求
• 指出后续步骤（凭据、测试）
• 提出添加更多端点

常见用户请求：

• “添加身份验证” → 加载 references/AUTHENTICATION_PATTERNS.md → 选择模式
• “无法运行” → 检查：变量是否已定义、{{ }} 语法、是否已加载 .env
• “串联请求” → 使用 # @name 和 exports 变量
• “添加测试” → 添加包含断言的 {{ }} 代码块
• “配置 CI/CD” → 加载 references/CLI_CICD.md → 提供示例

---

版本

版本：2.0.0（重构版）
最后更新：2025-12-15
基于：httpYac v6.x

相较于 v1.x 的主要变更：

• 重构为模块化参考资料（7 个文件）
• 聚焦于工作流指导和决策点
• 采用渐进式信息呈现设计（按需加载详细内容）
• 提供 grep 模式，便于快速查阅参考资料
• 将 SKILL.md 从 1289 行精简至约 400 行

功能特性：

• 基于模板生成文件
• 10 种身份验证模式
• 多环境管理
• 安全最佳实践
• CI/CD 集成示例
• 高级功能（GraphQL、WebSocket、gRPC）