企业官网建设流程全解析

Bruno 教程:本地优先的开源 API 测试工具,5 分钟跑通并接入 CI

【免费下载链接】brunoOpensource IDE For Exploring and Testing API's (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno

Bruno 是一款开源的 API 测试工具,定位是 Postman / Insomnia 的轻量替代。它最大的特点只有一个:API 集合就存在你电脑的文件夹里,用纯文本格式保存,天然可进 Git、天然离线可用。没有账号、没有云端同步——官方明确说过,永远不会加云同步。

一、API 集合,还是一堆"黑盒"吗?

用 Postman 这类工具的人多半踩过同一个坑:

• 集合存在云端,团队共享靠"邀请+空间",离线就歇菜;
• 文件格式不透明,想 diff 一下上周改了什么请求,基本无解;
• 想接入 CI 跑自动化,得走平台 API,链路又长又脆。

Bruno 的思路是反着来:集合 = 本地文件夹 + 纯文本文件。你在文件管理器里能直接看到每个请求,改完git commit,同事git pull就能拿到最新版;CI 上拉个代码库就能跑,不依赖任何 Web 服务。

它支持的能力覆盖日常 API 调试:REST、GraphQL、WebSocket、gRPC/Protobuf、SSE 流式,以及 API Key、OAuth 1/2 等认证方式,还能给集合挂 mock server。界面如下:

二、5 分钟跑起来:安装、开发环境与第一个请求

直接装客户端

Bruno 是桌面应用,Mac / Windows / Linux 都有官方二进制包,也进了各家包管理器:

brew install bruno # macOS choco install bruno # Windows snap install bruno # Linux

打开后新建集合,界面就是"左侧文件树 + 右侧请求编辑器",发一个 GET 请求和你在 Postman 里操作几乎没有学习成本。

想跑源码?

Bruno 是个 npm workspaces 单仓,入口脚本都在根目录package.json里:

git clone https://gitcode.com/GitHub_Trending/br/bruno cd bruno npm run setup # 按 scripts/setup.js 装齐各子包依赖 npm run dev # 启动开发环境

开发工作流、分支规范可以看 contributing.md 和 CODING_STANDARDS.md。

一个最小请求长这样

新建集合里的请求文件(扩展名.bru)就是一个文本文件:

meta { name: ping type: http } get { url: https://httpbin.org/get body: none } tests { test("status is 200", function() { expect(res.getStatus()).to.equal(200); }); }

get块里写方法和 URL,tests块里写断言——请求和它的测试就绑在同一个文件里,这是 Bruno 和"先写请求、再补测试"的两段式工具最直观的区别。

三、.bru 文件怎么读:请求就是纯文本

这是全文最核心的一节,看懂它,Bruno 的所有"高级玩法"都只是组合。

一个.bru请求由若干块(block)组成,常见的是:

几个值得注意的细节:

• 变量插值:URL、header、body 里可以写{{变量名}},运行时按"请求变量 → 环境 → 集合 → 全局"的顺序解析。密钥类信息放环境变量文件里,别写死在.bru里——这是进 Git 后最容易踩的坑。
• 前后置脚本:前置脚本能动态改请求(比如塞时间戳签名),后置脚本里用expect断言,语法接近 Chai,仓库里 packages/bruno-js/ 就是脚本沙箱的实现。
• 双格式并存:较新的集合还支持.yml格式(测试目录里大量migrate-to-yml用例就是在覆盖 bru→yml 迁移),两者解析逻辑都在 packages/bruno-filestore/src/formats/,想看格式细节直接读源码最快。

四、用 Bruno CLI 把 API 测试变成 CI 资产

桌面端负责"调试",CLI 负责"自动化"。CLI 是独立 npm 包,装在集合所在目录执行即可:

npm install -g @usebruno/cli

常用组合:

bru run # 跑整个集合 bru run auth/ # 只跑某个文件夹 bru run auth/ --env Local # 指定环境 bru run --reporter-junit ci.xml # 输出 JUnit 报告 bru run --bail # 一挂就停,CI 里最有用

几个实战点:

• 环境变量覆盖:--env-var key=value可以在命令行临时覆盖变量,配合--env切环境,不用动任何文件。
• 报告输出:支持 json / junit / html 三种 reporter,JUnit 文件直接丢给 Jenkins / GitLab CI 消费。
• Docker 跑测试:不想在 CI 机器装 Node,用官方镜像一行搞定:docker run -v $(pwd):/bruno usebruno/cli run。
• 导入 OpenAPI:手上只有 OpenAPI 规范时,bru import openapi -s api.yml -o ./my-collection一条命令转成 Bruno 集合,再进 Git 管理。

CLI 的完整参数表(客户端证书、CSV 数据驱动等)在 packages/bruno-cli/readme.md。

五、对比 Postman / Insomnia,什么时候选 Bruno?

选 Bruno 的场景:团队本来就用 Git 管代码、想要离线/私有化、CI 里要跑接口测试。

几个提前说好的"坑":

1. 没有云同步是特性不是 bug。别指望多设备实时同步,你的协作工具就是 Git。
2. 格式在演进。bru 和 yml 两种格式并存,老集合可以走应用内迁移,但升级大版本前建议备份集合目录。
3. 密钥纪律。.bru会进 Git,token、密码一律走环境变量,CI 上用--env-var注入。
4. CLI 与客户端是分开的:桌面端装完不等于有bru命令,需要单独npm install -g @usebruno/cli。

六、单仓导览:代码往哪看

Bruno 是 monorepo,子包都在 packages/,按职责划分:

• packages/bruno-app/ —— React 写的界面层,组件、主题、hooks 都在这;
• packages/bruno-electron/ —— Electron 壳、IPC、文件系统服务;
• packages/bruno-cli/ —— 命令行 runner 与报告器;
• packages/bruno-filestore/ —— bru / yml 集合解析与字符串化,格式问题先看它;
• packages/bruno-js/ —— 脚本沙箱与bru脚本 API 实现;
• packages/bruno-lang/ —— 语言层,含 example/request.bru 这个最完整的请求样例。

想贡献代码,先从 contributing.md 的多语言版本入手;跑 E2E 测试的话 Playwright 配置在根目录playwright.config.ts。多语言文档和贡献指南也在 docs/ 下,翻一翻能少走不少弯路。

【免费下载链接】brunoOpensource IDE For Exploring and Testing API's (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno