Bruno 中文 API 测试实战：本地集合、搜索技巧与避坑

Bruno 中文 API 测试实战：本地集合、搜索技巧与避坑

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

当你第一次打开 Bruno 准备跑一个全中文参数的接口时，先要处理的往往不是发请求，而是两件事：编码会不会乱、几百个请求里怎么快速找到目标。Bruno 是一个完全离线、本地存储的 API 测试客户端，请求以纯文本文件保存在磁盘上，整个集合就是一个普通目录，这让中文内容的协作与检索比云端工具可控得多。

核心机制：集合是目录，变量分层

请求是 .bru 纯文本文件，不是数据库记录

Bruno 用一套叫 Bru 的标记语言保存请求（新版本也可用 .yml），每个请求对应一个文件。你可以用任何文本编辑器打开它，方法、URL、请求体、脚本、断言全部是可见文本。这意味着中文请求体和中文注释天然是普通文本，能被 Git 直接 diff、被命令行工具直接 grep，不存在"云数据库里的黑盒记录"。

一个集合对应一个目录

目录里的关键文件分工明确：bruno.json 声明集合名与版本，collection.bru 放集合级变量、头和预请求脚本，environments/ 子目录存放各环境（如 dev、prod）的变量文件，请求则按业务模块拆成嵌套子文件夹。新增、移动、重命名请求，本质上就是增删文件。

环境变量分三层

变量按 Global（应用级）→ Environment（集合当前选中环境）→ Collection 变量 → 请求内 vars 的优先级解析，统一用 {{变量名}} 写法引用。团队共享一份集合，但每个人可以在本地选择不同环境指向各自的接口地址，互不干扰。

最小可用配置：从装好到跑通第一个请求

安装并打开 Bruno

从官网下载对应系统的安装包，或用包管理器（Homebrew、Scoop、Apt 等）安装，启动后进入主界面。

新建第一个集合

在左侧边栏打开一个空目录作为集合位置，或让 Bruno 在指定位置新建一个集合目录，此时会自动生成 bruno.json 等骨架文件。

添加一个请求

在集合上点右键选择新建 Request，侧边栏出现一个 .bru 文件对应的请求项。

填入中文请求体

在请求面板里选择 body 模式为 JSON，写入含中文的键值，例如 {"用户名": "张三"}；URL 里的 query 参数建议先保持英文，原因见后文避坑部分。

点击 Send 并查看响应

右侧时间线显示请求头与耗时，响应面板直接展示中文内容；在终端执行 bru run 则可以用同样的集合跑全量请求。

集合在文件系统里就是普通文件夹，请求、环境、脚本各占其位，可直接纳入版本控制

📦 按场景展开的进阶技巧

当搜索命中率低：给请求起中英混排的名字

当你的集合请求超过百条，靠肉眼翻侧边栏不现实。侧边栏顶部的 Search requests 输入框做的是对请求名的大小写不敏感子串匹配，它不会搜请求体和响应。操作：把稳定的英文关键词（login、get-user）放进请求名，中文业务含义放到 name 旁的描述字段。效果：输入 login，树形列表立刻只展开命中的分支。

当大集合难定位：按业务模块建文件夹树

当单层目录超过二三十个请求时，把请求按"模块/资源"拆成子文件夹，文件夹本身也可以挂集合级脚本。效果：侧边栏折叠成二级结构，配合搜索框，两步内定位任意请求。

当需要审查变更：用 Git 对纯文本做 diff

当团队多人维护同一集合时，把集合目录 clone 到本地（仓库地址 https://gitcode.com/GitHub_Trending/br/bruno ），谁改了哪条请求的 URL 或断言，git diff 直接显示为文本行差异，不需要额外工具导出。效果：代码评审流程原样套用到 API 资产上。

请求是纯文本文件，Git 提交记录即 API 资产的完整变更历史

当要在 CI 里跑集合：Bruno CLI

当回归测试要进流水线时，用 npm 安装 @usebruno/cli，在集合目录下执行 bru run，可指定单个请求、某个文件夹或 --env 指定环境；官方还提供 Docker 镜像，宿主机无需 Node 环境。效果：同一份集合在桌面端和流水线里跑的是同一套文本。

bru run 让集合回归测试进入 CI/CD 流水线

🐛 避坑与排错

中文响应显示为问号或方框

现象：响应面板里中文全是 ? 或豆腐块。原因：通常是服务端响应头没声明 charset=utf-8，客户端按默认编码解码；其次是系统缺少 CJK 字体。修复动作：先查响应头里的 Content-Type，让后端补上 charset；客户端侧在 Preferences → Display → Font 里把 codeFontSize 调大并确认字体栈包含中文字形，系统层面安装完整中文语言包。

搜索框输入内容却无结果

现象：一个词明明出现在请求体里，搜索框输进去树却是空的。原因：集合搜索只匹配请求的 name 字段，不匹配 body、headers 或脚本。修复动作：把要检索的词挪进请求名，用短关键词而非整句；坚持用中文命名的话，搜索时按你保留的英文/拼音前缀输入。

中文 URL 参数发过去变 400

现象：query 里的中文参数发出后服务端返回 400，或解码出来是乱码。原因：URL 参数会做百分号编码，服务端若按非 UTF-8 解码就会错位。修复动作：把中文数据移进 JSON 请求体并在 Content-Type 上声明 charset=utf-8；确实要放 URL 的场景，先用标准 UTF-8 预编码再提交。

🚀 延伸与收尾

下一步：把团队现有的 Postman 或 Insomnia 导出文件用 Bruno 的导入功能迁进本地集合，再把这个目录提交到 Git，完整验证一遍"纯文本 + 版本控制"的工作流。安装与各平台包管理器命令见 readme.md，中文介绍可看 docs/readme/readme_cn.md。Bruno 的"中文优化"本质上不是把界面换成中文，而是让你的中文内容始终留在磁盘上，可搜、可 diff、可回滚。

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