API 的多分支管理，APIfox强大迭代分支管理

在产品迭代的过程中，对 API 的更新和维护是必然的，也是至关重要的。当产品需要引入新功能或对现有功能进行调整时，相应的 API 往往也需要进行升级或修改，这种情况在快速迭代的产品中很是常见。

然而，API 的迭代更新并非易事，在随着产品进行升级或修改的过程中，在管理 API 时往往会面临一些问题：

• 如何在保证现有接口稳定性的同时，有效地进行 API 迭代和测试？

• 如何在多个并行开发的迭代中管理 API，确保各迭代不会相互干扰？

针对这些场景，Apifox 推出了「迭代分支」功能。这个功能提供了一种灵活的方式来管理 API，它允许你在独立的分支上进行 API 的迭代升级和新功能开发，而不会影响主分支中线上接口的稳定性。

迭代分支功能支持版本控制、并行协作和快速合并，每个分支都是独立的版本，互不干扰，并且可以快速将分支中的更改合并回主分支。

Apifox 中的分支工作流

理解迭代分支的使用场景

「迭代分支」功能允许你在项目中创建多个开发分支，以便在不同阶段进行 API 的升级、迭代和测试，而不会影响到主分支（即当前稳定版本）。

何时考虑使用迭代分支？

什么情况下应该使用迭代分支呢？以下几种情况很适合：

• 功能开发与测试：在新的迭代分支上开发和测试新功能，而不影响主分支上的稳定版本。

• 升级与 Bug 修复：在专门的分支上升级、更新接口或者修复 Bug，测试通过后合并到主分支。

• 实验和验证：对 API 进行实验性修改，验证其效果后再决定是否合并到主分支。

何时考虑不使用迭代分支？

如果只是进行小规模的接口更新，或者修复一个简单的错误，直接在主分支上操作可能更方便快捷。

如果你的业务需要提供多个版本的 API 供外部用户进行调用，为了确保外部用户使用的稳定性和一致性，更推荐使用最新的「接口版本」功能，这会更契合你的业务需求。

下面就来简要介绍一下「迭代分支」功能的使用，如果要更详细的使用方法可以参考帮助文档的迭代分支模块，在开始之前，请确保将 Apifox 更新到了最新版。

下载 Apifox 最新版

创建迭代分支

当你的项目角色为「管理员」或「编辑者」时，可以在目录树顶端右上角的「迭代分支」组件中，点击「创建迭代分支」选项，建立一个新的迭代分支以开启迭代相关工作。

在迭代分支中设计 API

Apifox 的迭代分支功能仅覆盖迭代中修改、新增部分的内容。因此，新的迭代分支中内容为空，要自己选择需要修改和新增的内容放入迭代分支中。

导入的资源会跟主分支有明显的关联标识，包括接口、接口用例、数据模型等。如果是在迭代分支内新创建的资源，则无关联标识。

在设计 API 的过程中，你也可以对某个与主分支有关联关系的迭代分支资源上，进行单个资源的对比，查看这个资源与主分支的具体差异。

在迭代分支中测试 API

「自动化测试」功能也支持在迭代分支中进行操作，你可以新建「测试场景」，或者从主分支导入已有的「测试场景」。

导入的测试场景，在目录树中，你可以看到这些导入资源与主分支中的资源有明显的关联标识，类似于「接口管理」中的资源标识。

在迭代分支中，可以像在主分支中一样编排测试场景。由于测试场景可能涉及到迭代分支和主分支中的接口，系统会用「分支图标」来区分这些测试步骤使用的是迭代分支还是主分支中的资源。

当你点击查看这些步骤的详细信息时，也能看到它们关联的资源属于哪个分支。

当分支中相关的接口、测试场景被设计、编排好以后，就可以对其进行测试。

对于自动化测试，在测试时会根据步骤中标识的资源来源来使用相应的数据。如果测试步骤标识为使用迭代分支的资源，那么测试将使用迭代分支中的数据；如果标识使用主分支的资源，测试将使用主分支中的数据。

合并迭代分支

在迭代分支中完成 API 开发并成功上线后，可以将这些变更合并到主分支中，合并的内容可以是部分或全部接口的更改。

合并入口位于目录树右上角「分支组件的下拉菜单」中，也可以在接口管理的目录树下方看到「合并到主分支」按钮。

在接口管理中，点击「合并」按钮会打开合并总览的弹窗。你可以在弹窗中查看当前迭代分支与主分支之间的修改资源或所有资源，并且可以选择合并后如何调整资源在主分支中的状态（比如开发中、测试中、已发布等状态）。

点击目录树上的资源，可以展开查看其详细内容，帮助决定是否合并，不同类型的资源会有不同的合并逻辑。

合并完成后，会弹出提示，显示实际改动的主分支资源。

在主分支中查看、撤销合并

在主分支的「接口管理」中，通过查看资源的历史记录，可以看到最近合并操作带来的变更，并且可以看到是从哪个分支合并而来的。

你可以查看具体的修改内容，并与其他版本进行比较，该历史记录功能方便你追踪变更历史，并在需要时进行内容回滚。

归档、恢复、删除分支

分支合并后，你可以通过「项目设置 -> 迭代分支」进入迭代分支的管理页面。在管理页面中，你可以查看项目中所有的迭代分支列表及其统计数据，还可以对这些分支进行各种操作，包括迭代分支的归档、恢复与删除。

分支操作的消息通知

迭代分支的操作发生变更时可以触发消息通知，其结果可以发送给第三方应用，比如飞书、钉钉、企业微信等。

具体需要你在 Apifox 的【项目设置 -> 通知设置 -> 外部通知】中配置通知事件，可参考这篇文章：《Apifox 中如何将「消息通知」集成到第三方应用（钉钉、飞书等）》

 常见问题

所有类型的接口都支持迭代分支功能吗？

目前只支持 HTTP 接口。

谁可以创建一个迭代分支？

项目管理员和项目编辑者。

谁可以访问迭代分支？

项目管理员、编辑者和只读成员。

谁可以合并迭代分支中的更改？

项目管理员和项目编辑者。

迭代分支可以合并到迭代分支吗？

目前仅支持合并到主分支，将会在后续版本中支持合并到迭代分支。

在迭代分支中工作时，如果主分支中的接口也发生变更，合并后会发生什么情况？

合并后，迭代分支的更改会覆盖主分支中相同接口的变更。这意味着在主分支中对该接口的增加、删除或修改操作都会被迭代分支的内容所替代。

迭代分支后面会加一个「从主分支拉取更新内容」的功能，你可以将主分支中的最新更改拉取到迭代分支中，敬请期待！

如果在迭代分支中删除了某些资源，合并到主分支时会对主分支产生什么影响？

如果删除的是整个接口、数据模型等资源，这意味着该接口、数据模型等资源与主分支不再建立关联，因此合并时主分支的对应接口、数据模型等资源不会受到影响，相当于没有改动。这是因为迭代分支的一个基本原则是仅涉及修改和新增资源，删除操作需直接在主分支中进行，迭代分支不处理删除操作。

如果迭代分支中的接口、数据模型等资源与主分支有关联，当你删除了其中的某些资源（如参数、说明等）时，合并后主分支中对应的资源也会被删除，这个操作相当于修改了迭代分支中的资源。

如果在迭代分支中新建了一个与主分支接口 URL 和参数完全相同的接口，合并后会发生什么？

在迭代分支中新建的接口与主分支中的接口 URL 和参数完全相同，但它们默认没有关联。合并后，主分支将新增这条与迭代分支完全相同的接口，即使主分支中已存在相同 URL 和参数的接口。

因此，如果你要对现有接口进行升级、测试或修改，请从主分支导入该接口，以确保它们建立关联。这样，如果接口发生更改，合并后主分支中的接口也会同步更新。

可以回溯和复原回之前迭代的分支内容吗？

可以。

如果你因为某些原因需要查看之前迭代的内容，可以将其从归档状态恢复成正常分支状态（注意迭代分支限额），恢复后即可在接口管理的目录树中重新访问这个分支。归档前分支内的数据会自动保留不变。如果你希望恢复分支历史内容，可以直接使用该分支再次合并到主分支完成还原。 

单个资源建议在「接口管理」中直接使用「历史记录」功能来进行回溯和复原。

可以分享迭代分支的接口文档给其他人吗？

如果需要内部协同分享，可以通过「复制协作链接」给已加入项目的成员。目前暂不支持将接口文档对外分享，后续版本会支持。