1.现状API文档作为公司研发的重要数据资产，承载着公司的核心业务逻辑。随着数字化的发展，API研发管理成为公司研发最重要的一环，德物目前有两个与接口文档相关的平台：文档管理平台-YApi基于开源的YApi平台，提供基础的API管理能力.数据Mock平台-MooncakeMooncake平台为前端和客户端提供零侵入、场景化的Mock服务。2.面临的问题据业内报道，开发团队约50%的工作时间是围绕API展开的。目前，在得物的研发过程中，围绕API文档的协同工作分散在不同的工具或平台上，导致现有API在研发协同中的流动效率低下。API文档资源利用率低YApi作为现有的文档管理平台，由于控制过度、交互复杂、分类混乱，现有文档的利用率非常低。据统计，大部分使用场景是上传文档、确认文档等，API文档的质量无法保证。由于YApi文档管理平台缺少文档的最终测试环节，导致后期接口变更时接口无法及时同步到文档平台，最终无法保证文档的统一性和质量。API研发流程分为接口的整个研发生命周期（设计-开发/Mock-联调-验收），涉及服务端、前端/客户端、测试多个角色，跨越YApi、Mooncake等多个角色和测试平台。平台。3.商业思维优质的API可以进一步提升团队的研发效率，从而达到降本增效的效果。在此背景下，解决团队间API的内部传递，解决前后端基于文档的工作对接，提高文档的研发利用率和文档质量成为平台升级的核心问题。因此，文档和测试就成为了核心环节。基于这样的思考，我们提出两个核心点，文档驱动和测试驱动，最终驱动整个研发流程的运行。文档驱动：服务端完成接口文档和测试用例，前端和客户端可以通过接口文档了解接口定义以及如何与接口进行交互，各职能团队独立完成需求研发参考API文档。测试驱动：在每次迭代中，交付的接口文档都通过测试，确保文档的质量。对于未通过测试的文档，需要不断改进，最终保证文档的交付。基于文档驱动和测试驱动，我们提出了DTDD（Document&TestDrivenDevelopment）研发模型。通过对DTDD模型的探索，打通了整个研发流程，实现了研发流程的闭环。在DTDD模式下，平台要做的事情非常明确：沉淀API数据资产：沉淀具有业务价值分类的API接口文档资产，产生规模化的商业价值。测试驱动开发：为自动化测试平台同步API的测试用例，提高API交付质量。实现数据mocking：基于API的数据mocking，提高前端和客户端的研发效率。丰富的文档能力：围绕API使用场景，提供文档类型转换和接口调试能力。降低沟通成本：基于消息通知机制，降低沟通噪音和信息复杂度，提升产品平台价值。4.解决方案明确了DTDD研发模式的目标之后，接下来就是如何去做。通过对业界主流API文档管理方案的研究，结合得物目前已有的平台YApi和Mooncake，我们最终决定对这两个平台同时进行功能升级。平台架构如下图所示：月饼平台的研发不是一蹴而就的。下面从数据分类管理、文档利用率提升、界面交付质量提升、用户沟通成本降低、平台使用难度降低五个方面谈谈月饼研发过程中的一些思考。4.1数据分类治理Classification/grouping从本质上讲，找到事物的共同点和不同点是我们认识和认识世界的基本方法和能力。合理的分类/分组可以帮助我们更好地理解事物的共同点，帮助我们判断、推理，最终形成概念来做决定。YApi原有的项目分组和文档分类比较混乱。API文档作为业务资产，无法帮助研发很好地理解业务，无法提升效率。为了更好的辅助促进业务研发的迭代效率，我们取消了原有的Project分组和文档分类，如何进行合理的项目分组和文档分类成为了一个问题。项目分组：一开始我们想到按照公司组织架构对现有项目文档进行分组，但由于组织架构调整频繁，通过调研发现与项目密切相关的RDC业务领域相对稳定，最终我们将项目文档分组与业务领域相关联，现有的项目文档按照业务领域进行划分。我们获取项目最新上传的十个接口，获取接口的维护人员，查询维护人员的业务领域，通过计算不同的业务领域。例子：记录人为A，下面得到的业务线为{[a,80],[b,60],[c,10],[d,5]}记录人为B，下面得到的业务线is{[a,60],[b,30],[e,10]}//业务线aweight_a=(80+60)/2=70//业务线bweight_b=(60+30)/2=45//业务线cweight_c=(10+0)/2=5//业务线dweight_d=(5+0)/2=2.5//业务线eweight_e=(10+0)/2=5weight_a>weight_b>weight_c=weight_e>weight_d，通过对项目数据的清洗，对YApi原有项目进行业务域划分，也达到了以下目的：通过对项目的业务域进行分组，可以更清晰的获取项目的相关业务属性.默认情况下，用户属于业务域，降低了用户获取信息的成本。接口分类：YApi平台接口分类管理能力较弱。随着文档和分类的增多，文档的可维护性逐渐变差，文档与业务的关系逐渐弱化。例如，在一个大型项目中，有数千个接口和数百个目录，文档的分类管理失去了原有的能力。初始界面分类管理方案：a．手动创建分类并维护分类映射关系，插件仍沿用原有的上传逻辑。缺点：需要经常维护类之间的关系，后期维护成本高。b.使用贝叶斯算法根据服务、接口名称和接口路径构建分类关系。缺点：分类效果不明确，需要时常筛选维护分类不准确的接口。通过后台团队调研，对现有界面分类能力做了如下优化升级：摒弃原有分类，提供多级分类能力。支持原始数据批量分类能力。通过为用户提供灵活的多级分类能力，界面分类具有更深层次的业务能力，对于项目文档资产的积累非常有帮助。比如store项目，我们可以很清楚的了解到接口的业务能力，如图：4.2基于文档数据Mock提高文档利用率API文档前后端的联系自然是密不可分的来自数据模拟。根据文档字段，平台提供一键Mock功能。根据文档字段，可以生成更准确的mock数据，比如图片、时间、姓名、城市等生成相关数据。此外，我们提供更强大的Mock功能：Mock空间数据隔离：通过提供更灵活的私有场景集和更稳定的公共场景集，保证Mock数据的安全性和数据隔离性。Mock接口多场景：同一个接口提供不同的数据Mock场景。用户可自定义模拟场景数据，如404场景、支付成功场景等，一键激活或切换场景。Mock插件零侵入：目前市面上常见的Mock服务要么自己在业务代码中写入Mock数据，要么提供插件侵入项目的业务代码。Mooncake平台提供基于Chrome插件的零代码入侵Mock功能。基于文档的调试能力目前人们还是使用Postman来调试接口。配置URL和参数的过程仍然很繁琐。文档更改后，无法及时更改。Mooncake基于已有的文档数据，提供了调试功能，省去了配置输入输出参数的麻烦。主要特点如下：支持多环境配置：用户可以预先配置多套运行调试环境，如开发、测试、生产等环境，一键切换调试环境。免登录配置：通过账号的配置，可以自动获取token，解决调试时获取token的问题。公共参数配置：配置公共头参数，减少接口配置次数，节省配置时间和成本。调试场景：支持远程调试和本地调试。基于文档的转换能力YApi提供的文档转换能力较弱，无法判断该字段是否必填。在对前端的调研中，发现大家对现有的转换能力并不满意，导致功能使用率不高。但是文档转换能力是前端使用过程中的高频功能，手动转换比较耗时，所以我们丰富了文档转换能力。多文档类型支持：支持多种文档类型的数据转换，包括Schema、JSON、Raw类型等。更精准的字段定义：根据字段是否必填，可选择直接在TypeScript中转换字段。支持更多语言：目前支持将类型声明转换为TypeScript、Java、Swift、Go、Kotlin、Dart等，月饼平台通过丰富基于文档的内容和功能，提高文档利用率。月饼平台最近3次迭代，与原来的YApi相比，人均PV提升了2倍，使用时长提升了23倍。4.3提高接口交付质量DTDD最重要的核心测试驱动就是通过接口文档的测试来保证文档的交付质量。在月饼平台上，将接口文档的数据同步到自动化测试平台，进行接口测试和编写测试用例。月饼平台同步测试用例。在开发文档交付之前，可以运行测试用例，以保证接口的交付质量。开发可以在月饼中查看当前用例的参数设置，也可以运行用例查看用例的执行结果，如下图：4.4降低用户沟通成本整个开发过程围绕着API文档的生命周期，因为不同的功能角色（前端、后端、测试、客户端）等，所以接口的变化会影响到整个研发环节。频繁围绕接口变更进行沟通，或者因为接口变更没有及时通知其他角色，经常会发生影响整个研发进度的事情。基于这样的考虑，我们增加了以下功能：接口订阅：通过订阅您关心的接口，您可以实时收到接口变更通知，一键查看接口变更。历史版本：平台记录接口变化的历史版本，非常方便查看当前版本与历史版本的差异。群消息通知：平台新增了基于webhook的群消息通知功能，项目接口文件的增删改查可以通过机器人进行通知。4.5降低平台使用难度子曰：工欲善其事，必先利其器。工具的重要性不言而喻。为了让平台更方便使用，提高工作效率，我们支持月饼平台，提供以下工具链：前端工具：针对不同的项目配置提取前端代理SDK、服务和代理插件，包括Webpack插件、Vite插件、UmiPlugins、Chrome插件等。如图：后端工具：IDEA插件：提供交互式IDEA插件，减少代码侵入，增强约束关于文档分类。Go命令行工具：基于社区的Go文档生成工具，一键上传Yaml文件到指定项目。本地调试工具：提供本地调试工具Chrome插件，解决本地调试的跨域问题。通过对DTDD模型的探索和思考，最终完成了得物一站式文档协同平台的自主研发。月饼一站式文档协作平台的推出只是起点，不是终点。文档平台的前景如下图所示。通过构建文档协同平台，促进业务发展，达到产生经济价值的目的。基础功能：提供围绕API的基础功能，如接口文档、接口测试、数据mock等。降本增效，如信息变更：基于API的可扩展性解决方案，体验研发流程的效率，降低生产成本，以及促进业务发展五、总结&思考本文简要介绍了月饼作为一站式研发协作平台的演变过程。平台的整合需要深入思考整合前的现状和最终要解决的问题。对于你想要的最终产品，首先要进行充分的调研，充分了解用户当前的痛点，先做调研，明确目的，提出符合的问题，解决问题的核心，打磨每一个细节和每一个细节功能。目前月饼平台已经实现了文档管理功能，我们也在规划后续平台的方向：完善对Dubbo协议的支持和调试；定时扫码，实现文档自动更新；丰富文档依赖的上游信息，实现变更通知；接口Orchestration实现业务数据的组装等*文/migor
