【获奖名单公布】yapi-to-all 接口文档驱动开发

本文字数：5574字

预计阅读时间：33分钟

• 引言

• 前端业务开发做什么

• 通常消费的物料

• 通常业务的开发流程

• 选择优化开发物料

• 抽象以及关联我们的业务开发的各个环节

• 如何使用 yapi-to-all

• 核心流程

• 总结

• 未来

SOHU

01

引言

随着互联网的快速发展和普及，前端开发已成为现代软件开发中的重要组成部分。然而，随着前端技术的日新月异和项目的不断复杂化，前端开发人员需要编写大量的代码来实现各种功能和需求，这给开发者带来了极大的工作压力。

与此同时，在实际开发中，很多项目中的代码都是模板化的、重复性的，这不仅增加了开发者的工作量，还容易导致代码质量不佳、出现漏洞和错误。

1. 重复性工作：开发过程中经常需要编写重复的代码，如类型定义、页面代码和 service 定义等。这种重复性的工作不仅耗费时间，也容易引发错误。开发人员可能需要花费大量时间在编写重复的代码上，而不能专注于更加复杂和有价值的功能开发.

2. 接口和项目信息的管理问题：开发过程中需要处理大量的接口文档和项目信息，手动管理这些信息可能会导致信息丢失或出错。

3. 质量控制问题：手动编写代码可能存在质量不稳定的问题，特别是在大型项目中，代码风格的一致性和准确性尤为重要。

在本文中，我们将介绍如何使用自动生成代码工具来解决前端开发中的重复性工作和效率问题。我们将从获取接口文档和项目信息开始，然后介绍如何区分不同类型的项目，并生成相关的关联对象。接着，我们将介绍如何使用自动生成代码工具来生成 ts 定义、页面代码、service 定义等，以及如何将这些代码结合起来并输出到对应页面路径。最后，我们将介绍如何统计项目生成的代码信息，以便于更好地了解项目开发状况和提高开发效率。目前我们已经在业务线陆续接入，包含后台和微信小程序已经有7个项目，生成代码行数五万行加。

02

前端业务开发做什么

如果前端一个业务侧需求开发是一次函数调用，一个函数如何发挥他的功能取决于他的输入和输出。如果我们从函数的角度剖析前端业务的开发，功能需求的开发看作一次函数调用。输入是物料和与各端的对接，输出是业务代码。需要消费的物料包括：

1.组件库；

2.帮助前端做状态管理的工具；

3.开源库的一些现成解决方案；

4.项目代码封装过的可复用逻辑。

关于与各端对接同学输入则是：

1.与产品经理沟通确认的业务需求；

2.与设计同学沟通确认的用户界面设计；

3.与后端同学沟通确认的接口实现方式；

4.测试同学提出的 bug。

function frontendDevelopment(
 {
    componentLibrary,
    stateManagementLibrary,
    otherOpenSourceLibrary,
    businessCode,
  ...
  }，  
  { requireMent, ui, yapi, bug, ... },
) {
  // ...
  return logicCode;
}

03

通常消费的物料

主要消费的有三块内容：组件库，请求模块，请求状态处理。一般情况下，关于组件：我们会用基础组件在项目代码里去不断封装组件，或者有业务组件库，在面对各种业务场景，引用组件，组合场景代码；关于请求模块：我们会做一堆 if…else 去做简单功能堆叠；关于请求状态：我们会根据选择的状态管理库，每次都定义一个接口的状态包括但不限于 loading，error，data 等等。

04

通常业务的开发流程

我们拿到需求文档，与产品以及设计同学选定我们本次需求需要消费的组件，与后端同学确定我们的接口定义。首先我们根据接口文档定义请求方法，以及 ts 类型。然后用我们的状态管理库结合请求方法，完成状态变更方法的编写，然后将方法和状态传入对应的页面，在业务组件库以及基础组件库里选择以及组合组件组合完成业务场景代码的编写，在页面内对应的组件消费我们之前定义的方法完成本次需求的开发。

这个高度重复的编码流程完全可以抽象出来，用代码生成的方式完成各个环节的组合和关联。

下面我们将先优化以及选择我们消费的物料，然后再组织优化整理后的物料，完成开发流程的整理和抽象。

05

选择优化开发物料

对于业务侧的场景，我们对于不同端有不同的业务组件库：基于 ant-design 的 pro-components 后台组件库， 基于 uview 的 pro-mini-components 小程序组件库，再根据通用的业务场景，组合业务组件以及基础组件，用作通用的业务场景代码，构建模版池。

• 提供了一致的 UI 组件和设计模式，确保应用程序的一致性和标准化；

• 维护和更新应用程序变得更加便捷，只需在组件库中进行修改即可影响整个应用程序；

• 促进了设计师、开发人员和产品经理之间的跨团队协作和沟通；

• 使用经过优化的组件提升了用户界面的质量和用户体验；

• 具有可扩展性和定制性，可根据项目需求进行定制和扩展。

对于请求状态处理，我们选择 useRequest hook

ahooks 库中的 useRequest 方法是一个非常实用的 hook，可以帮助我们更加便捷地进行数据请求和状态管理。它的主要好处包括：

• 简化了数据请求的代码结构，让代码更加清晰易懂；

• 支持缓存机制，可以在数据请求时缓存数据，从而避免重复请求；

• 支持请求结果转换、异常处理等功能，可以有效提高代码质量和可维护性。

useRequest 方法的主要功能包括：

• 请求数据：可以通过 useRequest 方法来请求数据；

• 缓存数据：支持缓存机制，可以在数据请求时缓存数据，从而避免重复请求；

• 转换数据：支持请求结果转换功能，可以将请求结果转换为指定格式；

• 处理异常：支持异常处理功能，可以在请求过程中捕获异常并进行相应的处理；

• 取消请求：支持取消请求的功能，可以在请求过程中取消请求；

• 状态管理：支持状态管理功能，可以管理请求状态、请求结果等信息。

关于请求模块，我们选择 umi-request：现成方案；以及经过改造过的适用于小程序的请求方案

主要好处：

避免手写重复的请求和错误处理逻辑，提高代码复用和可维护性，同时也可以提高请求和响应数据的处理效率和质量。还具有灵活的配置和扩展性，可以根据自己的需求来进行定制和扩展，满足不同场景下的请求和响应处理需求。主要功能：

• 支持拦截器：可以在请求前和响应后拦截请求，改变请求和响应的参数和结果；

• 支持全局错误处理：可以在全局配置中设置错误处理函数，统一处理发生错误的请求；

• 支持终止请求：可以通过 cancelToken 终止正在请求的请求；

• 支持超时处理：可以设置请求超时时间，避免请求时间过长；

• 支持请求缓存：可以设置请求缓存时间，避免重复请求；

• 支持请求重试：可以设置请求重试次数和时间间隔，避免请求失败；

• 支持多种数据格式：可以发送和接收多种数据格式，如 JSON、FormData、ArrayBuffer 等；

• 支持上传和下载文件：可以上传和下载文件，支持进度条显示；

• 支持请求和响应的拦截器：可以在请求和响应拦截器中修改请求和响应数据，如添加请求头、处理响应数据等；

• 支持自定义请求和响应的处理逻辑：可以通过自定义处理逻辑来处理请求和响应数据；

• 支持请求和响应的转换器：可以在请求和响应转换器中对请求和响应数据进行转换；

• 支持扩展请求库：可以通过扩展请求库来实现更多的功能，如添加一些常用的请求头、修改默认配置等。

06

抽象以及关联我们的业务开发的各个环节

组件库对应的物料

众所周知，组件是业务提效以及业务线基建的重中之重，我们通常遇到的会有以下几种：

1. 选择的基础组件

2. 业务组件

3. 通用的业务场景（基础组件和业务组件组合的产物）

其中部分业务场景和组件类似，有着约定俗成的数据输入格式，比如表单的展示搜索以及增删改查，对于这类场景我们完全可以用模版化的方法，根据接口的定义去动态生成对应的代码。通过不断丰富我们的模版池，大大降低我们的开发成本。

我们通过通用业务场景的方式，完成组件之间的关联，形成场景模版池；再进一步通过关联我们约定的接口定义将接口和场景模版代码关联在一起。

请求对应的物料

我们将 useRequest 和 service 定义整合在一起，每次定义一个请求的方法，这个方法就会挂一个 useRequest hook 整合了请求的状态，这样我们不需要像之前需要分别定义再做传参调用，而是直接内聚在一起，让业务同学根据场景决定是否使用。完成了请求方法和状态定义的聚合。

我们将每一个请求的参数以及返回值的 ts 定义都聚合在一个 type 上，而且也做了平铺处理，这样所有请求方法的 ts 定义在都在同一级可以直接获取到，没有嵌套也让类型的消费更简单。参数类型名为 ServiceTypes[methodName + ‘Params’], 返回值类型名为 ServiceTypes[methodName + ‘Response’] ，使用上，只要引入对应页面的 ServiceTypes 文件名，就可以直接消费对应方法的定义。

请求状态和请求方法以及请求类型定义的聚合，在这里将不同的模块关联在一起方便我们后续生成关联的代码：

优化请求物料的定义方式

我们通过 pointfree 的方式以及合理的整合参数和类型重新定义接口声明方式，将一个10行的包含 ts 定义的请求函数改造成了4行，大大增强了可读性。（ps：多层嵌套对于业务代码来说是一眼晕）

优化代码的组织结构

将每一个 page 的不同类型的业务逻辑都放在一个目录内，聚合业务逻辑，解耦请求方法，上面的内容包括整理了请求方法，请求状态，请求接口，请求 typescript 定义，目录规范方面的内容，提供一个更便于业务开发同学消费的方式生成内容。

将紧密关联的代码放在一起，从全目录开发转为单目录开发，就这么愉快。

将我们上述的所有环节关联起来形成闭环，就是 yapi-to-all 接口文档驱动开发 隆重登场的时候了。

07

如何使用 yapi-to-all

配置文件

只有 yapi 地址，和项目 token，足够简单有没有？

路由配置 service 以及 template 信息

目录：路由关联 service 对应的 service, 这里请求相关的配置都在页面路径下的 generateServices 里，这样就会在对应的页面路径下生成一个 service 文件。如下所示，每一个路径都关联了一个 generateServices 的数组属性，这种关联确保了具体页面需要消费的接口生成在对应的页面。做到页面代码与请求代码的内聚。

我们可以通过 template 去选择我们的业务场景，如果是有约定固定消费数据格式的 template，还可以直接帮助我们完成接口和页面的关联。

componentName 决定我们的文件目录名：

生成代码

如果不加 template 参数，不生成模版代码，只生成请求函数，请求状态，类型定义：

请求模块代码

我们通过中间件，和拦截器的抽象，通过请求模块的组合封装，而不是一堆 if…else，完成每一个子功能的解耦。以下代码会在没有这个模块的时候直接生成，如果有则跳过。

生成的代码文件

直接聚合在一起：

生成的列表页模板

如上文提到的约定的模版关联约定的接口以及类型定义，我们将三者直接关联在一起，我们只要再做一些额外场景的代码编写就完成了需求的开发，够快有没有？

生成的抽屉提交表单页代码

生成的请求模块

如注释所提到的，如果我们想加一些 header 或者 useRequest 对应的入参时，可以直接加在第二个参数这里，值得一提的是，虽然我们这个文件的代码都是自动生成的，但再再次生成的时候会做一个简单的 dif 保留一些我们需要自己定义的参数，而不是完全不可编辑的状态。

聚合导出请求方法以及 ts 定义

我们在对应页面的任何地方，在需要时不论时发出请求还是引用 ts 类型，都可以直接引用一个聚合变量，便捷消费。

08

核心流程

我们首先根据产品功能定义，以及 ui 的交互设计复用或新增业务组件，然后定义的接口与 useRequest 整合，完成接口状态管理，以及补充接口的 typescript  定义，最后基于业务组件的消费的数据格式，整合注入接口的 useRequest hook 调用返回的数据。我们可以抽象业务流程去用类低代码的方式根据配置以及生成示的方式完成我们的业务开发。

下面是设计图：

我们的配置文件，是在路由里新增生成示的 generateService 字段，在里面配置接口地址，以及需要消费的模版名，以及格式化的函数去转换接口文档提供给我们的请求返回参数。

根据这些配置信息，再根据对应是后台还是微信小程序选择消费我们的组件库对应的 demo 模版，以及对应的请求模块完成我们的业务代码：请求函数，状态管理，ts 定义，视图页面。最后按照团队代码风格的注入方式和顺序完成业务的开发。

下面是流程图：

09

总结

我们通过 yapi-to-all，将接口的定义，类型的定义，接口对应的状态，组件代码，请求模块整体关联起来，每个重复出现的业务场景都可以沉淀在我们的模版池中，避免二次开发。成块的模版代码也对我们的物料做了补充，从小到大分为，基础组件库，业务组件库，业务场景模版库。帮助我们解决重复性工作和效率问题，加快项目开发速度，提高代码质量和可维护性，降低项目开发成本，提高团队协作效率，并减少开发人员之间的沟通成本。此外，自动生成代码工具还可以生成统一的代码风格，减少代码错误，从而提高项目开发效率和代码质量。将工程师们从面向具体的业务场景开发中解放出来，可以更加专注于解决业务问题和技术难点。

10

未来

• 增加插件方便业务线拓展；

• 分析 lanhu 的结构自动关联业务组件或基础组件；

• 接入 ai 辅助我们的代码分析和代码生成示工作。

  上期获奖名单公布
  

  恭喜三位读者！

  @kl♓️ @羽夜 @阿策~

  以上读者请及时添加小编微信@sohu-tech20 兑换获奖书籍~

兑奖截止至8月24日，请参与读者及时兑奖