usebruno/converters 使用指南将 Postman、Insomnia、OpenAPI 与 WSDL 集合一键转换为 Bruno 格式【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno本文围绕 Bruno 开源仓库中的转换器包 bruno-converters 展开讲解如何把 Postman、Insomnia、OpenAPISwagger与 WSDL 等异构格式的 API 定义与集合以编程方式Node.js API或命令行方式Bruno CLI转换为可直接被 Bruno 使用的 Bruno 集合并深入源码解读其转换原理与边界限制。读完本文你将掌握postmanToBruno、insomniaToBruno、openApiToBruno、wsdlToBruno等全部公开 API 的正确用法能独立编写“读取源文件 → 转换 → 落盘/写入目录”的迁移脚本也能读懂底层 schema 校验、脚本翻译与 SOAP Envelope 生成等实现细节。一、bruno-converters 是什么bruno-convertersnpm 包名为usebruno/converters是 Bruno 仓库中负责“格式互转”的核心包将其他格式的集合转换成一个 Bruno collection。根据其 readme.md 的定位它既可以作为独立 npm 包单独安装使用也可以作为 Bruno 框架的一部分被上层如 bruno-cli 的import命令调用。从仓库源码结构看该包由多个相互独立的转换器组成src/index.js 是统一的导出入口导出名称目标格式核心实现文件postmanToBrunoPostman 集合 → Bruno 集合src/postman/postman-to-bruno.jspostmanToBrunoEnvironmentPostman 环境 → Bruno 环境src/postman/postman-env-to-bruno-env.jsbrunoToPostmanBruno 集合 → Postman 集合反向src/postman/bruno-to-postman.jsopenApiToBrunoOpenAPI 规格 → Bruno 集合src/openapi/openapi-to-bruno.jsinsomniaToBrunoInsomnia 集合 → Bruno 集合src/insomnia/insomnia-to-bruno.jswsdlToBrunoWSDL 文件 → Bruno 集合src/wsdl/wsdl-to-bruno.jspostmanTranslationPostman 脚本翻译能力src/postman/postman-translations.jsopenCollectionToBruno/brunoToOpenCollectionOpenCollection 与 Bruno 互转src/opencollection/二、安装与绝大多数 Node 包相同使用 npm 安装即可npm install usebruno/converters在 package.json 中可以看到该包同时提供 CJS 与 ESM 两种入口main指向dist/cjs/index.jsmodule指向dist/esm/index.js因此require与import两种模块方式均受支持。若你是从仓库源码本地联调也可进入packages/bruno-converters后执行包内定义的build脚本rollup 构建见 package.json生成dist。三、五种导入方式的 API 用法阅读 readme.md 中的 Usage 一节可见该包提供了非常一致的使用范式把源格式的 JS 对象传给对应的转换函数得到 Bruno 格式的集合对象。3.1 将 Postman 集合转换为 Bruno 集合const { postmanToBruno } require(usebruno/converters); // Convert Postman collection to Bruno collection const result await postmanToBruno(postmanCollection); const brunoCollection result.collection;注意这里的postmanToBruno是异步函数。以当前仓库实现为准它返回的是{ collection, issues }结构而非直接返回集合对象其中collection是转换完成并通过 schema 校验的 Bruno 集合issues是转换过程中收集的非致命问题详见 src/postman/postman-to-bruno.js 末尾的postmanToBruno定义。这一点在仓库测试中体现得很清楚例如 tests/postman/postman-to-bruno/partial-import.spec.js 中统一使用const { collection, issues } await postmanToBruno(...)的方式取值。3.2 将 Postman 环境转换为 Bruno 环境const { postmanToBrunoEnvironment } require(usebruno/converters); const brunoEnvironment postmanToBrunoEnvironment(postmanEnvironment);阅读 src/postman/postman-env-to-bruno-env.js 可知环境转换器会逐条处理environment.values为每个变量生成uid将变量名中不合法的字符替换为下划线invalidVariableCharacterRegex并透传enabled状态尤其值得注意的是它会读取 Postman 变量的type字段当类型为secret时把 Bruno 变量的secret标记为true从而把机密变量语义也保留下来。3.3 将 Insomnia 集合转换为 Bruno 集合const { insomniaToBruno } require(usebruno/converters); const brunoCollection insomniaToBruno(insomniaCollection);Insomnia 转换器src/insomnia/insomnia-to-bruno.js既能解析 v4经典的resources扁平结构导出含workspace、request、request_group等资源类型也能解析 v5 新格式通过根级type是否以collection.insomnia.rest/5开头来判别实现细节可参考同文件中的isInsomniaV5Export函数。转换时它还做了几件贴心处理同名请求自动追加数字后缀addSuffixToDuplicateName、统一去除变量引用中不必要的下划线写法normalizeVariables并从body.mimeType映射请求体语言如application/json→ JSON 体、multipart/form-data→ 表单体、application/graphql→ GraphQL 请求等。3.4 将 OpenAPI 规格转换为 Bruno 集合const { openApiToBruno } require(usebruno/converters); const brunoCollection openApiToBruno(openApiSpecification);入口实现在 src/openapi/openapi-to-bruno.js支持传入解析后的对象也支持直接传 YAML 字符串内部会先用js-yaml加载若检测到specification.swagger以2开头会转交给 src/openapi/swagger2-to-bruno.js 走 Swagger 2.0 的转换路径。OpenAPI 转换对 schema 示例值的挖掘尤其深入如从example、default、enum[0]中逐级提取属性示例值遇到 enum 参数还会为每个枚举值生成多条可开关的参数条目见同文件的getSchemaPropertyExampleValue与getParameterEntries。3.5 将 WSDL 文件转换为 Bruno 集合import { wsdlToBruno } from usebruno/converters; const brunoCollection await wsdlToBruno(wsdlContent);WSDL 导入是异步操作入参必须是一个包含 WSDL/XML 文本的字符串src/wsdl/wsdl-to-bruno.js 中会显式校验类型非字符串直接抛错。其内部实现值得展开阅读WSDLParser类负责把 XML 解析为命名空间、复杂类型、消息、端口类型、绑定与服务等结构化数据随后parseWSDLCollection按**服务service**分组生成 Bruno 文件夹并把每个 WSDL 操作映射为一个POST请求导出的XMLSampleGenerator类还可基于 XSD 递归生成带类型样例值的请求体。四、文件级转换脚本从 Postman JSON 到 Bruno JSONreadme.md 提供了一个完整的“读文件 → 转换 → 写文件”示例下面给出与当前仓库实现一致的可运行版本const { postmanToBruno } require(usebruno/converters); const fs require(fs/promises); const path require(path); async function convertPostmanToBruno(inputFile, outputFile) { try { // Read Postman collection file const inputData await fs.readFile(inputFile, utf8); // Convert to Bruno collection const { collection: brunoCollection, issues } await postmanToBruno(JSON.parse(inputData)); if (issues issues.length 0) { console.warn(转换过程中发现的问题, issues); } // Save Bruno collection await fs.writeFile(outputFile, JSON.stringify(brunoCollection, null, 2)); console.log(Conversion successful!); } catch (error) { console.error(Error during conversion:, error); } } // Usage const inputFilePath path.resolve(__dirname, demo_collection.postman_collection.json); const outputFilePath path.resolve(__dirname, bruno-collection.json); convertPostmanToBruno(inputFilePath, outputFilePath);几点实践提示转换函数不会检查磁盘、不会做文件 IO输入输出都是普通对象因此可以自由嵌入到任何构建脚本、迁移工具中返回的 Bruno 集合在写出前已经通过了usebruno/schema的collectionSchema严格校验见 src/postman/postman-to-bruno.js 中validateSchema的调用链不合法的条目会以issues形式收集而非直接中断整个转换——这正是partial-import测试所验证的“单条坏请求不影响整批导入”能力参考 tests/postman/postman-to-bruno/partial-import.spec.js转换链路中还包含transformItemsInCollection统一条目类型命名、query→params 迁移与hydrateSeqInCollection为缺失序号的请求补齐seq两个后处理步骤确保产物符合 Bruno 内部数据模型。五、Postman 导入的深度转换细节Postman 转换器是全部转换器中最复杂的部分了解其内部逻辑能帮助你预判迁移结果。5.1 版本识别与包裹解包parsePostmanCollection会先识别 Postman 导出文件info.schema中声明的 schema 地址目前支持 v2.0.0 与 v2.1.0 的四种 URL 写法同时会兼容“新版导出把整个集合包在{ collection: { ... } }壳里”的情况见 src/postman/postman-to-bruno.js 的parsePostmanCollection。识别失败会抛出 “Unsupported Postman schema version” 异常。5.2 认证类型全量映射processAuth函数同文件约第 249 行起将 Postman 的 auth 对象映射为 Bruno 的认证结构AUTH_TYPES常量列举了双方都能覆盖的类型basic、bearer、awsv4、apikey、digest、oauth1、oauth2、edgegridAkamai、ntlm、noauth。值得注意的映射细节Postman 集合设为 “No Auth” 时 auth 为null此时保持 Bruno 默认模式请求/文件夹设为 “Inherit” 时也为null同样保留继承语义只有显式 “No Auth” 才把 mode 置为noneOAuth2 的grant_type会做语义归一化如authorization_code_with_pkce→ Bruno 的authorization_code并显式置pkce: truepassword_credentials→password各类辅助请求参数authRequestParams/tokenRequestParams/refreshRequestParams会连同 Postman 的send_as位置信息一起映射为 Bruno 的additionalParametersAkamai EdgeGrid 的maxBodySize会被强转为数字非法值置空。5.3 脚本翻译与 npm 依赖报告Postman 的prerequest/test事件脚本会分别落到 Bruno 的script.req/script.res。默认情况下脚本会经过postmanTranslation翻译把 Postman 的pm.*API 翻译为 Bruno 的bru.*/req.*/res.*语义翻译可放到 src/workers/postman-translator-worker.js 对应的 worker 中并行执行通过useWorkers选项开启适合大型集合脚本中通过pm.require()引用的 npm 包会被提取并重写为require()最终汇总为集合上的packageReport方便你在迁移后统一安装依赖。若想“原样保留脚本、不做任何翻译”可传入{ preserveScripts: true }选项。六、WSDL 导入特性详解readme.md 的 “WSDL Import Features” 一节归纳了 WSDL 导入器的六个核心能力结合 src/wsdl/wsdl-to-bruno.js 可进一步印证其实现Service Discovery服务端点自动提取parseServices解析wsdl:service/wsdl:port并通过extractAddress从soap:address等节点取出location作为请求 URLOperation Mapping操作映射为 HTTP 请求每个 WSDL 操作经transformWSDLOperation映射成一个POST的http-request条目SOAP Envelope GenerationSOAP 报文生成generateSOAPEnvelope依据操作输入消息关联的 element用XMLSampleGenerator递归生成带注释可选/可重复提示与类型化示例值如string、0、true、2024-01-01等的请求体并套入标准soap:Envelope骨架Header Configuration请求头配置为每个请求预置Content-Type: text/xml; charsetutf-8与SOAPAction两个请求头其中SOAPAction优先取自 binding 中的soap:operation缺失时回退为targetNamespace operationName的拼接形式Environment Variables环境变量服务端点地址直接写入各请求的 URL便于后续用 Bruno 环境变量替换为不同环境的真实地址Folder Organization按服务分组集合按service生成一个文件夹再将该服务所有端口port下、经由 binding → portType 关联到的操作全部归入此文件夹见parseWSDLCollection。6.1 代码级导入示例import { wsdlToBruno } from usebruno/converters; import fs from fs/promises; async function importWSDL() { try { // Read WSDL file const wsdlContent await fs.readFile(service.wsdl, utf8); // Convert to Bruno collection const brunoCollection await wsdlToBruno(wsdlContent); // Save Bruno collection await fs.writeFile(soap-collection.json, JSON.stringify(brunoCollection, null, 2)); console.log(WSDL import successful!); } catch (error) { console.error(Error during WSDL import:, error); } } importWSDL();七、使用 Bruno CLI 导入 WSDL除了直接调用 Node API还可以通过 Bruno CLI 完成导入。仓库中 packages/bruno-cli/src/commands/import.js 实现了bruno import type命令type目前支持openapi与wsdl两种WSDL 的三种典型用法如下# Import WSDL file to a directory bruno import wsdl --source service.wsdl --output ~/Desktop/soap-collection --collection-name SOAP Service # Import WSDL from URL bruno import wsdl --source https://example.com/service.wsdl --output ~/Desktop --collection-name Remote SOAP Service # Import WSDL and save as JSON file bruno import wsdl --source service.wsdl --output-file ~/Desktop/soap-collection.json --collection-name SOAP Service7.1 命令参数说明对照 import.js 的builder定义各参数语义如下参数别名必填说明--source-s是源文件路径或 URL支持本地文件与 http/https 远程拉取--output-o二选一输出目录若指向已存在目录会按集合名创建子目录并落盘集合文件--output-file-f二选一直接把转换结果以单个 JSON 文件保存与--output互斥--collection-name-n否覆盖导入集合的名称--collection-format—否落盘格式bru或opencollection默认opencollection会以 YAML 形式写出--insecure—否从 URL 拉取时跳过 SSL 证书校验自签名证书场景使用--group-by-g否仅 OpenAPI 导入有效tags按标签分组或path按 URL 路径分组默认tagsCLI 处理流程可参考同文件的handlerWSDL 内容以字符串读取readWSDLFile随后调用wsdlToBruno转换若有--collection-name则覆盖collection.name最后按输出参数分别走“写 JSON 文件”或“按 bru/yml 格式在目录中重建集合”两条路径。远程拉取设有 30 秒超时与 10 MB 内容上限证书类错误CERT_HAS_EXPIRED、自签名等会被捕获并提示改用--insecure。八、支持格式与使用边界根据 readme.md 的 “Supported Formats” 一节导入侧支持的格式如下Postman Collectionsv2.1源码同时兼容 v2.0 schema 地址并拒绝其他 schema 版本Insomnia Collectionsv4 与 v5 两种导出结构OpenAPI Specificationsv3.0源码对swagger: 2.x走独立转换路径WSDL FilesWeb Services Description LanguageSOAP 1.x 常见结构导出/互转侧则额外提供了brunoToPostmanBruno → Postman与 OpenCollection 双向转换openCollectionToBruno/brunoToOpenCollection覆盖“从 Bruno 迁出或与 OpenCollection 生态同步”的场景。需要说明的是各转换器主要面向 HTTP/HTTPS 请求WSDL 导入固定生成POST请求体模式、认证类型与脚本能力以双方 Schema 的公共子集为上限超出范围的内容通常以issues提示或默认值形式保留不会导致整个集合转换失败。九、依赖组成readme.md 列出的运行时依赖及其职责如下lodash— 集合遍历与取值工具函数each/get等在全部转换器中被广泛使用nanoid— 为生成的集合条目生成唯一 IDuidjs-yaml— YAML 解析Insomnia 与 OpenAPI 字符串入参的解析xml2js— WSDL/XML 解析usebruno/schema— 对产物做 Bruno 集合 Schema 校验结合 package.json实际还依赖usebruno/common示例状态转换等公共工具、jscodeshift脚本语法树级翻译的基础设施、mime-types从文件扩展名推断二进制体的 Content-Type见 Postmanfile模式请求体的处理等。当你把该包安装进自己的工程后这些依赖会一并随包安装。十、总结迁移到 Bruno 的推荐路径综合上文把一个现成 API 集合迁移到 Bruno 的推荐路径是评估来源格式Postman v2.x / Insomnia v4、v5 / OpenAPI 3.0含 Swagger 2.0/ WSDL 均可直接使用usebruno/converters若手头只有.bru集合或 OpenCollection也可用双向转换能力处理小规模验证先用postmanToBruno或insomniaToBruno在脚本中打印issues确认是否存在个别无法映射的条目脚本注意点Postman 集合转换记得解构{ collection, issues }需要原样保留pm.*脚本时传{ preserveScripts: true }大批量或 WSDL可直接借助bruno import openapi/wsdl命令完成文件/URL 导入与目录落盘无需手写脚本检查依赖若集合脚本依赖第三方 npm 包参考产物集合的packageReport统一补齐依赖。通过 packages/bruno-converters 与其在 bruno-cli 中的落地import命令Bruno 生态实现了“存量集合低成本迁入、格式标准化统一”的目标本文给出的 API 用法与源码解读可直接用于你接下来的实际迁移任务。【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考