237 lines
4.6 KiB
Markdown
237 lines
4.6 KiB
Markdown
|
# Go Linting 配置說明
|
|||
|
|
|
|||
|
|
本項目使用現代化的 Go linting 工具來確保代碼質量和風格一致性。
|
|||
|
|
|
|||
|
|
## 工具介紹
|
|||
|
|
|
|||
|
|
### golangci-lint
|
|||
|
|
- **現代化的 Go linter 聚合工具**，整合了多個 linter
|
|||
|
|
- 比傳統的 `golint` 更快、更全面
|
|||
|
|
- 支持並行執行和緩存
|
|||
|
|
- 配置文件：`.golangci.yml`
|
|||
|
|
|
|||
|
|
## 安裝
|
|||
|
|
|
|||
|
|
### 安裝 golangci-lint
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# macOS
|
|||
|
|
brew install golangci-lint
|
|||
|
|
|
|||
|
|
# Linux
|
|||
|
|
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.55.2
|
|||
|
|
|
|||
|
|
# Windows
|
|||
|
|
go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.55.2
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 安裝其他工具
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 格式化工具
|
|||
|
|
go install mvdan.cc/gofumpt@latest
|
|||
|
|
go install golang.org/x/tools/cmd/goimports@latest
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 使用方法
|
|||
|
|
|
|||
|
|
### Makefile 命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 基本代碼檢查
|
|||
|
|
make lint
|
|||
|
|
|
|||
|
|
# 自動修復可修復的問題
|
|||
|
|
make lint-fix
|
|||
|
|
|
|||
|
|
# 詳細輸出
|
|||
|
|
make lint-verbose
|
|||
|
|
|
|||
|
|
# 只檢查新問題（與 main 分支比較）
|
|||
|
|
make lint-new
|
|||
|
|
|
|||
|
|
# 格式化代碼
|
|||
|
|
make fmt
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 直接使用 golangci-lint
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 基本檢查
|
|||
|
|
golangci-lint run
|
|||
|
|
|
|||
|
|
# 自動修復
|
|||
|
|
golangci-lint run --fix
|
|||
|
|
|
|||
|
|
# 檢查特定目錄
|
|||
|
|
golangci-lint run ./pkg/...
|
|||
|
|
|
|||
|
|
# 詳細輸出
|
|||
|
|
golangci-lint run -v
|
|||
|
|
|
|||
|
|
# 只顯示新問題
|
|||
|
|
golangci-lint run --new-from-rev=main
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 配置說明
|
|||
|
|
|
|||
|
|
### 啟用的 Linters
|
|||
|
|
|
|||
|
|
我們的配置啟用了以下 linter 類別：
|
|||
|
|
|
|||
|
|
#### 核心檢查
|
|||
|
|
- `errcheck`: 檢查未處理的錯誤
|
|||
|
|
- `gosimple`: 簡化代碼建議
|
|||
|
|
- `govet`: 檢查常見錯誤
|
|||
|
|
- `staticcheck`: 靜態分析
|
|||
|
|
- `typecheck`: 類型檢查
|
|||
|
|
- `unused`: 檢查未使用的變量和函數
|
|||
|
|
|
|||
|
|
#### 代碼質量
|
|||
|
|
- `cyclop`: 循環複雜度檢查
|
|||
|
|
- `dupl`: 代碼重複檢測
|
|||
|
|
- `funlen`: 函數長度檢查
|
|||
|
|
- `gocognit`: 認知複雜度檢查
|
|||
|
|
- `gocyclo`: 循環複雜度檢查
|
|||
|
|
- `nestif`: 嵌套深度檢查
|
|||
|
|
|
|||
|
|
#### 格式化
|
|||
|
|
- `gofmt`: 格式化檢查
|
|||
|
|
- `gofumpt`: 更嚴格的格式化
|
|||
|
|
- `goimports`: 導入排序
|
|||
|
|
|
|||
|
|
#### 命名和風格
|
|||
|
|
- `goconst`: 常量檢查
|
|||
|
|
- `gocritic`: 代碼評論
|
|||
|
|
- `gomnd`: 魔術數字檢查
|
|||
|
|
- `stylecheck`: 風格檢查
|
|||
|
|
- `varnamelen`: 變量名長度檢查
|
|||
|
|
|
|||
|
|
#### 安全
|
|||
|
|
- `gosec`: 安全檢查
|
|||
|
|
|
|||
|
|
#### 錯誤處理
|
|||
|
|
- `errorlint`: 錯誤處理檢查
|
|||
|
|
- `nilerr`: nil 錯誤檢查
|
|||
|
|
- `wrapcheck`: 錯誤包裝檢查
|
|||
|
|
|
|||
|
|
### 配置文件結構
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
# .golangci.yml
|
|||
|
|
run:
|
|||
|
|
timeout: 5m
|
|||
|
|
skip-dirs: [vendor, .git, bin, build, dist, tmp]
|
|||
|
|
skip-files: [".*\\.pb\\.go$", ".*\\.gen\\.go$"]
|
|||
|
|
|
|||
|
|
linters:
|
|||
|
|
disable-all: true
|
|||
|
|
enable: [errcheck, gosimple, govet, ...]
|
|||
|
|
|
|||
|
|
linters-settings:
|
|||
|
|
# 各個 linter 的詳細配置
|
|||
|
|
|
|||
|
|
issues:
|
|||
|
|
# 問題排除規則
|
|||
|
|
exclude-rules:
|
|||
|
|
- path: _test\.go
|
|||
|
|
linters: [gomnd, funlen, dupl]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## IDE 整合
|
|||
|
|
|
|||
|
|
### VS Code
|
|||
|
|
項目包含 `.vscode/settings.json` 配置：
|
|||
|
|
- 自動使用 golangci-lint 進行檢查
|
|||
|
|
- 保存時自動格式化
|
|||
|
|
- 使用 gofumpt 作為格式化工具
|
|||
|
|
|
|||
|
|
### GoLand/IntelliJ
|
|||
|
|
1. 安裝 golangci-lint 插件
|
|||
|
|
2. 在設置中指向項目的 `.golangci.yml` 文件
|
|||
|
|
|
|||
|
|
## CI/CD 整合
|
|||
|
|
|
|||
|
|
### GitHub Actions
|
|||
|
|
項目包含 `.github/workflows/ci.yml`：
|
|||
|
|
- 自動運行測試
|
|||
|
|
- 執行 golangci-lint 檢查
|
|||
|
|
- 安全掃描
|
|||
|
|
- 依賴檢查
|
|||
|
|
|
|||
|
|
### 本地 Git Hooks
|
|||
|
|
可以設置 pre-commit hook：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
#!/bin/sh
|
|||
|
|
# .git/hooks/pre-commit
|
|||
|
|
make lint
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 常見問題
|
|||
|
|
|
|||
|
|
### 1. 如何忽略特定的檢查？
|
|||
|
|
|
|||
|
|
在代碼中使用註釋：
|
|||
|
|
```go
|
|||
|
|
//nolint:gosec // 忽略安全檢查
|
|||
|
|
password := "hardcoded"
|
|||
|
|
|
|||
|
|
//nolint:lll // 忽略行長度檢查
|
|||
|
|
url := "https://very-long-url-that-exceeds-line-length-limit.com/api/v1/endpoint"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 如何為測試文件設置不同的規則？
|
|||
|
|
|
|||
|
|
配置文件中已經為測試文件設置了特殊規則：
|
|||
|
|
```yaml
|
|||
|
|
exclude-rules:
|
|||
|
|
- path: _test\.go
|
|||
|
|
linters: [gomnd, funlen, dupl, lll, goconst]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 如何調整複雜度閾值？
|
|||
|
|
|
|||
|
|
在 `.golangci.yml` 中調整：
|
|||
|
|
```yaml
|
|||
|
|
linters-settings:
|
|||
|
|
cyclop:
|
|||
|
|
max-complexity: 15 # 調整循環複雜度
|
|||
|
|
funlen:
|
|||
|
|
lines: 100 # 調整函數行數限制
|
|||
|
|
statements: 50 # 調整語句數限制
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 性能優化
|
|||
|
|
|
|||
|
|
- 使用緩存：`golangci-lint cache clean` 清理緩存
|
|||
|
|
- 只檢查修改的文件：`--new-from-rev=main`
|
|||
|
|
- 並行執行：默認已啟用
|
|||
|
|
|
|||
|
|
## 升級和維護
|
|||
|
|
|
|||
|
|
定期更新 golangci-lint：
|
|||
|
|
```bash
|
|||
|
|
# 檢查版本
|
|||
|
|
golangci-lint version
|
|||
|
|
|
|||
|
|
# 升級到最新版本
|
|||
|
|
brew upgrade golangci-lint # macOS
|
|||
|
|
# 或重新下載安裝腳本
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
定期檢查配置文件的新選項和 linter：
|
|||
|
|
```bash
|
|||
|
|
# 查看所有可用的 linter
|
|||
|
|
golangci-lint linters
|
|||
|
|
|
|||
|
|
# 查看配置幫助
|
|||
|
|
golangci-lint config -h
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 參考資源
|
|||
|
|
|
|||
|
|
- [golangci-lint 官方文檔](https://golangci-lint.run/)
|
|||
|
|
- [Go 代碼風格指南](https://github.com/golang/go/wiki/CodeReviewComments)
|
|||
|
|
- [Effective Go](https://golang.org/doc/effective_go.html)
|