@pilllesss/yorn 1.0.182 → 1.0.183

package/dist/skills/code-review/reference/go.md

@@ -0,0 +1,993 @@
+# Go 代码审查指南
+
+基于 Go 官方指南、Effective Go 和社区最佳实践的代码审查清单。
+
+## 快速审查清单
+
+### 必查项
+- [ ] 错误是否正确处理（不忽略、有上下文）
+- [ ] goroutine 是否有退出机制（避免泄漏）
+- [ ] context 是否正确传递和取消
+- [ ] 接收器类型选择是否合理（值/指针）
+- [ ] 是否使用 `gofmt` 格式化代码
+
+### 高频问题
+- [ ] 循环变量捕获问题（Go < 1.22）
+- [ ] nil 检查是否完整
+- [ ] map 是否初始化后使用
+- [ ] defer 在循环中的使用
+- [ ] 变量遮蔽（shadowing）
+
+---
+
+## 1. 错误处理
+
+> 📖 通用原则和跨语言示例详见 [错误处理跨语言指南](cross-cutting/error-handling-principles.md)
+
+### 1.1 永远不要忽略错误
+
+```go
+// ❌ 错误：忽略错误
+result, _ := SomeFunction()
+
+// ✅ 正确：处理错误
+result, err := SomeFunction()
+if err != nil {
+    return fmt.Errorf("some function failed: %w", err)
+}
+```
+
+### 1.2 错误包装与上下文
+
+```go
+// ❌ 错误：丢失上下文
+if err != nil {
+    return err
+}
+
+// ❌ 错误：使用 %v 丢失错误链
+if err != nil {
+    return fmt.Errorf("failed: %v", err)
+}
+
+// ✅ 正确：使用 %w 保留错误链
+if err != nil {
+    return fmt.Errorf("failed to process user %d: %w", userID, err)
+}
+```
+
+### 1.3 使用 errors.Is 和 errors.As
+
+```go
+// ❌ 错误：直接比较（无法处理包装错误）
+if err == sql.ErrNoRows {
+    // ...
+}
+
+// ✅ 正确：使用 errors.Is（支持错误链）
+if errors.Is(err, sql.ErrNoRows) {
+    return nil, ErrNotFound
+}
+
+// ✅ 正确：使用 errors.As 提取特定类型
+var pathErr *os.PathError
+if errors.As(err, &pathErr) {
+    log.Printf("path error: %s", pathErr.Path)
+}
+```
+
+### 1.4 自定义错误类型
+
+```go
+// ✅ 推荐：定义 sentinel 错误
+var (
+    ErrNotFound     = errors.New("not found")
+    ErrUnauthorized = errors.New("unauthorized")
+)
+
+// ✅ 推荐：带上下文的自定义错误
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation error on %s: %s", e.Field, e.Message)
+}
+```
+
+### 1.5 错误处理只做一次
+
+```go
+// ❌ 错误：既记录又返回（重复处理）
+if err != nil {
+    log.Printf("error: %v", err)
+    return err
+}
+
+// ✅ 正确：只返回，让调用者决定
+if err != nil {
+    return fmt.Errorf("operation failed: %w", err)
+}
+
+// ✅ 或者：只记录并处理（不返回）
+if err != nil {
+    log.Printf("non-critical error: %v", err)
+    // 继续执行备用逻辑
+}
+```
+
+---
+
+## 2. 并发与 Goroutine
+
+> 📖 通用并发模式和跨语言示例详见 [异步与并发跨语言指南](cross-cutting/async-concurrency-patterns.md)
+
+### 2.1 避免 Goroutine 泄漏
+
+```go
+// ❌ 错误：goroutine 永远无法退出
+func bad() {
+    ch := make(chan int)
+    go func() {
+        val := <-ch // 永远阻塞，无人发送
+        fmt.Println(val)
+    }()
+    // 函数返回，goroutine 泄漏
+}
+
+// ✅ 正确：使用 context 或 done channel
+func good(ctx context.Context) {
+    ch := make(chan int)
+    go func() {
+        select {
+        case val := <-ch:
+            fmt.Println(val)
+        case <-ctx.Done():
+            return // 优雅退出
+        }
+    }()
+}
+```
+
+### 2.2 Channel 使用规范
+
+```go
+// ❌ 错误：向 nil channel 发送（永久阻塞）
+var ch chan int
+ch <- 1 // 永久阻塞
+
+// ❌ 错误：向已关闭的 channel 发送（panic）
+close(ch)
+ch <- 1 // panic!
+
+// ✅ 正确：发送方关闭 channel
+func producer(ch chan<- int) {
+    defer close(ch) // 发送方负责关闭
+    for i := 0; i < 10; i++ {
+        ch <- i
+    }
+}
+
+// ✅ 正确：接收方检测关闭
+for val := range ch {
+    process(val)
+}
+// 或者
+val, ok := <-ch
+if !ok {
+    // channel 已关闭
+}
+```
+
+### 2.3 使用 sync.WaitGroup
+
+```go
+// ❌ 错误：Add 在 goroutine 内部
+var wg sync.WaitGroup
+for i := 0; i < 10; i++ {
+    go func() {
+        wg.Add(1) // 竞态条件！
+        defer wg.Done()
+        work()
+    }()
+}
+wg.Wait()
+
+// ✅ 正确：Add 在 goroutine 启动前
+var wg sync.WaitGroup
+for i := 0; i < 10; i++ {
+    wg.Add(1)
+    go func() {
+        defer wg.Done()
+        work()
+    }()
+}
+wg.Wait()
+```
+
+### 2.4 避免在循环中捕获变量（Go < 1.22）
+
+```go
+// ❌ 错误（Go < 1.22）：捕获循环变量
+for _, item := range items {
+    go func() {
+        process(item) // 所有 goroutine 可能使用同一个 item
+    }()
+}
+
+// ✅ 正确：传递参数
+for _, item := range items {
+    go func(it Item) {
+        process(it)
+    }(item)
+}
+
+// ✅ Go 1.22+：默认行为已修复，每次迭代创建新变量
+```
+
+### 2.5 Worker Pool 模式
+
+```go
+// ✅ 推荐：限制并发数量
+func processWithWorkerPool(ctx context.Context, items []Item, workers int) error {
+    jobs := make(chan Item, len(items))
+    results := make(chan error, len(items))
+
+    // 启动 worker
+    for w := 0; w < workers; w++ {
+        go func() {
+            for item := range jobs {
+                results <- process(item)
+            }
+        }()
+    }
+
+    // 发送任务
+    for _, item := range items {
+        jobs <- item
+    }
+    close(jobs)
+
+    // 收集结果
+    for range items {
+        if err := <-results; err != nil {
+            return err
+        }
+    }
+    return nil
+}
+```
+
+---
+
+## 3. Context 使用
+
+### 3.1 Context 作为第一个参数
+
+```go
+// ❌ 错误：context 不是第一个参数
+func Process(data []byte, ctx context.Context) error
+
+// ❌ 错误：context 存储在 struct 中
+type Service struct {
+    ctx context.Context // 不要这样做！
+}
+
+// ✅ 正确：context 作为第一个参数，命名为 ctx
+func Process(ctx context.Context, data []byte) error
+```
+
+### 3.2 传播而非创建新的根 Context
+
+```go
+// ❌ 错误：在调用链中创建新的根 context
+func middleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        ctx := context.Background() // 丢失了请求的 context！
+        process(ctx)
+        next.ServeHTTP(w, r)
+    })
+}
+
+// ✅ 正确：从请求中获取并传播
+func middleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        ctx := r.Context()
+        ctx = context.WithValue(ctx, key, value)
+        process(ctx)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+```
+
+### 3.3 始终调用 cancel 函数
+
+```go
+// ❌ 错误：未调用 cancel
+ctx, cancel := context.WithTimeout(parentCtx, 5*time.Second)
+// 缺少 cancel() 调用，可能资源泄漏
+
+// ✅ 正确：使用 defer 确保调用
+ctx, cancel := context.WithTimeout(parentCtx, 5*time.Second)
+defer cancel() // 即使超时也要调用
+```
+
+### 3.4 响应 Context 取消
+
+```go
+// ✅ 推荐：在长时间操作中检查 context
+func LongRunningTask(ctx context.Context) error {
+    for {
+        select {
+        case <-ctx.Done():
+            return ctx.Err() // 返回 context.Canceled 或 context.DeadlineExceeded
+        default:
+            // 执行一小部分工作
+            if err := doChunk(); err != nil {
+                return err
+            }
+        }
+    }
+}
+```
+
+### 3.5 区分取消原因
+
+```go
+// ✅ 根据 ctx.Err() 区分取消原因
+if err := ctx.Err(); err != nil {
+    switch {
+    case errors.Is(err, context.Canceled):
+        log.Println("operation was canceled")
+    case errors.Is(err, context.DeadlineExceeded):
+        log.Println("operation timed out")
+    }
+    return err
+}
+```
+
+---
+
+## 4. 接口设计
+
+### 4.1 接受接口，返回结构体
+
+```go
+// ❌ 不推荐：接受具体类型
+func SaveUser(db *sql.DB, user User) error
+
+// ✅ 推荐：接受接口（解耦、易测试）
+type UserStore interface {
+    Save(ctx context.Context, user User) error
+}
+
+func SaveUser(store UserStore, user User) error
+
+// ❌ 不推荐：返回接口
+func NewUserService() UserServiceInterface
+
+// ✅ 推荐：返回具体类型
+func NewUserService(store UserStore) *UserService
+```
+
+### 4.2 在消费者处定义接口
+
+```go
+// ❌ 不推荐：在实现包中定义接口
+// package database
+type Database interface {
+    Query(ctx context.Context, query string) ([]Row, error)
+    // ... 20 个方法
+}
+
+// ✅ 推荐：在消费者包中定义所需的最小接口
+// package userservice
+type UserQuerier interface {
+    QueryUsers(ctx context.Context, filter Filter) ([]User, error)
+}
+```
+
+### 4.3 保持接口小而专注
+
+```go
+// ❌ 不推荐：大而全的接口
+type Repository interface {
+    GetUser(id int) (*User, error)
+    CreateUser(u *User) error
+    UpdateUser(u *User) error
+    DeleteUser(id int) error
+    GetOrder(id int) (*Order, error)
+    CreateOrder(o *Order) error
+    // ... 更多方法
+}
+
+// ✅ 推荐：小而专注的接口
+type UserReader interface {
+    GetUser(ctx context.Context, id int) (*User, error)
+}
+
+type UserWriter interface {
+    CreateUser(ctx context.Context, u *User) error
+    UpdateUser(ctx context.Context, u *User) error
+}
+
+// 组合接口
+type UserRepository interface {
+    UserReader
+    UserWriter
+}
+```
+
+### 4.4 避免空接口滥用
+
+```go
+// ❌ 不推荐：过度使用 interface{}
+func Process(data interface{}) interface{}
+
+// ✅ 推荐：使用泛型（Go 1.18+）
+func Process[T any](data T) T
+
+// ✅ 推荐：定义具体接口
+type Processor interface {
+    Process() Result
+}
+```
+
+---
+
+## 5. 接收器类型选择
+
+### 5.1 使用指针接收器的情况
+
+```go
+// ✅ 需要修改接收器时
+func (u *User) SetName(name string) {
+    u.Name = name
+}
+
+// ✅ 接收器包含 sync.Mutex 等同步原语
+type SafeCounter struct {
+    mu    sync.Mutex
+    count int
+}
+
+func (c *SafeCounter) Inc() {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.count++
+}
+
+// ✅ 接收器是大型结构体（避免复制开销）
+type LargeStruct struct {
+    Data [1024]byte
+    // ...
+}
+
+func (l *LargeStruct) Process() { /* ... */ }
+```
+
+### 5.2 使用值接收器的情况
+
+```go
+// ✅ 接收器是小型不可变结构体
+type Point struct {
+    X, Y float64
+}
+
+func (p Point) Distance(other Point) float64 {
+    return math.Sqrt(math.Pow(p.X-other.X, 2) + math.Pow(p.Y-other.Y, 2))
+}
+
+// ✅ 接收器是基本类型的别名
+type Counter int
+
+func (c Counter) String() string {
+    return fmt.Sprintf("%d", c)
+}
+
+// ✅ 接收器是 map、func、chan（本身是引用类型）
+type StringSet map[string]struct{}
+
+func (s StringSet) Contains(key string) bool {
+    _, ok := s[key]
+    return ok
+}
+```
+
+### 5.3 一致性原则
+
+```go
+// ❌ 不推荐：混合使用接收器类型
+func (u User) GetName() string   // 值接收器
+func (u *User) SetName(n string) // 指针接收器
+
+// ✅ 推荐：如果有任何方法需要指针接收器，全部使用指针
+func (u *User) GetName() string { return u.Name }
+func (u *User) SetName(n string) { u.Name = n }
+```
+
+---
+
+## 6. 性能优化
+
+### 6.1 预分配 Slice
+
+```go
+// ❌ 不推荐：动态增长
+var result []int
+for i := 0; i < 10000; i++ {
+    result = append(result, i) // 多次分配和复制
+}
+
+// ✅ 推荐：预分配已知大小
+result := make([]int, 0, 10000)
+for i := 0; i < 10000; i++ {
+    result = append(result, i)
+}
+
+// ✅ 或者直接初始化
+result := make([]int, 10000)
+for i := 0; i < 10000; i++ {
+    result[i] = i
+}
+```
+
+### 6.2 避免不必要的堆分配
+
+```go
+// ❌ 可能逃逸到堆
+func NewUser() *User {
+    return &User{} // 逃逸到堆
+}
+
+// ✅ 考虑返回值（如果适用）
+func NewUser() User {
+    return User{} // 可能在栈上分配
+}
+
+// 检查逃逸分析
+// go build -gcflags '-m -m' ./...
+```
+
+### 6.3 使用 sync.Pool 复用对象
+
+```go
+// ✅ 推荐：高频创建/销毁的对象使用 sync.Pool
+var bufferPool = sync.Pool{
+    New: func() interface{} {
+        return new(bytes.Buffer)
+    },
+}
+
+func ProcessData(data []byte) string {
+    buf := bufferPool.Get().(*bytes.Buffer)
+    defer func() {
+        buf.Reset()
+        bufferPool.Put(buf)
+    }()
+
+    buf.Write(data)
+    return buf.String()
+}
+```
+
+### 6.4 字符串拼接优化
+
+```go
+// ❌ 不推荐：循环中使用 + 拼接
+var result string
+for _, s := range strings {
+    result += s // 每次创建新字符串
+}
+
+// ✅ 推荐：使用 strings.Builder
+var builder strings.Builder
+for _, s := range strings {
+    builder.WriteString(s)
+}
+result := builder.String()
+
+// ✅ 或者使用 strings.Join
+result := strings.Join(strings, "")
+```
+
+### 6.5 避免 interface{} 转换开销
+
+```go
+// ❌ 热路径中使用 interface{}
+func process(data interface{}) {
+    switch v := data.(type) { // 类型断言有开销
+    case int:
+        // ...
+    }
+}
+
+// ✅ 热路径中使用泛型或具体类型
+func process[T int | int64 | float64](data T) {
+    // 编译时确定类型，无运行时开销
+}
+```
+
+---
+
+## 7. 测试
+
+### 7.1 表驱动测试
+
+```go
+// ✅ 推荐：表驱动测试
+func TestAdd(t *testing.T) {
+    tests := []struct {
+        name     string
+        a, b     int
+        expected int
+    }{
+        {"positive numbers", 1, 2, 3},
+        {"with zero", 0, 5, 5},
+        {"negative numbers", -1, -2, -3},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Add(tt.a, tt.b)
+            if result != tt.expected {
+                t.Errorf("Add(%d, %d) = %d; want %d",
+                    tt.a, tt.b, result, tt.expected)
+            }
+        })
+    }
+}
+```
+
+### 7.2 并行测试
+
+```go
+// ✅ 推荐：独立测试用例并行执行
+func TestParallel(t *testing.T) {
+    tests := []struct {
+        name  string
+        input string
+    }{
+        {"test1", "input1"},
+        {"test2", "input2"},
+    }
+
+    for _, tt := range tests {
+        tt := tt // Go < 1.22 需要复制
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel() // 标记为可并行
+            result := Process(tt.input)
+            // assertions...
+        })
+    }
+}
+```
+
+### 7.3 使用接口进行 Mock
+
+```go
+// ✅ 定义接口以便测试
+type EmailSender interface {
+    Send(to, subject, body string) error
+}
+
+// 生产实现
+type SMTPSender struct { /* ... */ }
+
+// 测试 Mock
+type MockEmailSender struct {
+    SendFunc func(to, subject, body string) error
+}
+
+func (m *MockEmailSender) Send(to, subject, body string) error {
+    return m.SendFunc(to, subject, body)
+}
+
+func TestUserRegistration(t *testing.T) {
+    mock := &MockEmailSender{
+        SendFunc: func(to, subject, body string) error {
+            if to != "test@example.com" {
+                t.Errorf("unexpected recipient: %s", to)
+            }
+            return nil
+        },
+    }
+
+    service := NewUserService(mock)
+    // test...
+}
+```
+
+### 7.4 测试辅助函数
+
+```go
+// ✅ 使用 t.Helper() 标记辅助函数
+func assertEqual(t *testing.T, got, want interface{}) {
+    t.Helper() // 错误报告时显示调用者位置
+    if got != want {
+        t.Errorf("got %v, want %v", got, want)
+    }
+}
+
+// ✅ 使用 t.Cleanup() 清理资源
+func TestWithTempFile(t *testing.T) {
+    f, err := os.CreateTemp("", "test")
+    if err != nil {
+        t.Fatal(err)
+    }
+    t.Cleanup(func() {
+        os.Remove(f.Name())
+    })
+    // test...
+}
+```
+
+---
+
+## 8. 常见陷阱
+
+### 8.1 Nil Slice vs Empty Slice
+
+```go
+var nilSlice []int     // nil, len=0, cap=0
+emptySlice := []int{}  // not nil, len=0, cap=0
+made := make([]int, 0) // not nil, len=0, cap=0
+
+// ✅ JSON 编码差异
+json.Marshal(nilSlice)   // null
+json.Marshal(emptySlice) // []
+
+// ✅ 推荐：需要空数组 JSON 时显式初始化
+if slice == nil {
+    slice = []int{}
+}
+```
+
+### 8.2 Map 初始化
+
+```go
+// ❌ 错误：未初始化的 map
+var m map[string]int
+m["key"] = 1 // panic: assignment to entry in nil map
+
+// ✅ 正确：使用 make 初始化
+m := make(map[string]int)
+m["key"] = 1
+
+// ✅ 或者使用字面量
+m := map[string]int{}
+```
+
+### 8.3 Defer 在循环中
+
+```go
+// ❌ 潜在问题：defer 在函数结束时才执行
+func processFiles(files []string) error {
+    for _, file := range files {
+        f, err := os.Open(file)
+        if err != nil {
+            return err
+        }
+        defer f.Close() // 所有文件在函数结束时才关闭！
+        // process...
+    }
+    return nil
+}
+
+// ✅ 正确：使用闭包或提取函数
+func processFiles(files []string) error {
+    for _, file := range files {
+        if err := processFile(file); err != nil {
+            return err
+        }
+    }
+    return nil
+}
+
+func processFile(file string) error {
+    f, err := os.Open(file)
+    if err != nil {
+        return err
+    }
+    defer f.Close()
+    // process...
+    return nil
+}
+```
+
+### 8.4 Slice 底层数组共享
+
+```go
+// ❌ 潜在问题：切片共享底层数组
+original := []int{1, 2, 3, 4, 5}
+slice := original[1:3] // [2, 3]
+slice[0] = 100         // 修改了 original！
+// original 变成 [1, 100, 3, 4, 5]
+
+// ✅ 正确：需要独立副本时显式复制
+slice := make([]int, 2)
+copy(slice, original[1:3])
+slice[0] = 100 // 不影响 original
+```
+
+### 8.5 字符串子串内存泄漏
+
+```go
+// ❌ 潜在问题：子串持有整个底层数组
+func getPrefix(s string) string {
+    return s[:10] // 仍引用整个 s 的底层数组
+}
+
+// ✅ 正确：创建独立副本（Go 1.18+）
+func getPrefix(s string) string {
+    return strings.Clone(s[:10])
+}
+
+// ✅ Go 1.18 之前
+func getPrefix(s string) string {
+    return string([]byte(s[:10]))
+}
+```
+
+### 8.6 Interface Nil 陷阱
+
+```go
+// ❌ 陷阱：interface 的 nil 判断
+type MyError struct{}
+func (e *MyError) Error() string { return "error" }
+
+func returnsError() error {
+    var e *MyError = nil
+    return e // 返回的 error 不是 nil！
+}
+
+func main() {
+    err := returnsError()
+    if err != nil { // true! interface{type: *MyError, value: nil}
+        fmt.Println("error:", err)
+    }
+}
+
+// ✅ 正确：显式返回 nil
+func returnsError() error {
+    var e *MyError = nil
+    if e == nil {
+        return nil // 显式返回 nil
+    }
+    return e
+}
+```
+
+### 8.7 Time 比较
+
+```go
+// ❌ 不推荐：直接使用 == 比较 time.Time
+if t1 == t2 { // 可能因为单调时钟差异而失败
+    // ...
+}
+
+// ✅ 推荐：使用 Equal 方法
+if t1.Equal(t2) {
+    // ...
+}
+
+// ✅ 比较时间范围
+if t1.Before(t2) || t1.After(t2) {
+    // ...
+}
+```
+
+---
+
+## 9. 代码组织
+
+### 9.1 包命名
+
+```go
+// ❌ 不推荐
+package common   // 过于宽泛
+package utils    // 过于宽泛
+package helpers  // 过于宽泛
+package models   // 按类型分组
+
+// ✅ 推荐：按功能命名
+package user     // 用户相关功能
+package order    // 订单相关功能
+package postgres // PostgreSQL 实现
+```
+
+### 9.2 避免循环依赖
+
+```go
+// ❌ 循环依赖
+// package a imports package b
+// package b imports package a
+
+// ✅ 解决方案1：提取共享类型到独立包
+// package types (共享类型)
+// package a imports types
+// package b imports types
+
+// ✅ 解决方案2：使用接口解耦
+// package a 定义接口
+// package b 实现接口
+```
+
+### 9.3 导出标识符规范
+
+```go
+// ✅ 只导出必要的标识符
+type UserService struct {
+    db *sql.DB // 私有
+}
+
+func (s *UserService) GetUser(id int) (*User, error) // 公开
+func (s *UserService) validate(u *User) error         // 私有
+
+// ✅ 内部包限制访问
+// internal/database/... 只能被同项目代码导入
+```
+
+---
+
+## 10. 工具与检查
+
+### 10.1 必须使用的工具
+
+```bash
+# 格式化（必须）
+gofmt -w .
+goimports -w .
+
+# 静态分析
+go vet ./...
+
+# 竞态检测
+go test -race ./...
+
+# 逃逸分析
+go build -gcflags '-m -m' ./...
+```
+
+### 10.2 推荐的 Linter
+
+```bash
+# golangci-lint（集成多个 linter）
+golangci-lint run
+
+# 常用检查项
+# - errcheck: 检查未处理的错误
+# - gosec: 安全检查
+# - ineffassign: 无效赋值
+# - staticcheck: 静态分析
+# - unused: 未使用的代码
+```
+
+### 10.3 Benchmark 测试
+
+```go
+// ✅ 性能基准测试
+func BenchmarkProcess(b *testing.B) {
+    data := prepareData()
+    b.ResetTimer() // 重置计时器
+
+    for i := 0; i < b.N; i++ {
+        Process(data)
+    }
+}
+
+// 运行 benchmark
+// go test -bench=. -benchmem ./...
+```
+
+---
+
+## 参考资源
+
+- [Effective Go](https://go.dev/doc/effective_go)
+- [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments)
+- [Go Common Mistakes](https://go.dev/wiki/CommonMistakes)
+- [100 Go Mistakes](https://100go.co/)
+- [Go Proverbs](https://go-proverbs.github.io/)
+- [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md)