Insomnia — 是什么，开发中的 REST 和 GraphQL 客户端

什么是 Insomnia 及其主要特点

Insomnia — 一款用于发送 HTTP 请求和调试 API 的跨平台应用程序（Electron）。自 2016 年起由 Kong 公司开发，作为 Postman 的替代品，注重工作速度和隐私：数据存储在本地，云同步是可选功能且需要注册。

界面和导航

主窗口分为三列：左侧是请求树（Workspace），中间是带有 Params、Headers、Body 选项卡的请求编辑器，右侧是带有 Pretty、Raw 和 Preview 模式的响应面板。深色主题默认启用，支持通过 CSS 变量自定义主题。

代码生成

Insomnia 支持将请求导出为 20 多种语言和框架的代码：cURL、HTTPie、Python Requests、JavaScript Fetch/Axios、Kotlin OkHttp、Swift URLSession、Java Unirest、Ruby Net::HTTP 等。生成器会考虑请求头、请求体和认证类型，从而加快 API 与应用程序代码的集成。

Insomnia 与 Postman：API 客户端对比

Insomnia 和 Postman 解决相同的任务，但侧重点不同。Insomnia 更轻量（约 80 MB，Postman 约 300 MB），启动更快，无需强制注册即可完全离线工作。Postman 提供更成熟的生态系统，包括监控、mock 服务器和团队工作空间。

根据任务选择工具

对于个人开发和快速测试端点，Insomnia 由于轻量且无需注册而更加方便。对于使用共享集合、CI/CD 集成和生产 API 监控的团队协作，Postman 仍然是行业标准。

工作空间和环境的组织

Insomnia 中的 Workspace 包含按文件夹划分的请求树。每个请求可以是 HTTP、GraphQL、WebSocket 或 gRPC 类型。支持拖拽、复制以及按彩色标签对请求进行分组。工作空间的配置文件以 JSON 格式存储。

带继承的环境变量

Insomnia 支持嵌套环境（Sub Environments），它们继承父级变量。这样可以在全局环境中定义基础 URL，并仅为不同环境覆盖不同的参数。变量通过 {`{`}_variable${`}`} 语法进行替换。

// Insomnia 环境结构示例
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

在 Insomnia 中使用 GraphQL

Insomnia 提供 API 客户端中最好的 GraphQL 编辑器之一。GraphQL Query 选项卡允许基于加载的模式编写带字段自动补全的请求。右侧实时显示类型、字段和参数的文档。

加载模式和 Introspection

模式通过向端点发送 GraphQL Introspection 请求来加载。Insomnia 将模式缓存到本地，并在更改时自动更新。加载后即可使用自动补全（Ctrl+Space）、请求验证以及发送前的可能错误预览。

# 在 Insomnia 中使用变量的 GraphQL 请求
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

插件和功能扩展

Insomnia Plugin Hub 包含 100 多个扩展客户端功能的插件。插件通过 Preferences → Plugins 菜单或手动通过 npm 安装。热门类别包括测试数据生成、导出为各种格式以及自定义响应验证器。每个插件在发布到开发者的公共中心之前都必须经过强制审核。

热门插件

• insomnia-plugin-faker — 为测试请求生成虚假数据（姓名、邮箱、电话）。
• insomnia-plugin-aws4 — 根据 AWS Signature Version 4 对请求进行签名，用于配合 Amazon API Gateway 和 S3 使用。
• insomnia-plugin-utils — 直接在请求中处理日期、哈希和 Base64 编码的实用工具。

插件使用 JavaScript 编写，并通过模板 API 与 Insomnia 交互（response.*、request.*、environment.*）。开发插件需要基本的 Node.js 知识，并通过带有 insomnia-plugin 标签的 npm 包进行发布。

CLI 和测试自动化

Inso CLI — 内置于 Insomnia 的控制台工具，用于从终端运行请求和测试。Inso 可以运行单个请求或整个集合，将结果导出为 JSON，并可集成到 CI/CD 流水线中。inso run collection 命令按顺序执行集合中的所有请求。

GitHub Actions 集成示例

Inso CLI 可在 Docker 容器和 headless 模式下运行，因此可用于 GitHub Actions 和 GitLab CI。运行配置在 YAML 文件中描述，指明导出集合和环境的路径。支持通过 JavaScript 脚本对状态码和响应体进行断言。

# 使用 Inso CLI 的 GitHub Actions 工作流
- name: Run API tests
  run: npx insomnia-inso run collection
    --collection "Auth API"
    --env "Staging"
    --reporter junit
    --output reports/api-results.xml

Insomnia 与 Git 的集成及团队协作

Insomnia 支持通过 Git 同步集合。集合文件以 JSON 格式存储，可以添加到项目仓库中。Insomnia 提供内置 Git 客户端，可直接在界面中查看更改、创建提交和解决合并冲突。

设置 Git 同步

要连接 Git，请创建一个包含仓库的本地文件夹，并在 Insomnia 设置中将其指定为根目录。应用程序会自动跟踪集合文件的更改，并将其显示在Version Control面板中。支持标准操作：commit、push、pull 以及查看版本之间的差异。

通过 Insomnia Cloud 进行团队协作

对于没有 Git 的项目，Insomnia 通过 Insomnia Cloud 提供云同步。免费套餐包括最多 3 名团队成员以及集合的自动备份。付费套餐增加了访问管理、更改审计和优先支持。

Design Mode 和规范生成

Insomnia 中的 Design Mode 允许创建 OpenAPI 3.0 格式的 API 规范。该模式就像一个可视化编辑器：无需手动编写 YAML 即可定义端点和数据模式。规范可以导出为 JSON 或 YAML。

从 OpenAPI 生成集合

Insomnia 导入 OpenAPI 规范，并为每个端点创建请求集合。路径和模式被转换为现成的 HTTP 请求。在集成微服务时此功能很有用，因为规范存储在团队单独的仓库中。

请求标记

可以为每个请求分配彩色标签：red、blue、green、orange、purple。按标签筛选通过搜索栏工作，与文件夹结构无关，从而简化了具有数百个端点和多个模块的项目的导航。

Design Mode 和规范生成

Insomnia 中的 Design Mode 允许直接在应用程序内创建 OpenAPI 3.0 格式的 API 规范。该模式就像一个可视化编辑器：无需手动编写 YAML 即可定义端点、数据模式和参数。规范可以导出为 JSON 或 YAML 以便发布到仓库。

从 OpenAPI 生成集合

Insomnia 导入现有的 OpenAPI 规范，并自动为每个端点创建请求集合。路径和模式被转换为具有正确数据类型的现成 HTTP 请求。在集成微服务时此功能很有用，因为规范由单独的开发人员团队存储和维护。

请求的标记和筛选

为了组织大量请求，Insomnia 支持标记 — 可以为每个请求分配彩色标签：red、blue、green、orange、purple。按标签筛选通过搜索栏工作，与文件夹结构无关，从而简化了具有数百个端点和多个功能 API 模块的项目的导航。