跳至主要內容

Insomnia：Collection 存储与 Inso 自动化边界

高谷深陵大约 9 分钟约 2727 字
Insomnia 从请求集合、存储方式、环境密钥到 Inso CLI 和团队治理的机制图
Insomnia 请求资产控制面Collection、环境和测试只有绑定明确的存储主源、运行时 Secret、Inso CLI 与退出路径，才能从个人调试走向团队资产。高清原图

Insomnia 在个人电脑上很容易用起来：创建请求、选择鉴权、填入环境变量，然后发送。团队真正会遇到的难题在第二台电脑出现。同事能否取得同一份请求，Git 与云端哪一份才是主源，私有变量是否跟着同步，CI 怎样找到 Collection，升级后格式能否回退，这些问题决定它是一款临时客户端，还是可以维护的接口资产入口。

安装之后先确认发布线和数据位置

桌面端应从官方发布渠道或企业软件仓库安装，校验发布者、摘要和适用平台。Inso CLI 与桌面端来自同一产品线，但应分别记录实际版本。协作成员保持相同 major，升级前在样例项目验证导出、Git Sync、脚本和 CLI；官方发布策略没有 LTS 线，major 变化可能包含格式、CLI 或插件 API 的不兼容调整。

inso --version
inso --help

启动后不要急着导入所有历史集合。先创建一个只含 /health 的样例 Collection，记录项目采用哪种存储方式、应用数据目录在哪里，以及系统代理和证书从何处读取。能够发送请求，只证明当前设备的当前状态可用，不能证明项目能在另一个工作站或无界面 runner 重建。

Collection、Design Document 与环境各自负责什么

Collection 保存可执行请求、文件夹、脚本和测试；Design Document 以 API 规范设计、lint 和测试为中心；环境提供请求中引用的可变值。三个对象可以关联，却不应互相冒充。OpenAPI 是接口形状的主源时，不要让 Collection 中的手工请求反向成为第二份契约；Collection 更适合保存调用场景、调试样本和回归断言。

环境的层级会影响变量解析。Global、Collection、Folder 以及选中的子环境可能同时定义同名字段。使用 baseUrl、租户和功能开关时，应约定唯一层级，避免 GUI 看似取到正确值，CLI 却因选择不同环境落到另一目标。生产地址不应成为默认值；没有显式环境时，请求应失败，而不是静默访问最敏感环境。

{
  "baseUrl": "https://api.test.example",
  "tenant": "sandbox-a",
  "requestTimeoutMs": 5000
}

这类非敏感配置可以进入版本控制。token、Cookie、客户端私钥和真实用户数据不属于同一层。

四种存储方式代表四种责任

Insomnia 官方提供 Local Vault、Scratch Pad、Cloud Sync 与 Git Sync。它们不是同一数据的四个备份按钮，而是不同的主源和协作模型。

存储方式适合的入口主要治理责任
Scratch Pad个人临时试验本地清理，不能成为团队唯一副本
Local Vault离线或严格本地项目设备加密、备份、换机和离职交接
Git Sync需要仓库审查与数据自持的团队Git 凭证、冲突、分支保护与 Secret 扫描
Cloud Sync多设备和内建协作组织身份、席位、数据边界与云端退出

切换存储类型会改变后续修改写到哪里。Cloud Sync 转为 Local Vault 前要让协作者拉取最新状态；Git Sync 转出后，远程仓库不会自动随新主源变化。迁移时先冻结编辑、拉齐最新提交、做脱敏备份，再在候选版本完成转换和 CLI 复测。否则“转换成功”可能只代表本机保留了一份不完整状态。

Git Sync 仍然需要标准 Git 治理

Git Sync 把项目资源保存为仓库中的 YAML，并让 Insomnia 充当 Git 客户端。分支保护仍由 Git 服务端执行，回退提交仍需使用 Git 工具或托管平台。应用产生的 metadata 变化不一定改变请求语义，评审者需要区分结构维护与 URL、Header、脚本、断言等真实行为变化。

团队接入时应固定仓库位置、默认分支、Code Owner、合并策略和允许的凭证方式。每位协作者需要自己连接远程仓库，组织里出现同名项目不代表大家天然共享同一主源。遇到冲突时先看文件差异，不能为了让界面恢复而覆盖整个项目目录。

一份合理仓库把 Collection、规范和执行脚本放在可理解的位置：

api-assets/
  .insomnia/
  openapi/
    service.yaml
  README.md
  scripts/
    smoke.ps1

README 说明存储方式、环境名、Secret 来源、CLI 命令和 owner。真实凭证、vault key、客户端私钥与运行报告不得进入目录。

Secret 要在运行时进入请求

私有 global sub-environment 可以保存 Secret 类型变量。它们默认不参与同步或导出，需要 vault key 解锁；vault key 丢失后重置会删除已有 Secret。Secret 默认也不暴露给脚本，开启 vault script access 会扩大所有相关脚本的能力，应以项目安全评审为前提。

CI 更适合从外部 Secret Manager 或流水线 Secret 注入。Insomnia 支持通过 Inso CLI 集成外部 vault，runner 使用工作负载身份取得值，不把云端长期密钥塞进 YAML。无论采用哪种方式，Collection 只保存引用，环境选择与 Secret 注入必须在任务开始时明确。

Secret 脱离仓库并不等于不会泄漏。请求脚本可能打印变量，服务端可能在错误响应中回显 Header，JUnit 或控制台报告也可能保存 Body。测试报告默认保留最少字段，只记录请求标识、断言、耗时与关联 ID；需要调试敏感响应时，使用短保留、受控访问的专用 artifact。

用同一请求区分网络、身份和应用失败

建立一个不会修改业务状态的 /health 请求，并要求响应携带 x-request-id。第一次把 baseUrl 指向 .invalid 域名，预期得到 DNS 或连接错误，服务端没有 request id。第二次改回测试地址并使用已撤销 token，预期完成 TLS 与 HTTP 交换，返回 401 或 403，网关或服务端能关联 request id。第三次从私有环境注入有效低权限 token，断言状态码、Content-Type 和一个稳定业务字段。

const body = insomnia.response.json();
insomnia.test('health endpoint is ready', () => {
  insomnia.expect(insomnia.response.code).to.equal(200);
  insomnia.expect(body.status).to.equal('ready');
});

具体脚本 API 以目标版本内置模板为准，升级时通过样例 Collection 复测。实验重点不是语法，而是三种失败分别落在传输、身份和应用层，并能由 CLI 复现。

Inso CLI 把桌面资产带入自动化

Inso 会在工作目录的 .insomnia 和桌面应用数据目录中寻找项目，也可以通过参数指定来源。CI 必须显式传入工作目录与环境，不应依赖 runner 恰好安装过桌面端。

inso --ci --workingDir api-assets run collection "Health Smoke" \
  --env "ci"

--ci 禁止交互等待，Collection 名称、工作目录和环境应稳定。执行前打印 Inso 版本与 Git 提交号，执行后保存退出码、请求数量和脱敏断言结果。CLI 找不到 Collection 时，先检查数据源和标识符；不要临时导入另一份 JSON，让桌面和 CI 从此维护两套资产。

Design Document 还可以通过 Inso 执行规范 lint、测试与导出。将 lint 与请求 smoke 分成不同任务：前者证明契约可以解释，后者证明选定环境的调用场景成立。两者全绿也不替代服务端授权、数据副作用和业务端到端检查。

代理、CA 和 mTLS 分别校准

桌面成功、CLI 失败时，先比较代理、NO_PROXY、系统信任库、自定义 CA 和客户端证书。401 是 HTTP 身份结果，证书失败发生在 HTTP 之前；把 TLS 错误归为 token 问题，只会让凭证在更多地方暴露。

客户端证书应按目标域名配置，只保存受控路径或 Secret 引用。私钥、PFX 密码和企业根证书的分发有独立 owner。关闭证书验证只能作为一次对照实验：如果关闭后连接成功，结论是信任链需要修复，不是把不安全选项写进团队模板。

插件与脚本属于本地执行面

Insomnia 插件可以读取或改变请求、响应和界面行为，模板标签还能动态注入数据。第三方插件必须审查来源、维护状态、依赖和所需能力，固定版本后在样例项目验证。插件市场存在不等于项目已完成安全审核。

脚本同样会接触环境与响应。避免复制来历不明的认证脚本，不在脚本里执行长期 token 交换或打印完整对象。组织基线应记录允许插件、脚本 owner 和升级复测；停用项目时同时删除本地插件配置与相关凭证。

升级、迁移和退出按资产主源收尾

升级前保存当前版本、存储类型、未推送修改、脱敏导出和固定 smoke 结果。在隔离分支用候选桌面端与 Inso 重跑，再比较 YAML、请求数量、环境解析和脚本行为。格式发生迁移时不要直接用旧版本继续写新数据；先决定完成迁移还是回退提交。

停用 Insomnia 时，先把仍有效的请求和断言迁移到新的权威入口，撤销 Cloud 组织成员、OAuth 与外部 vault 权限，删除 Git Sync 凭证、本地 Vault、缓存、证书副本和报告，最后卸载应用。仅删除桌面程序不会撤销云端席位或 runner 身份。

Insomnia 是否适合团队，不取决于界面按钮多少。能明确选择存储主源，让环境与 Secret 分层，由同一项目驱动桌面和 Inso，在证书、插件、升级和人员退出时完整收敛，它才真正成为可治理的接口资产控制面。

跳到正文