Insomnia13.1.0

Insomnia 是一款开源、跨平台的 API 客户端，适合设计、调试和测试 REST、GraphQL、WebSocket、SSE、gRPC 等接口。它的价值不只是发送一次请求，而是把 API 规范、请求集合、环境变量、Mock、测试脚本和命令行验证放到同一套工作流中。当前按官方发布记录核验到的稳定版为 13.1.0；如果你看到 beta 版本，先确认是否愿意承担预发布版本的兼容性风险。

先确定工作区和数据边界

Insomnia 可以在不登录的情况下使用 Scratch Pad，也可以把请求放进项目，再按需要使用本地、Git 或 Cloud 存储。选择哪一种方式，取决于你是在临时排查接口、维护个人项目，还是要与团队共享请求和规范。不要一开始就把所有内容都放进云端：请求头、环境变量和示例响应里可能含有真实凭据或业务数据。

官方文档把本地存储、Git Sync、Cloud Sync 和本地 Vault 分开说明。对个人调试而言，本地或 Scratch Pad 往往更简单；对团队协作而言，Git 更容易审查变更，但仍要把真实密码、Token 和生产数据排除在可同步内容之外。

按协议和平台选择起点

Insomnia 官方定位覆盖 REST、GraphQL、WebSocket、SSE、gRPC 以及其他兼容 HTTP 的协议。安装时可从官方页面按 Windows、macOS 或 Linux 选择入口；本文记录的 13.1.0 是稳定版，13.2.0-beta.1 这类预发布版本不应当当作生产环境默认选择。

• REST：从请求方法、URL、Query、Headers、Body 和 Auth 开始，适合快速复现接口问题。
• GraphQL：准备 endpoint、Query 或 Mutation 以及变量，检查请求体和响应错误，不要只看 HTTP 状态码。
• gRPC：先确认服务定义、方法和消息结构，客户端是否能加载对应 proto 会直接影响调用入口。
• WebSocket / SSE：关注连接建立、消息方向、鉴权和持续连接状态；它们与一次性 HTTP 请求的排错顺序不同。
• 系统与架构：Windows、macOS、Linux 的安装包和权限行为可能不同；在 ARM 设备上要按官方页面选择对应架构，不能只看系统名称。

官方应用界面和文档当前以英文资料为主；菜单名称、插件能力和平台包名可能随版本变化。安装后先确认应用能正常打开，再决定是否启用同步或导入已有项目。

从 Collection 建立第一条请求

Collection 是 Insomnia 的工作单元：它可以集中保存请求，按文件夹组织接口，并继续用于 Collection Runner、脚本和 CLI 执行。第一次使用时，建议先创建一个小型 Collection，不要把整个团队的接口资料一次性导入后再寻找问题。

先把请求的可变部分拆出来

1. 创建 Collection：按项目或服务命名，例如 billing-api，再按资源或业务流程建立文件夹。名称要能帮助你定位请求，不要用一堆日期或临时编号。
2. 创建请求：填写 Method 和 URL，随后补齐 Query、Headers、Body、Auth 与脚本。需要复现线上问题时，先把原始 cURL 导入，再删除不必要的 Cookie 和个人标识。
3. 第一次发送：先使用开发或测试环境，确认 URL、鉴权和请求体后再点击 Send。看响应时同时检查状态码、响应头、实际 JSON 字段、耗时和服务端错误信息。
4. 保存可复用结果：把稳定的请求保留在 Collection，把一次性排查用的临时请求放到单独文件夹；这样后续运行 Collection Runner 时不会把实验请求一起执行。

请求编辑器支持导入 cURL、Postman、OpenAPI、HAR 和 WSDL 等来源。导入只是起点：字段名、鉴权方式、变量引用和脚本通常需要按目标服务重新核对，不能因为请求能显示在列表里就认为迁移完成。

Environment 负责地址，私密值另行保护

把开发、测试、预发布和生产环境的差异放进 Environment，能避免复制多份几乎相同的请求。常见做法是设置一个基础环境，再建立多个子环境，使用 base_url、api_version、tenant_id 等变量替换 URL 或请求参数。

1. 先放非敏感配置：主机地址、端口、API 版本和测试租户可以作为普通变量，名称保持一致，避免每条请求使用不同叫法。
2. 再区分环境：开发和生产只替换必要变量，检查子环境当前是否被选中；变量未解析时，先看作用域和拼写，不要盲目重建请求。
3. 把凭据放在私密区域：Token、密码和私钥不要写进共享 JSON 或 Git 仓库。使用官方文档所述的 Private Environment 或 Vault 机制时，还要记住本地密钥丢失可能影响恢复。
4. 发送前做一次环境确认：看请求 URL、Auth、Headers 和当前 Environment 标签，特别是生产环境。客户端颜色或命名提示只能降低误操作概率，不能替代服务端权限。

环境变量解决的是配置切换，不是权限控制。即使请求保存在本地，也应避免把真实响应、客户数据和生产 Token 混入可共享的 Collection。

把设计、Mock 和验证串成一条链

从 OpenAPI 规范开始约定接口

Insomnia 提供 API Spec 工作流，可编辑或预览 OpenAPI 文档，并据此生成或维护请求。规范先明确路径、参数、响应和错误结构，调试请求时才有可对照的契约；如果请求与规范不一致，要先判断是接口实现变了，还是本地请求落后了。

用 Mock 和测试缩短反馈周期

接口尚未完成时，可以用 Mock 让前端或集成方先验证响应形状。接口可用后，再通过 pre-request 和 after-response 脚本处理变量、链式请求和断言；Collection Runner 适合按顺序运行一组请求，检查完整流程而不是只看一条成功响应。脚本里的断言应尽量验证关键字段、状态和业务条件，不要只断言状态码等于 200。

需要自动化时接入 Inso CLI

Inso CLI 可以在终端或 CI/CD 中运行规范、Collection 和测试。第一次接入流水线时，先在本机使用与 CI 相同的 Environment 和数据，再确认退出码、变量注入、凭据来源和报告输出。桌面端能运行而 CLI 失败，通常不是软件功能缺失，而是工作目录、环境变量、项目文件或认证上下文不同。

迁移和导出先看清范围

官方文档列出的导入来源包括 Insomnia JSON/YAML、Postman、HAR、OpenAPI、Swagger、WSDL 和 cURL；导出则要区分文档、项目和全部数据。迁移前先做一份只读备份，再按下面顺序检查：

• 只迁移接口规范：优先导入 OpenAPI 或 Swagger，随后检查生成的请求、示例和鉴权字段是否符合当前服务。
• 迁移已有调试集合：导入 Postman 或 Insomnia 数据后，逐个检查变量、脚本、Cookie、证书和文件上传引用。
• 只带走一个请求：cURL 适合快速复现单条 HTTP 请求，但不会完整带出原项目的 Environment、测试脚本和协作关系。
• 准备离开当前工作区：先明确是导出当前文档、项目还是全部数据，再检查导出文件里是否包含 Token、私密变量、响应体或个人信息。

导入后最可靠的验收方式是选一条低风险接口：核对 URL、变量、认证、请求体和响应断言，再运行一次 Collection。不要只以“导入成功”提示作为迁移完成标准。

故障先定位层级

遇到具体问题时，可对照 官方 Requests 文档、官方 Environments 文档 和 官方测试文档，先把问题归到请求、环境、网络、脚本或存储层，再处理具体配置。