beltranaceves/uber-go-lint-style
GitHub: beltranaceves/uber-go-lint-style
一个针对 Uber Go 风格规范的 golangci-lint 插件，用于静态检查和强制执行 Uber 内部 Go 代码标准。
Stars: 0 | Forks: 0
# uber-go-lint-style
[](https://github.com/beltranaceves/uber-go-lint-style/actions/workflows/go-test.yml)
[](https://codecov.io/gh/beltranaceves/uber-go-lint-style)
[](https://goreportcard.com/report/github.com/beltranaceves/uber-go-lint-style)
A golangci-lint plugin for [Uber's Go Style Guide](https://github.com/uber-go/guide).
## 目录
- [Overview](#overview)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Setup Option 1: Automated Setup (Recommended)](#setup-option-1-automated-setup-recommended)
- [Setup Option 2: Manual Configuration](#setup-option-2-manual-configuration)
- [Rules](#rules)
- [Development](#development)
- [Project Structure](#project-structure)
- [Adding a New Rule](#adding-a-new-rule)
- [Running Tests](#running-tests)
- [Contributing](#contributing)
- [Resources](#resources)
## 概述
This is a custom linter that strives to enforce Uber's internal Go coding standards through static analysis. It's designed to catch style violations early and guide developers toward safer, more maintainable code patterns.
## 安装
### 先决条件
- Go 1.23+
- golangci-lint 1.59.0+ ([Install docs](https://golangci-lint.run/usage/install/))
Follow these steps:
### 设置选项 1：自动化设置（推荐）
Run the setup script to auto-generate configuration files:
```
go run github.com/beltranaceves/uber-go-lint-style/cmd/setup@latest
```
This creates:
- `.custom-gcl.yml` — Plugin configuration
- `.golangci.yml` — Linter settings
- `Makefile` — Build and run commands
Then simply:
```
make uber_lint
```
### 设置选项 2：手动配置
If you prefer manual setup, follow these steps:
**Step 1: Create `.custom-gcl.yml`**
```
version: v1.59.0
plugins:
- module: 'github.com/beltranaceves/uber-go-lint-style'
version: v0.1.1 # Use latest release
```
**Step 2: Create a `.golangci.yml` to enable the plugin and rules**
```
version: "1"
linters:
disable-all: true
enable:
- uber-go-lint-style
linters-settings:
custom:
uber-go-lint-style:
type: "module"
description: "Uber Go style guide linter"
original-url: "github.com/beltranaceves/uber-go-lint-style"
severity:
# Recommended: many rules are heuristic or subjective. Configure the
# plugin to report findings as warnings by default so suggestions are
# visible to developers without failing CI builds. Projects can opt-in
# to stricter settings per-team or per-rule as needed.
rules:
- linters:
- uber-go-lint-style
severity: warning
```
**Disabling plugin rules via YAML**
The `uber-go-lint-style` plugin accepts a YAML string in the `disabled_rules_yaml`
setting inside your `.golangci.yml` to disable specific analyzers at runtime.
You can provide either a plain YAML list or a mapping with a `disabled:` (or
`disable:`) key. The entries must match the analyzer name returned by a rule's
`BuildAnalyzer()`.
Example (`.golangci.yml`):
```
linters-settings:
uber-go-lint-style:
disabled_rules_yaml: |
- TodoRule
- AtomicRule
- MapInitRule
```
**Step 3: Build the custom binary and run**
```
golangci-lint custom
./custom-gcl run ./...
```
**Step 4: Add a Makefile (optional)**
To avoid running commands manually each time, add these targets to your `Makefile`:
```
.DEFAULT_GOAL := uber_lint
# 运行 linter（按需构建插件）
uber_lint:
@if [ ! -f "./custom-gcl" ]; then \
echo "Building custom golangci-lint with uber-go-lint-style plugin..."; \
golangci-lint custom || exit 1; \
fi
@./custom-gcl run
```
This automatically builds the binary on first run and caches it for subsequent runs. Then simply:
```
make uber_lint
```
Optional targets: `make uber_help` for usage, `make uber_clean` to reset.
```
# 查看帮助
uber_help:
@echo "Usage: make [target]"
@echo ""
@echo "Targets:"
@echo " make uber_lint Build plugin (if needed) and run linter"
@echo " make uber_clean Remove cached plugin binary"
@echo ""
@echo "Examples:"
@echo " make uber_lint # First run builds plugin, subsequent runs are fast"
@echo " make uber_clean # Reset and rebuild plugin next time"
.PHONY: uber_lint uber_help uber_clean
uber_clean:
@rm -f custom-gcl*
@echo "Cleaned custom linter artifacts"
```
## 规则
See [RULES.md](RULES.md) for full rule descriptions and examples.
## 开发
### 项目结构
```
uber-go-lint-style/
├── plugin.go # golangci-lint plugin entry point
├── plugin_test.go # plugin tests
├── rules/ # rule implementations (one file per rule)
├── testdata/ # testdata used by rule tests
├── cmd/ # helper CLI tools (e.g., setup)
│ └── setup/ # setup command source
├── style_guide/ # generated and source docs for the style guide
│ └── rules/ # markdown source files for the guide
├── test-client/ # integration test client and examples
├── assets/ # images and other assets
├── Makefile # convenience targets
├── installation.md # installation instructions
└── RULES.md # rule descriptions and examples
```
### 添加新规则
1. Create a new file in `rules/` (e.g., `rules/myrule.go`):
```
package rules
import (
"golang.org/x/tools/go/analysis"
)
type MyRule struct{}
func (r *MyRule) BuildAnalyzer() *analysis.Analyzer {
return &analysis.Analyzer{
Name: "myrule",
Doc: "enforce your style convention",
Run: r.run,
}
}
func (r *MyRule) run(pass *analysis.Pass) (any, error) {
// Your linting logic here
return nil, nil
}
```
2. Add test data in `testdata/src/testlintdata/myrule/`:
```
package myrule_test
// Violations here
func bad() {
undesirable code // want "error message"
}
// Good practices here
func good() {
}
```
3. Add test in `plugin_test.go`:
```
func TestMyRule(t *testing.T) {
// Similar to existing test patterns
}
```
4. Register in `plugin.go`:
```
func (f *PluginExample) BuildAnalyzers() ([]*analysis.Analyzer, error) {
return []*analysis.Analyzer{
(&rules.TodoRule{}).BuildAnalyzer(),
(&rules.AtomicRule{}).BuildAnalyzer(),
(&rules.MyRule{}).BuildAnalyzer(), // Add here
}, nil
}
```
### 运行测试
```
go test ./...
```
## 贡献
This project implements style rules from [Uber's Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md). When adding new rules:
1. Reference the specific style guideline being enforced
2. Document how the check works in the rule's `Doc` field
3. Provide comprehensive test cases (both good and bad patterns)
4. Keep rules focused and single-purpose
## 资源
- [uber-go/guide](https://github.com/uber-go/guide) — Uber's Go style guide
- [golangci-lint plugins](https://golangci-lint.run/docs/plugins/plugins-configuration/) — Custom plugin documentation
- Analysis tools:
- [go/analysis](https://pkg.go.dev/golang.org/x/tools/go/analysis)
- [golang.org/x/tools/go/ssa](https://pkg.go.dev/golang.org/x/tools/go/ssa)
- [go/ast](https://pkg.go.dev/go/ast)
- [go/types](https://pkg.go.dev/go/types)
标签：CI集成, EVTX分析, Go 1.23, golang, golangci-lint, Go Style, Go开发, lint, Makefile, Uber Go Style Guide, 二进制发布, 云安全监控, 代码规则, 代码规范, 安全专业人员, 开源工具, 插件, 日志审计, 自定义规则, 错误基检测, 静态代码分析, 静态分析, 风格指南