README_zh.md
1
2将相关文件按规则解析成特定格式，提供处理接口
3
4## 目录
5
6```
7
8├─src #工具代码
9| ├─bin #命令行执行配置
10| | ├─config.ts
11| | ├─index.ts
12| | └─writer.ts
13| ├─coreImpl #工具实现的功能及接口
14| | ├─checker #检查声明文件中的格式规范
15| | | ├─config #存放检查工具运行所需要的一些配置文件
16| | | ├─src #工具代码
17| | | ├─local_entry.ts #检查工具入口文件
18| | ├─diff #比较两个版本sdk差异的工具
19| | | ├─diff.ts #实现工具的对外接口
20| | | ├─DiffProcessor.ts
21| | | └─PermissionsProcessor.ts #逻辑运算工具，用于判断权限范围变化
22| | ├─parser #基础解析工具
23| | | ├─JsDocProcessor.ts
24| | | ├─NodeProcessor.ts
25| | | ├─parser.ts #实现工具的对外接口
26| | | └─ResultsProcess.ts #将parser解析完的结果处理为其他接口需要的格式
27| | └─statistics #api统计工具
28| | └─Statistics.ts
29| ├─typedef #每个工具中class，type的定义
30| | ├─diff
31| | | └─ApiInfoDiff.ts
32| | ├─parser
33| | | ├─ApiInfoDefination.ts
34| | | ├─comment.ts
35| | | └─ResultsInfo.ts
36| | └─statistics
37| | └─ApiStatistics.ts
38| ├─utils #通用方法
39| | ├─Constant.ts #全局静态常量
40| | ├─FileUtils.ts #文件工具
41| | ├─logUtil.ts #log日志工具
42| | ├─FunctionUtils.ts #公共方法
43| | └─StringUtils.ts #字符串数据处理工具
44| └─main.ts #commander调用入口
45├─test #工具自动化测试配置及用例
46| ├─expect #测试用例结果检验，与测试用例输出结果进行对比，每个工具单独新建子文件
47| ├─mocha #mocha相关配置
48| ├─output #测试用例执行输出结果
49| ├─testCase #测试用例调用工具接口
50| | └─runTest.ts
51| └─ut #测试用例，每个工具单独新建子文件
52
53```
54
55## 工具说明
56
57### 基础解析工具
58
59[代码](src/coreImpl/parser/parser.ts)
60
61提供接口
62
631. parseDir(fileDir)
64 解析一个文件夹下的文件，返回所有数据
652. parseFile(fileDir,filePath)
66 解析单个文件，fileDir为根节点，需要用来计算相对路径
673. getApiInfo(locations,apiMap)
68 将层级关系和通过上述两个接口的返回值可以直接获取对应节点
694. getParseResults(apiMap)
70 将接口1、2的树形结构的数据遍历展开
715. getParseEachSince(apiMap)
72 将接口1、2的树形结构的数据遍历展开，进行特殊处理，根据since来区分子节点
73
74### check工具（线上版本）
75
76[代码](src/coreImpl/checker/local_entry.ts)
77
78提供接口
79
801. checkEntryLocal(filePathArr, fileRuleArr, output, prId, excel)
81 根据传入的文件路径和检查规则检查文件中存在的规范错误
82
83工具调用命令
84
85```
86node --nolazy -r ts-node/register ./src/main.ts -N checkOnline --path 待检查文件路径（非build-tools） --checker 检查规则 --prId 兼容性检查文件路径 --output 报告输出目录 --excel false
87```
88
89### check工具（线下版本）
90
91[代码](src/coreImpl/checker/local_entry.ts)
92
93提供接口
94
951. checkEntryLocal(filePathArr, fileRuleArr, output, prId, excel)
96 根据传入的文件路径和检查规则检查文件中存在的规范错误（默认生成excel表格，默认不执行兼容性变更校验）
972. 打开interface_sdk-js\build-tools\mdFiles.txt文件，将待检查文件的路径填入此文件。
98 注意：文件名与文件名之间直接换行，行尾无需加任何符号。
99
100工具调用命令
101
102```
103node --nolazy -r ts-node/register ./src/main.ts -N check
104```
105
106### api change check工具
107
108[代码](src/coreImpl/checker/local_entry.ts)
109
110提供接口
111
1121. apiChangeCheckEntryLocal(prId, fileRuleArr, output, excel)
113 根据传入的文件路径和检查规则检查文件中存在的修改不兼容规范错误
114
115工具调用命令
116
117```
118node --nolazy -r ts-node/register ./src/main.ts -N apiChangeCheck --prId 待检查文件路径 --checker 检查规则 --output 报告输出目录 --excel false
119```
120
121### diff工具
122
123[代码](src/coreImpl/diff/diff.ts)
124
125提供接口
126
1271. diffSDK(oldSDKApiMap,newSDKApiMap)
128 将两个版本的文件通过基础解析工具解析之后，传入两个结果计算diff
129
130工具调用命令
131
132```
133node --nolazy -r ts-node/register ./src/main.ts -N diff --old 旧版本目录/文件（sdk/windows/ets） --new 新版本目录/文件（sdk/windows/ets) --old-version 旧版本号 --new-version 新版本号 --output 报告输出目录 --format excel
134```
135
136### api统计工具
137
138[代码](src/coreImpl/statistics/ApiStatistics.ts)
139
140提供接口
141
1421. getApiStatisticsInfos(apiMap)
143 将文件通过基础解析工具解析之后，传入计算api接口
144
145工具调用命令
146
147```
148node --nolazy -r ts-node/register ./src/main.ts -N collect -C 目录路径/文件路径 --output 报告输出目录 --format excel
149```
150
151### 元服务API集标签检测工具
152
153[代码](..\api_label_detection\src\main.py)
154
155对于元服务标签@atomicservice的漏标误标场景做出识别，辅助API标签排查，将不符合规定标签详情信息汇总至Excel表格中输出.也可根据需求对@form、@crossplatform标签进行校验
156
157工具调用命令
158
159```
160node --nolazy -r ts-node/register ./src/main.ts -N detection -L 验证标签 -C api全文件 -F 统计目录/文件 -O 报告输出目录
161```
162
163详细内容见[元服务API集标签检测工具](..\api_label_detection\README_zh.md)
164
165## 工具xiangx调用
166
167通过commander调用相关工具，[调用入口](src/main.ts)只有（src/main.ts），到当前目录下，执行命令 ts-node ./src/main.ts 后接相关参数。
168
169### 参数配置
170
171 -N,--tool-name <collect, diff> tool name (default: "collect")
172 -V, --version output the version number
173 -C,--collect-Path `<string>` collect api path (default: "./api")
174 --path `<string>` check file path
175 --checker `<string>` check file rule
176 --prId `<string>` check file change rule
177 --excel `<string>` check ouput file contain excel
178 --old `<string>` diff old sdk path (default: "./api")
179 --new `<string>` diff new sdk path (default: "./api")
180 --old-version `<string>` old sdk version (default: "0")
181 --new-version `<string>` new sdk version (default: "0")
182 --output `<string>` output file path (default: "./")
183 --format <json, excel, changelog> output file format (default: "json")
184 --changelogUrl `<string>` changelog url (default: "")
185 -h, --help display help for command
186
187例如
188
189```
190ts-node ./src/main.ts '-N' 'diff' '-C' '.\test\ut\parser\ut_jsdoc_constant_001.d.ts' '--old' '.\test\ut\apiDiff\old\ut_api_name_change.d.ts' '--new' '.\test\ut\apiDiff\new\ut_api_name_change.d.ts' '--old-version' '1' '--new-version' '2' '--output' '.\'
191```
192
193```
194node --nolazy -r ts-node/register ./src/main.ts '-N' 'diff' '-C' '.\test\ut\parser\ut_jsdoc_constant_001.d.ts' '--old' '.\test\ut\apiDiff\old\ut_api_name_change.d.ts' '--new' '.\test\ut\apiDiff\new\ut_api_name_change.d.ts' '--old-version' '1' '--new-version' '2' '--output' '.\'
195```
196
197```
198node ./package/JS_API_OPTIMIZE_PLUGIN.js '-N' 'diff' '-C' '.\test\ut\parser\ut_jsdoc_constant_001.d.ts' '--old' '.\test\ut\apiDiff\old\ut_api_name_change.d.ts' '--new' '.\test\ut\apiDiff\new\ut_api_name_change.d.ts' '--old-version' '1' '--new-version' '2' '--output' '.\'
199```
200
201## 工具开发注意事项
202
2031、禁止全量工具使用__dirname
204
205可以通过import src\utils\FileUtils.ts，通过FileUtils.getBaseDirName，获取当前项目的根目录，之后在通过文件相对路径获取文件
206
207## 项目启动
208
209项目分为线上运行和线下运行
210
211### 本地运行
212
2131. 先确认本地node版本是否为14版本，本工具只支持使用14版本的node
2142. 运行以下脚本安装相关依赖
215
216```
217npm install
218```
219
220安装完成之后根据目录和注意事项完成工具开发或测试
221
222### 线上运行
223
224线上存在需要打包生成bundle.js文件
225
2261、安装依赖，在全量仓下执行安装依赖命令
227
228```
229npm install
230```
231
2322、执行打包命令，将ts打包为js
233
234```
235npm run build
236```
237
238执行完之后生成./package/JS_API_OPTIMIZE_PLUGIN.js
239
2403、根据上方的工具调用说明，通过node和参数来调用相关方法
241
242例如
243
244```
245node ./package/JS_API_OPTIMIZE_PLUGIN.js '-N' 'diff' '-C' '.\test\ut\parser\ut_jsdoc_constant_001.d.ts' '--old' '.\test\ut\apiDiff\old\ut_api_name_change.d.ts' '--new' '.\test\ut\apiDiff\new\ut_api_name_change.d.ts' '--old-version' '1' '--new-version' '2' '--output' '.\'
246```
247