Yaak 使用指南

一、简介

Yaak (https://github.com/mountain-loop/yaak) 是一个跨平台（Windows/Mac/Linux）且本地优先的 API 客户端，支持 REST、GraphQL、WebSocket、SSE（Server-Sent Events）以及 gRPC。
其主要特点包括：

• 无需登录、无强制云服务依赖，数据可本地保存。
• 支持将请求和环境以文本／文件夹形式同步到文件系统，从而可配合 Git 管理。
• 支持插件扩展、动态变量、模板标签、环境切换等高级功能。
  

---

二、安装与初次运行

1. 前往 Yaak 官网 下载适用于你系统的安装包。
2. 安装完成后启动，第一次运行可能提示创建工作区或导入现有集合。
3. 可选择将工作区设定为本地目录，以便于版本控制。

---

三、基本使用流程

3.1 创建请求

• 在左侧面板点击 “New Request” 或 “+” 创建新的请求。
• 选择请求类型（GET/POST/PUT/DELETE 等 REST 请求），也可选择 GraphQL、gRPC、WebSocket、SSE。([GitHub][1])
• 在 URL 栏输入请求地址。若 URL 中含 路径参数（如 /users/:userId/comments/:commentId），Yaak 会识别 :userId、:commentId 并自动在 Params 栏生成。
• 配置请求参数、头信息（Headers）、主体（Body）等。Body 可设置为 JSON、XML、表单等格式。
• 点击 “Send” 执行请求。结果在右侧显示（状态码、响应时间、响应体、响应头等）。

3.2 组织请求

• 可在左侧创建 Workspaces（工作区）进行分组。
• 每个工作区里可建立文件夹／子文件夹，用来把请求按项目、模块、环境划分。
• 支持为每个请求或文件夹设定环境变量，比如 {{base_url}}。

3.3 环境管理

• 在 “Environments” 面板中定义环境（如 dev、staging、prod），为每个环境配置变量。
• 切换环境后，当前请求会使用对应环境的变量值。
• 可结合版本控制将环境配置文件（例如 env.dev.json）保存到 Git。

3.4 导入/导出

• 支持从 Postman、Insomnia、OpenAPI、Swagger、Curl 等格式导入已有集合。
• 同样支持导出集合或请求，用来备份或共享。
  

---

四、进阶功能

4.1 模板标签 & 动态变量

• Yaak 支持在请求中插入动态值，如 {{uuid()}}、{{timestamp()}} 等。
• 模板也可以用于响应体处理或变量提取，例如将响应中的某个字段保存为环境变量供后续请求使用。
• 插件系统允许你自定义模板标签或变量生成逻辑。

4.2 插件扩展

• Yaak 内置插件机制，可用于添加自定义认证方式（OAuth 2.0、JWT、API Key）、请求预处理／后处理、UI 扩展等。
• 若你有特殊需求，可编写插件并安装到 Yaak。

4.3 Git/文件系统集成

• 工作区可与本地文件夹同步，成为普通的文件结构（如 /requests, /env, /secrets）。你可以将此文件夹纳入 Git、Dropbox、OneDrive 等同步服务。
• 优势在于：团队协作、更易于版本审查、无需依赖云服务。

4.4 支持多种协议

• 除了普通 REST 请求外，Yaak 支持：

  • GraphQL：发送 query、mutation，也可带变量。
  • gRPC：发起 RPC 调用（需要你配置 proto／服务地址等）。
  • WebSocket & SSE：建立流式连接，查看实时数据。

---

五、典型使用场景示例

假设你正在开发一个以微服务为后端、同时暴露 REST 和 GraphQL 接口的前端项目。那么你可以这样用 Yaak：

1. 在 workspace “MyProject” 下创建两个文件夹：REST、GraphQL。

2. 在 Environments 定义三个环境：dev (base_url = https://api-dev.example.com)、staging、prod。

3. 在 REST 文件夹下创建请求：

   • GET {{base_url}}/users
   • POST {{base_url}}/users (Body 为 JSON)
   • REST 请求中用 {{token}} 环境变量表示认证 token。

4. 在 GraphQL 文件夹下创建请求：

   • Query Launches 等 GraphQL 查询，使用 ${{limit}} 变量。

5. 执行请求后，用模板标签提取响应，比如将 access_token 存成 {{token}} 环境变量，后续请求自动用上。

6. 将这个 workspace 同步到本地 Git 仓库（例如 ~/Projects/MyProject/yaak-workspace），团队成员共享。

---

六、优缺点总结

优点：

• 流畅、轻量、无登录门槛。
• 本地优先、版本可控、适合开发协作。
• 支持多协议，适用范围广。
• 插件扩展机制良好，可定制。

缺点／需要注意：

• 相比一些老牌工具（如 Postman、Insomnia），可能缺少极复杂的自动化监控、测试脚本等企业级功能。
• 初次使用模板、插件、Git 集成可能需要一定学习成本。
• 虽然是开源，但商业使用或二进制发行可能有许可或费用注意。

---

七、快速上手 5 分钟指南

1. 下载并安装 Yaak。
2. 创建一个新工作区（Workspace）→ 新建请求。
3. 输入一个简单的 GET 请求（例如 https://api.spacexdata.com/v4/launches/latest）。发送并查看响应。
4. 在环境中定义 base_url = https://api.spacexdata.com/v4，修改请求为 {{base_url}}/launches/latest。切换环境。
5. 创建 POST 请求或 GraphQL 请求，尝试在 Body 中插入模板标签例如 {{uuid()}}。
6. 导出当前工作区／请求备注到文件夹，尝试用 Git 提交。