apifox-workflow-api-lifecycle

# API 生命周期工作流 > 开始前必须读取 `../apifox-cli/SKILL.md`。若旧总入口与本 workflow 的领域规则冲突，以当前 CLI help 和本 workflow 为准。按步骤再读取 `apifox-branch`、`apifox-import-export`、`apifox-test-case`；涉及复杂测试流程时读取 `apifox-test-scenario`，涉及执行和 CI 时读取 `apifox-test-automation`。 具体 endpoint、schema、environment、test-report 命令以当前 CLI help 为准。本流程用于从需求到 API 资产、测试、报告和分支合并的端到端交付，重点关注资源顺序、质量门禁和交付验证。Agent 执行时优先形成 `help/schema -> get -> validate -> write -> run/report` 闭环，不要仅凭旧文档或记忆写入。 ## 适用场景 - 根据需求创建或更新一组接口。 - 导入 OpenAPI/Postman 后整理接口、Schema、目录和测试。 - 从代码库、PRD、需求文档、测试文档或讨论内容生成 API spec 后导入 Apifox。 - 给接口补 Mock、测试用例、文档和发布设置。 - 在 AI 分支完成 API 变更并准备合并。 ## 工作流 ```text 确认项目/分支 -> 如需从代码/文档导入，先做 spec 生成和质量门禁 -> 设计接口和 Schema -> 配置环境和变量 -> 配置 Mock -> 创建接口测试用例 -> 运行测试并查看报告 -> 导出/发布文档 -> 合并或创建 MR ``` ## Step 1：确认上下文 按当前 CLI help 确认身份、项目、目标分支和是否需要 AI 分支。 - 用户要直接改主分支/迭代分支时，确认 AI 写入权限或走 AI 分支。 - 如果通过 AI 分支改已有资源，先用 `branch pick-to` 导入源资源。 ## Step 2：设计 API 资源 按当前 CLI help 使用 endpoint、schema、response-component、security-scheme、folder 等 API 设计资源命令。 最小边界：endpoint 是接口定义，test-case 是接口下测试用例，不要混写；schema、response-component、security-scheme 等可复用资源应先创建，再由 endpoint 引用；环境变量不要写进 common-parameter。 如果任务是从代码库、PRD 或文档生成并导入 API spec，先读取 `../apifox-import-export/SKILL.md`，完成生成器搜索、OpenAPI 指标校验、tags 分组和临时项目导入验证，再进入接口设计或测试补充。 - 先建 `schema`、`response-component`、`security-scheme` 等可复用资源，再引用到 endpoint。 - 创建后必须 `endpoint get` 验证真实保存结构。 ## Step 3：配置环境 按当前 CLI help 使用 environment、variables、database-connection、vault 等环境和运行上下文命令。 - 没有合适环境时创建或更新环境。 - 敏感变量不要出现在最终回复中。 - 运行测试和 CI 交付命令建议显式带 `--environment`，避免默认环境变化导致不可复现。 ## Step 4：补测试用例 读取 `../apifox-test-case/SKILL.md`。 - 不要创建空壳 case。 - 创建后 `test-case get` 验证步骤、断言、提取器被保存。 ## Step 5：验证和交付 - 测试报告异常先区分本地报告、云端上传和下载概要；必要时转 `apifox-cli-checkup`。 - 前端展示异常转 `apifox-cli-checkup`。 - 需要合并时转 `apifox-branch`。 - 如果新建 API 的测试运行返回 404 或断言失败，先检查 Mock/环境是否配置，不要直接判定 endpoint 或 test-case 创建失败。Mock 未配置导致运行失败是执行环境问题，不等于设计资产未保存。 ## 不可违反规则 1. 不要跳过 project/branch 确认。 2. 不要直接在受保护主分支写入。 3. 不要只创建接口不验证保存结构。 4. 不要只创建空测试用例。 5. 不要把测试失败当作接口创建失败；分别定位 API 定义、环境、测试用例和执行报告。