智慧芽：探索大型研发团队多项目的高效 API 研发协同管理之道
关于 智慧芽
智慧芽（Patsnap）成立于 2007 年 ，是一家知识产权和科技创新信息服务商，致力于为全球创新企业和创新生态人群提供服务。
通过机器学习、计算机视觉、自然语言处理（NLP）等人工智能技术，智慧芽为科技公司、高校和科研机构、金融机构等提供大数据情报服务，围绕科技创新与知识产权已构建起产品矩阵，旗下产品包括全球专利数据库、知识产权管理系统、研发情报库、新药情报库、生物序列数据库、化学结构数据库等。
凭借自身的技术能力和产品能力，截至 2023 年，智慧芽已经服务全球 50 多个国家超 12000 家客户，涵盖了高校和科研院所、生物医药、新材料、新能源、智能制造、新能源汽车、半导体等 50 多个高科技行业。
智慧芽致力于通过提供创新数据和工具，以开放合作构建创新生态，促进全球创新企业和科研人员之间更深入的合作，实现其“连接创新，突破边界”的愿景。
成功故事
过去，智慧芽商业洞察与生物医药工程团队并未对 API 进行统一的协同管理，各部门成员主要依靠自己的工具进行分散使用。工程团队常用 Swagger 进行接口定义，Postman 进行调试，JMeter 进行性能压测。尽管这些工具都可以调用接口，但由于侧重点不同，都无法充当合格的接口管理工具。同时，管理层进行接口管理和统计也会比较困难。
为解决这一问题，工程团队决定引入 API 管理软件，实现以下目标：
- API 文档遵循统一规范，版本控制清晰，便于查看；
- 集中管理所有 API，提高开发效率避免重复开发；
- 不同团队和成员之间协作更紧密，内容保持一致，接口信息对齐；
- 提高开发效率和测试覆盖率，减少生产问题；
- 优化团队协作，提升 API 开发质量。
通过引入专业的 API 管理平台，工程团队希望实现 API 的全生命周期管理，包括设计、开发、测试、发布和监控。这不仅可以提高 API 质量，也可以优化协作流程，降低沟通成本。
制定 API 研发流程，使得团队协作紧密配合
由于之前工程团队使用的接口工具较为分散，大部分接口没有统一的输出规范和集中管理。在开发中期前后端开始联调时，存在多人编辑和多次迭代，无法确定最终定稿的版本，需要花费大量人力进行二次对齐。最终在需求上线阶段，提供给测试的接口与需求不一致，可能导致测试覆盖不全，最终发布至线上产生问题，影响用户体验。
为解决这一问题，工程团队引入了一体化协作平台 Apifox，项目负责人当即制定出了一整套完备的 API 协作模式和流程，帮助团队从之前分散无序的状态，进入互相配合、高效协作的开发模式：
API 研发流程最佳实践
- 需求评审会：PO 以及 PM 需开展需求沟通讨论，确认总需求并制定详细的周迭代计划，以明确最小可行产品（MVP）需求
- 周迭代开发：后端工程师先开发好基础代码框架以及接口代码，包括入参出参
- 生成 API 文档：后端工程师通过插件扫描项目工程文件，将 API 导入到 Apifox 中生成在线文档
- API Mock：前端工程师使用 Apifox 的智能 Mock 引擎进行页面开发
- API 调试：后端工程师完成业务代码的开发后，进入接口调试验证阶段
- 构建接口用例：后端工程师将接口调试结果保存成接口用例，便于后续项目迭代过程中接口的快速调试及接口质量把控
- 构建业务场景：测试工程师根据实际业务场景，将接口用例串联起来，调整参数及前后置操作，并编排接口步骤，形成完整测试场景。
- 搭建持续集成平台：通过 Apifox 一键生成 CI 命令，构造 CI 平台配置文件，搭建测试管理平台和 CI 平台，再通过 Webhook 功能对接 IM 平台，形成持续集成体系
- 最小 MVP 需求上线：首周需求上线后，重新返回步骤 2，进入第双周迭代，快速确认双周迭代计划并开发基础代码框架。
在实践上述流程后，团队各角色得以在接口整个生命周期中发挥作用，将风险控制到最低：
- 后端工程师在接口设计阶段定义新增 API 的信息，如端点、参数、认证等；
- 前端工程师在接口调试阶段参与 API 联调；
- 测试工程师针对接口进行用例设计及验证。
这样，接口的每个阶段都有对应的工程师进行全程参与和质量控制，可以最大程度降低项目风险。
API 双研发模式灵活应用，快速高效完成项目落地
在 API 研发管理方面，工程团队通常会根据不同场景采用不同的开发模式：
- 如果快速响应的需求或简单接口，且后端任务优先开发，多数采用「Code First」模式；
- 如果是大型且较为复杂的项目需求，有大量 API 和数据模型需要定义，往往会采用「API First」模式。
这两种开发模式也会采用不同的工具：
- 「Code First」模式会使用 Swagger 或提供 API Curl 脚本；
- 「API First」模式会提前将 API 定义撰写到 Confluence 文档中。
如何选择这两种开发模式取决于具体的项目和团队需求。
- 「Code First」模式适合需要快速产出原型或功能的场景，以及采用敏捷方法的团队，可以快速响应变化需求；
- 「API First」模式通过前期定义可以使接口规范化，确保接口设计的合理性，使开发过程更透明，减少后期修改，提升协作效率。尤其适合团队协作场景，可以统一接口标准，让团队更高效协作。
Code First
- 优势：最大优势在于编码快速，可以在需求确认后立即进行开发，快速产出结果。跳过了接口预先定义这个步骤，使得开发人员可以更高效地完成简单或独立接口的开发，以更敏捷地满足需求。
- 适用场景：适合需要快速响应的简单需求，或者单一接口开发的场景。
- 流程图：
API First
- 优势：前期进行了充分的文档以及数据模型的设计，减少了后期前后端产生误解时的沟通成本，也使得接口规范和标准统一，对后续的开发和维护都会有很大的帮助。API First 模式通过前期定义，可以避免开发过程中的歧义和偏差，规范的接口也有利于项目的持续优化。
- 适用场景：更适合大型复杂项目，或者需要长期迭代和维护的项目。
- 流程图：
构建 API 测试的全自动化业务平台，降本增效
随着产品不断迭代更新，工程团队需要采用自动化测试来降本增效，于是决定引入一款新的自动化工具，需要满足：
- 能与智慧芽当前质量管理平台能快速集成，实现用例联动、结果回填、报告生成；
- 由于产品迭代快、业务广泛、数据类型复杂，需要快速编写大量测试脚本以保证发布质量；
- 存在使用同一个脚本去验证不同环境的情况，需要依靠数据隔离与管理功能来更好地解决多环境的执行问题。
Apifox 的自动化测试模块满足以上所有需求，具有脚本编写便捷、数据管理完善、集成自由度高的特点。当工程团队引入 Apifox 后，测试人员可以快速完成脚本编写，形成一套流程规范；而团队基于协作形成的资产积累，可以减少重复工作，高效提升团队的测试能力与质量管理水平。新人也可以快速了解工作方法，节省培训成本。
客户心声
“作为一款开源的接口管理工具，Apifox 在客户服务方面体现出了非常高的关注和重视，在使用 Apifox 当天就将团队核心人员拉到一个微信群，合作的一年内，无论什么时间发送使用过程中的任何大大小小的问题或者建议到群里，都非常快速的进行了专业的响应。在偶尔的沟通会中，都能感受到 Apifox 的真诚和热情。记得有一次因为脚本语法问题，导致通过 Apifox run 的方式无法执行，群里立马出现了三位开发联系我，不仅为我解决了问题还非常耐心的给我讲解错误的原因，让我学到了很多。
在产品功能上，Apifox 也有独特优势。开发可以实时分享已完成的 API 设计，减少重复工作。测试可以只校验关键参数，利用“响应校验”校验非关键数据，提高代码覆盖率。此外，Apifox 在参数生成、报告展示等方面也有特色设计。
虽然许多功能尚待发掘，但至今的协作经历令我对 Apifox 团队的专业能力和真诚服务留下深刻印象。他们不遗余力地倾听用户，以开源精神优化产品。我期待继续深入使用 Apifox，也衷心推荐更多团队使用这一出色的接口管理平台！
——智慧芽研发团队”
