版本与迁移
ApiGo 用两个不同层次的「版本」描述接口演进：
| 概念 | 字段 | 粒度 | 用途 |
|---|---|---|---|
| 接口版本 | version / sourceVersion | 接口定义 | 业务版本号，如 v1、v2 |
| 发布修订 | deployRevision | 每次发布 | 同一版本每次发布的递增编号，用于回滚 |
接口版本升级会产生一份新的接口源；发布修订只是同一接口源的一次快照。两者不要混用。
版本管理
查看版本
在「接口列表 → 已发布」中点击「版本管理」列的版本号，打开版本管理弹窗。
dev 环境展示版本族中的全部接口源：
| 列 | 说明 |
|---|---|
| 接口 ID | 接口源 ID |
| 接口名称 | 点击打开接口详情 |
| 认证类型 | 无认证 / 简单认证 / 签名认证 |
| 接口状态 | 草稿 / 已上线 / 已下线 |
| 版本号 | 接口版本 |
| 修订号 | 当前发布修订 |
| 发布时间 | 最近发布/快照时间 |
| 操作 | 编辑、版本升级、同步环境、上下线、删除 |
非 dev 环境展示该接口在该环境的全部发布快照，操作包括上下线与删除。
版本升级
版本升级用于并行维护多个业务版本（如 v1 稳定版、v2 新版）：
- 在 dev 版本列表中点击「版本升级」；
- 工作台以升级模式打开当前接口；
- 修改接口内容，并把「版本号」改为新版本号；
- 保存后生成一个新的接口源，状态为草稿、未上线；
- 对新版本执行发布，再按需同步到其他环境。
升级规则：
- 版本号必须为正整数；
- 同一版本族内版本号不能重复，否则提示「该接口版本已存在，请更换升级的版本号」；
- 新版本的接口地址与请求方式不能与其他版本冲突（平台按路径 + 方法校验）；
- 新版本与原版本共享版本族关联（
apiLinkId），但各自拥有独立的发布快照与上下线状态； - 原版本不会被替换或下线，可继续使用。
只修改接口内容、不改变业务版本时，直接保存并重新发布即可；需要同时保留旧版本对外服务时，才使用版本升级。
删除版本
| 环境 | 删除行为 |
|---|---|
| dev | 删除接口源及其关联数据；若仍有上线快照则不允许 |
| 非 dev | 删除该接口在该环境的全部发布快照，不影响其他环境 |
批量删除接口时，只要任一环境存在上线快照，整批操作都会被拒绝。
修订与回滚
修订号如何产生
每次发布生成 dev 快照时，修订号在同一版本族内递增。同步到目标环境时沿用 dev 的修订号，因此同一修订在不同环境可对应不同快照 ID，但修订号一致，便于对账。
回滚
回滚只适用于非 dev 环境：
- 在目标环境行点击「历史版本」；
- 选择一条非当前快照；
- 点击「回滚」并确认；
- 系统把该快照设为当前生效，其他快照标记为非当前，并刷新运行态。
回滚要求数据源仍可访问；dev 环境不支持回滚，需要重新发布。
删除快照
删除非 dev 版本会删除该接口在该环境的全部快照，包括历史修订。该操作不可恢复，且不会影响 dev 或其他环境。
迁移包
迁移包（.apigo.json）用于在项目、环境或部署实例之间搬运接口定义，适合从测试环境复制到另一个项目、交付私有化部署、备份接口配置。
导出
入口：接口列表 → 已发布 → 批量导出。
- 选择来源环境与关键字，勾选要导出的接口（基于该环境的当前生效快照）；
- 选择要包含的数据项；
- 点击导出，浏览器下载迁移包。
| 选项 | 默认 | 说明 |
|---|---|---|
| 接口信息 | 必选 | 接口定义、参数、代理/编排配置、插件配置 |
| 数据源 | 是 | 数据源连接配置（密码、SecretKey 导出为空） |
| 分组与分类 | 是 | 分组树与分类定义 |
| 测试用例 | 否 | 接口的 dev 测试用例 |
限制与说明：
- 单次最多导出 100 个接口；
- 只导出所选环境的当前生效快照；
- 文件名格式：
apigo-migration-{项目ID}-{yyyyMMddHHmm}.apigo.json； - 迁移包为 ApiGo 自有格式，内部包含 OpenAPI 3.0.3 文档；
- 导出路径已去掉项目前缀与环境前缀，导入后会重新拼接；
- 数据源密码与 SecretKey 不会写入迁移包，导入时需重新填写或映射。
导入
入口：接口列表 → 已发布 → 导入接口。流程分为「上传 → 预览 → 导入」三步。
1. 上传
支持上传或粘贴 .apigo.json / .json 内容。平台校验：
- 内容必须是 JSON；
- Bundle 版本必须为 1.x；
- 内部 OpenAPI 文档必须为 3.x。
2. 预览
预览展示接口总数、新增数、覆盖数、跳过数，以及数据源、测试用例数量。每条接口可单独调整：
| 项 | 说明 |
|---|---|
| 接口名称 | 可改名 |
| 接口地址 | 可改路径 |
| 处理方式 | 新增 / 覆盖 / 跳过；已存在的接口不能选新增 |
| 目标分组 | 选择现有分组；留空时自动创建同名分组 |
数据源处理：
- 新建数据源：按迁移包中的定义创建，需要填写密码（前端 SM2 加密后传输）；
- 映射到已有数据源：从当前项目的数据源列表中选择；
- 迁移包不含数据源时，必须选择一个默认数据源。
3. 导入
选择目标环境后提交。目标环境要求：
- 环境存在且已启用；
- 不能是生产环境（
isProd = 1），生产导入会被拒绝； - 支持导入到 dev，导入后的接口为「已发布、未上线」状态，需要手动上线。
导入规则：
- 单次最多导入 100 个接口；
- 重复判断按「接口地址 + 请求方法」；
- 覆盖会更新已有接口定义，但不会删除目标环境中不在迁移包内的接口；
- 分组按目标分组 → 分组映射 → 同名查找 → 自动创建 → 默认分组的顺序解析；
- 接口路径重新拼接项目前缀与环境前缀；
- 修订号取当前最大修订 +1；
- 数据源按名称映 射或默认数据源回退；
- 任一条写入失败会整体回滚，不会留下部分导入的数据。
迁移导入禁止直接写入生产环境。正确做法是导入到 dev 或预发环境，验证后再通过「同步环境」发布到生产。
常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 版本升级保存失败 | 版本号重复，或路径/方法与已有版本冲突 | 更换版本号或接口地址 |
| 升级后旧版本消失 | 误用了普通保存而非版本升级 | 版本升级会新增接口源，不覆盖旧版本；检查是否在旧版本上直接编辑 |
| 回滚按钮灰色 | 选中的是当前快照，或当前为 dev | 选择历史修订；dev 请重新发布 |
| 导出提示超过 100 个 | 单次选择过多 | 分批导出 |
| 导入提示生产环境 | 目标环境标记为生产 | 改选非生产环境 |
| 导入后接口不可调用 | 接口为已发布但未上线 | 在目标环境执行上线 |
| 导入后数据源报错 | 密码/SecretKey 未填写或映射错误 | 编辑接口重新选择数据源，或重新导入并完成映射 |
| 导入部分失败 | 任一条失败会整体回滚 | 按返回的错误定位并修正后重试 |