Bruno：开源离线、Git 原生的 API 测试工具实战

团队里做接口联调的人大概都遇到过这种场景周五下午代码评审你打开 Postman 想给同事演示一个刚加好的 API结果它先弹登录框接着工作区转圈最后告诉你同步失败请求列表还是三天前的旧版本。更难受的是接口定义到底哪一版是对的谁最后改的改了哪几个字段全都没人说得清——集合躺在某个人的账号云端导出成 JSON 之后 diff 出来几千行乱码。这篇要聊的就是冲着这几个痛点去的一款 API 测试工具开源免费、完全离线、基于 Git 做版本控制目前已经拿了 20K star。它就是 Bruno。下面我会把它的设计逻辑、安装配置、脚本写法、Git 协作流程、CI 落地方式以及我自己踩过的坑一次性讲透适合刚被 Postman 折腾过的新手也适合正在给团队做工具选型的负责人。1. 为什么我又换了一个 API 测试工具选型这件事最怕两种人一种是用惯了懒得换一种是看见新工具就想换。我换 Brun 的原因既不是它花哨也不是图新鲜而是某些日常动作在旧工具里真的做不到或者说做起来很别扭。1.1 Postman 用久了会撞到的几堵墙先把话说公道Postman 是个好工具界面、Mock、监控、文档这些能力做得很全很多团队靠它把接口资产沉淀了下来。但功能全和日常顺手是两件事尤其在网络受限的内网环境里或者团队根本不想把接口定义放到外部云上的时候问题就来了。我遇到的第一个墙是强账号依赖。较新版本的 Postman 在工作区、集合同步、团队协作上都要求登录不登录能用的功能越来越少。离线环境里这不是不方便而是直接卡住。第二个墙是集合的存储格式对 Git 极不友好。导出的 collection JSON 是一个巨大的嵌套结构改一个 URLdiff 出来可能是整块重排代码评审时根本看不清改了哪里冲突更是没法手工合。第三个墙是接口定义和代码不在同一个评审流程里。代码走 Git 分支、走 MR、走 CI接口测试集合却走云端点发布两边的变更节奏对不上。接口改了、代码合了、测试集合忘了更新这种事发生一两次团队就会开始怀疑我们的接口测试到底靠不靠谱。这些墙叠起来结论就很清楚了我需要一个文件存在本地、内容人能看懂、能跟着代码仓库一起走评审的 API 客户端。1.2 Bruno 的核心定位文件即集合Git 即同步Bruno 的做法非常朴素朴素到有点返璞归真它把每个请求保存成一个独立的纯文本文件用自己的一套轻量标记语言.bru后缀描述。一个集合就是一个文件夹文件夹里就是一堆.bru文件加一个bruno.json的集合描述文件。没有云端数据库没有账号绑定没有同步这个动作——因为同步这件事被你熟悉的 Git 接管了。这个定位带来三个直接后果。第一完全离线可用。客户端本身不依赖任何远程服务你断网也能编辑请求、跑本地服务、看历史响应。第二版本控制是天然的。集合文件夹就是一个普通 Git 仓库你在里面git log、git diff、开分支、发合并请求和平时代码的流程一模一样。第三评审成本骤降。因为.bru是行式文本改一个参数就是改一行diff 干净得能让人愿意认真读。注意这不是另一个 Postman 皮肤。它放弃了云工作区、在线 Mock 这类能力换来的是本地化、可评审、可进 CI。选型时一定要先想清楚你要的是哪一头。1.3 选型对照它适合谁不适合谁我把常见几个工具放到一张表里方便你对号入座。这张表是我自己实际用过之后的判断不是官网参数的搬运。工具集合存储离线能力Git 友好度最适合的场景Bruno本地纯文本.bru文件完全离线高行级 diff想和代码同仓评审、内网环境、注重接口资产自主可控Postman云端/本地 JSON 导出依赖登录低需要 Mock、监控、在线文档发布的团队Insomnia本地 可选云同步中等中个人使用愿意接受账号体系Hoppscotch浏览器本地存储/自建中等中轻量试用、临时验证接口VS Code 的 REST Client 类插件.http文件完全离线高只做简单请求不需要图形化环境管理我的建议很直接如果你的日常动作是写接口、联调、跑回归、把测试集合和代码一起提交Bruno 几乎是为你准备的如果你重度依赖 Mock 服务和线上监控面板那就别硬换工具没有对错只有合不合适。2. 核心设计思路拆解为什么敢做离线优先理解一个工具的设计取舍比记住它的菜单在哪有用得多。Bruno 的很多看起来是缺点的地方其实都是有意的选择。2.1 离线优先意味着什么完全离线这四个字很多人第一反应是那团队怎么共享。答案是把共享这件事交回给 Git 或者任何文件同步方式。这背后有个很实在的判断接口定义本质上是工程资产它和源码一样需要评审、需要追溯、需要回滚那它就应该待在工程资产该待的地方——代码仓库。离线优先还带来一个容易被忽略的好处响应速度和确定性。没有网络往返、没有账号鉴权、没有同步队列你点开工具、切环境、发请求中间没有不可控的等待。我做过一个很土的对比在内网环境下连续切换五个环境、发二十个请求Bruno 的操作手感是一致的而依赖云同步的客户端偶发的转圈和正在加载工作区会明显打断思路。工具打断思路这件事一天累积下来就是实打实的时间。代价也很明确没有实时协作。两个人同时在同一个集合里改无法像云工作区那样看到对方的光标。但换个角度想代码协作本来也不靠光标同步靠的是分支和评审。真要说损失是临时看一眼同事的集合这种动作变麻烦了得走拉取或者共享目录。2.2 一个.bru文件的完整解剖理解.bru格式是入门的关键。它不是 JSON不是 YAML而是一种极简的块结构可读性比我见过的大多数配置格式都好。下面这个文件把我常用的几个块都塞进去了你可以直接照着改。meta { name: 创建订单 type: http seq: 3 } post { url: {{baseUrl}}/api/v1/orders body: json auth: inherit } params:query { dryRun: false source: app } headers { Content-Type: application/json X-Trace-Id: {{$randomUUID}} } body:json { { sku: SKU-1001, count: 2, remark: 来自自动化用例 } } script:pre-request { const ts Date.now().toString(); bru.setVar(ts, ts); req.setHeader(X-Timestamp, ts); } script:post-response { test(状态码应为 200, function() { expect(res.getStatus()).to.equal(200); }); bru.setEnvVar(lastOrderId, res.getBody().data.id); } assert { res.status: eq 200 res.body.data.id: isString res.responseTime: lt 1500 }几个关键点值得单独说。meta块里的seq决定请求在集合里的显示顺序auth: inherit表示沿用上层文件夹或集合的鉴权配置这个继承机制能省掉大量重复劳动。{{baseUrl}}是变量插值双大括号的写法和大家熟悉的模板语法一致学习成本几乎为零。assert块是 Bruno 的一个亮点它用极简的字段: 操作符 值语法做断言不用写 JS。eq、neq、lt、gt、isString、isNumber、contains这几个操作符覆盖了八成日常校验。复杂的逻辑再交给script:post-response里的expect。提示同一个请求里assert和script:post-response可以共存都会被执行。我通常用assert做一看就懂的基础校验用脚本做依赖注入和需要条件分支的判断。2.3 集合的目录结构与它的 Git 友好性一个真实的集合目录大概长这样我按我自己的习惯组织order-service-api/ ├── bruno.json # 集合描述必须提交 ├── collection.bru # 集合级变量、鉴权、脚本 ├── environments/ │ ├── Local.bru # 本地环境通常不提交 │ ├── Dev.bru │ ├── CI.bru │ ── Example.bru # 给新同事参考的样例 ├── auth/ │ ├── folder.bru # 文件夹级配置可覆盖集合级 │ ├── 登录.bru │ └── 刷新令牌.bru ├── orders/ │ ├── 创建订单.bru │ ├── 查询订单.bru │ └── 取消订单.bru └── scripts/ └── common.bru # 放公共片段靠脚本调用这个结构的 Git 友好性体现在三处。第一粒度小。创建订单.bru只描述创建订单这一个请求改它不会影响到别的文件PR 的 diff 范围天然被限制住。第二行式文本。参数、头部、脚本各占一块改一行显示一行没有 JSON 的缩进连锁反应。第三目录即分类。文件夹就是集合里的分组重命名文件夹在 Git 里是一次可追踪的移动操作而不是整个 JSON 重排一遍。我实测过的一个对比很有说服力同样是给所有请求统一加一个X-Env头部在云端 JSON 集合里导出的 diff 可能有几百行重排在 Bruno 里如果我把这个头部放在collection.bru的集合级配置里diff 只有一行。这就是格式选择带来的复利。2.4 架构带来的代价提前说清楚Bruno 是桌面客户端本地文件读写脚本在本地 JS 沙箱里跑。这意味着两件事需要注意。一是集合目录不要放在同步盘的冲突高发区如果你把集合放在某些自动同步的目录里同时客户端又在写文件偶尔会打架用 Git 管理就没这个问题。二是脚本能力虽然有边界但仍然是可执行代码团队的集合如果来自外部导入先看一眼脚本块里写了什么再运行客户端里的安全模式开关可以在不信任集合时临时关掉脚本执行。3. 安装与初始化实操环境准备这块我按我实际怎么装、装完先改什么、怎么跑通第一条链路的顺序写你可以直接抄。3.1 三条安装路径怎么选桌面客户端是主力三种获取方式各有适用场景。追求简单就用官方发布的安装包双击下一步就完事习惯包管理器的 macOS 用户可以走 Homebrew 的 cask升级和卸载都干净Linux 下官方提供 AppImage、deb、rpm 几种形态AppImage 免安装适合随身带deb/rpm 适合长期用。至于社区维护的包管理器版本能用但版本可能滞后一两个月接口工具这种迭代快的软件我建议跟着官方走。命令行工具是进 CI 的关键通过 npm 全局安装依赖 Node 运行时。命令很朴素npm install -g usebruno/cli bru --version如果你的机器上有多个 Node 版本建议用版本管理器切一个 18 以上的环境再装避免全局包和项目依赖互相干扰。装完之后bru --version能输出版本号就说明通了。便携版适合两类人一是公司电脑权限受限装不了软件二是需要在多台机器之间带着集合跑。便携版解压即用配置和集合默认放在程序目录附近拷走整个文件夹就完成了搬家。提示不管哪条路径装完后先去设置里确认一下更新检查和遥测相关的开关。既然选它的理由之一是完全离线那就顺手把不需要的外呼关掉环境干净心里也踏实。3.2 首次启动我建议先改的六项设置客户端装好之后的默认配置是给所有人用的我一般会做这六项调整能让日常顺手很多。第一关掉自动更新检查。内网或受限网络里更新检查会带来无意义的等待而且它往往在你刚打开工具时触发。手动更新完全够用。第二关掉使用数据上报。这是完全离线这个主张落到你自己机器上的最后一公里。第三设置请求超时和响应体上限。默认值偏保守大响应体或者慢接口容易让你误以为是工具卡了我一般把超时调到 30 秒级别响应体展示上限视机器内存调整。第四配置自签名证书信任。内网测试环境大量用自签名证书提前在客户端里把内部 CA 证书导入能省掉后面每一次的证书报错排查。第五调整历史记录的保留策略。历史响应体是排查问题的好材料但会占空间我一般保留最近两周。第六确认默认工作目录。集合放哪里和你的项目目录树怎么对齐这个决定会影响后面的 Git 操作效率。3.3 建集合、连 Git、跑通第一个请求真正的落地流程是四步。第一步新建一个集合客户端会创建目录和bruno.json。第二步在这个目录里git init或者直接把它放到已有的服务端仓库里当子目录——我个人更推荐后者接口集合和它服务的代码在同一个仓库变更能一起评审避免代码合了测试集合没合的错位。第三步配置一个环境比如Dev.bru把baseUrl、token这类会变的东西都抽出来vars { baseUrl: http://127.0.0.1:8080 timeout: 30000 } vars:secret [ token ]第四步新建第一个请求用{{baseUrl}}/health之类的健康检查接口先跑通确认网络、证书、变量插值这三条链路都是通的。跑通之后再开始批量导入业务接口别一上来就导两百个请求然后发现变量没生效那样排查起来很痛苦。3.4 CLI 与.gitignore该写什么集合要进仓库就得想清楚哪些文件不该进。我的习惯是这样# 本地个人环境含真实密钥不进仓库 environments/Local.bru # 依赖目录和临时产物 node_modules/ .bruno/ # 测试报告 reports/ *.junit.xml # 系统文件 .DS_Store Thumbs.db这里面最关键的是第一条。Bruno 的环境文件支持把变量标记为 secret但标记为 secret 只影响界面上是否明文显示值本身仍然写在文件里。所以真实令牌、口令这类东西绝不能提交。稳妥的做法是提交一份Example.bru作为模板让新同事拷成Local.bru自己填同时在仓库说明里写清楚需要填哪几个键。CI 环境里则完全靠外部注入用 CLI 的参数把值传进去bru run ./order-service-api -r \ --env CI \ --env-var token$API_TOKEN \ --env-var baseUrl$BASE_URL \ --reporter-junit \ --output reports/bru.xml-r表示递归跑子目录--env指定环境--env-var覆盖环境文件里的同名变量。这一层的执行顺序我实测下来是命令行传入的值优先级高于环境文件里的值所以 CI 里用命令行注入最省心。具体参数以bru run --help的输出为准版本迭代比较快养成先看帮助的习惯。4. 核心功能实战变量、脚本、断言、鉴权前面是骨架这一节是肌肉。API 测试工具的价值八成体现在变量体系、脚本能力和断言这三件事上。4.1 变量体系的分层与优先级Bruno 的变量分了层次理解层次能帮你避免为什么这里读到的是空值这类玄学问题。我把它整理成一张表层级定义位置典型用途生命周期进程变量系统环境变量脚本里用bru.getProcessEnv读CI 注入的密钥、机器相关路径随进程全局变量客户端全局配置跨集合共用的常量比如公司统一域名长期集合变量collection.bru整个集合共用的默认值、公共头部随集合环境变量environments/*.bru不同环境的 baseUrl、账号随环境切换运行时变量脚本里bru.setVar一次运行内的临时值、链路数据单次运行优先级我实测的顺序是运行时变量 环境变量 集合变量 全局变量。也就是说脚本里bru.setVar设的值会盖住环境里的同名变量这也是链路测试能实现的原因。这里有个很实用的技巧用bru.interpolate做二次插值。有些场景下变量值本身还含有变量引用直接取出来是带双大括号的原始字符串需要再解析一层。另外环境切换是有快捷键的日常在 Dev 和 Local 之间来回切的时候用快捷键比点菜单快得多。注意环境文件里vars:secret标记的变量在日志和报告里会被打码但别把它当成保险箱真正的密钥要么不进仓库要么由 CI 从安全存储注入。4.2 前置脚本签名、时间戳、动态参数前置脚本在请求发出之前执行最适合干三类活补动态值、算签名、改请求内容。下面这段是我在一个需要签名的接口里用的思路可以直接迁移// 1. 生成时间戳和随机串 const ts Date.now().toString(); const nonce Math.random().toString(36).slice(2, 10); // 2. 组装签名原文按服务端约定顺序拼接 const raw ${req.getMethod()}\n${req.getUrl()}\n${ts}\n${nonce}; const sign crypto.createHmac(sha256, bru.getEnvVar(secretKey)) .update(raw).digest(hex); // 3. 写回请求 req.setHeader(X-Timestamp, ts); req.setHeader(X-Nonce, nonce); req.setHeader(X-Sign, sign);这段代码里有几个点值得强调。req.getUrl()拿到的是插值之后的完整 URL所以用它算签名和实际请求的地址是一致的不会出现签名算的是模板发的是真地址这种错位。bru.getEnvVar读的是当前激活环境的变量切环境时签名密钥也跟着换这就是为什么把secretKey放在环境里而不是硬编码。常见坑是时间戳单位。有的服务端要秒级有的要毫秒级签名对不上十有八九是这个原因。我一般会先在本地把签名原文打印出来用服务端同学的校验逻辑对一遍确认算法再放进脚本。req对象还提供了不少有用的方法比如改超时、改重定向策略、改请求体。我常用的就是req.setHeader、req.setBody、req.setTimeout这三个。4.3 后置脚本与断言把验证写进请求后置脚本在响应回来之后执行核心任务是验证和传递。我的习惯是分层写能在assert块里表达的就用assert需要判断分支或者做数据传递的才写脚本。// 基础校验状态码和业务码 test(HTTP 状态码为 200, function() { expect(res.getStatus()).to.equal(200); }); test(业务码为 0, function() { expect(res.getBody().code).to.equal(0); }); // 数据传递把订单号存进环境变量给后续请求用 if (res.getStatus() 200 res.getBody().data) { bru.setEnvVar(lastOrderId, res.getBody().data.id); } // 响应时间守护 test(响应时间小于 1500ms, function() { expect(res.getResponseTime()).to.be.lessThan(1500); });关于响应体解析有个细节res.getBody()会自动尝试解析 JSON如果响应不是合法 JSON 就会拿到字符串或者报错。我踩过的坑是——服务端返回了 HTML 错误页比如网关返回的 502 页面脚本里直接访问res.getBody().code就会抛异常导致整个请求被标记为失败但失败原因看起来像是脚本错误而不是接口返回了非 JSON。稳妥写法是先判断状态码再解构。res对象上我常用的属性有getStatus()、getStatusText()、getHeaders()、getBody()、getResponseTime()以及原始的res.headers和res.body。4.4 鉴权与令牌自动续期Bruno 支持把鉴权配置在集合级、文件夹级或请求级下级默认继承上级。这个继承链是我最喜欢的设计之一登录接口单独放一个文件夹不设鉴权业务接口全部放在需要 Bearer 令牌的文件夹里自动继承。令牌续期的实现思路是登录请求负责写其他请求负责读登录请求的后置脚本把令牌写进环境变量业务请求的鉴权配置里引用这个变量。这样你只要跑一次登录后面所有请求都能用上新令牌。这里有个实测经验如果令牌过期了一批请求会集体返回 401这时不要逐个排查。正确做法是把登录请求放在集合最前面用seq控制顺序每次批量运行前先跑一遍登录或者干脆用bru.setNextRequest在检测到 401 时自动跳转到登录请求再重跑。后者更优雅但要注意别写出死循环加一个重试计数器。4.5 请求串联与依赖调用真实业务里很多请求是依赖链下单要商品 ID查订单要订单号取消订单要订单号加状态校验。Bruno 提供了两种串联方式。一种是顺序编排。集合里请求按seq排序加上-r递归执行天然就是一个线性用例。另一种是脚本跳转用bru.setNextRequest(请求名)在运行时决定下一个跑谁适合如果创建失败就跳过后续这种分支逻辑。还有一种更彻底的用法在脚本里直接发起子请求。Bruno 提供了在脚本中发送请求的能力可以在一个请求的脚本里调另一个接口拿数据适合需要多步前置准备的场景。不过我得提醒一句嵌套请求别写太深超过两层之后断言的归属就会变得模糊——到底是外层失败了还是内层失败了报告里不好读。我的原则是能拆成独立请求就拆保持一个请求一个关注点。5. 团队协作与 CI 落地工具换掉只是第一步真正让团队受益的是流程改造。这一节写怎么把 Bruno 接进现有的 Git 和 CI 流程。5.1 Git 协作流程怎么设计我的推荐是集合跟着服务走每个后端服务的仓库里放一个api-tests目录或者在根目录放集合接口定义跟着代码一起提交、一起评审。这样做的好处是变更原子化——同一个 MR 里既能看到接口代码的改动也能看到对应测试集合的改动评审人能一眼判断测试有没有跟着接口更新。分支策略上不用特殊设计沿用团队现有的就行。接口集合的冲突比代码冲突好处理得多因为.bru是行式的冲突通常是两个人在相邻行改了不同的参数手工合并就是取舍一下。真正需要注意的冲突场景是bruno.json和collection.bru这两个全局文件多人同时改设置容易撞车。我的做法是约定这两个文件的修改要单独提一个 MR并在提交信息里说明改了什么减少并发修改。有个容易被忽略的动作值得写进团队规范重命名请求时顺手检查有没有别的地方用名字引用它。因为bru.setNextRequest这类跳转是按名字找的改了名字没改引用链路会静默断掉——不是报错是这次跑的时候后面的请求没跑很阴。5.2 在流水线里跑bru runCI 集成是这套方案真正拉开差距的地方。下面这份是通用性比较好的流水线配置你可以按自己的 CI 系统改语法name: api-tests on: push: branches: [main] pull_request: jobs: bru: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - name: 安装 CLI run: npm install -g usebruno/cli - name: 跑接口用例 env: API_TOKEN: ${{ secrets.API_TOKEN }} BASE_URL: ${{ secrets.STAGING_BASE_URL }} run: | bru run ./api-tests -r \ --env CI \ --env-var token$API_TOKEN \ --env-var baseUrl$BASE_URL \ --reporter-junit \ --output reports/bru.xml - name: 上传报告 if: always() uses: actions/upload-artifactv4 with: name: bru-report path: reports/几个实践要点。第一用独立环境跑 CI。别拿开发环境跑流水线环境里的数据被别人改来改去用例会莫名失败。第二密钥从 CI 的密钥存储注入永远不要写进CI.bru提交上去。第三报告一定要上传而且用if: always()否则用例失败时你拿不到报告等于白跑。第四先跑冒烟再跑全量。如果 CI 时间有预算限制用标签把一批请求标成核心用例日常只跑这部分全量用例放在夜间定时任务里。5.3 从 Postman 迁移的实操顺序迁移这件事最怕的是一把导进来就宣布迁移完成。我的顺序是这样的。第一步导入集合。Bruno 支持导入 Postman 集合的导出文件把集合拉进来之后先做一次全景浏览重点看哪些请求有脚本、哪些有环境依赖。第二步环境变量的映射。Postman 的环境文件也要一起导导完之后逐个环境核对变量名看看有没有漏掉的键。这一步最容易出问题因为变量名对不上不会报错只会变成空字符串请求就发出去了然后服务端返回 400你还以为是脚本问题。第三步脚本语法适配。两者都用 JS但对象和方法名不一样比如取响应体、设置环境变量的写法都有差异需要逐个改。第四步双跑比对。在同一个环境下用旧工具和新工具各跑一遍关键用例对比状态码和响应结构确认行为一致。第五步切换并冻结旧集合。新集合进仓库旧集合设为只读避免出现两边都在改的混乱期。提示迁移期不要追求一次到底。先把每天都会用的那二三十个请求迁过来跑顺一周再迁长尾。渐进式迁移的返工成本远低于一次性重做。5.4 数据驱动批量测试同一个接口用不同参数跑一批是回归测试的常态。Bruno 的 CLI 支持用数据文件驱动执行把参数抽成表一个请求跑 N 次。用法上是在命令行指定数据文件在脚本里从运行时把当前行数据取出来往请求里塞。这个能力最典型的用法是边界值回归把参数合法值、非法值、超长值整理成一张 CSV跑一遍看服务端的错误码是否都符合预期。我实际用下来最大的收益不是发现了新 bug而是把接口校验逻辑有没有被改动这件事变成了一次自动检查——服务端某个字段的长度限制从 32 悄悄改成 64或者错误码从 4001 改成 4002这种改动人工测很容易漏数据驱动一跑就现形。数据文件的编码我建议统一用 UTF-8列名用英文缩写避免中文列名在某些环境下解析异常。6. 常见问题与排查技巧实录这一节是我在实际使用中攒下来的问题清单按类型整理遇到问题可以直接对照排查。6.1 导入与变量类问题速查现象大概率原因处理方式导入后请求全变红集合格式版本不兼容用旧工具重新导出一次选较新的导出格式变量显示成{{baseUrl}}原文环境没激活或变量名拼错检查右上角当前环境再逐个核对变量名大小写环境切换后请求仍打到旧地址变量在请求级硬编码覆盖了环境变量请求里改用{{}}引用去掉硬编码脚本里读到空值环境文件里的键没被加载或读的是别的层级用客户端变量面板确认当前生效值再换对应的读取方式提交后发现密钥泄露环境文件被提交立刻轮换密钥把文件加进忽略列表改用模板文件这里我要强调一个反直觉的点变量名大小写敏感。baseUrl和baseurl是两个不同的变量而拼错的下场是插值失败——多数情况下它会保持原样发出去服务端返回 404 或者 400你会以为是接口路径改了。排查这类问题最快的办法是看一眼请求实际发出的 URL那里显示的是插值之后的真实地址。6.2 网络与证书类问题自签名证书是最常见的一类。表现是请求直接失败提示证书校验不通过。处理方式是把内部 CA 证书导入客户端的信任列表而不是关掉校验。关掉校验在本地图一时痛快但这份集合如果被带进 CI 就会出现本地能跑 CI 跑不了的分裂反过来也一样。另一类是超时设置不当。有些接口在冷启动时第一响应很慢默认超时容易误判为失败。我的做法是把集合级超时设成一个宽松值再对个别确实需要严格卡时间的接口用脚本单独收紧。这样默认宽松、重点严格不会因为环境抖动产生大量误报。还有一类是重定向行为。有些网关会把请求 302 到登录页如果客户端自动跟随重定向你最终拿到的是一个登录页的 HTML脚本里解析 JSON 就报错。这种情况在脚本里关掉自动跟随先看第一跳的响应头问题立刻就清楚了。6.3 脚本与断言类问题脚本报错是最容易让人怀疑工具的一类但九成是自己写的逻辑问题。我总结出三条规律。第一条test()和直接断言的区别要分清。放在test()里的断言失败会让用例失败并记录一条测试结果而散在脚本里的语句如果抛异常表现是整个请求失败报告里的信息量少很多。所以重要的校验一定要放进test()给自己留好排查线索。第二条异步逻辑不要藏在断言后面。脚本执行完才收集结果如果断言依赖异步回调可能出现断言还没跑完脚本就结束了的情况。需要异步的话把逻辑理清楚不要图和省事。第三条assert块的类型判断比想象中严格。服务端返回的123和123在类型断言下是两个结果如果接口把数字序列化成了字符串用isNumber就会失败。遇到这种就直接改成字符串断言或者跟服务端确认类型约定别自己骗自己。6.4 体感与性能类问题大响应体渲染慢。返回几兆的 JSON 时界面展开响应体会卡。处理方式是限制展示的响应体大小需要看全量内容时用脚本把响应保存成本地文件再打开看。这个坑我在做日志查询接口时踩过一个返回几十万条记录的接口差点把客户端拖死。历史记录占用空间。每个请求的响应体都会保留历史跑了几千次之后目录会变大。设置里的保留策略要定期检查特别是做长时间的回归测试时。安全模式下的困惑。客户端有个安全模式开启后脚本不会执行。有一次我导入了一个外部集合怎么跑断言都不生效排查半天才发现是安全模式拦住了脚本执行。如果你确认集合来源可信需要显式关掉它。Cookie 与会话保持。依赖 Cookie 的接口在同一个集合内是共享会话的但跨环境切换时要注意会话可能失效。我的处理办法是尽量用令牌而不是 Cookie 做鉴权Cookie 只保留给确实需要的老接口。7. 几条踩坑之后总结的个人经验聊了这么多操作层面的东西最后分享几条我自己使用下来觉得最有价值的判断都是被坑过之后才明白的。第一条集合的目录结构要在开始的时候就定好。我一开始是平铺放所有请求二十个请求还行到八十个就完全找不到东西了。后来按业务模块一级分组、特殊动作单独一层重排配合 Git 的重命名操作历史记录也是干净的。这个重构动作越早做越好晚了就要在评审里解释一大堆文件移动。第二条公共配置一律往上层放。能在集合级写的头部、鉴权、超时就不要在请求级重复写。这不仅是省事的问题更重要的是改一次通全局。我见过一个集合里三十个请求各写了一遍Authorization头改鉴权方式时改到怀疑人生。第三条把断言当文档写。test(业务码为 0)这种带中文描述的断言读起来就是接口行为的说明。新同事接手接口时先读一遍断言比读接口文档还快。我自己写断言的习惯是描述里带上期望值比如响应时间小于 1500ms失败信息一目了然。第四条本地环境和样例环境一定要分开。提交一份带占位值的Example.bru把真实值的Local.bru忽略掉这条规矩只要严格执行就不会出现密钥进仓库的事故。我见过一次密钥泄露的排查现场代价远超想象为了省一份模板文件不值得。第五条让 CLI 成为习惯而不是补救手段。很多人把命令行执行当成CI 需要才装其实本地跑一遍 CLI 特别有用它会按顺序执行、记录结果、给出退出码。写完一批用例本地用 CLI 跑一遍确认全绿再提交能省掉一轮 CI 排队的时间。再补一个后续可以延伸的方向如果团队接口多、变更频繁可以在 CI 里加一步接口定义变更检测——当代码仓库里的接口定义文件发生变更时自动提示对应的集合文件是否需要同步更新把接口改了测试集合忘了改这个问题从靠自觉变成靠流程。这一步不需要复杂的工具一个脚本加一条流水线规则就够用。