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