apifox-import-export

导入导出与质量门禁

前置条件：先阅读 ../apifox-cli/SKILL.md。若旧总入口与本 skill 的领域规则冲突，以当前 CLI help 和本 skill 为准。

具体命令参数以当前 CLI help 为准。导入前重点检查文件格式、OpenAPI 质量门禁、路由骨架风险、tags 分组、原生格式模块策略、ignoreCount 和是否需要干净项目验证。Agent 导入后必须按 agentHints、list/get 和必要的 run/report 做结果确认，不要只依据导入命令返回成功判断完成。

何时使用

• 从代码库、PRD、需求文档、测试文档、讨论记录生成 API spec 并导入 Apifox。
• 导入 OpenAPI、Postman、HAR、Apifox 原生格式等项目数据。
• 配置自动导入。
• 导出 OpenAPI、Markdown、HTML、Postman 或 Apifox 原生格式。
• 需要判断生成的 spec 是否只是“路由骨架”。
• 迁移、备份或复制 Apifox 项目，尤其是需要控制模块复用或新建时。

不应使用

• 把已有 endpoint、test-case 或 test-scenario step 导入/复制到测试场景：转 apifox-test-scenario，使用 test-scenario import-steps 或 test-scenario add-ref。
• 精细维护测试场景步骤、变量、断言或处理器：转 apifox-test-scenario。

命令入口

使用当前 CLI help 查询 import、import auto-import、export 和 export settings 的参数。导入前不要跳过下面的质量门禁。

核心原则

1. 优先查项目内已有生成器，不要先手写提取脚本。
2. 不要把“路径完整”误判为“接口 spec 完整”。
3. 导入前必须输出质量指标。
4. 完整性和可读性要同时验收。
5. 导入策略不确定时，优先新建临时/修正版项目验证，不要污染已有项目。
6. 导入结果里的大量 ignoreCount 是风险信号，不是普通成功。
7. Apifox 目录分组依赖 OpenAPI operation tags。
8. 不要假设文件扩展名代表实际格式。

标准流程

Step 0. 明确任务类型

先判断用户要做的是哪一类任务：

任务	下一步
从代码库、PRD、文档生成 spec 并导入	继续 Step 1
直接导入已有文件	从 Step 3 开始
配置自动导入	先读取当前 CLI help 和 schema，再创建配置
导出文档或 OpenAPI	直接使用 export 命令，导出后检查文件是否生成
迁移或备份 Apifox 项目	使用 Apifox 原生格式导出导入，并确认模块导入策略
把已有资源导入测试场景	转 apifox-test-scenario，不要走 OpenAPI import

如果用户没有指定目标项目、团队、导入策略或是否允许创建新项目，先根据上下文判断；不确定时只问一个最小必要问题。

Step 1. 搜索项目内已有生成器

遇到“从源码/文档/PRD/测试文档/讨论生成 API spec / 文档 / 类型”的需求，先搜索项目内是否已有：

openapi
swagger
routegen
route-gen
docs generator
api docs
schema generator
cmd/openapi
cmd/*openapi*

正确方向：

• 先运行项目自带生成器。
• 优先使用能抽取 handler request/response struct、DTO、schema 的工具。
• 不要先手写脚本从 router 文件提取路径，否则很容易只得到 method + path 骨架。

如果找不到生成器，再考虑从框架路由、注释、DTO、schema、测试或文档生成 spec；生成后仍必须继续 Step 3 之后的质量门禁。

Step 2. 生成 spec 并确认文件格式

• 运行项目自带生成器或官方生成命令。
• 保存原始产物，不要直接覆盖用户已有文件。
• 不要根据扩展名判断格式。
• 读取生成文件前，先看文件开头或用支持 JSON/YAML 的 parser。
• 生成器可能输出 YAML 到 .json 文件；如果实际是 YAML，应改名为 .yaml 或按 YAML 解析。

Step 3. 统计导入前质量指标

导入前必须实际解析生成的 OpenAPI 文件，并报告真实统计值。不要使用示例值、默认值或占位值。

必须统计：

指标	含义	用途
paths	OpenAPI paths 数量	判断接口规模
operations	实际 operation 数量	判断导入规模
schemas	components.schemas 数量	判断模型完整度
writes	POST/PUT/PATCH 等写接口数量	判断 body 覆盖目标
withBody	写接口中有 requestBody 的数量	判断 requestBody 覆盖率
emptyObjectBodies	requestBody schema 是空对象的数量	判断是否路由骨架

输出时必须写“真实统计结果”，例如使用表格或 JSON 均可，但每个值必须来自当前文件解析结果。

Step 4. 判断 spec 完整性

• 不按固定 schema 数量判定质量。
• 小型、纯 GET、健康检查、webhook 透传、无 JSON body 项目，schemas=0/1 可以接受。
• 大项目如果接口很多、写接口很多，但 schemas 极少，视为疑似路由骨架 spec。
• 大量 POST/PUT/PATCH 的 body 缺失或是空 {}，是强风险信号。
• 只有 method + path 不能证明 requestBody、response、schema 完整。

风险判断：

现象	判断	处理
接口规模大、写接口多，但 schemas 极少	疑似路由骨架 spec	继续查 DTO、handler request/response struct、项目内生成器或文档来源
写接口很多，但 withBody 覆盖明显不足	requestBody 不完整	继续补充 request DTO 或换生成器
emptyObjectBodies 很多	强风险，可能只是空壳 body	不要作为最终 spec 导入
小型、纯 GET、健康检查、webhook 透传	schemas 很少可能合理	结合业务形态判断，不强制失败

如果判定为路由骨架 spec，不要导入为最终版本；最多导入临时项目用于探索。

Step 5. 校验 tags 和文档可读性

API spec 不只要模型完整，还要在 Apifox 中可读、可导航、分组合理。

必须检查：

• operation 是否有业务化 tags。
• tags 是否按业务域分组，而不是按 URL path 机械分组。
• schema 是否保留完整。
• operationId、summary、description 是否可读。

推荐 tags 形态：

paths:
  /api/v1/<resource>:
    post:
      tags:
        - <业务域名称>

不推荐导入后目录按技术路径机械展开，例如：

api / v1 / <resource>

更推荐按产品模块、业务域、资源域或用户可理解的功能域设置 tags，让 Apifox 客户端中的目录服务于业务导航，而不是服务于代码路径还原。

如果生成器产物的 tags 明显过粗或机械来自技术路径，例如大量接口都落在 api、v1、rest、service、controller 等目录下，必须停在导入前，先询问用户是否允许生成一个 tags 更合理、项目文档更整洁的修正版 spec。用户同意前，不要把该 spec 导入为最终项目。

Step 6. 选择导入项目

• 导入策略不确定时，优先创建临时/修正版项目验证。
• 不要用新 spec 反复导入污染已有项目。
• 如果已有项目里导入过骨架 spec，再导入完整 spec 可能出现旧接口 ignore、新接口追加、项目混杂。
• 临时项目命名建议表达版本和目的，例如 API - Full Spec、API - Grouped Full Spec。

Step 7. 执行导入并检查结果

导入后不要只看命令成功，还要看结果计数。

如果导入结果中 ignoreCount 明显偏高，不能把“命令执行成功”当成“导入质量合格”。必须继续判断：

• 是否导入到了已有项目。
• 是否接口匹配策略不符合预期。
• 是否旧 spec 和新 spec 混杂。
• 是否应该改用干净项目重新导入。

Step 7A. Apifox 原生格式导入策略

Apifox 原生格式适合项目迁移、备份、跨项目复制和局部资源搬迁。常用命令：

apifox import --project <projectId> --format apifox --file ./project.apifox.json

默认模块策略是 match-name：源模块名与目标项目模块名唯一匹配时导入已有模块，未匹配时新建模块。二次导入同一个项目时，优先使用默认策略，避免重复创建同名模块。

apifox import --project <projectId> --format apifox --file ./project.apifox.json --module-import-mode match-name

如果测试目标是每次复制一套全新模块，使用 new：

apifox import --project <projectId> --format apifox --file ./project.apifox.json --module-import-mode new

目标项目存在多个同名模块，或需要精确控制源模块去向时，使用 --module-map。它可以重复传，且优先级高于 --module-import-mode：

apifox import --project <projectId> --format apifox --file ./project.apifox.json \
  --module-map "商店 API=8049476" \
  --module-map "管理 API=8049482"

常用映射写法：

写法	用途
"源模块名=目标模块ID"	导入到指定已有模块
"source:源模块ID=目标模块ID"	源模块重名时用源模块 ID 精确指定
"源模块名=default"	导入到目标项目默认模块
"源模块名=new"	只让该源模块新建

只指定部分源模块也可以；未指定的源模块继续按 --module-import-mode 处理。目标模块建议使用模块 ID，避免目标项目同名模块歧义。

导入后必须验证：

• 模块数量是否符合预期，二次导入不应无意新增同名模块。
• API、Schema、测试用例、测试场景、WebSocket、Socket.IO 等资源数量是否符合导入结果。
• 单接口测试用例分类是否可见。
• 如导入测试套件，抽查套件里的场景和用例引用是否指向新项目资源。

Step 7B. Apifox 原生格式导出策略

全量备份或迁移：

apifox export --project <projectId> --format apifox --output ./project.apifox.json

只导出指定接口或目录，适合局部搬迁或最小复现：

apifox export --project <projectId> --format apifox --scope apis --api-ids 1001,1002 --output ./selected.apifox.json
apifox export --project <projectId> --format apifox --scope folders --folder-ids 2001 --output ./folder.apifox.json

按标签导出，适合按业务域交付：

apifox export --project <projectId> --format apifox --scope tags --include-tags pet,store --exclude-tags deprecated --output ./tagged.apifox.json

默认会包含接口调试和单接口用例；如果只需要接口定义，显式关闭：

apifox export --project <projectId> --format apifox --no-include-api-cases --output ./apis-only.apifox.json

导出后检查文件存在、大小合理，并在临时项目中做一次导入验证，尤其是发给他人或用于迁移前。

Step 8. 回读验证并汇报

• 回读接口列表，确认接口总数与导入结果一致。
• 抽查至少一个读接口和一个写接口；写接口要确认 requestBody、response、schema 引用正常。
• 如导入了数据模型，抽查 schema 能否正常回读。
• 如导入 Apifox 原生格式，额外确认模块策略、测试用例分类、测试场景和测试套件引用。
• 最终汇报必须包含文件路径、质量指标或导出范围、导入项目、导入计数、抽查结果和遗留风险。

不可违反规则

1. 不要先手写路由提取脚本，先查项目内生成器。
2. 不要把接口数量多等同于 spec 完整。
3. 不要跳过导入前质量指标。
4. 不要在已有项目上反复试错导入。
5. 不要忽略大量 ignoreCount。
6. 不要导入 tags 混乱、无法按业务导航的 spec 作为最终成果。
7. 不要把 schema 极少的大项目 spec 当成最终版本。

常见恢复

现象	处理
导入成功但只有路径	回查生成器是否只抽路由，继续找 DTO/handler schema
schemas 极少	结合 operations/writes/withBody/emptyObjectBodies 判断是否路由骨架
大量空 body	回查 request DTO 或项目生成器
Apifox 目录按 URL 分组	重写 operation tags 后重新导入到干净项目
大量 ignoreCount	判断是否污染已有项目，必要时新建干净项目验证
JSON.parse 失败	检查实际是否 YAML，不要信扩展名
原生格式二次导入后出现重复模块	检查是否使用默认 match-name，目标同名模块是否唯一；必要时用 --module-map
目标项目有多个同名模块	不要让 CLI 自动猜，使用 --module-map "源模块名=目标模块ID"