Skip to content

Commit 9958bea

Browse files
cyw3cyw3
authored
📝 Add tool docs (#546)
* 📝 Add tool docs Signed-off-by: cyw3 <2927096163@qq.com> * 📝 Update tool docs Signed-off-by: cyw3 <2927096163@qq.com> Signed-off-by: cyw3 <2927096163@qq.com>
1 parent c13f1d9 commit 9958bea

File tree

8 files changed

+484
-0
lines changed

8 files changed

+484
-0
lines changed

‎doc/.vuepress/configs/sidebar/en.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,14 @@ export const en: SidebarConfig = {
2121
text: '代码检查',
2222
children: [
2323
'/en/guide/代码检查/分析结果查看.md',
24+
'/en/guide/代码检查/添加规则配置.md',
25+
{
26+
text: '典型工具接入指引',
27+
children: [
28+
'/en/guide/代码检查/工具/eslint.md',
29+
'/en/guide/代码检查/工具/golangcilint.md',
30+
],
31+
},
2432
]
2533
},
2634
{

‎doc/.vuepress/configs/sidebar/zh.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,14 @@ export const zh: SidebarConfig = {
2121
text: '代码检查',
2222
children: [
2323
'/zh/guide/代码检查/分析结果查看.md',
24+
'/zh/guide/代码检查/添加规则配置.md',
25+
{
26+
text: '典型工具接入指引',
27+
children: [
28+
'/zh/guide/代码检查/工具/eslint.md',
29+
'/zh/guide/代码检查/工具/golangcilint.md',
30+
],
31+
},
2432
]
2533
},
2634
{

‎doc/en/guide/代码检查/工具/eslint.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Eslint 使用手册
2+
3+
代码分析支持 Eslint 分析，并支持用户自由扩展配置。
4+
5+
## 适用场景
6+
7+
目前 TCA-Eslint 的适用场景很广，灵活扩展：
8+
9+
- JavaScript
10+
- TypeScript
11+
- React
12+
- Vue
13+
- Google 代码规范分析
14+
- 其他，包括项目自己维护的 Eslint 配置
15+
16+
## 快速接入
17+
18+
以下是接入步骤：
19+
20+
1. 在代码分析创建项目，会自动匹配 JavaScript 或者 TypeScript 对应的推荐规则集
21+
2. 启动分析即可
22+
23+
## 高级配置
24+
25+
### 基础概念
26+
27+
在进行高级配置之前，这里先普及下代码分析这边的基础概念——Eslint 类型。
28+
由于 JavaScript 语法、 Vue 语法和 TypeScript 语法之间的区别，三者使用的语法解析器也是不一样的，这里基于其使用的语法解析器的不同，从 Eslint 中拆分出来了 Eslint_vue 和 Eslint_typescript 工具。可以根据需要选择对应工具下的规则进行分析。而配置也会基于类型的不同匹配到对应的工具中。
29+
目前代码分析上 Eslint 类型有：
30+
31+
- JAVASCRIPT
32+
分析 JavaScript 以及基于 JavaScript 写的 React 代码，默认分析文件后缀名为.js,.jsx
33+
- VUE
34+
分析 Vue 框架的代码，默认分析文件后缀名为.vue
35+
- TYPESCRIPT
36+
分析 TypeScript 以及基于 TypeScript 写的 React 代码，默认分析文件后缀名为.ts,tsx
37+
38+
### 设置 Globals
39+
40+
因为项目会用到各式各样的框架，其中会有全局变量是 Eslint 无法识别到的，比如 `_` 或者 jtest，从而导致分析出不少误报。这里支持使用下面环境变量设置这些全局变量，减少误报。可以在代码分析项目中设置对应的环境变量。
41+
42+
| 环境变量名称 | 描述 |
43+
| :------------------------ | :----------------- |
44+
| ESLINT_JAVASCRIPT_GLOBALS | 字符串，以分号分割 |
45+
| ESLINT_VUE_GLOBALS | 字符串，以分号分割 |
46+
| ESLINT_TYPESCRIPT_GLOBALS | 字符串，以分号分割 |
47+
48+
比如：
49+
50+
```shell
51+
ESLINT_JAVASCRIPT_GLOBALS=_:readonly;jtest:readonly
52+
```
53+
54+
其中，
55+
56+
- writable 表示允许重写变量
57+
- readonly 表示不允许重写变量
58+
- off 表示禁用该全局变量
59+
60+
### 指定参数配置文件
61+
62+
代码分析执行 Eslint 分析，默认会使用 Alloy Team 的 Eslint 配置来分析，但是也支持修改配置。
63+
64+
1. 在代码库中创建一个参数配置 Json 文件，结果类似 Eslint 的 Json 配置文件
65+
2. 在代码分析项目设置下面对应环境变量，指向这个参数配置文件
66+
指定了参数配置文件之后，Eslint 分析时候就会自动将代码分析默认的配置与该参数配置文件进行合并。
67+
3. 启动全量分析即可
68+
69+
| 环境变量名称 | 描述 |
70+
| :------------------------ | :--------------------------- |
71+
| ESLINT_JAVASCRIPT_OPTIONS | 字符串，相对代码库根目录路径 |
72+
| ESLINT_VUE_OPTIONS | 字符串，相对代码库根目录路径 |
73+
| ESLINT_TYPESCRIPT_OPTIONS | 字符串，相对代码库根目录路径 |
74+
75+
### 指定 Eslint 配置文件
76+
77+
代码分析也支持用户指定自己维护的 Eslint 配置文件进行分析。
78+
79+
| 环境变量名称 | 描述 |
80+
| :----------------------- | :--------------------------- |
81+
| ESLINT_JAVASCRIPT_CONFIG | 字符串，相对代码库根目录路径 |
82+
| ESLINT_VUE_CONFIG | 字符串，相对代码库根目录路径 |
83+
| ESLINT_TYPESCRIPT_CONFIG | 字符串，相对代码库根目录路径 |
84+
85+
### 设置配置类型
86+
87+
代码分析自带支持 Google 代码规范，可以在代码分析项目设置对应环境变量，使用对应的配置文件。
88+
89+
| 环境变量名称 | 描述 |
90+
| :---------------------------- | :---------------------------------------------- |
91+
| ESLINT_JAVASCRIPT_CONFIG_TYPE | 字符串, google,default,custom |
92+
| ESLINT_VUE_CONFIG_TYPE | 字符串, 可选：default,custom |
93+
| ESLINT_TYPESCRIPT_CONFIG_TYPE | 字符串, 可选：default,custom |
94+
95+
其中：
96+
97+
- google，表示使用 google 代码规范配置文件
98+
- default，表示使用代码分析维护的配置文件
99+
- custom，表示使用项目代码库中 Eslint 配置文件
100+
101+
### 配置优先顺序
102+
103+
这里介绍 TCA-Eslint 的配置使用顺序：
104+
105+
1. 优先检查是否设置对应的 ESLINT_CONFIG 环境变量，比如 ESLINT_JAVASCRIPT_CONFIG
106+
2. 然后检查是否设置对应的 ESLINT_CONFIG_TYPE 环境变量，比如 ESLINT_JAVASCRIPT_CONFIG_TYPE
107+
3. 若是 JAVASCRIPT 类型的项目，会自动检测代码库根目录下是否有 ESLINT 配置文件，若有则使用该配置文件进行分析，其他类型的项目便不会有这一步
108+
4. 使用代码分析维护的 Alloy Team 的配置文件进行分析
109+
110+
### 分析路径配置
111+
112+
可以在代码分析页面上设置分析路径设置，这里建议多使用 Exclude 设置，因为 Eslint 工具本身对 include 支持不友好。
113+
114+
## Q&A
115+
116+
Q：JavaScript 内存溢出
117+
118+
A：Eslint 执行可能会出现 Js 内存溢出，以下有三种方案可以解决：
119+
120+
- 可以设置环境变量 NODE_OPTIONS，比如
121+
122+
```shell
123+
NODE_OPTIONS="--max-old-space-size=4096"
124+
```
125+
126+
- 设置环境变量 ESLINT_MAX_OLD_SPACE_SIZE，比如
127+
128+
```shell
129+
ESLINT_MAX_OLD_SPACE_SIZE=4096
130+
```
131+
132+
- 设置分析路径过滤，将无用的文件进行过滤
133+
134+
Q：一个配置同时分析 JS 和 TS
135+
136+
A：若代码库中既有 JavaScript 代码，又有 TypeScript 代码，并且共用一个配置文件。
137+
若规则集中既有 Eslint 规则又有 Eslint_typescript 规则，为了避免执行两次 Eslint 以及可能出现重复单的情况，并且因为 Eslint_typescript 的语法解析器也能够解析 JavaScript 代码，所以这里将这样的项目当作 TypeScript 项目。
138+
139+
1. 这里建议只指定 ESLINT_TYPESCRIPT_CONFIG 环境变量
140+
2. 规则集中剔除 Eslint 的规则，只保留 Eslint_typescript 规则。
141+
3. 并指定 ESLINT_TYPESCRIPT_EXT=.js,.jsx,.ts,.tsx
142+
143+
Q：找不到依赖
144+
145+
A：用户自己配置的配置文件中，可能会用到代码分析没有管理到的规则插件，导致分析时候找不到对应的依赖，这里有两个方案提供解决：
146+
147+
- 在代码库根目录下 npm 安装对应插件，并设置分析路径过滤 node_modules
148+
149+
Q：custom 与指定配置文件的区别
150+
151+
A：- custom 模式，会检测代码库中的 Eslint 配置文件进行分析，包括子目录和代码注释中设置的配置，都是可以生效的。
152+
153+
- 相对的，指定配置文件的方式，只会对指定的配置文件中的配置会生效。

‎doc/en/guide/代码检查/工具/golangcilint.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# [Golangcilint](https://github.com/golangci/golangci-lint) 使用手册
2+
3+
## 对比 GoMetaLinter
4+
5+
Golangci-lint 是为了解决 GoMetalinter 的弊端而改版升级的。
6+
7+
1. 比 GoMetaliner 快个 2 到 7 倍
8+
9+
2. 共享代码缓存，消耗内存比 Gometaliner 少 26%
10+
11+
3. 更精准的 issue，会内置一些 exclude 列表过滤掉误报 issue
12+
13+
4. 支持增量分析
14+
15+
## 快速接入
16+
17+
1. 在 CI 系统上选用 TCA 插件，或者下载 TCA 客户端到本地机器上
18+
19+
2. 因为 GolangCiLint 要求找寻到项目需要的全部依赖，否则就会执行失败。所以这里需要在 Ci 系统或者本地机器上配置好项目的依赖，并确保能够**编译通过**
20+
21+
3. 检查是否设置了 GOPATH 和 GOROOT，在分析方案的环境变量中设置 `GOPATH=$GOPATH`
22+
23+
4. 在 代码分析 页面上关联待分析的代码库并创建分析方案，并在代码检查-规则设置的自定义规则包里面添加 GolangCiLint 工具规则
24+
25+
5. 在分析方案中增加编译命令
26+
27+
6. 然后在 CI 系统上或者本地启动代码分析即可
28+
29+
## 高级配置
30+
31+
### Include
32+
33+
若项目目录结构如下图，需要设置 include 执行 myproj，比如 src/myproj/\*
34+
35+
这是因为 GolangCiLint 分析前会优先检查所有代码文件的依赖是否齐全，所以需要设置 include，让工具只关注 include 下面的代码文件的依赖。
36+
37+
在分析方案的过滤配置，路径过滤中添加 include 路径。
38+
39+
![include](../../../../images/golangcilint.jpg)
40+
41+
## Q&A
42+
43+
- **Q：出现 no go files to analyze 问题**
44+
45+
**A：这里可能为以下原因：**
46+
47+
1. 机器环境没有项目的完整依赖，使用以下命令查找对应依赖在 GOPATH 下是否存在或者 GOPATH 设置是否完整（有的项目有多个 GOPATH 内容），或者对应依赖是否存在，需要用户部署好机器环境
48+
49+
```BASH
50+
grep -nr "path/to/GOPATH" .
51+
```
52+
53+
2. 没有指定 include 分析路径过滤，这样才不会检查依赖中的依赖，而是关注源码文件的依赖完整性
54+
55+
3. 也可能是某 go 文件中使用到该依赖，但是 GOPATH 没有设置正确的依赖搜索路径导致。需要找到依赖相对的当前目录：
56+
57+
```BASH
58+
grep -nr "path/to/GOPATH" .
59+
```
60+
61+
然后设置到 GOPATH 中，比如
62+
63+
```BASH
64+
GOPATH=$GOPATH:$SOURCE_DIR/test
65+
```
66+
67+
4. 还有可能是部分依赖是需要编译之后生成的，需要正确填写好编译命令，使得项目编译成功。
68+
69+
- **Q：could not determine GOARCH and Go compiler 问题**
70+
71+
**A：跟问题 1 是一样的问题。解决方案也是一样。**
72+
73+
- **Q：failed to run 'go env': exit status 1 问题**
74+
75+
**A：原因是找不到正确的 GOPATH。解决方案是设置 GOPATH 环境变量。**
76+
77+
- **Q：GO 版本限制**
78+
79+
**A：因为 golangci-lint 用到了 go mod 特性，该特性是在 1.11 之后才有的。所以要求 go 版本在 1.11 版本以上。**
80+
81+
![go版本限制](../../../../images/golangcilintversion.jpg)

‎doc/images/golangcilint.jpg‎

56.6 KB
Loading

‎doc/images/golangcilintversion.jpg‎

303 KB
Loading

0 commit comments

Comments
 (0)