Posting 请求导入实战指南curl、OpenAPI 3.x 与 Postman 集合的终端化迁移【免费下载链接】postingThe modern API client that lives in your terminal.项目地址: https://gitcode.com/gh_mirrors/po/postingPosting 是一个运行在终端中的现代 API 客户端TUI其所有请求都以本地 YAML 文件形式组织在集合目录中。当你在已有项目中使用 curl 命令、OpenAPI 规范或 Postman 集合时importing功能可以帮你把这些外部世界的请求描述一键转换为 Posting 原生格式避免手工重建每一个请求。读完本文你将掌握三种导入方式的完整操作流程、底层实现原理以及导入产物请求 YAML、.env环境文件、README的组织规则。导入功能总览Posting 的导入能力由 docs/guide/importing.md 定义分为三条通道导入来源操作方式适用场景curl 命令直接粘贴到 URL 输入栏浏览器开发者工具 / 他人分享的单条命令OpenAPI 3.x 规范posting import spec子命令从 API 设计文档批量生成整个集合Postman 集合posting import --type postman json从 Postman 迁移既有集合需要说明的是官方文档明确标注三种导入均为实验性功能experimental。在命令行入口 src/posting/main.py 中每次执行posting import都会先以黄色粗体输出 Importing is currently an experimental feature. 的提示意味着导入逻辑仍在演进格式细节可能在后续版本调整。三种导入方式共享同一套输出模型最终都会在目标目录中生成以.posting.yaml结尾的请求文件结构可参考 tests/sample-collections/jsonplaceholder/posts/get-all.posting.yaml内含name、url、method、headers等字段使得导入结果与手写请求完全同构可直接在 TUI 中打开、编辑与发送。从 curl 命令导入粘贴即用操作步骤curl 导入是三种方式中最轻量的一条路径无需命令行参数只需两步复制任意 curl 命令例如从浏览器开发者工具的 Copy as cURL 生成将其粘贴到 Posting 的 URL 输入栏ctrll可快速聚焦该输入框。Posting 会解析这条命令把其中的 URL、请求方法、请求头、请求体、认证信息等细节填充到 UI 中的对应位置并覆盖overwrite当前已有的请求值。因此官方文档特别建议粘贴前先新建一个空请求以免误覆盖正在编辑的内容。这一提示同样写在了 URL 输入框的帮助文本里见 src/posting/widgets/request/url_bar.py。成功导入后界面右下角会弹出通知 Successfully imported request to 如果解析失败则会以错误级别通知 Couldnt import curl command.处理逻辑见 src/posting/app.py。底层解析原理粘贴事件的处理链路如下URL 输入框在on_paste事件中检测到文本以curl开头时会拦截默认粘贴行为并发出CurlMessage消息url_bar.py应用层收到后调用CurlImport解析器将其转换为内部RequestModelapp.py。CurlImport类src/posting/importing/curl.py的解析策略有几点值得注意去前缀与容错清洗剥离开头的curl字样将\换行符替换为空格并移除行内反斜杠——这是为了兼容从 Chrome 复制出来的多行命令基于shlexargparse的标记解析命令被拆分为 tokens 后按 curl 参数表逐一解析。支持的参数包括-X/--request、-H/--header可多次、-d/--data、--data-raw、--data-binary、--data-urlencode、-F/--form、-u/--user、--compressed、-k/--insecure、-e/--referer、-A/--user-agent、-m/--max-time、--digest以及位置参数 URL方法推断显式-X优先否则只要携带-d/-F/--data-*任一数据参数就推断为POST其余默认为GET表单判定若存在-F则视为 multipart 表单若带数据且请求头包含application/x-www-form-urlencoded或完全没有Content-Type头curl-d的默认内容类型则按表单键值对拆分否则作为 raw 请求体认证抽取_extract_auth_from_headerscurl.py-u参数映射为 Basic 或 Digest 认证Authorization头中的Basicbase64 解码出用户名/密码、Digest解析参数取 username与Bearer直接取 token也会被识别并转换成 Posting 的Auth模型URL 拆分查询字符串会被剥离开按和拆分为独立的QueryParam列表URL 主体部分保留为请求地址选项默认值导入后的请求默认verify_ssl not insecure即-k会关闭 SSL 校验、默认跟随重定向、默认附加 Cookie来源留痕请求的description字段会写入 Imported from curl at 时间戳 以及完整原始命令方便日后回溯来源。测试用例佐证仓库中的 tests/test_curl_import.py 为这套解析逻辑提供了丰富的边界覆盖可作为理解行为的参考test_simple_get最简curl http://example.com应解析为 GET、无头、无数据test_post_with_form_data与test_multiple_data_options多个-d参数会以拼接并按表单键值对拆分test_post_with_json_data显式声明Content-Type: application/json时不会被误判为表单test_curl_with_escaped_newlines多行反斜杠续行的命令可以正常解析test_curl_imports_max_time--max-time等此前缺失的参数已得到处理注释表明修复于 2.5.1test_curl_with_utf8_characters与test_curl_with_special_characters_in_dataUTF-8 与%编码字符均可保留。从 OpenAPI 3.x 规范导入命令与输出行为OpenAPI 导入通过posting import子命令完成# 基本用法将 spec 导入默认集合目录 posting import path/to/openapi.yaml # 指定输出目录 posting import -o path/to/output path/to/openapi.yaml # 完整参数形式--type 默认即为 openapi可省略 posting import --type openapi --output path/to/output path/to/openapi.yaml命令的参数定义位于 src/posting/main.pyspec_path是必填位置参数要求文件已存在--output/-o指定保存目录--type/-t可选openapi或postman。当未提供输出目录时导入结果会被写入默认集合目录下的子目录默认集合目录/集合名默认集合目录的准确位置可以用posting locate collection查询实现在 src/posting/locations.py遵循 XDG 规范位于数据目录的posting/default下。官方文档承诺Posting 会尽量按被导入 API 的 URL 结构在集合中构建文件树。从源码实现src/posting/importing/open_api.py看这一结构具体体现为按 tag 分组带有tags的 Operation 会被归入以首个 tag 命名的子集合Collection没有 tag 的请求直接挂在主集合下URL 模板化每个请求的 URL 统一写成${{BASE_URL}}{path}形式实际服务器地址由环境变量BASE_URL决定server 变量解析spec 顶层servers[].variables中声明的变量会按其默认值解析进BASE_URL的值参数映射in: query参数变成请求的QueryParamin: header参数变成Header两者的deprecated属性会被映射为enabledFalse即导入后默认停用见 open_api.py请求体生成application/json媒体类型会依据 Schema 生成一份带缩进的示例 JSONJsonBodyGenerator根据字段类型回填默认值或空值application/x-www-form-urlencoded则转换为表单键值对列表认证绑定Operation 的security声明会匹配components.securitySchemes中的方案basic 与 bearer 两类被转换为请求级认证。环境变量与.env文件生成OpenAPI 导入的产物并不只是请求 YAML。源码中的extract_server_variables与create_env_fileopen_api.py 与 open_api.py表明每个 server 都会生成一个独立的.env文件文件名由集合名与 server URL 组合、slugify 后得到超长部分会被截断尾部下划线会被移除例如petstore_api_v1_env之类的唯一名.env文件中总是包含BASE_URL解析后的服务器地址并附注释说明若 spec 声明了 HTTP Basic 安全方案会追加SCHEME_USERNAME/SCHEME_PASSWORD占位符默认值YOUR USERNAME HERE/YOUR PASSWORD HERE若为 Bearer 方案则追加SCHEME_BEARER_TOKEN占位符其余安全方案类型暂不生成变量这些变量会被回填到请求的认证配置中例如type: bearer_token的token字段引用${{SCHEME}_BEARER_TOKEN}最终由环境机制解析。测试 tests/test_open_api_import.py 印证了这一行为导入 3.1.0 规格后请求 URL 为${{BASE_URL}}/account_id头因为deprecated: True而被设为enabledFalse认证 token 引用${{BEARERAUTH_BEARER_TOKEN}}同一文件也覆盖了 3.0.x 规格下的$ref解析、tag 分组与 JSON 请求体示例生成。版本支持范围_get_openapi_modelsopen_api.py说明导入器按openapi字段前缀分派解析模型3.0.x与3.1.x均受支持其余版本会抛出ValueError并提示 Only 3.0.x and 3.1.x are supported.。同时路径中的$ref含#/components/schemas/...、parameters、requestBodies会通过parse_component_ref递归解析并带有循环引用保护seen 集合可以放心导入组件间相互引用的规范。集合 README 的自动生成导入时还会在主集合下生成一份 READMEgenerate_readmeopen_api.py内容包含spec 的标题与文件名、描述、版本、服务条款、联系信息、许可证、外部文档链接以及每个 server 对应的.env文件名清单并提示使用posting --env file选项加载环境。这使得导入后的集合自带文档上下文无需手工维护。从 Postman 集合导入命令与输出行为Postman 导入同样走posting import子命令但必须显式声明类型# 基本用法 posting import --type postman path/to/postman_collection.json # 指定输出目录 posting import --type postman -o path/to/output path/to/postman_collection.json与 OpenAPI 导入一致-o可选缺省时使用默认集合目录若漏掉--type postman而直接传入 Postman JSON命令行会报错并提示使用该参数见 src/posting/main.py。Postman 导入器src/posting/importing/postman.py按如下规则重建集合结构文件夹folder映射为子集合Postman collection 中嵌套的item本身包含item列表的节点会被转换为同名子 Collection目录层级一一对应请求映射为.posting.yaml请求文件名由条目名去除非字母数字后按单词首字母大写拼接例如get all posts会变成GetAllPosts.posting.yaml并保存在所属集合目录中URL 处理raw URL 中的查询字符串会被拆出作为独立的QueryParam列表请求头、描述原样保留请求体处理mode: raw且语言为json时按 JSON 文本导入mode: formdata时转为表单键值对disabled状态映射为enabled集合级 README以 Postmaninfo中的名称、描述、schema 生成主集合 README。变量导入与{{var}}语法转换Postman 导入最大的特色是变量迁移官方文档明确指出Variables will also be imported from the Postman collection and placed in a.envfile inside the collection directory.。实现细节如下集合顶层的variable数组会被写入集合名.env文件名由集合名决定由命令行入口 src/posting/main.py 调用create_env_file完成变量名经过sanitize_variables规范化postman.pycamelCase 或 kebab-case 的名字会被转成大写蛇形例如userId变为USER_ID请求 URL 与 JSON 请求体中的{{variable}}占位符会被sanitize_str统一替换为 Posting 的$VARIABLE语法例如{{userId}}→$USER_ID。这意味着导入后的请求无需改动即可接入 Posting 的环境变量机制。导入流程与错误处理完整的 Postman 导入流程是读取 JSON → 用 pydantic 模型校验PostmanCollection等模型定义于 postman.py→ 递归构建集合树 → 保存请求 YAML 到磁盘 → 生成环境文件。主流程在 src/posting/main.py 中完成若过程中出现异常命令行会输出红色错误信息、提示检查导入类型并打印完整 traceback 以便上报问题。导入产物的后续使用无论通过哪条通道导入产物的消费方式都是统一的查看默认目录posting locate collection打印默认集合目录绝对路径导入的集合位于其下加载集合启动posting --collection 目录或posting -c 目录以指定集合启动 TUIsrc/posting/main.py加载环境变量posting --env file可多次指定加载.env环境文件Posting 还会自动加载当前目录下的posting.envsrc/posting/main.py在 TUI 中发送请求导入的请求会出现在集合浏览器中可直接聚焦 URL 输入栏发送请求编辑界面中也能看到导入时填充的认证、头、参数与请求体。三种导入方式的选型建议场景推荐方式理由临时复现他人分享/浏览器导出的单条请求粘贴到 URL 栏零成本、立即填充 UI且自动识别认证头团队已有 OpenAPI 3.x 文档需要整套 API 的请求集合posting import spec按 tag 与 URL 结构自动建树自动生成环境变量与示例请求体从 Postman 迁移既有集合posting import --type postman json保留层级结构并自动完成变量语法转换一个实用的工作流是先用posting import --type postman -o ./collections将历史集合迁入仓库再用posting import -o ./collections openapi.yaml补充按规范生成的请求最后用posting -c ./collections打开统一后的集合进行验证与精修。由于导入产物都是纯文本 YAML它们可以直接纳入版本控制与团队共享这也是 Posting 的核心设计理念——请求文件简单、可读、可 diff。【免费下载链接】postingThe modern API client that lives in your terminal.项目地址: https://gitcode.com/gh_mirrors/po/posting创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考