从 Express/Next.js/Fastify/Hono…

当你需要把代码库中的 API 路由导出为 Postman 集合（v2.1 JSON）以便调试或共享时使用。

适用场景

解决思路

1. 扫描路由：在代码库中查找所有 API 路由定义（Express 的 app.get()/router.post()、Next.js 的 app/api/**/route.ts、Fastify 的 fastify.get() 与 schema、Hono 的 app.get()/app.post()、NestJS 的 @Get()/@Post() 装饰器、Koa 的 router.get()/router.post()）。
2. 提取元数据：解析出 HTTP 方法、路径、路径/查询参数、请求体、请求头。
3. 组织端点：按资源或目录结构分组为文件夹。
4. 生成集合：输出 Postman Collection v2.1 JSON（info.schema 为 https://schema.getpostman.com/json/collection/v2.1.0/collection.json）。
5. 添加示例：为每个请求附带请求/响应示例。
6. 配置变量：为 baseUrl、authToken 等设置环境变量。
7. Express 扫描：用 @babel/parser 解析源码，@babel/traverse 遍历 CallExpression，匹配 callee.property.name 为 get/post/put/patch/delete 且第一个参数为 StringLiteral 的调用，记录 method、path、name、params。
8. 提取路径参数：用正则 /:(\w+)/g 从路径中提取参数，type 设为 path，example 设为 {{参数名}}。
9. 生成路由名：将路径中的 / 和 : 替换为空格并 trim，拼成 `${METHOD} ${cleanPath}`。
10. Next.js 扫描：用 glob 匹配 `${appDir}/**/route.{ts,js}`，读取文件内容，检测 export async function / export function / export const 形式的 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。
11. 转换 Next.js 路径：把 [..slug] 转为 :slug*，把 [id] 转为 :id。
12. Fastify 扫描：用正则匹配 fastify.(get|post|put|patch|delete)('path', { schema }, handler)，提取 method、path 和 schema。
13. 生成集合结构：构造 info（name、description、schema）、item、variable（baseUrl、authToken）、auth。
14. 配置认证：当 auth 为 bearer 时，设置 collection.auth = { type: 'bearer', bearer: [{ key: 'token', value: '{{authToken}}', type: 'string' }] }。
15. 按资源分组：取路径按 / 分割后的第二段（或第一段）作为资源名，将路由归入对应分组文件夹。
16. 创建请求项：设置 method、Content-Type: application/json 请求头、url（raw 为 {{baseUrl}}${path}，host 为 ['{{baseUrl}}']，path 为路径分段，variable 为路径参数）。
17. 添加请求体：当方法为 POST/PUT/PATCH 且存在 body 时，设置 body.mode 为 raw，raw 为格式化 JSON，options.raw.language 为 json。
18. 提供 CLI：用 commander 定义 postman-gen，支持 -f/--framework（默认 express）、-s/--source（默认 ./src）、-o/--output（默认 ./postman-collection.json）、-n/--name、-b/--base-url（默认 http://localhost:3000）、-a/--auth。
19. CLI 主流程：按 framework 调用对应扫描器，生成集合，写入输出文件，并打印生成的端点数。
20. 生成环境模板：输出包含 baseUrl、authToken（type 为 secret）、userId 等键值的 Development 环境 JSON。
21. 遵循最佳实践：使用 {{baseUrl}}/{{authToken}} 变量、按资源分组、添加描述、预填真实请求体示例、配置集合级认证、加入基础响应校验脚本、将集合 JSON 提交到版本控制、在路由变更时通过 CI 自动生成。
22. 按输出清单自检：所有路由已扫描、端点已分组、路径参数已提取、POST/PUT/PATCH 已含请求体、环境变量已配置、认证已设置、已导出 v2.1 JSON、已创建环境模板。

适用边界 · 注意事项

• 代码库不使用上述任一受支持框架（Express、Next.js、Fastify、Hono、NestJS、Koa）时。
• 路由定义是高度动态生成（如运行时拼接路径或循环注册）导致静态扫描无法识别时。
• 只需要手动维护少量接口、无需从代码自动同步时。