Bruno：深入解析以本地文件为核心的离线开源 API 客户端

Bruno 是一个聚焦"数据主权"的开源 API 客户端，其核心设计是让 API 集合以纯文本的 Bru 标记语言直接存储在你自己的文件系统文件夹中，并通过 Git 等版本控制工具实现协作。本文以 docs/readme/readme_ka.md（格鲁吉亚语项目说明）为主线，结合本仓库源码，为你讲清 Bruno 的存储架构、Bru 语言格式、离线优先理念、跨平台能力，以及从 macOS 到 Linux 的完整安装方法。

Bruno 是什么：定位与核心设计哲学

Bruno 定位为"用于探索与测试 API 的开源 IDE"，官方描述将其称作一个旨在革新 Postman 等既有工具现状的新一代 API 客户端（见 docs/readme/readme_ka.md）。

与常见的"云同步 + 账号体系"型 API 工具相比，Bruno 在架构层面有两条非常明确的、写在文档首页的设计原则：

1. 集合即文件夹：你的每个 API 集合（Collection）都被保存为文件系统中某个文件夹里的一组文件，而不是被锁在私有数据库或云端服务中；
2. 纯文本标记语言 Bru：描述 API 请求信息的载体是 Bru——一种面向人类可读的纯文本标记格式（plain text markup language），你可以在任何编辑器中直接查看与修改。

这带来一个直接推论：Bruno 只离线运行（offline-only）。项目明确表示"没有计划在未来加入云同步功能"，理由是重视数据隐私、认为数据应当保留在用户自己的设备上。这一长期愿景对应仓库根目录 readme.md 与格鲁吉亚语页面中反复强调的 privacy 主张。

这套"本地文件优先（files-first）"的设计，使 Bruno 的集合在概念上回归为普通的版本化文本资产，天然适合与现代软件工程里已有的 Git 协作工作流无缝衔接，而不是再造一套需要迁移的私有格式。

Bru 语言：API 请求如何被写成纯文本

Bru 是 Bruno 生态的核心语法。在仓库中，它由独立的语言处理包实现：packages/bruno-lang 同时维护了 v1 与 v2 两套实现（packages/bruno-lang/v1/src 与 packages/bruno-lang/v2/src），v2 目录中的 bruToJson.js、jsonToBru.js、collectionBruToJson.js、jsonToCollectionBru.js、envToJson.js 等文件表明：Bru 与 JSON 之间具备双向解析能力，请求（request）、集合（collection）与环境（environment）都可以用 Bru 表示并被工具链读取。

看一个真实的 Bru 文件示例（packages/bruno-lang/example/request.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",
    "numbers": "[phone]",
    "data": {
      "sender": "TXTLCL",
      "messages": [{
        "numbers": "[phone]",
        "message": "Hello World"
      }]
    }
  }
/body

body(type=graphql)
  {
    launchesPast {
      launch_site {
        site_name
      }
      launch_success
    }
  }
/body

script
  let user = 'John Doe';

  function onRequest(request) {
    request.body.user = user;
  }

  function onResponse(request, response) {
    expect(response.status).to.equal(200);
  }
/script

可以从中归纳出 Bru 的几个关键语法特征：

• 键值式头部区：文件顶部的 type、name、method、url、body-mode、seq 等字段，直接定义了请求类型（如 http-request）、方法、目标 URL 与请求体内的格式；
• 区块式结构：params、headers、body、script 各自以"起始标记 + 内容 + /结束标记"成对出现，像 headers 区块用前导 1/0 标记条目是否启用；
• 内联变量插值：如 {{transactionId}} 形式的占位符，为集合/环境变量注入预留了接口；
• 多 body 与脚本共存：同一个 .bru 文件可以承载多个 body 变体（如 JSON 与 GraphQL），并通过 script 区块声明 onRequest/onResponse 生命周期钩子。

在仓库的持久化层面，packages/bruno-filestore/src/formats 下提供了 bru/ 与 yml/ 两种格式目录，说明集合文件既可用 Bru 保存，也支持 OpenCollection YAML 等结构，进一步印证了"磁盘上的集合 = 可读、可版本化的文件"这一架构事实。

本地存储 + Git 协作：集合的版本化工作流

由于每个集合只是文件系统中的一个文件夹，你可以直接用 Git 或任意你熟悉的版本控制系统（VCS）来管理、分享与协同维护 API 集合：

• 分支与评审：像管理代码一样管理 API 定义，Pull Request 中可以直接 diff 出 .bru 文件内容的变化，评审改动一目了然；
• 历史追溯：任何一次对接口、参数、脚本的修改都能通过提交历史定位与回滚；
• 团队同步去中心化：不需要中心化的云端数据库，成员通过 Git 远端（自建 GitLab、GitHub 或任何 Git 服务）同步集合快照。

这一工作流的成立基础正是 Bru 的纯文本性——文本文件是可 diff 的，这是二进制/私有格式难以直接替代的价值。因此 Bruno 文档里把 Git 协作列为开箱即用的核心特性，并将其描述为"通过 Git，或任何你选择的版本控制系统进行协作"。

跨平台运行：同一集合，多种运行载体

Bruno 客户端面向桌面用户提供三端覆盖：macOS、Windows 与 Linux（图见 run-anywhere.png）。从源码打包配置可以交叉印证其多平台目标：

• packages/bruno-electron/package.json 的 scripts 中定义了 dist:mac、dist:win、dist:linux、dist:deb、dist:rpm、dist:snap 等多个构建入口，说明官方同时维护 macOS、Windows 与多类 Linux 分发物；
• packages/bruno-electron/electron-builder-config.js 中，mac 侧目标为 pkg/dmg/zip 且同时产出 x64 与 arm64；Windows 侧为 nsis 安装器；Linux 侧则覆盖 AppImage/deb/rpm，并注册了 bruno:// 自定义协议。

从架构上看，集合文件这种"单一格式、多处消费"的形态，让不同平台上的客户端可以打开同一份文件夹而互不冲突；同一份集合数据也得以在 GUI、命令行等场景之间无缝复用。

安装 Bruno：官方二进制与各大包管理器

Bruno 官方在官网（见 readme_ka.md 的下载链接）提供适用于 Mac、Windows、Linux 的二进制下载。此外，它也覆盖了主流的包管理器通道，官方给出的各平台命令如下：

macOS：通过 Homebrew

brew install bruno

Windows：通过 Chocolatey / Scoop / winget

# Chocolatey
choco install bruno

# Scoop（需要先添加 extras bucket）
scoop bucket add extras
scoop install bruno

# winget
winget install Bruno.Bruno

Linux：通过 Snap / Flatpak / Apt

# Snap
snap install bruno

# Flatpak
flatpak install com.usebruno.Bruno

# 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

需要说明的是：Apt 通道的命令会向系统写入 GPG 密钥环（/etc/apt/keyrings/bruno.gpg）并新增 /etc/apt/sources.list.d/bruno.list 软件源，仅适用于 Debian/Ubuntu 系的 amd64 环境。若你的团队使用 Arch Linux，仓库根目录 readme.md 中还记录了 AUR 渠道（yay -S bruno）作为补充安装方式。

从桌面客户端延伸出去

需要明确的是，本仓库的工程结构远不止一个 GUI：

• 桌面客户端主体位于 packages/bruno-app（React/Redux 界面）与 packages/bruno-electron（Electron 壳层）；
• 命令行动态相关能力由 packages/bruno-cli 承载，仓库根目录 readme.md 展示了 npm install -g @usebruno/cli 与 bru run 等 CLI 用法，适合自动化测试与 CI/CD 场景；
• 底层语言、存储、请求执行等能力被拆分为 bruno-lang、bruno-filestore、bruno-requests、bruno-js、bruno-common 等独立包，形成可复用模块。

不过，本文所依据的 readme_ka.md 本体只承诺桌面三端体验；CLI、Docker 等能力在格鲁吉亚语页面中并未展开，阅读时应以对应语言页面与根目录 readme.md 的实际描述为准。

扩展阅读与合规说明

围绕本仓库，还有几份与日常使用直接相关的文档值得跟进：

• 贡献指南：contributing.md，中文版见 docs/contributing/contributing_cn.md；
• 发布到新包管理器（涉及 Bruno 商标的使用约定）：publishing.md；
• 开源许可：license.md（MIT）。

关于品牌与资产：Bruno 名称是其作者持有的商标；客户端 Logo 素材来源于 OpenMoji（Emoji 1F436，小狗图案），采用 CC BY-SA 4.0 许可。若要在新的包管理器上分发 Bruno，请先阅读 publishing.md 并与作者沟通后再行动。

小结

如果把传统 API 客户端比作"账号 + 云盘"，那么 Bruno 提供的是一条相反的路线：集合即本地文件夹、格式即纯文本 Bru、协作即 Git。通过离线优先的设计把数据主权交还给用户，再以人类可读、可 diff 的文件格式换取与既有研发基础设施的天然兼容——这正是 Bruno 在众多 API 工具中形成差异化定位的架构内核。上手它最简单的方式，就是从本文的包管理器命令中选一条完成安装，然后把你自己的请求写成一个 .bru 文件放进 Git 仓库开始体验。