从 Express/Next.js/Fastify 等…

当需要为开源、Git 友好的 Bruno API 客户端生成可版本管理的接口测试集合时使用。

适用场景

解决思路

1. 扫描路由：找出所有 API 路由定义
2. 提取元数据：方法、路径、参数、请求体
3. 创建集合：初始化 bruno.json 清单
4. 生成 .bru 文件：每个请求一个文件
5. 组织文件夹：按资源分组
6. 添加环境：dev、staging、production
7. 按结构创建目录：collection/ 下含 bruno.json、environments/、按资源划分的子目录（如 users/、auth/、products/）
8. 写入 bruno.json 清单：包含 version: "1"、name、type: "collection"、ignore: ["node_modules", ".git"]
9. 生成环境文件：在 environments/ 下为 Development（http://localhost:3000/api）、Staging（https://staging-api.example.com）、Production（https://api.example.com）各创建一个 .bru 文件
10. 环境文件内容：vars 块中定义 baseUrl、authToken 等变量，并用 vars:secret [authToken] 标记敏感变量
11. 按资源分组路由：取路径第一段作为资源名（无则用 api），为每个资源创建子目录
12. 为每个资源目录创建 folder.bru：内容为 meta { name: <首字母大写的资源名> }
13. 为每个路由生成 .bru 文件：文件名由请求名小写并将空格替换为连字符
14. 生成 meta 块：包含 name、type: http、seq（从 1 递增）
15. 生成请求块：方法名小写作为块名，url 使用 {{baseUrl}} 前缀，路径参数 :param 转为 {{param}}
16. 设置 body 字段：POST/PUT/PATCH 且有请求体时为 json，否则为 none
17. 设置 auth 字段：需要认证且指定了 authType 时写入对应类型，否则为 none
18. 生成 auth:bearer 块：token 使用 {{authToken}}
19. 生成 auth:basic 块：包含 username: {{username}} 和 password: {{password}}
20. 生成 query 块：列出所有查询参数及其默认值
21. 生成 headers 块：始终包含 Accept: application/json，POST/PUT/PATCH 时追加 Content-Type: application/json
22. 生成 body:json 块：将请求体以 JSON 格式写入
23. 生成 docs 块：写入路由描述
24. 生成环境变量文件：vars 块中定义 baseUrl、authToken、userId 等，并用 vars:secret 标记 authToken
25. 在登录请求中添加 script:post-response 脚本：若 res.body.token 存在则 bru.setEnvVar("authToken", res.body.token)
26. 使用 script:pre-request 脚本：在请求前设置动态值，如用 Date.now() 生成 requestId 并 bru.setVar("requestId", ...)
27. 使用 script:post-response 脚本：从响应中提取 token 和 id 写入环境变量，并 console.log 状态码与响应时间
28. 在 tests 块中编写断言：如 expect(res.status).to.equal(200)、检查 res.body.data 为数组、检查 res.body.meta 含 page 和 total
29. 提供 CLI 脚本：使用 commander 定义 -f/--framework、-s/--source、-o/--output、-n/--name、-b/--base-url、-a/--auth 选项
30. CLI 主流程：调用 scanRoutes 扫描路由，再调用 generateBrunoCollection 生成集合，最后打印输出路径和 bruno run 命令
31. 遵循最佳实践：纯文本存储便于 Git、用环境文件存 URL 和 token、用 vars:secret 标记敏感变量、为每个请求写 docs、用 pre/post 脚本自动化 token 提取、添加测试断言、按资源组织文件夹、用 seq 排序请求
32. 按输出清单自检：bruno.json 已创建、dev/staging/prod 环境文件齐全、按资源分文件夹、每个文件夹有 folder.bru、请求 .bru 语法正确、路径参数用 {{param}}、查询参数在 query 块、请求体在 body:json 块、认证已配置、docs 块有文档、pre/post 脚本处理 token

适用边界 · 注意事项

• 不使用 Bruno 作为 API 客户端时
• API 路由不是 Express、Next.js、Fastify 等可扫描的框架时