1. 项目概述为什么Bruno值得你投入时间如果你是一名开发者、测试工程师或者DevOps每天和API打交道那么Bruno这个名字最近可能已经不止一次出现在你的视野里了。它被很多人称为“Postman的本地化、开源替代品”但这个标签其实远远不够。Bruno的核心魅力在于它的“Git-Native”理念——你的API集合不再是锁在某个云端平台里的黑盒而是一个个可以像代码一样被版本控制、被评审、被协作的纯文本文件。这意味着你的API测试脚本可以和你的后端代码库放在同一个Git仓库里每一次接口变更的测试用例更新都能像提交代码一样有迹可循、有史可查。我最初接触Bruno是因为厌倦了传统API工具繁琐的账号体系、强制性的云端同步以及团队协作时令人头疼的权限管理。当Postman宣布逐步淘汰本地草稿功能时我意识到是时候寻找一个真正尊重开发者数据主权和工作流的工具了。Bruno的出现恰好击中了这个痛点。它不是一个试图构建生态闭环的“平台”而是一个纯粹的、高效的、能与开发者现有工具链无缝集成的“客户端”。这篇文章我将结合自己从零上手到深度使用的经验分享10个实战技巧帮你快速跨越新手期成为能高效利用Bruno的专家。无论你是想摆脱云服务的束缚还是希望将API测试真正融入CI/CD流程这些技巧都能让你事半功倍。2. 核心设计理念与快速上手配置2.1 理解“Git-Native”与“Local-First”的真正含义在深入技巧之前我们必须先吃透Bruno的两个核心设计哲学“Git-Native”和“Local-First”。这不仅仅是口号而是决定了你如何使用它的根本。Git-Native这意味着Bruno的“集合”和“环境”等所有资产都以纯文本文件.bru文件的形式存储在本地文件夹中。一个集合就是一个文件夹里面包含多个.bru文件每个文件对应一个API请求及其配置。这种设计带来了几个革命性的优势版本控制友好你可以直接用git add,git commit,git push来管理你的API测试套件。接口文档更新了修改对应的.bru文件并提交团队其他成员git pull就能同步。回滚到某个历史版本进行测试一个git checkout命令就能搞定。与代码共置你可以把API测试集合直接放在后端项目的根目录或/api-tests目录下。这样开发新功能时编写接口代码和编写对应的测试用例可以同步进行极大提升了开发测试的一体化和可发现性。无供应商锁定你的数据完全掌握在自己手中格式是开放的。即使未来Bruno不维护了你的测试用例依然是可读的文本文件迁移成本极低。Local-FirstBruno默认不进行任何云端同步。没有账号没有登录没有强制性的“工作区”。所有操作都在本地完成。协作通过你已有的Git工作流如GitHub, GitLab, Gitee来实现。这彻底解决了数据隐私和安全的担忧也避免了因网络问题或服务宕机导致工具不可用的尴尬。注意很多从Postman转过来的朋友会下意识地寻找“同步”或“分享集合”的按钮。在Bruno里这个动作被“Git提交与推送”替代了。你需要转变思维将API测试资产视为项目源码的一部分。2.2 五分钟完成Bruno的安装与初体验Bruno的安装过程极其简单它提供了多种平台的安装包。下载与安装官方网站访问 Bruno 的官方网站下载对应你操作系统Windows, macOS, Linux的安装包。通常是一个.dmgMac、.exeWindows或.AppImageLinux文件。包管理器安装推荐给开发者macOS (Homebrew):brew install brunoLinux (Snap):snap install brunoWindows (Winget):winget install Bruno.Bruno安装后打开你会看到一个非常简洁的界面没有注册弹窗直接进入工作区。创建你的第一个集合 在Bruno中核心单位是“集合”。点击界面上的“Create Collection”按钮。命名给你的集合起个名字例如My-Project-APIs。选择存储位置这是最关键的一步。不要随意放在桌面或下载文件夹。我强烈建议你将其创建在你的项目代码仓库目录内。例如如果你的项目路径是~/projects/my-backend那么就在这个目录下创建一个子文件夹比如api-tests然后将Bruno集合创建在这里。这样它天生就和你的代码在一起了。观察文件结构创建完成后去你选择的目录看看。你会发现一个以集合名命名的文件夹如My-Project-APIs里面有一个bru.json的元数据文件。后续你在这个集合里创建的每一个请求都会是一个独立的.bru文件。发送第一个请求 在新建的集合上右键选择“Add Request”。命名请求例如Get User List。填写URL输入一个公开的测试API比如https://jsonplaceholder.typicode.com/users。选择方法默认是GET保持即可。点击“Send”右侧会立刻显示响应的状态码、时间和响应体。至此你已经完成了Bruno最基础的搭建。但这只是开始下面的技巧将带你解锁它的真正威力。3. 从新手到精通的10个核心实战技巧3.1 技巧一像管理代码一样管理你的集合结构新手常犯的错误是把所有请求都堆在一个集合里。在Bruno中你应该利用其文件系统的特性构建清晰的目录结构。按功能模块划分文件夹在集合根目录下创建子文件夹来对应不同的业务模块。例如My-Project-APIs/ ├── bru.json ├── Auth/ │ ├── Login.bru │ ├── Logout.bru │ └── RefreshToken.bru ├── UserManagement/ │ ├── GetUsers.bru │ ├── CreateUser.bru │ └── UpdateUser.bru └── Order/ ├── CreateOrder.bru └── GetOrderHistory.bru这样当你的后端代码按模块组织时测试用例能完美映射查找和维护都非常直观。使用.bru文件命名规范文件名就是请求名。建议使用动词资源的格式如CreateProduct.bru,GetUserById.bru。保持一致性团队协作时一目了然。实操心得我习惯在集合根目录的bru.json里添加一个简单的README.bru文件虽然Bruno不识别.md但你可以创建一个内容为Markdown格式文本的请求不实际发送仅作说明。在里面写明这个集合测试的API版本、基础URL、以及重要的环境变量说明这对新加入项目的同事非常友好。3.2 技巧二深度玩转环境变量与脚本实现动态化环境变量是API测试自动化的基石。Bruno的环境变量管理非常灵活支持多个环境如local,dev,staging,prod并且可以在脚本中动态赋值。创建与管理环境点击左侧边栏的“Environments”图标地球形状。点击“Create Environment”命名为Development。在Key-Value表格中添加你的变量。例如KeyValuebase_urlhttps://api-dev.example.comapi_versionv1admin_tokenyour_test_token_here你可以创建多个环境并通过顶部的下拉菜单快速切换。切换环境时所有使用这些变量的请求都会自动更新URL和参数。在请求中使用变量在任何可以输入文本的地方URL, Headers, Body使用双花括号{{}}来引用变量。URL:{{base_url}}/{{api_version}}/usersHeader:Authorization: Bearer {{admin_token}}Body (JSON):{email: {{test_user_email}}}使用脚本动态设置变量这是Bruno的高级功能能让你在请求前后执行JavaScript代码。前置脚本 (Pre-request Script)在请求发送前运行。常用于生成签名、计算时间戳、或从其他来源获取token。后置脚本 (Assertion Script)在收到响应后运行。用于提取响应数据并存入变量或进行复杂的断言。实战示例自动处理登录Token假设你需要先登录获取token然后用于后续所有请求。在Login.bru的断言脚本里写入// 假设登录响应是 {“token”: “xyz123”, “user”: {…}} const responseData JSON.parse(bruno.response.body); // 将token设置到环境变量中 bruno.setEnvVar(‘auth_token’, responseData.token); // 你也可以断言状态码 bruno.test(“Status code is 200”, () { bruno.expect(bruno.response.status).to.equal(200); });在后续需要认证的请求的Header中使用Authorization: Bearer {{auth_token}}即可。3.3 技巧三高效处理认证与Cookie管理API认证是测试中的高频需求。Bruno支持多种认证方式并且对Cookie的管理非常直观。内置认证类型在请求的“Auth”标签页下你可以选择None,Bearer Token,Basic Auth,OAuth 2.0等。对于最常见的Bearer Token直接粘贴token或使用{{auth_token}}这样的变量即可。手动管理Cookie应对热词“bruno设置cookie”有些API的认证依赖于Cookie特别是Session认证或某些SSO场景。Bruno没有像浏览器那样显式的Cookie管理器但它会自动处理响应头中的Set-Cookie并在后续发往同一域名的请求中自动携带。查看Cookie发送一个登录请求后你可以在响应结果的“Cookies”标签页中看到服务器设置的Cookie详情。手动设置Cookie如果某些场景需要你手动初始化Cookie可以在请求的“Headers”标签页中直接添加一个Cookie头。其值格式与浏览器相同例如sessionIdabc123; userId456。使用脚本处理Cookie对于更复杂的场景你可以在前置脚本中通过bruno.setCookie(‘domain.com’, ‘cookieName’, ‘cookieValue’)来动态设置。注意事项Bruno的Cookie是跟随“集合”存储的并且是明文保存在本地文件中的。切勿将包含敏感信息如生产环境Session的Cookie集合提交到公开的Git仓库。务必使用.gitignore忽略这些包含敏感信息的集合或使用环境变量来管理敏感值。3.4 技巧四编写健壮且可读的断言脚本断言是自动化测试的灵魂。Bruno的断言脚本基于一个轻量级的断言库语法直观。基础断言示例// 断言状态码为200 bruno.test(“Status is 200”, () { bruno.expect(bruno.response.status).to.equal(200); }); // 断言响应体包含某个字段 bruno.test(“Response has user id”, () { const body JSON.parse(bruno.response.body); bruno.expect(body).to.have.property(‘id’); bruno.expect(body.id).to.be.a(‘number’); }); // 断言响应时间在合理范围内 bruno.test(“Response time is acceptable”, () { bruno.expect(bruno.response.time).to.be.lessThan(500); // 小于500毫秒 });提取数据供后续请求使用// 提取新建用户的ID存入变量 const body JSON.parse(bruno.response.body); if (body body.id) { bruno.setEnvVar(‘new_user_id’, body.id.toString()); // 注意转为字符串 }然后在下一个删除或查询用户的请求URL中就可以使用/users/{{new_user_id}}。组织断言一个请求的断言脚本里可以包含多个bruno.test块。Bruno会依次执行并报告每个测试的通过与否。清晰的测试描述能让你在测试失败时快速定位问题。3.5 技巧五利用Collection Runner实现接口流程自动化单个请求的测试是点Collection Runner能将点连成线实现完整的业务流程测试。创建测试流程在集合文件夹中你可以创建一个特殊的bru.json文件来定义运行顺序但更直观的方法是使用Bruno GUI界面中的“Collection Runner”。配置Runner在左侧边栏点击“Runner”图标播放键形状。将你的集合或文件夹拖入运行区域。调整顺序拖拽请求来调整执行顺序。例如1.登录 - 2.创建资源 - 3.查询资源 - 4.更新资源 - 5.删除资源 - 6.登出。选择环境为这次运行选择一个预设的环境如Development。设置迭代与延迟可以设置整个流程运行多次或请求之间添加延迟用于压力测试或模拟用户操作间隔。运行与查看报告点击“Run”按钮Bruno会依次执行所有请求。你可以实时看到每个请求的状态通过/失败、耗时。运行结束后会有一个简单的摘要报告列出所有断言的结果。实战场景每晚定时跑一遍核心业务流程的回归测试确保主功能正常。你可以将Bruno集合与GitHub Actions或Jenkins等CI工具结合实现自动化详见技巧十。3.6 技巧六处理GraphQL和gRPC等现代APIBruno并非只支持REST API它对现代API协议的支持是其一大亮点。GraphQL测试创建新请求将方法从GET/POST切换到GRAPHQL。在“Query”标签页中直接编写你的GraphQL查询Query或变更Mutation语句。在“Variables”标签页中以JSON格式提供查询变量。在“Headers”中通常需要设置Content-Type: application/json。 它的体验非常原生比在Postman中把GraphQL查询塞进Body里要清晰得多。gRPC测试需要服务反射创建新请求将方法切换到GRPC。输入你的gRPC服务器地址如localhost:50051。Bruno会尝试连接服务器并获取服务定义如果服务器启用了反射。成功后你可以从下拉列表中选择服务、方法。在“Message”标签页中以JSON格式填写请求的protobuf消息内容。 这对于测试微服务接口极其方便无需手动编译proto文件生成客户端。3.7 技巧七团队协作与Git工作流集成这是Bruno“Git-Native”理念的核心价值体现。团队如何高效地共用一套API测试集合共享集合仓库为API测试单独创建一个Git仓库或者将其作为子目录放在后端项目仓库中。这是唯一的“真相之源”。定义协作规范分支策略可以模仿代码开发流程。main分支存放稳定的测试用例。开发新功能时创建feature/login-test分支来添加或修改测试用例。代码评审对.bru文件的修改新增接口测试、更新断言、修改环境变量发起Pull Request。团队成员可以像评审代码一样评审测试逻辑确保测试的准确性和覆盖率。解决冲突因为文件是纯文本合并冲突时可以使用标准的Git工具或IDE来解决非常清晰。环境变量分离个人本地环境变量如本地数据库连接串、个人测试账号绝对不能提交到共享仓库。Bruno的环境变量可以导出为文件。团队应该共享一个environments文件夹里面存放dev.bruenv,staging.bruenv等不包含敏感值的环境定义文件例如只定义base_url,api_version。每个成员在本地克隆仓库后导入这些环境文件再在本地添加自己的敏感变量如个人token。这些本地添加的变量不会污染共享文件。3.8 技巧八使用快捷键与高级功能提升效率任何工具熟练使用快捷键都能极大提升效率。常用快捷键Cmd/Ctrl N: 新建请求Cmd/Ctrl S: 保存当前请求Bruno是自动保存但这是个好习惯快捷键Cmd/Ctrl Enter: 发送当前请求Cmd/Ctrl Shift R: 运行Collection RunnerCmd/Ctrl B: 切换侧边栏显示在URL/Header输入框按Tab键可以快速补全已输入过的历史值或变量名。高级功能导入导出Bruno支持从Postman、Insomnia等工具导入集合Collection v2.1格式迁移成本很低。你也可以将Bruno集合导出为OpenAPI (Swagger) 规范用于生成文档。代码生成在请求发送后点击响应区域下方的“Code”按钮Bruno可以为你生成当前请求的cURL命令以及多种编程语言如JavaScript Fetch, Python requests, Go的代码片段方便你将其集成到自己的自动化脚本中。3.9 技巧九调试与问题排查实战指南即使是最简单的请求也可能遇到问题。以下是快速排查的步骤检查网络与代理首先确认你的网络连接正常。如果公司有代理需要在Bruno的设置Settings - Network中配置。Bruno默认使用系统代理设置。仔细查看请求详情发送请求前点击URL输入框旁边的“Preview”按钮可以预览最终将要发送的完整请求URL变量已被替换。在“Headers”标签页确认所有必要的请求头都已正确添加且值无误特别是Content-Type和Authorization。查看原始请求与响应发送请求后在结果面板的“Timeline”或“Raw”标签页你可以看到原始的HTTP请求和响应文本。这是排查问题的金矿。对比你预期的请求和实际发出的请求差异往往就在这里。活用控制台日志在你的前置脚本和断言脚本中可以使用console.log()输出调试信息。这些日志会在请求结果下方的“Console”标签页中显示。例如console.log(‘Extracted token:’, bruno.getEnvVar(‘auth_token’));。环境变量未定义如果遇到{{variable}}没有被替换的情况请检查1当前选择的环境是否正确2变量名是否拼写错误3变量是否确实在当前环境中定义。SSL证书问题在测试本地开发环境https://localhost时可能会遇到SSL证书错误。你可以在Bruno的设置中临时关闭SSL验证Settings - General - SSL Verification但仅限本地开发切勿用于测试远程服务器。3.10 技巧十将Bruno集成到CI/CD流水线这是实现API测试自动化的最后一步也是价值最大的一步。Bruno本身是图形化工具但可以通过其命令行工具bru实现无头运行。安装CLI工具bru这是一个独立的Node.js包。通过npm或yarn全局安装npm install -g usebruno/cli编写运行脚本 在你的项目根目录创建一个脚本文件例如run-api-tests.sh#!/bin/bash echo “Running Bruno API tests…” # 切换到测试集合目录 cd ./api-tests/My-Project-APIs # 使用bru run命令运行整个集合指定环境文件 bru run --env ../../environments/staging.bruenv # 检查退出码非0表示测试失败 if [ $? -ne 0 ]; then echo “API Tests Failed!” exit 1 else echo “All API Tests Passed!” fi在CI中配置以GitHub Actions为例 在项目.github/workflows目录下创建api-test.ymlname: API Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 with: { node-version: ‘18’ } - name: Install Bruno CLI run: npm install -g usebruno/cli - name: Run API Tests run: bash ./run-api-tests.sh env: # 将敏感的环境变量如token通过GitHub Secrets注入 PROD_API_TOKEN: ${{ secrets.PROD_API_TOKEN }}这样每次代码推送或发起PR时都会自动运行API测试套件确保接口变更不会破坏现有功能。4. 常见问题与进阶排查技巧即使掌握了上述技巧在实际使用中仍会遇到一些特有的问题。这里记录了几个我踩过的坑和解决方案。问题1团队共用集合时环境变量如何管理才不会混乱这是Bruno协作中最常见的问题。我们的解决方案是“三层环境变量管理法”项目级默认环境(default.bruenv)存放在集合仓库的environments目录下包含所有非敏感的、项目通用的变量如base_url,api_version。每个成员克隆后导入。个人本地覆盖每个成员在Bruno App中在导入的项目环境基础上添加自己本地的敏感变量如个人账号密码、本地开发数据库配置。这些设置保存在本地不提交。CI/CD环境变量在GitHub Actions/GitLab CI等平台上通过bru run --env指定环境文件同时利用CI平台的Secrets功能注入敏感变量如PROD_API_TOKEN。环境文件里可以引用这些注入的变量格式可能需调整如使用$VAR。问题2.bru文件冲突了怎么办因为.bru文件是JSON格式的纯文本合并冲突和解决代码冲突一模一样。打开冲突文件你会看到标准的Git冲突标记,,。你需要理解冲突部分通常是请求的URL、Header、Body或脚本被不同的人修改了。与发生冲突的同事沟通确定最终的正确内容。手动编辑文件删除冲突标记保留正确的内容。保存文件然后执行git add和git commit完成冲突解决。问题3断言脚本中bruno.response.body有时不是对象这是一个容易出错的地方。bruno.response.body永远是字符串类型。即使响应头是application/json你也需要先解析它。// 正确做法 let responseData; try { responseData JSON.parse(bruno.response.body); } catch (e) { bruno.test(“Response is valid JSON”, () { bruno.expect.fail(“Response body is not valid JSON: “ e.message); }); return; // 如果不是JSON提前结束 } // 现在可以使用responseData.user.id了对于非JSON响应如XML、纯文本你需要使用其他方式解析或直接进行字符串匹配。问题4Collection Runner中如何让一个请求的变量传递给下一个请求这依赖于环境变量。在第一个请求的断言脚本中使用bruno.setEnvVar(‘key’, ‘value’)设置变量。这个变量会进入当前Runner会话的环境上下文。在后续的请求中直接使用{{key}}引用即可。Runner会按顺序执行并保持这个环境上下文。问题5Bruno的性能或功能不如Postman强大这需要客观看待。Bruno的优势在于轻量、快速、本地优先和与Git的无缝集成。它的核心定位是一个高效的开发者客户端而不是一个全功能的API监控、Mock和文档平台。对于复杂的API监控、自动化工作流编排你可能需要结合其他工具如专门的API监控服务、Mock服务器等。但对于日常开发、调试、回归测试和团队协作Bruno提供的功能已经绰绰有余且其简洁的设计避免了不必要的认知负担。选择工具关键是看它是否契合你的核心工作流。