技能介绍

被云端收藏夹困住的接口调试

很多团队的 API 调试仍停留在“个人工具”阶段：请求散落在 Postman 等云端服务的私有空间里，无法纳入 Git 进行版本管理，协作只能靠导出导入 collection。一旦同事离职或更换设备，接口知识随账号一起丢失；付费墙又限制了团队规模与高级断言的使用。这种模式下，接口变更的历史不可追溯，评审流于形式，新人上手成本极高。

以本地文件为中心的 Git 原生协作

本指南提炼自 Bruno 开源客户端的设计理念，核心主张是 本地文件即真相：每个请求就是一个文本文件，整个集合就是一个文件夹，直接 git commit 即可完成版本化。接口变更通过 Pull Request 评审，历史可追溯。配合 JS 前置/后置脚本，可以编写自动校验与变量提取，把冒烟测试纳入 CI 流程。

关键步骤与团队规范

按业务域组织文件夹：如 users/、orders/、payments/，让接口归属清晰。
环境变量隔离：用 local、test、prod 等环境区分地址与密钥，避免硬编码。
关键断言入库：状态码、字段存在性、延迟上限等校验脚本纳入仓库，随接口一起演进。
密钥绝不入库：token、密码等敏感信息只走环境变量或 CI Secret，.env 文件加入 .gitignore。
变更同步文档：修改请求时同步更新示例与 PR 描述，说明影响范围，方便其他成员评审。

适用边界与常见误区

这套方法适合已经使用 Git 进行协作、且希望将 API 契约纳入工程化管理的团队。但它不是银弹：对于一次性探索性请求，频繁提交反而增加噪音；对于完全离线、无法使用 Git 的环境，本地文件方案也难以发挥协作价值。另外，务必避免把 token 写进请求文件直接提交，这是最常见的泄露路径；也不要把指南当成“个人玩具”，只有真正提交到仓库、参与 PR 评审，才能释放协作价值。