CN110244940A - 优化web应用系统开发的方法及web前端项目结构 - Google Patents

Abstract

本发明公开了一种优化web应用系统开发的方法，包括：通过Swagger统一web应用开发前后端接口定义与对接的规范与风格，使用Java作为开发语言，并使用springboot或springmvc作为开发框架；在web应用后端定义API并集成Swagger，通过Swagger生成对应的web接口文档和接口类型定义文件；在web应用前端使用有javascript运行能力的引擎作为开发的支持环境，web应用前端查看并获取web应用后端生成的web接口文档和接口类型定义文件，通过脚本将接口类型定义文件转为web应用前端开发中可用的接口方法。本发明方法通过统一web应用前后端定义API的框架，使用Swagger作为桥梁起到简化流程、提高效率的效果。

Description

优化web应用系统开发的方法及web前端项目结构

技术领域

本发明涉及使用Typescript开发web应用的前后端研发技术领域，特别涉及一种优化web应用系统开发的方法及web前端项目结构。

背景技术

目前市场上web应用普遍流行使用前后端分离的开发技术，即前后端同时进行开发，此种开发模式使前后端能够并发的进行工作，加快项目的诞生。但在此种模式下定义API以及前后端的沟通与对接会消耗大量的时间。

在web后端的开发领域，Java一直占有很大的比例，截止到目前，多采用springmvc(或springboot)作为开发框架，maven作为包管理，使用Swagger作为定义RESTFUL接口的API框架。

web应用前端开发自前后端独立开发后有较大的发展，特别是node的诞生使得前端的开发人员能更加独立的开发。目前，常采用nodeJs作为前端页面开发的支持环境，使用React/Vue/Angular作为开发框架。但在实际开发中Javascript的弱类型一直饱受诟病，很多问题不能及时发现和解决，只能通过全面测试或者上线问题暴露后再解决。在此种环境下，Typescript的应运而生使得前端开发又进一步。

发明内容

本发明的目的是克服上述背景技术中不足并基于上述背景技术，提供一种优化web应用系统开发的方法及web前端项目结构，旨在以目前主流开发技术的环境下，使web应用前后端的开发者能减少接口定义以及沟通成本,从而更多的关注自身业务研发。

为了达到上述的技术效果，本发明采取以下技术方案：

一种优化web应用系统开发的方法，用于优化web应用系统开发的方法，包括：

通过Swagger统一web应用开发前后端接口定义与对接的规范与风格，使用Java作为开发语言，并使用springboot或springmvc作为开发框架；实际中，也可选用其他可以继承Swagger的开发语言或框架；

在web应用后端定义API并集成Swagger，同时，通过Swagger生成对应的web接口文档和接口类型定义文件；其中，具体是通过注解或其他方式自动生成如json、yaml或其他类型的web接口文档；

在web应用前端使用有javascript运行能力的引擎如nodeJs作为开发必须的支持环境，web应用前端实时查看并获取所述web应用后端生成的web接口文档和接口类型定义文件，并通过javascript或Typescrip语言编写的脚本将所述接口类型定义文件转为web应用前端开发中可用的接口方法；其中，web应用后端虽然会对每个API做详细的类型以及参数类型定义，但名称一般不太友好，故本方案中，web应用前端会根据API接口类型再自定义接口类型，然后进行集中管理和使用，从而使前端项目结构更加缜密。

进一步地，所述web应用后端集成Swagger并生成对应的web接口文档和接口类型定义文件时具体包括以下步骤：

S1.所述web应用后端采用可以集成Swagger框架的语言如Java语言作为开发语言并采用可以集成Swagger的框架如springmvc或springroot框架作为开发框架；

S2.所述web应用后端通过集成Swagger，在定义API的过程中生成详细的接口类型定义文件并通过Swagger UI将此接口类型定义文件以web页面形式作为展现，直接作为web形式的web接口文档。

进一步地，所述接口类型定义文件是通过Swagger生成的如json或yaml等能定义详细数据结构以及类型的文档。

进一步地，所述接口类型定义文件中包括：接口的请求host、公有请求路径、每个详细的API模块私有请求路径、对每个详细的API模块分别包含或部分包含增删改查的数据操作方式、对每一种操作中包含对应的请求参数名称以及类型定义、对每一种操作中包含对应的请求参数所处位置定义、对每一种操作定义进行全部定义或部分定义请求接口的返回状态码以及对应的返回数据格式及内容。

进一步地，所述web应用前端具体使用node作为前端开发的环境支持，且web应用前端使用Typescript作为前端开发语言，通过nodeJs运行脚本的方式以网络请求获取接口类型定义文件，且所述web应用前端开发中可用的接口方法为Typescript方法。

进一步地，通过javascript或Typescrip语言编写的脚本将所述接口类型定义文件转为web应用前端开发中可用的接口方法时，所述脚本通过nodeJs执行，且包括以下步骤：

S1.所述脚本根据web应用后端集成Swagger后产生服务的网络地址，使用nodeJs的request模块请求所述接口类型定义文件；其中，若脚本先在请求接口类型定义文件中若遇到请求不到或权限限制或其他问题时，则需要web应用前端与web应用后端协调使整个过程能顺利进行；

S2.所述脚本将接口类型定义文件转为针对一个个独立的API访问方法来访问web应用后端的参数结构与类型定义，并以所述API访问方法的形参结构与类型来展现。

进一步地，所述步骤S2中脚本将接口类型定义文件转为针对一个个独立的API访问方法时，具体包括以下步骤：

S101.提取所述接口类型定义文件的公有请求路径组成API的基础访问路径；

S102.按一定顺序提取每个详细的API模块私有请求路径，并遍历对应请求类型，以小驼峰的方式组成对每个详细的API模块每种请求方式的API访问方法的方法名；

S103.根据所述web应用后端定义的参数位置类型生成所述API访问方法的参数的传递类型；如包括但不限于body，path，query等；

S104.根据所述返回状态码以及对应的返回数据格式及内容，定义所述API访问方法的返回值与类型；

S105.结合所述web前端使用的网络请求架构，将对应的网络请求方法注入到每个所述API访问方法中。

进一步地，所述API访问方法的形参结构与类型包括所述接口类型定义文件所定义的参数结构、参数类型与必填类型，其中，所述必填类型通过Typescript所中Partial的方式来体现，其具体的写法为参数定义中是否含有“？”；所述步骤S104中所述返回状态码为request协议的网络请求状态码，所述步骤S105中所述网络请求架构包括axios或ajax，所述注入到每个所述API访问方法具体是将所有API统一放置到一个Service的Generate方法中，通过外部传入请求模块的配置来实现。

进一步地，所述web应用前端实时查看所述web接口文档的同时也使用所述web接口文档做实时请求，并自定义请求参数和查看接口详细的返回数据，则所述web应用后端的接口类型定义有变化时，只需刷新所需web接口文档便可立即查看更新，其中，web应用前端可以通过浏览器访问web应用后端集成SwaggerUI后产生的服务地址查看具体的接口定义，若web应用前端不能访问web接口文档时，则需要与web应用后端协商使其能正常工作。

同时，本发明还公开了一种web前端项目结构，包括：

基础组件模块，用于存放web前端项目的全局公用基础组件；

构建模块，用于存放和项目相关的脚本文件，其中，所述脚本文件至少包括API生成脚本；

接口服务模块，用于存放使用所述API生成脚本生成的API模块以及对API模块进行二次封装，或实现对全局API请求的拦截与注入的方法；

功能模块，用于将web前端按照功能模块划分，并在各个功能模块中，自定义页面以及私有组件。

本发明与现有技术相比，具有以下的有益效果：

本发明的优化web应用系统开发的方法及web前端项目结构，可用于提升web应用前后端定义与对接API的效率，通过统一web应用前后端定义API的框架，使用Swagger作为桥梁，起到简化流程、提高效率的效果，同时，本发明的web前端项目结构，具有较高的合理性与可扩展性，更加便于开发者的应用。

附图说明

图1是本发明web应用后端集成Swagger并生成相关web接口文档的流程架构示意图。

图2是本发明web应用后端集成Swagger生成接口文档步骤示意图。

图3是本发明Swagger生成的RESTful接口类型示意图。

图4是本发明web应用前端自动化生成API流程架构示意图。

图5是本发明web应用前端自动化生成API的流程步骤示意图。

图6是本发明web应用前后端通过Swagger对接API的整体示意图。

图7是本发明web应用前端的项目结构及功能示意图。

具体实施方式

下面结合本发明的实施例对本发明作进一步的阐述和说明。

实施例：

实施例一：

一种优化web应用系统开发的方法，用于优化web应用系统开发的方法，包括对Typescript引入使web应用前端开发更加可靠和规范的同时，通过Swagger的引入统一web应用开发中关于API定义的规范和风格，并以此作为桥梁，通过脚本的使用减少人员沟通上的无用成本消耗，从而提高前后端API的定义与对接效率，并降低出错率，与此同时，再对前端项目的结构进行更合理的优化布置，增加其合理性与扩展性，从而更广泛的适应变动的需求。

包括：

流程一：通过Swagger统一web应用开发前后端接口定义与对接的规范与风格，使用Java作为开发语言，并使用springboot或springmvc作为开发框架；实际中，也可选用其他可以继承Swagger的开发语言或框架。

流程二：在web应用后端定义API并集成Swagger，同时，通过Swagger生成对应的web接口文档和接口类型定义文件；其中，具体是通过注解或其他方式自动生成如json、yaml或其他类型的web接口文档。

流程三：在web应用前端使用有javascript运行能力的引擎如nodeJs作为开发必须的支持环境，使用node作为前端开发的环境支持，且web应用前端使用Typescript作为前端开发语言，web应用前端实时查看并通过nodeJs运行脚本的方式以网络请求获取web应用后端生成的web接口文档和接口类型定义文件，并通过javascript或Typescrip语言编写的脚本将接口类型定义文件转为web应用前端开发中可用的接口方法即Typescript方法。其中，web应用后端虽然会对每个API做详细的类型以及参数类型定义，但名称一般不太友好，故本方案中，web应用前端会根据API接口类型再自定义接口类型，然后进行集中管理和使用，从而使前端项目结构更加缜密。

作为优选，web应用前端实时查看web接口文档的同时也使用web接口文档做实时请求，并自定义请求参数和查看接口详细的返回数据，则web应用后端的接口类型定义有变化时，只需刷新所需web接口文档便可立即查看更新，其中，web应用前端可以通过浏览器访问web应用后端集成SwaggerUI后产生的服务地址查看具体的接口定义，若web应用前端不能访问web接口文档时，则需要与web应用后端协商使其能正常工作。

具体的，接口类型定义文件是通过Swagger生成的如json或yaml等能定义详细数据结构以及类型的文档。且接口类型定义文件中包括：接口的请求host、公有请求路径、每个详细的API模块私有请求路径、对每个详细的API模块分别包含或部分包含增删改查的数据操作方式、对每一种操作中包含对应的请求参数名称以及类型定义、对每一种操作中包含对应的请求参数所处位置定义、对每一种操作定义进行全部定义或部分定义请求接口的返回状态码以及对应的返回数据格式及内容。

具体的，本实施例中，web应用前端通过javascript或Typescrip语言编写的脚本将接口类型定义文件转为web应用前端开发中可用的接口方法时，脚本通过nodeJs执行，且包括以下步骤：

S1.脚本根据web应用后端集成Swagger后产生服务的网络地址，使用nodeJs的request模块请求接口类型定义文件；其中，若脚本先在请求接口类型定义文件中若遇到请求不到或权限限制或其他问题时，则需要web应用前端与web应用后端协调使整个过程能顺利进行；

S2.脚本将接口类型定义文件转为针对一个个独立的API访问方法来访问web应用后端的参数结构与类型定义，并以API访问方法的形参结构与类型来展现。其中，API访问方法的形参结构与类型包括接口类型定义文件所定义的参数结构、参数类型与必填类型，且必填类型通过Typescript所中Partial的方式来体现。

其中，脚本将接口类型定义文件转为针对一个个独立的API访问方法时，具体包括以下步骤：

步骤一.提取接口类型定义文件的公有请求路径组成API的基础访问路径；

步骤二.按一定顺序提取每个详细的API模块私有请求路径，并遍历对应请求类型，以小驼峰的方式组成对每个详细的API模块每种请求方式的API访问方法的方法名；

步骤三.根据web应用后端定义的参数位置类型生成API访问方法的参数的传递类型；如包括但不限于body，path，query等；

步骤四.根据返回状态码以及对应的返回数据格式及内容，定义API访问方法的返回值与类型；其中，返回状态码为request协议的网络请求状态码；

步骤五.结合web前端使用的网络请求架构如axios或ajax等，将对应的网络请求方法注入到每个API访问方法中，即将所有API统一放置到一个Service的Generate方法中，通过外部传入请求模块的配置来实现。

其中，如图1所示为本实施例中web应用后端集成Swagger并生成相关web接口文档的流程架构，包括：在web应用后端API层集成Swagger模块，集成Swagger后当生成API时即生成对应的API类型文件，随后通过集成的SwaggerUI将API类型文件转为可直接通过浏览器访问的web接口文档。

具体的，web后端API层是web应用后端开发中定义API的class，在引入Swagger后，要经过编写Swagger启动类以及进行spring静态资源、拦截器的配置，经过这些配置后就可以直接通过Java注解的方式直接使用Swagger，其中，SwaggerUI则可以通过直接下载对应Swagger版本的UI资源，将dist目录下的文件，复制到webapp下的Swagger目录中或项目中自定义的Swagger路径下，然后修改SwaggerUI资源里index.html的文档加载地址为web后端定义的服务地址即可。则API类型文件即为通过集成Swagger后，使用注解生成的包含web后端定义的全量API类型文件。该API类型文件，为一定结构的json文件，此文件可以转成符合Swagger规范的yaml文件，两者互通。若是后端API已经稳定而不再变动，则可以直接保存此json或yaml文件供离线使用。

如图2所示为本实施例中，web应用后端集成Swagger并生成相关web接口文档的步骤示意图，则通过本实施例的方法在web应用后端集成Swagger和SwaggerUI可节省web应用后端对接口文档的编写，提高开发效率，具体包括以下步骤：

步骤s201：web应用后端通过一定步骤集成Swagger以及对应版本的UI资源，当可以正常启动和访问对应资源时则表示集成成功；

步骤s202：web应用后端先引入Swagger资源，然后根据项目需求而定义对应的API类，然后在API类上添加Swagger注解，基本的注解包括但不限于@Api(表示这个类为Swagger的资源)；

步骤s203：集成成功的Swagger会在启动后根据web应用后端定义的API注解以及内容生成对应的API类型文件，并能通过SwaggerUI生成web接口文档。

具体的，如图3所示为本实施例中，web应用后端集成Swagger后所生成的接口类型Json文档的简单目录结构，其中，swagger 301表示Swagger的版本信息；info 302表示项目的基本信息，包括但不限于描述、名称、版本；host 303表示该API类型文件中所有API的Host；basepath 304表示所有API的BasePath，及子API的公用路径，可以理解为该API项目的命名空间；schemes 305表示该项目支持的协议类型，一般为Request或Requests，或两者兼备；除基本或者公用的配置信息外，剩下的则为RESTful风格的具体资源操作定义即Paths，RESTful风格的API，则将所有的API定义为网络资源，然后所有的请求都可理解为对具体网络资源的操作，paths306表示Paths下面包含具体的API访问路径，如本实施例中以{RESOURCE PATH}307作为访问网络资源路径的示例，其中，REQUEST TYPE 308表示对具体API的操作类型，常见的增删改查为：Put，Post，Get，Delete，不常见的则基本可以忽略；parameters 309表示每个API请求的请求参数；response 310表示对每个API请求后对应的返回code码以及数据结构和类型。

本实施例中图3所示的结构仅为使用Swagger生成接口类型文件的部分结构示意，其中还有更加详细的定义和使用方法，可以直接通过网络获取。

具体的，图4所示为本实施例中，web应用前端在nodeJs环境的支持下，通过脚本生成前端能直接使用的API方法的流程架构示意图，本实施例中，web应用前端的运行环境为nodeJs，具体包括先通过脚本获取到接口类型定义文件，再生成可供web应用前端直接调用的Typescript类型的方法。

如图5所示为本实施例中，web应用前端通过脚本获取web应用后端生成的接口类型定义文件并生成供web应用前端直接调用的方法的步骤示意，包括：

步骤s501：编写脚本基础功能，调用nodeJs中的request模块请求接口类型定义文件，并解析成js对象；

步骤s502：使用javascript编写解析脚本，转换步骤s501所获取的接口类型定义文件，基本步骤包括：按照格式化生成每个API请求方法的名称；生成每个API请求方法的参数结构以及类型；生成每个API请求方法的返回值结构以及类型。

因此，本实施例的技术方案中，解析时由于业务的原因，部分的API请求方法的参数结构与类型，以及返回值的结构与类型可以复用，此种情况可以单独抽离Interface类型，提高复用率。

如图6所示为本实施例的使用Swagger作为web应用前后端统一API风格与规范的桥梁，提高开发效率的整体方案示意图，主要包括定义接口类型、集成Swagger、运行Swagger服务并生成所需的web文档与类型定义，然后通过nodeJs的引入，可以通过javascript编写脚本来实现文件拉取、解析、创建；最后通过网络请求将web应用后端通过Swagger生成的接口类型定义文件转为web应用前端开发中所需的API请求方法。

由上可知，本发明的优化web应用系统开发的方法，可提升web应用前后端定义与对接API的效率，且可以在不同的项目中进行复用，从而在web应用后端可以减少人为书写接口文档数量，而在web应用前端则更可以显著的减少API模块的开发任务量。

实施例二

如图7所示为通过本发明的优化web应用系统开发的方法优化后生成的web前端应用项目目录结构，该结构具有较高的合理性和扩展性。

其中，module模块701表示web应用前端的所有功能module，通过不按照常见的使用页面来划分结构的方式，提高各个模块内部的合理性，实现模块内部高内聚，多复用，且各模块间采用相互引用来加以联系。

models模块702为全局公用的类型模块，用于对web应用前端公用interface与type的公共抽离，通过全局定义的方式，事先定义好基础类型池，从而减少不合理的类型滥用。

services模块703与build模块705相关联，services模块703是用于存储本发明实施案例中通过API自动化构建脚本生成的API方法文件，并可对此再进行封装，build模块705则用于存放web前端应用中用到的脚本文件，如本发明实施案例中提到的API自动化构建脚本就可以存放在这里。

components模块704用于对web应用前端的基础组件定义，常见的包括但不限于Button、Toast、Table等进行统一封装，方便module中的引用，且为后续项目的进一步扩展提供空间，如生成统一的UI库，具体采用npm包管理和引用的方式。

可以理解的是，以上实施方式仅仅是为了说明本发明的原理而采用的示例性实施方式，然而本发明并不局限于此。对于本领域内的普通技术人员而言，在不脱离本发明的精神和实质的情况下，可以做出各种变型和改进，这些变型和改进也视为本发明的保护范围。

Claims (10)

1.一种优化web应用系统开发的方法，用于提升web应用前后端定义与对接API的效率，其特征在于，包括：

通过Swagger统一web应用开发前后端接口定义与对接的规范与风格，使用Java作为开发语言，并使用springboot或springmvc作为开发框架；

在web应用后端定义API并集成Swagger，同时，通过Swagger生成对应的web接口文档和接口类型定义文件；

在web应用前端使用有javascript运行能力的引擎作为开发必须的支持环境，web应用前端实时查看并获取所述web应用后端生成的web接口文档和接口类型定义文件，并通过javascript或Typescrip语言编写的脚本将所述接口类型定义文件转为web应用前端开发中可用的接口方法。

2.根据权利要求1所述的一种优化web应用系统开发的方法，其特征在于，所述web应用后端集成Swagger并生成对应的web接口文档和接口类型定义文件时具体包括以下步骤：

S1.所述web应用后端采用可以集成Swagger框架的语言作为开发语言并采用可以集成Swagger的框架作为开发框架；

S2.所述web应用后端通过集成Swagger，在定义API的过程中生成详细的接口类型定义文件并通过Swagger UI将此接口类型定义文件以web页面形式作为展现，直接作为web形式的web接口文档。

3.根据权利要求2所述的一种优化web应用系统开发的方法，其特征在于，所述接口类型定义文件是通过Swagger生成的能定义详细数据结构以及类型的文档。

4.根据权利要求3所述的一种优化web应用系统开发的方法，其特征在于，所述接口类型定义文件中包括：接口的请求host、公有请求路径、每个详细的API模块私有请求路径、对每个详细的API模块分别包含或部分包含增删改查的数据操作方式、对每一种操作中包含对应的请求参数名称以及类型定义、对每一种操作中包含对应的请求参数所处位置定义、对每一种操作定义进行全部定义或部分定义请求接口的返回状态码以及对应的返回数据格式及内容。

5.根据权利要求4所述的一种优化web应用系统开发的方法，其特征在于，所述web应用前端具体使用node作为前端开发的环境支持，且web应用前端使用Typescript作为前端开发语言，通过nodeJs运行脚本的方式以网络请求获取接口类型定义文件，且所述web应用前端开发中可用的接口方法为Typescript方法。

6.根据权利要求5所述的一种优化web应用系统开发的方法，其特征在于，通过javascript或Typescrip语言编写的脚本将所述接口类型定义文件转为web应用前端开发中可用的接口方法时，所述脚本通过nodeJs执行，且包括以下步骤：

S1.所述脚本根据web应用后端集成Swagger后产生服务的网络地址，使用nodeJs的request模块请求所述接口类型定义文件；

S2.所述脚本将接口类型定义文件转为针对一个个独立的API访问方法来访问web应用后端的参数结构与类型定义，并以所述API访问方法的形参结构与类型来展现。

7.根据权利要求6所述的一种优化web应用系统开发的方法，其特征在于，所述步骤S2中脚本将接口类型定义文件转为针对一个个独立的API访问方法时，具体包括以下步骤：

S101.提取所述接口类型定义文件的公有请求路径组成API的基础访问路径；

S102.按一定顺序提取每个详细的API模块私有请求路径，并遍历对应请求类型，以小驼峰的方式组成对每个详细的API模块每种请求方式的API访问方法的方法名；

S103.根据所述web应用后端定义的参数位置类型生成所述API访问方法的参数的传递类型；

S104.根据所述返回状态码以及对应的返回数据格式及内容，定义所述API访问方法的返回值与类型；

S105.结合所述web前端使用的网络请求架构，将对应的网络请求方法注入到每个所述API访问方法中。

8.根据权利要求7所述的一种优化web应用系统开发的方法，其特征在于，所述API访问方法的形参结构与类型包括所述接口类型定义文件所定义的参数结构、参数类型与必填类型，其中，所述必填类型通过Typescript所中Partial的方式来体现；所述步骤S104中所述返回状态码为request协议的网络请求状态码，所述步骤S105中所述网络请求架构包括axios或ajax，所述注入到每个所述API访问方法具体是将所有API统一放置到一个Service的Generate方法中，通过外部传入请求模块的配置来实现。

9.根据权利要求1所述的一种优化web应用系统开发的方法，其特征在于，所述web应用前端实时查看所述web接口文档的同时也使用所述web接口文档做实时请求，并自定义请求参数和查看接口详细的返回数据，则所述web应用后端的接口类型定义有变化时，只需刷新所需web接口文档便可立即查看更新。

10.一种web前端项目结构，其特征在于，包括：

基础组件模块，用于存放web前端项目的全局公用基础组件；

构建模块，用于存放和项目相关的脚本文件，其中，所述脚本文件至少包括API生成脚本；

接口服务模块，用于存放使用所述API生成脚本生成的API模块以及对API模块进行二次封装，或实现对全局API请求的拦截与注入的方法；

功能模块，用于将web前端按照功能模块划分，并在各个功能模块中，自定义页面以及私有组件。