vscode-httpyac-config

用途

本技能用于在 VSCode 中配置 httpYac，将 API 文档（Swagger、Postman 集合、接口文档）转换为可执行、可测试的 .http 文件，并构建生产级 API 集合，支持脚本、认证、环境管理与 CI/CD 集成。

主要能力

• 将 API 规范转换为 httpYac 格式的 .http 文件。
• 实现认证流程：静态 Bearer Token、OAuth2 凭据自动获取 Token、Token 自动刷新、API Key（Header 或 Query）等。
• 组织大型集合：按端点数量决定单文件或多文件结构（<20 个端点单文件，20+ 多文件）。
• 请求链式调用：通过 # @name 与 exports 变量在请求间传递数据（如登录 → 使用 Token → 创建 → 更新）。
• 环境管理：使用 .env 文件与环境变量，支持 dev/test/staging/production 切换，可选 .httpyac.json 配置。
• 团队协作：基于 Git 的协作流程与安全凭据处理（.env 加入 .gitignore，提供 .env.example 占位符）。
• CI/CD 集成（可选）：GitHub Actions、GitLab CI、Docker 集成示例。
• 高级特性：GraphQL、WebSocket、gRPC（见 references/ADVANCED_FEATURES.md）。

使用方式

本技能遵循 7 阶段工作流：

• 第 1 阶段：发现与规划。确认端点数、认证方式、所需环境、现有文档，并向用户提出文件结构建议。
• 第 2 阶段：基于模板创建文件。强制从 assets/ 目录中的模板开始：assets/http-file.template（完整 .http 文件结构）、assets/httpyac-config.template（配置文件）、assets/env.template（环境变量）。需创建 .http 文件、.env（gitignore）、.env.example（提交）、.httpyac.json（可选）。
• 第 3 阶段：实现认证。根据 API 类型选择模式，参考 references/AUTHENTICATION_PATTERNS.md，使用 grep -n "Pattern [0-9]:" 搜索。
• 第 4 阶段：脚本与测试。前置/后置请求脚本、测试断言、请求链式调用，参考 references/SCRIPTING_TESTING.md。
• 第 5 阶段：环境管理。使用 .env 文件与 .httpyac.json，参考 references/ENVIRONMENT_MANAGEMENT.md。
• 第 6 阶段：文档。创建 README.md、文件内注释、API 参考，参考 references/DOCUMENTATION.md。
• 第 7 阶段：CI/CD 集成（可选）。参考 references/CLI_CICD.md。

关键语法规则：

• 环境变量：@baseUrl = {{API_BASE_URL}}，@token = {{API_TOKEN}}，在文件顶部使用 @variable = {{ENV_VAR}} 语法。
• 工具函数：在脚本块中导出为 exports.validateResponse = function(response, actionName) { ... }；调用时不带 exports，如 if (validateResponse(response, 'Test')) { ... }。
• 响应数据（仅后置响应）：exports.userId = response.parsedBody.id; 用于下一请求。
• 禁止：使用 exports/process.env 处理环境变量；调用时使用 exports。

创建后检查清单：使用模板作为基础；请求间用 ### 分隔；变量使用 @variable = {{ENV_VAR}}；函数导出为 exports.func = function() {}；调用函数不带 exports；创建 .env.example；.http 文件中不含密钥。

为 httpbook UI 优化格式：使用 60 字符分隔符 # =============；内联描述用 | 分隔；@description 用于悬停详情；使用表情符号作视觉提示（⭐⚠️📄）；避免 80+ 字符分隔符、HTML 注释、多行文档块、过多 ### 装饰。

安全配置：.gitignore 必须包含 .env、.env.local、.env..local、.env.production、.httpyac.cache、.httpyac.cache、httpyac-output/。始终使用环境变量存密钥，.env 加入 .gitignore，.env.example 不含真实密钥，日志中截断 Token（token.substring(0, 10) + '...'）。禁止在 .http 文件硬编码凭据、提交 .env 文件、记录完整 Token/密钥、在生产环境禁用 SSL。

参考材料加载指南：按需加载 references 目录下的文件，如设置认证加载 AUTHENTICATION_PATTERNS.md（grep -n "Pattern [0-9]"）、脚本错误加载 SCRIPTING_TESTING.md（grep -n "Pre-Request|Post-Response"）、环境切换加载 ENVIRONMENT_MANAGEMENT.md（grep -n ".env|.httpyac"）、安全配置加载 SECURITY.md（grep -n "gitignore|secrets"）、团队文档加载 DOCUMENTATION.md（grep -n "README|CHANGELOG"）、高级特性加载 ADVANCED_FEATURES.md（grep -n "GraphQL|WebSocket|gRPC"）、CI/CD 加载 CLI_CICD.md（grep -n "GitHub Actions|GitLab"）、完整语法加载 SYNTAX.md（grep -n "@|??|{{"）。常用快速参考：SYNTAX_CHEATSHEET.md、COMMON_MISTAKES.md、WORKFLOW_GUIDE.md。

适用场景

• 将 API 文档（Swagger、Postman、文档）转换为可执行文件。
• 实现 OAuth2、Bearer Token 或复杂认证流程。
• 组织 10+ 端点的大型集合，采用多文件结构。
• 请求链式调用：登录 → 使用 Token → 创建 → 更新。
• 环境管理：dev/test/production 切换。
• 团队工作流：基于 Git 的协作与安全凭据处理。
• CI/CD 集成：在 GitHub Actions、GitLab CI 等中自动化测试。

限制

• 版本：2.0.0（重构版），最后更新 2025-12-15，基于 httpYac v6.x。
• v1.x 到 v2.0.0 的主要变化：重构为模块化 references（7 个文件）；聚焦工作流指导与决策点；渐进式披露设计（按需加载细节）；使用 grep 模式快速导航；SKILL.md 从 1289 行缩减至约 400 行。
• 本技能提供的功能包括：模板驱动文件生成、10 种认证模式、多环境管理、安全最佳实践、CI/CD 集成示例、高级特性（GraphQL、WebSocket、gRPC）。
• 源页面未提供价格、收费模式、平台兼容性细节、性能数据或效果承诺等信息，暂未提供。
• 使用前需确认 API 文档完整性、验证认证要求，并与用户确认文件结构。