企业官网建设流程全解析

Bruno 开源 API 客户端（Bru 语言 · 离线优先 · Git 协作）：以官方俄语 README 为纲的全面技术解读

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

本文以仓库中官方文档 docs/readme/readme_ru.md（Bruno 项目官方俄语介绍页）为骨架，结合本仓库的源码、.bru格式范例与测试夹具展开成文。核心覆盖：Bruno 是什么、为何离线优先、集合以纯文本 Bru 语言落盘于文件系统、Git/任意版本控制协作、跨平台运行，以及安装、CLI 与 Docker 的实战路径。读完本文，你可以掌握 Bruno 的定位与数据模型，能够用一个git clone或一句bru run在自己的机器上跑通 API 测试。

一、项目定位：面向探索与测试 API 的开源 IDE

Bruno 是一款开箱即用、面向探索与测试 API 的开源 IDE，项目主页与各语言 README 均以此为核心定位。仓库根目录 readme.md 中将其表述为"Opensource IDE for exploring and testing APIs"，而关联文档 docs/readme/readme_ru.md 进一步说明：Bruno 是一个"新颖而创新的 API 客户端"，其目标是"变革 Postman 及类似工具所代表的既有格局"。

需要注意：这句话是项目自身的愿景陈述，而非一个已被第三方验证的结论，因此本文不将其作为性能或市场地位的事实引用，仅作为项目的自我定位呈现。

从仓库结构可以确认该定位落到了实处——仓库是典型的多包（monorepo）工程，桌面应用本体位于 packages/bruno-app，Electron 壳层位于 packages/bruno-electron，CLI 位于 packages/bruno-cli。俄语 README 明确指出桌面版由Next.js + React + Electron构建，并支持"本地集合"（локальные коллекции），这与仓库中的技术选型一一对应：

• 界面框架：Next.js + React（见 packages/bruno-app，其package.json中声明了相关依赖）
• 桌面封装：Electron（见 packages/bruno-electron，由src/index.js作为进程入口）
• 样式：Tailwind（见 packages/bruno-app/tailwind.config.js）
• 编辑器：CodeMirror（编辑器相关代码集中在packages/bruno-app/src/components/codemirror附近）
• 状态管理：Redux（大量packages/bruno-app/src/providers与selectors基于 Redux 组织）
• 文件系统监听：chokidar（详见 packages/bruno-docs 与bruno-electron中对工作区文件的观察逻辑）

需要说明：此处的技术栈清单综合了 docs/contributing/contributing_ru.md 的明确声明与仓库源码结构，读者可依据上述路径在源码中逐一印证。

二、核心数据模型：集合即"文件系统上的一个文件夹"

这是 Bruno 与 Postman 类工具最本质的差异，也是俄语 README 中反复强调的基石：

"Bruno хранит ваши коллекции непосредственно в папке в вашей файловой системе."（Bruno 将你的集合直接存放在文件系统的一个文件夹里。）

换句话说，没有私有的云端数据库、没有隐藏的服务端存储，一个集合就是一个目录，目录里是若干用 Bru 语言编写的文本文件。这种"集合即目录"的模型带来了三个直接后果，均可在源码中验证：

1. 文本可读、可 diff。集合内容由纯文本标记语言 Bru 写成（详见下一节），因此天然适合版本控制。
2. 无供应商锁定。你随时可以复制、归档、迁移整个集合目录。
3. 协作基于通用工具。Git 或任意你喜欢的版本控制系统，就是协作工具（详见第四节）。

在仓库的测试夹具里可以直观看到"集合 = 目录 +.bru文件"的布局。以 packages/bruno-cli/tests/runner/fixtures/collection-json-from-pathname/collection/collection.bru 为根集合文件，同目录下嵌套folder_1、folder_2等子文件夹，子文件夹内各有自己的folder.bru，再往下就是一个个请求.bru文件——树状结构与磁盘目录结构一一对应。

三、Bru：一种用于描述 API 请求的纯文本标记语言

俄语 README 明确指出：为了保存 API 请求的信息，Bruno 使用一种纯文本标记语言 Bru。这一设计是本项目最值得深挖的实现细节，仓库中有完整独立的解析包 packages/bruno-lang 与其语言规范目录 packages/bruno-lang/v2/src。

3.1 一个真实的请求文件长什么样

以官方示例 packages/bruno-lang/example/request.bru 为例，一个典型的 HTTP 请求.bru文件包含：

type http-request name Send Bulk SMS method GET url https://api.textlocal.in/bulk_json?apiKey=secret=&numbers=919988776655&message=hello&sender=600010 body-mode json seq 1 params 1 apiKey secret 1 numbers 998877665 1 message hello /params headers 1 content-type application/json 1 accept-language en-US,en;q=0.9,hi;q=0.8 0 transaction-id {{transactionId}} /headers body(type=json) { "apikey": "secret", ... } /body

可以看到 Bru 是分段式（block 风格）的键值文本：

• 顶部是请求的标量属性：type（如http-request）、name、method、url、body-mode、seq（执行序号）等；
• params、headers等用段名+ 内容 +/段名的成对标记包裹，段内每行以启用标志 键 值的形式书写，其中数字1/0表示该参数或请求头是否启用（即 GUI 中的勾选框状态）；
• headers的值支持{{变量}}插值语法（示例中transaction-id使用了{{transactionId}}），变量可来自环境、集合变量等；
• body(type=json)支持按类型区分的请求体，示例中同时演示了json与graphql两种 body；
• script段书写请求前后脚本：示例中的onRequest(request)会在请求发送前改写 body，onResponse(request, response)则可用expect(response.status).to.equal(200)做断言（测试断言语义由 packages/bruno-js 的脚本运行环境提供）。

3.2 Bru 不是 JSON，而是"为 diff 而生"的文本

之所以用 Bru 而非 JSON/XML，可从解析器实现反推其设计意图：bru 文本与 JSON 的双向转换逻辑位于 packages/bruno-lang/v2/src/bruToJson.js 与 packages/bruno-lang/v2/src/jsonToBru.js，而包的统一出口 packages/bruno-lang/src/index.js 将bruToJsonV2、jsonToBruV2、环境变量互转、集合文件互转等能力集中导出。文本化 + 双向往返转换（round-trip）意味着：修改一个.bru文件只是几行文本变更，git diff 清晰可读、可审查。这正好回应了 README"用 git 协作"的前提——协作的前提是"变更可读"。

3.3 集合级与文件夹级 Bru 文件

集合目录里不止请求.bru，还有集合级与文件夹级的配置.bru。以测试集合 packages/bruno-tests/collection/collection.bru 为例：

headers { check: again token: {{collection_pre_var_token}} collection-header: collection-header-value } auth { mode: bearer } auth:bearer { token: {{bearer_auth_token}} } vars:pre-request { collection_pre_var: collection_pre_var_value collection_pre_var_token: {{request_pre_var_token}} collection-var: collection-var-value @number coll_num: 100 @boolean coll_bool: false @object coll_obj: ''' {"scope":"collection"} ''' } script:pre-request { const shouldTestCollectionScripts = bru.getVar('should-test-collection-scripts'); ... } tests { ... } docs { # bruno-testbench 🐶 This is a test collection ... }

由此可看出集合级 Bru 支持的关键机制：

• headers/auth继承：集合定义默认请求头与认证（此处为bearer模式），子请求无需重复填写即可继承；
• vars:pre-request集合变量：支持{{变量}}互相引用（如collection_pre_var_token: {{request_pre_var_token}}），还可用@number、@boolean、@object等类型注解强制变量类型（多行'''...'''用于对象/多行字符串）；
• script:pre-request：集合级预请求脚本，可调用bru.getVar / bru.setVar读写变量；
• tests：集合级断言脚本（上述样例中test("collection level script", ...)使用expect(...)断言）；
• docs：Markdown 风格的集合文档说明。

文件夹级.bru结构与集合级类似，实现同理，从而支持"集合 → 文件夹 → 请求"三级的默认值、脚本与变量继承。

四、协作方式：Git 与任意版本控制系统

这是俄语 README 除离线外的第二个核心卖点：

"Для совместной работы над коллекциями API можно использовать git или любой другой контроль версий по вашему выбору."（可以用 git 或你选定的任意版本控制系统，在 API 集合上进行协作。）

由于集合只是磁盘上的文本目录，你的协作流程与协作普通代码别无二致：

1. 克隆或分享集合目录（仓库内 packages/bruno-tests、tests 下大量以目录形式组织的测试集合即是这种形态的实例）；
2. 成员各自在本地修改.bru文件；
3. 通过 PR / MR 走常规代码评审；
4. 合并后其他人pull即获得最新的请求、环境与脚本。

没有集中式服务器、没有多人同时编辑同一份云文档的锁冲突——一切由你既有的 Git 工作流接管。仓库中的 Git 集成测试（如 tests/workspace/git-backed-collections）也印证了"git 作为一等公民"的开发方向。

五、离线优先：数据留在你的设备上

俄语 README 毫不含糊地声明了产品的隐私立场：

"Bruno работает только в автономном режиме. Добавление облачной синхронизации в Bruno не планируется."（Bruno 仅在离线模式下工作，且未来也不计划加入云同步。）

结合上文可以理解其中的因果链：因为集合以明文 Bru 落在本地文件系统、协作走 Git，云端同步既非必要，也与其数据主权理念相悖。Bruno 团队珍视用户数据隐私，认为"数据应当留在你自己的设备上"，长期愿景与路线图详见官方 Discussion（俄语页中给出的外部链接均为跳转至项目官方的在线讨论与文档站点，这里不再展开列出外部 URL）。

从工程实现看，"离线优先"体现在两个层面：

• 桌面端 packages/bruno-electron 通过 chokidar 等文件监听能力直接读取/观察本地集合目录，应用本身不需要后端服务即可完成集合的增删改查；
• 命令行的运行与测试亦完全在本地执行（见第六节），天然适配 CI/CD 与无网络环境。

需要客观说明的一点：README 所声明的"无云同步"是对产品当前形态与规划的陈述；若要了解最新状态（例如是否存在任何在线增值服务），应以官方站点与实际发布版本为准，本文不进行任何额外推断。

六、安装、CLI 与 Docker：三种运行形态

英文主 README readme.md 对如何获得、运行 Bruno 给出了比俄语页更完整的操作清单，以下结合两者整理。它们与本仓库的关系是：仓库是这些发布物的源码来源，例如 CLI 的实现位于 packages/bruno-cli/src，其index.js、commands目录分别承载命令注册与参数解析。

6.1 桌面客户端安装（Mac / Windows / Linux）

官方提供各主流平台二进制下载；同时支持多种包管理器安装：

# Mac 上使用 Homebrew brew install bruno # Windows 上使用 Chocolatey choco install bruno # Windows 上使用 Scoop scoop bucket add extras scoop install bruno # Windows 上使用 winget winget install Bruno.Bruno # Linux 上使用 Snap snap install bruno # Linux 上使用 Flatpak flatpak install com.usebruno.Bruno # Arch Linux 上使用 AUR yay -S bruno # Linux 上使用 Apt（通过官方 Debian 仓库） sudo mkdir -p /etc/apt/keyrings sudo apt update && sudo apt install gpg curl curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x9FA6017ECABE0266" \ | gpg --dearmor \ | sudo tee /etc/apt/keyrings/bruno.gpg > /dev/null sudo chmod 644 /etc/apt/keyrings/bruno.gpg echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/bruno.gpg] http://debian.usebruno.com/ bruno stable" \ | sudo tee /etc/apt/sources.list.d/bruno.list sudo apt update && sudo apt install bruno

（上述命令中的包源地址来自上游发布渠道；如需完整、最新的发行渠道，请查阅官方下载页。）

6.2 Bruno CLI：命令行运行集合

CLI 让你摆脱 GUI 也能运行集合，尤其适合自动化测试与 CI/CD。通过 npm 全局安装后，进入集合目录即可运行：

npm install -g @usebruno/cli # 运行集合中的全部请求 bru run # 运行单个请求 bru run request.bru # 针对指定环境运行某个文件夹 bru run folder --env Local

CLI 的代码结构位于 packages/bruno-cli/src/commands（命令解析与执行入口）与 packages/bruno-cli/src/runner（集合运行器）；运行结果的报告能力由 packages/bruno-cli/src/reporters 提供。bru run的所有细节（环境变量、超时、报告格式等）可参考其官方 CLI 文档，也可以直接阅读 CLI 包内自带的使用说明 packages/bruno-cli/readme.md 与变更日志 packages/bruno-cli/changelog.md。

6.3 用 Docker 运行 CLI（免装 Node）

若不想在宿主机安装 Node.js/npm，可使用官方 CLI 容器镜像在 CI/CD 或本地直接跑集合：

docker pull usebruno/cli:latest # 将当前目录挂载进容器并运行集合 docker run -v $(pwd):/bruno usebruno/cli run

主 README 中说明：镜像在每次 CLI 发布时同步推送到 Docker Hub 与 GitHub Container Registry，并提供alpine、debian变体、覆盖linux/amd64与linux/arm64架构。仓库内可查看镜像相关构建材料 packages/bruno-cli/docker 及冒烟测试脚本smoke-test.sh；实际可用的镜像 tag 组合请以发布页为准。

七、从仓库再往前走一步：如何亲自动手

• 直接体验桌面端：下载对应平台的 Bruno 安装包，选择一个本地目录作为集合根目录，新建请求、保存后立刻在该目录中查看生成的.bru文本文件。
• 零 GUI 验证 Bru 格式：对照 packages/bruno-lang/example/request.bru 手工编写一个http-request，再用bru run运行验证，能直观理解"文本即集合"。
• 阅读解析器加深理解：bru 文本 ⇄ JSON 双向转换实现集中在 packages/bruno-lang/v2/src，其对应测试（如 packages/bruno-lang/v2/tests/bruToJson.spec.js）以大量.bru与.jsonfixture 验证转换正确性，是学习 Bru 语法边界（注解、嵌套、多行值、collection/folder 级块）的最佳教材。
• 探索脚本能力：请求脚本、断言与内置库的运行语义在 packages/bruno-js（尤其sandbox、runtime子目录）中实现，测试集合 packages/bruno-tests/collection 展示了从简单断言到认证、Cookie、请求链等复杂场景的用法。

八、关于本地化文档与后续入口

俄语 README 是官方多语言 README 家族的一员（仓库 docs/readme 目录收录了简体中文、正体中文、日文、韩文、德文、法文、阿拉伯文等 20 余种语言的版本），其本身内容与英文主 README readme.md 保持一致。若想继续深入，仓库内还有：

• 参与贡献指南（俄语版）：docs/contributing/contributing_ru.md
• 发布流程说明：publishing.md，多语言版本见 docs/publishing
• 代码与工程规范：CODING_STANDARDS.md、governance.md
• 许可证：license.md（MIT）

说明：本文除基于俄语 README 与仓库源码外，还参考了仓库根目录英文 readme.md 的安装/CLI/Docker 操作细节以保证命令的完整与准确；其中链接指向的在线 Discussion、官方文档站点等属于仓库外资源，本文不再输出相关外部 URL，具体请以官方渠道为准。

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