如何通过「迭代分支」提高 API 开发的升级效率

浅浅的花香味﹌ 2024-02-05 19:07 53阅读 0赞

在软件快速迭代的今天，“敏捷开发”已经成为大多数软件公司的首选。通过小步快跑的方式快速更新产品，持续高效升级，提升用户体验，从而保证产品的竞争力和价值。

在使用敏捷方式进行产品迭代的过程中，必然会碰到以下场景：

1.  本次迭代需要对原有生产环境的 **[API][]** 进行升级；
2.  本次迭代需求的新功能需要引入新的 API。

针对于这类场景，**Apifox 推出了「迭代分支」功能**，提供了灵活可控的 API 迭代协作机制，既保证了主分支稳定性，又提升了团队工作效率。非常适合敏捷开发的团队，主要优势有：

*  **主分支稳定**：开发者基于已存在的 API 开发新版本，但不破坏原有的 API 定义与调用参数。每个迭代分支包含独立的**接口、数据模型、响应组件**等数据，数据互不影响，保证各分支数据的稳定性和独立性。
 *  **协作并行**：不同团队角色可在不同分支上同时工作，互不干扰，提升协作效率。
 *  **快速合并**：新分支开发完成后，可轻松快速地对比两个分支之间的内容差异，并将迭代分支的内容合并回主分支。

### **创建与管理迭代分支** ###

当你的 **项目角色为「管理员」** 时，你可以在「项目设置 - 项目资源 - 管理迭代分支」内创建和管理迭代分支。每条迭代分支都拥有独立的名称、创建时间、创建者信息及资源统计数据。

系统默认内置主分支（main），所有生产环境的 **[API 文档][API 1]** 都要处于这个主分支内。

对已上线且相关数据资源都已并入主分支的迭代分支，你可以 **执行「归档」** 操作将其收起，释放分支席位。当前，一个项目中暂时仅支持含有一个未归档的迭代分支。

![图片][75d044fb7a82a762899519b8c207952e.png]

### **在子分支上维护 API 文档** ###

在创建未被归档的迭代分支后，你可以点击接口管理的右上角的分支按钮组件，对迭代分支进行切换。**切换到分支时，目录树的 UI 背景为淡蓝色渐变**，与主分支的纯白背景有明显区别。

![图片][198f9e254f159226cea16b6f0a839df0.png]

新建的迭代分支中默认不包含任何内容。这里的最佳实践是：

1.  对需要升级调整的接口，从主分支创建副本到此迭代分支中；
2.  对需要新增的接口，直接在此迭代分支中添加。

*需要注意的是，在子分支创建副本时，尽量不要将本次迭代中无需改动的接口导入其中，这会导致数据冗余，降低功能可用性。这里与 Git 的 Fork 概念有区别，研发同学需要区分和理解。*

![图片][36f3062b72d251aab490998a79714e6b.png]

**从主分支拉取的副本会在目录树右侧显示关联图标**，代表该资源是现有的线上资源，需要进行升级。在迭代分支内编辑资源不会影响到主分支及其他分支的资源内容。

![图片][babc7ba3a7c8f239ab81405fd5a8c62c.png]

在子分支中完成 API 定义后，团队成员就需要根据子分支的内容进行研发协同了。前端 **[Mock][]** 数据来写页面，后端生成服务端代码写接口，测试根据文档写用例。

### **合并至主分支** ###

当实际的研发测试工作已完成，本次迭代的代码也已经发布到线上之后，我们需要回到 Apifox 对应的迭代分支中，对 API 文档、数据模型、响应组件等资源执行「合并至主分支」操作。

合并入口位于**目录树右上角分支组件的下拉菜单**中，也可以在**切换至具体子分支后，在目录最底部找到**。只有**项目管理员**才有权限执行整分支合并的操作。

![图片][ed9f9f1a4fe7ce528f25bf3cdec84919.png]

选择合并后，系统会根据资源具体变更情况及主分支关联关系，自动推荐最合适的处理方式。处理方式有三种：

*  **覆盖**：当子分支资源是主分支的关联副本时，默认选择「覆盖」方式，将会用子分支内容完全替换主分支的对应资源。常用于已有接口的升级场景；
 *  **新增**：当此子分支资源是新增的资源，与主分支没有对应关联时，默认选择「新增」方式将该资源在主分支中新增。常用于迭代开发的新功能新接口的场景；
 *  **不合并**：此子分支资源在合并后不对主分支资源做任何操作。常用于此资源没有实际发生变动，或实际上线代码内容与资源内容不匹配不可直接合并至主分支，需要后续调整的场景。

![图片][37cbc4d55215c008584cef8353857226.png]

合并分之前，你可以通过「对比」功能，**以 YAML 形式查看当前分支与主分支资源间的细节差异对比**。

![图片][0f9eafcae6544241c536ffacaa68a6a7.png]

其中**数据模型支持可视化** **对比**。

![图片][fe019f36b2e6a27add9e7d598a6f24cc.png]

当然，也可以根据实际情况**针对单资源进行合并、对比**，只需选中子分支资源后右键即可执行这些操作。

![图片][ddff596e2aa1330bed4cfe51e10ec057.png]

合并完成后，就可以在主分支中查看合并后的资源了。建议在完成合并之后，把已完成的迭代分支归档。

### **常见疑问** ###

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

A ：目前只支持 **[HTTP][] 接口**使用迭代分支功能。

Q ：**可以创建多个迭代分支吗？**

A ：公网版当前**每个项目仅可含一个未归档的迭代分支**，如果你有需要创建多个迭代分支的需求，可以联系客服使用企业版/私有化版本。

Q ：**子分支内的接口如何做[自动化测试][Link 1]？**

A ：目前迭代分支**暂不支持接口用例和自动化测试的相关功能**。但此功能已在开发计划中，会尽快上线与大家见面，同时，我们也会继续提升迭代分支的能力，真正实现从需求到测试的全链路闭环协作。

Q ：**可以只通过迭代分支修改主分支资源吗？我不想让我的项目成员随便修改主分支上的接口。**

A ：暂不支持，此需求已在规划中。当前的整分支合并需要管理员权限，我们也在研究是否增加一个合并审核流程来做到更好的合并控制。

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

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

Q ：**可以通过迭代分支功能管理多个线上版本的接口吗？**

A ：不建议这样使用。虽然迭代分支功能也有版本管理的概念在里面（研发中版本的接口、线上生产版本的接口），但主要还是针对「软件迭代」场景设计。后续会有其它功能来支持和满足接口多线上版本的管理这类场景的需求。

Q ：**可以分享子分支的接口文档给其他人吗？**

A ：你**可以分享接口、数据模型、响应组件的协作链接给已加入项目的伙伴**。普通的接口文档在线分享暂不支持分享子分支上的接口文档，后续会增加此功能。

Q ：**可以导入/导出子分支的数据吗？**

A ：目前只支持**主分支的导入导出**。子分支的相关功能后续会支持。

Q ：**迭代分支中的目录与主分支中的目录，是什么关系？**

A ：子分支是跟主分支**共用的一套**。子分支的资源（副本、新增）会显示主分支上级目录。子分支上不可对主分支的目录设置进行修改，仅支持修改目录名；在子分支上创建新的目录（UI 显示为渐变蓝色）可以在子分支中进行修改。

[API]: https://apifox.com/apiskills/understanding-apis/
[API 1]: https://apifox.com/apiskills/api-and-api-documentation/
[75d044fb7a82a762899519b8c207952e.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/f1a65fa851964437b65fb15beb75eba2.png
[198f9e254f159226cea16b6f0a839df0.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/aae7a369df6344df80b37b94f741887d.png
[36f3062b72d251aab490998a79714e6b.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/c6fa197712c14d92a97eb834de9aa063.png
[babc7ba3a7c8f239ab81405fd5a8c62c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/ea6b519fbd61488b960dda95a6953f5e.png
[Mock]: https://apifox.com/apiskills/mock-done/
[ed9f9f1a4fe7ce528f25bf3cdec84919.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/35fb879b9b894916aefe707675ace377.png
[37cbc4d55215c008584cef8353857226.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/003ebcabb84a413b8c98e07f71713fe4.png
[0f9eafcae6544241c536ffacaa68a6a7.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/7905c38867014cb9ac7952ff7d28c71f.png
[fe019f36b2e6a27add9e7d598a6f24cc.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/ca89a69b27174c77b8d98c88b9d0c8e1.png
[ddff596e2aa1330bed4cfe51e10ec057.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/1ce751bb0a954fd1b4e6c2db684c8bc9.png
[HTTP]: https://apifox.com/apiskills/the-5-pillars-of-every-http-request/
[Link 1]: https://apifox.com/apiskills/what-is-automation-testing/