一种枚举文档的生成方法、装置、电子设备及存储介质与流程

1.本申请涉及计算机技术领域，特别涉及一种枚举文档的生成方法、装置、一种电子设备及一种存储介质。


背景技术：

2.在系统开发过程中，通常会定义大量的枚举来存储固定的数据。枚举包括用来表示诸如色彩、状态、类别、月份等数目有限、形式离散、表达明确的常量。通过使用枚举，方便开发者书写代码逻辑，提高代码的可读性，帮助程序员写出更加简单易懂的代码。
3.随着业务系统日趋复杂，系统中用到的枚举越来越多，一个系统往往用到海量的枚举。在开发过程中开发人员需要花费大量的时间和精力人工撰写文档。同时，修改文档后还需要通知其他人员，极大的提高了沟通的成本。在复杂的业务中，需要频繁更新旧的枚举类，使得开发速度难以跟上业务系统更新的需求，限制了业务的拓展。
4.因此，如何自动化生成枚举文档，提高枚举文档的生成效率是本领域技术人员目前需要解决的技术问题。


技术实现要素：

5.本申请的目的是提供一种枚举文档的生成方法、装置、一种电子设备及一种存储介质，能够自动化生成枚举文档，提高枚举文档的生成效率。
6.为解决上述技术问题，本申请提供一种枚举文档的生成方法，该枚举文档的生成方法包括：
7.获取目标代码文件，并通过程序结构接口解析所述目标代码文件得到psiclass对象；
8.根据所述psiclass对象确定所述目标代码文件的枚举类；
9.将所述枚举类解析为psi树，并根据所述psi树中的元素生成枚举元数据；
10.拼接所有所述枚举元数据生成枚举文档。
11.可选的，在获取目标代码文件之前，还包括：
12.监听版本控制系统的代码提交事件；
13.若检测到代码提交事件，则获取本次提交的所有代码文件；
14.相应的，所述获取目标代码文件，包括：
15.根据文件类型从本次提交的所有代码文件中获取所述目标代码文件。
16.可选的，根据所述psiclass对象确定所述目标代码文件的枚举类，包括：
17.调用所述psiclass对象的isenum方法，得到返回值；
18.将返回值为ture的psiclass对象设置为目标代码文件的枚举类。
19.可选的，根据所述psi树中的元素生成枚举元数据，包括：
20.通过调用所述psiclass对象的getname方法获取枚举类的类名；
21.获取所述psiclass对象的psijavafile对象，并通过调用所述psijavafile对象的
getpackagename方法获取枚举类的包名；
22.通过调用所述psiclass对象的getdoccomment方法获取枚举类的注释文本，并利用所述注释文本解析枚举类的标题和描述；
23.获取枚举类的属性字段；
24.拼接所有所述枚举类的类名、包名、标题、描述和属性字段生成所述枚举元数据。
25.可选的，所述获取枚举类的属性字段，包括：
26.获取枚举类的属性；
27.判断所述属性是否为枚举常量；
28.若是，则通过调用枚举项的getargumentlist方法获取枚举项的所有参数，并将枚举项的所有参数设置为所述枚举类的属性字段；
29.若否，则通过获取所述属性的注释文本得到所述枚举类的属性字段。
30.可选的，所述拼接所有所述枚举元数据生成枚举文档，包括：
31.读取模板文件内容，并通过调用模板引擎对所述模板文件内容和所述枚举元数据生成文档内容；
32.通过调用文件接口将所述文档内容写入目标文件得到所述枚举文档。
33.可选的，在获取目标代码文件之后，还包括：
34.判断系统中是否存储有原枚举文档；
35.若是，则将所述原枚举文档所在的文件设置为所述目标文件。
36.本申请还提供了一种枚举文档的生成装置，该装置包括：
37.文件解析模块，用于获取目标代码文件，并通过程序结构接口解析所述目标代码文件得到psiclass对象；
38.枚举类确定模块，用于根据所述psiclass对象确定所述目标代码文件的枚举类；
39.元数据生成模块，用于将所述枚举类解析为psi树，并根据所述psi树中的元素生成枚举元数据；
40.文档生成模块，用于拼接所有所述枚举元数据生成枚举文档。
41.本申请还提供了一种存储介质，其上存储有计算机程序，所述计算机程序执行时实现上述枚举文档的生成方法执行的步骤。
42.本申请还提供了一种电子设备，包括存储器和处理器，所述存储器中存储有计算机程序，所述处理器调用所述存储器中的计算机程序时实现上述枚举文档的生成方法执行的步骤。
43.本申请提供了一种枚举文档的生成方法，包括：获取目标代码文件，并通过程序结构接口解析所述目标代码文件得到psiclass对象；根据所述psiclass对象确定所述目标代码文件的枚举类；将所述枚举类解析为psi树，并根据所述psi树中的元素生成枚举元数据；拼接所有所述枚举元数据生成枚举文档。
44.本申请在获取目标代码文件之后，通过程序结构接口解析所述目标代码文件得到psiclass对象，进而基于psiclass对象确定目标代码文件中的枚举类，通过将枚举类解析为psi树获取枚举元数据，拼接所有的枚举元数据可以得到生成枚举文档。上述过程无需人工参与，通过对目标代码文件进行解析、提取元数据等操作得到枚举元数据自动生成枚举文档，提高了枚举文档的生成效率。本申请同时还提供了一种枚举文档的生成装置、一种电
子设备和一种存储介质，具有上述有益效果，在此不再赘述。
附图说明
45.为了更清楚地说明本申请实施例，下面将对实施例中所需要使用的附图做简单的介绍，显而易见地，下面描述中的附图仅仅是本申请的一些实施例，对于本领域普通技术人员来讲，在不付出创造性劳动的前提下，还可以根据这些附图获得其他的附图。
46.图1为本申请实施例所提供的一种枚举文档的生成方法的流程图；
47.图2为本申请实施例所提供的一种枚举文档生成过程示意图；
48.图3为本申请实施例所提供的一种枚举元数据示意图；
49.图4为本申请实施例所提供的一种枚举文档的生成装置的结构示意图。
具体实施方式
50.为使本申请实施例的目的、技术方案和优点更加清楚，下面将结合本申请实施例中的附图，对本申请实施例中的技术方案进行清楚、完整地描述，显然，所描述的实施例是本申请一部分实施例，而不是全部的实施例。基于本申请中的实施例，本领域普通技术人员在没有做出创造性劳动前提下所获得的所有其他实施例，都属于本申请保护的范围。
51.在软件开发的生命周期中，除了后端开发人员需要使用枚举，前端开发也需要了解枚举项的定义，比如在性别的枚举中，“0”代表女，“1”代表男，那么当用户在界面上选择“男”时，前端在调用后端接口时需要传递值“1”。在存储数据时，保存到数据库的也是代码，测试人员需要理解枚举的定义，方便开展测试工作。因此在软件开发过程中需要撰写枚举文档，描述每个枚举项对应的详情信息，供前后端开发人员和测试人员阅读，了解枚举的定义。
52.相关技术中，枚举文档均由当前开发人员通过人工的方式撰写枚举的文档。在设计文档撰写的过程中，开发人员完成枚举文档的初始版本。同时在后续开发过程中，随着对业务的理解逐步完善枚举文档的完善。当业务变更时，开发人员也需要不停的对枚举文档进行修订以反映真实代码情况。针对于上述枚举文档生成方式的缺陷，本申请提供以下几种实施方式，可以极大的减少开发人员用于生成枚举文档的时间，解放开发人员的生产力，让开发人员把核心注意力放在实现代码逻辑上，从而提高研发团队的开发效率，更好的满足业务快速发展。
53.下面请参见图1，图1为本申请实施例所提供的一种枚举文档的生成方法的流程图。
54.具体步骤可以包括：
55.s101：获取目标代码文件，并通过程序结构接口解析所述目标代码文件得到psiclass对象；
56.其中，本实施例可以基于intellij平台实现。目标代码文件可以为新提交的代码文件，也可以为历史时刻生成的代码文件，本实施例也不限定目标代码文件的数量和编写语言。在获取目标代码文件之后，本实施例可以通过程序结构接口解析所述目标代码文件得到psiclass对象。
57.其中，程序结构接口即psi(program structure interface)，程序结构接口是
intellij平台中的一层，负责解析文件并创建语法和语义代码模型，以支持该平台的许多功能。psi文件表示psi元素的层次结构(即，psi树)。单个psi文件(本身就是psi元素)可能包含特定编程语言中的多个psi树，即psi元素可以包含其他psi元素。psi元素结构主要用于解析intellij平台的源代码文件的内部结构。例如，可以使用psi元素执行代码分析，执行代码检查或意图动作。psielement类是psi元素的通用基类。一个java类可以解析成psiclass(类)、psimethod(方法)和psifield(字段)等。idea是jetbrains公司开发的，基于intellij平台的java编程语言开发的集成环境。具体的，本实施例可以通过psi机制解析目标代码文件，从中获取psiclass对象。
58.s102：根据psiclass对象确定所述目标代码文件的枚举类；
59.其中，在得到psiclass对象的基础上，本实施例可以调用psiclass对象的isenum方法得到返回值，进而将返回值为ture的psiclass对象设置为目标代码文件的枚举类。
60.s103：将所述枚举类解析为psi树，并根据所述psi树中的元素生成枚举元数据；
61.其中，在得到枚举类之后，本实施例可以对枚举类进行解析得到psi树，根据所述psi树中的元素生成枚举元数据。上述枚举元数据包括枚举类的类名、包名、标题、描述和属性字段。
62.s104：拼接所有所述枚举元数据生成枚举文档。
63.其中，本实施例可以按照各个枚举元数据在目标代码文件中对应的位置顺序拼接各个枚举元数据得到枚举文档；本实施例也可以按照各个枚举元数据的数据类别拼接所有枚举元数据生成枚举文档。
64.枚举文档即记录枚举的文档，枚举(enum)的全称为enumeration，是jdk1.5中开始引入的新特性。在java代码中，被enum关键字修饰的类型就是枚举。java枚举本质上是一个特殊的类，表示一组常量，比如一年的四个季节，一个星期的七天，性别的男女等。通过定义枚举，开发人员可以将常量组织起来，统一进行管理，方便调用和阅读。在开发的过程中，枚举文档的常用场景包括错误码、状态机等。
65.本实施例在获取目标代码文件之后，通过程序结构接口解析所述目标代码文件得到psiclass对象，进而基于psiclass对象确定目标代码文件中的枚举类，通过将枚举类解析为psi树获取枚举元数据，拼接所有的枚举元数据可以得到生成枚举文档。上述过程无需人工参与，通过对目标代码文件进行解析、提取元数据等操作得到枚举元数据自动生成枚举文档，提高了枚举文档的生成效率。
66.作为对于图1对应实施例的进一步介绍，本实施例可以基于模板引擎生成枚举文档，具体过程可以为：读取模板文件内容，并通过调用模板引擎对所述模板文件内容和所述枚举元数据生成文档内容；通过调用文件接口将所述文档内容写入目标文件得到所述枚举文档。进一步的，本实施例可以设置特定的用于存储枚举文档的文件，因此在获取目标代码文件之后，还可以判断系统中是否存储有原枚举文档；若是，则将所述原枚举文档所在的文件设置为所述目标文件，通过上述方式可以实现枚举文档的快速更新。
67.模板引擎为用于使输出结果与业务数据分离的引擎，模版引擎通过把业务数据和模板信息结合，从而最终生成符合格式的文档。模板引擎通过替换，将指定标签替换为业务数据。上述模板引擎可以包括thymeleaf、velocity和freemarker等。
68.作为对于图1对应实施例的进一步介绍，本实施例可以通过以下方式获取目标代
码文件：监听版本控制系统的代码提交事件；若检测到代码提交事件，则获取本次提交的所有代码文件；根据文件类型从本次提交的所有代码文件中获取所述目标代码文件。
69.可以理解的是，代码提交事件对应的本次提交的所有代码文件可以包括多种文件类型，如c++、java、python等语言编写的代码文件。本实施例可以根据文件类型从本次提交的所有代码文件中选取特定语言编写的文件作为目标代码文件。
70.作为对于图1对应实施例的进一步介绍，本实施例可以通过以下方式生成枚举元数据：通过调用所述psiclass对象的getname方法获取枚举类的类名；获取所述psiclass对象的psijavafile对象，并通过调用所述psijavafile对象的getpackagename方法获取枚举类的包名；通过调用所述psiclass对象的getdoccomment方法获取枚举类的注释文本，并利用所述注释文本解析枚举类的标题和描述；获取枚举类的属性字段；拼接所有所述枚举类的类名、包名、标题、描述和属性字段生成所述枚举元数据。
71.进一步的，获取枚举类的属性字段的过程可以包括：获取枚举类的属性；判断所述属性是否为枚举常量；若是，则通过调用枚举项的getargumentlist方法获取枚举项的所有参数，并将枚举项的所有参数设置为所述枚举类的属性字段；若否，则通过获取所述属性的注释文本得到所述枚举类的属性字段。
72.下面通过在实际应用中的实施例说明上述实施例描述的流程。请参见图2和图3，图2为本申请实施例所提供的一种枚举文档生成过程示意图，图3为本申请实施例所提供的一种枚举元数据示意图。本实施例主要包括提取元数据和生成文档两部分。需要说明的是，本实施例阐述的提取过程基于idea展开，但其过程也适用于其他ide软件。同时，本发明阐述的是生成java枚举的文档，但也适用于其他语言的枚举文档的生成。提取元数据具体实现过程如下：
73.步骤1：打开idea时监听vcs(version control system，版本控制系统)提交事件，当用户提交代码时自动触发元数据提取过程。
74.步骤2：获取本次提交的所有文件，从中筛选出java文件。通过psi机制解析java文件，从中获取psiclass对象。需要注意的是，一个java文件可以包含一个或多个类，同时psiclass存在嵌套的可能性，因此从一个java文件中可能获取到多个psiclass对象。
75.步骤3：遍历所有的psiclass对象，调用psiclass对象的isenum()方法判断psiclass对象是否为枚举类，从而获取到该项目的所有的枚举类。
76.步骤4：遍历所有枚举类，解析枚举类成psi树，获取其中的元素，如类名、类所在的包名、属性psifield和javadoc等，具体步骤如下：
77.(1)调用psiclass对象的getname()方法获取类名，如genderenum。
78.(2)获取psiclass对应的psijavafile对象，调用psijavafile对象的getpackagename()方法获取枚举类的包名，如“com.example.enums”。
79.(3)调用psiclass对象的getdoccomment()方法获取枚举类的javadoc，从javadoc中解析出枚举的标题和描述。javadoc的第一行为枚举类的标题，如本例中的“性别枚举”；javadoc的第二行开始为枚举类的描述，如本例中的“这是一个用于描述性别的枚举”。
80.(4)获取枚举类中的所有属性psifield，遍历这些属性，用操作符instanceof判断属性是否为枚举常量psienumconstant。如果不是psienumconstant，则表示此属性为普通属性，如本例中的“code”和“name”。获取属性的javadoc，解析出属性对应的描述，如本例中
“
code”对应的“代码”和“name”对应的“名称”；如果是psienumconstant，则表示此属性为枚举项，如本例中的“male”和“female”。调用枚举项的getargumentlist()方法获取枚举项的所有参数，如male对应的参数为“0”,“女”。解析这些参数，并和普通属性对应，比如本例中“male”的code为“0”，name为“女”。
81.(5)拼接所有获取到的数据，组成此枚举的元数据。
82.步骤5：在获取到枚举的元数据后，可以把元数据进行拼接形成枚举文档，也可以使用模版引擎(如velocity)形成枚举文档。
83.使用markdown格式的velocity模板引擎如下：
84.#${enumtitle}
85.${enumpackage}.${enumnname}
86.##枚举描述
87.${enumdesc}
88.##枚举内容
89.|
‑‑‑
|
‑‑‑
|
‑‑‑
|
90.#foreach($item in$enumltems)
91.|$item[0]|$item[1]|$item[2]|
[0092]
#end
[0093]
markdown是一种轻量级标记语言，通过使用易读易写的纯文本格式编写文档，转换成最终的xhtml(或者html)文档。
[0094]
使用模版引擎生成文档的过程如下：通过java代码，读取模版文件内容；调用模版引擎，根据模版内容和枚举元数据生成枚举文档内容；调用文件接口，把文档内容写入到文件，文件名为“枚举名.md”，如本例中的“genderenum.md”，进而完成枚举文档生成流程。
[0095]
在开发工程中，枚举项目难以避免更新，修改之后需要同步修改文档并通知给相关开发人员和测试人员。在实际的操作过程中，当开发人员删除或则增加一个枚举项项目时，如果没有考虑到枚举类的使用范围或者人为原因的遗漏，会导致代码和文档的不同步，导致信息的不同步。这样容易造成线上的bug，不但浪费时间，也不利于后期问题的排查和项目的维护。通过本实施例，借助intellij平台可以快速自动化的生成和更新枚举文档，保证文档的及时性和有效性，不但节约了开发人员的时间，同时可以避免文档遗漏更新的问题，保证文档的准确性和及时性，减少线上bug和沟通成本。
[0096]
本实施例通过自动生成文档的方式，自动从枚举类中获取相应信息后生成枚举说明文档，不需要额外人工干预，可以保证枚举文档的准确性、及时性和有效性，减少各角色沟通成本和线上bug的产生。同时，每次只需要分析提交的文件(即有变更的文件)，减少分析的文件数量，可以增量生成文档。通过本实施例可以节省开发人员撰写文档的时间，让开发人员可以专注业务逻辑的书写，提高开发人员工作效率。
[0097]
请参见图4，图4为本申请实施例所提供的一种枚举文档的生成装置的结构示意图；
[0098]
该装置可以包括：
[0099]
文件解析模块401，用于获取目标代码文件，并通过程序结构接口解析所述目标代码文件得到psiclass对象；
[0100]
枚举类确定模块402，用于根据所述psiclass对象确定所述目标代码文件的枚举类；
[0101]
元数据生成模块403，用于将所述枚举类解析为psi树，并根据所述psi树中的元素生成枚举元数据；
[0102]
文档生成模块404，用于拼接所有所述枚举元数据生成枚举文档。
[0103]
本实施例在获取目标代码文件之后，通过程序结构接口解析所述目标代码文件得到psiclass对象，进而基于psiclass对象确定目标代码文件中的枚举类，通过将枚举类解析为psi树获取枚举元数据，拼接所有的枚举元数据可以得到生成枚举文档。上述过程无需人工参与，通过对目标代码文件进行解析、提取元数据等操作得到枚举元数据自动生成枚举文档，提高了枚举文档的生成效率。
[0104]
进一步的，在获取目标代码文件之前，还包括：
[0105]
监听版本控制系统的代码提交事件；
[0106]
若检测到代码提交事件，则获取本次提交的所有代码文件；
[0107]
相应的，所述获取目标代码文件，包括：
[0108]
根据文件类型从本次提交的所有代码文件中获取所述目标代码文件。
[0109]
进一步的，枚举类确定模块402用于调用所述psiclass对象的isenum方法，得到返回值；还用于将返回值为ture的psiclass对象设置为目标代码文件的枚举类。
[0110]
进一步的，元数据生成模块403包括：
[0111]
类名获取单元，用于通过调用所述psiclass对象的getname方法获取枚举类的类名；
[0112]
包名获取单元，用于获取所述psiclass对象的psijavafile对象，并通过调用所述psijavafile对象的getpackagename方法获取枚举类的包名；
[0113]
标题及描述获取单元，用于通过调用所述psiclass对象的getdoccomment方法获取枚举类的注释文本，并利用所述注释文本解析枚举类的标题和描述；
[0114]
属性字段获取单元，用于获取枚举类的属性字段；
[0115]
元素拼接单元，用于拼接所有所述枚举类的类名、包名、标题、描述和属性字段生成所述枚举元数据。
[0116]
进一步的，属性字段获取单元，用于获取枚举类的属性；还用于判断所述属性是否为枚举常量；若是，则通过调用枚举项的getargumentlist方法获取枚举项的所有参数，并将枚举项的所有参数设置为所述枚举类的属性字段；若否，则通过获取所述属性的注释文本得到所述枚举类的属性字段。
[0117]
进一步的，文档生成模块404用于读取模板文件内容，并通过调用模板引擎对所述模板文件内容和所述枚举元数据生成文档内容；还用于通过调用文件接口将所述文档内容写入目标文件得到所述枚举文档。
[0118]
进一步的，还包括：
[0119]
文件选取模块，用于在获取目标代码文件之后，判断系统中是否存储有原枚举文档；若是，则将所述原枚举文档所在的文件设置为所述目标文件。
[0120]
由于装置部分的实施例与方法部分的实施例相互对应，因此装置部分的实施例请参见方法部分的实施例的描述，这里暂不赘述。
[0121]
本申请还提供了一种存储介质，其上存有计算机程序，该计算机程序被执行时可以实现上述实施例所提供的步骤。该存储介质可以包括：u盘、移动硬盘、只读存储器(read
‑
only memory，rom)、随机存取存储器(random access memory，ram)、磁碟或者光盘等各种可以存储程序代码的介质。
[0122]
本申请还提供了一种电子设备，可以包括存储器和处理器，所述存储器中存有计算机程序，所述处理器调用所述存储器中的计算机程序时，可以实现上述实施例所提供的步骤。当然所述电子设备还可以包括各种网络接口，电源等组件。
[0123]
说明书中各个实施例采用递进的方式描述，每个实施例重点说明的都是与其他实施例的不同之处，各个实施例之间相同相似部分互相参见即可。对于实施例公开的装置而言，由于其与实施例公开的方法相对应，所以描述的比较简单，相关之处参见方法部分说明即可。应当指出，对于本技术领域的普通技术人员来说，在不脱离本申请原理的前提下，还可以对本申请进行若干改进和修饰，这些改进和修饰也落入本申请权利要求的保护范围内。
[0124]
还需要说明的是，在本说明书中，诸如第一和第二等之类的关系术语仅仅用来将一个实体或者操作与另一个实体或操作区分开来，而不一定要求或者暗示这些实体或操作之间存在任何这种实际的关系或者顺序。而且，术语“包括”、“包含”或者其任何其他变体意在涵盖非排他性的包含，从而使得包括一系列要素的过程、方法、物品或者设备不仅包括那些要素，而且还包括没有明确列出的其他要素，或者是还包括为这种过程、方法、物品或者设备所固有的要素。在没有更多限制的状况下，由语句“包括一个
……”
限定的要素，并不排除在包括所述要素的过程、方法、物品或者设备中还存在另外的相同要素。