---

name: go-ops description: "Go 开发模式、并发、错误处理、测试和项目结构。适用于：golang、go、goroutine、channel、context、errgroup、go test、go mod、go build、interface、generics、table-driven tests、worker pool、sync.Mutex、sync.WaitGroup、pprof、go vet、golangci-lint、go workspace、functional options、middleware、http handler。" license: MIT allowed-tools: "Read Write Bash" metadata: author: claude-mods related-skills: docker-ops, ci-cd-ops, api-design-ops, testing-ops

Go 操作指南

全面的 Go 技能，涵盖惯用模式、并发和生产实践。

模块快速入门

# New module
go mod init github.com/user/project

# Add dependency
go get github.com/lib/pq@latest

# Tidy (remove unused, add missing)
go mod tidy

# Vendor dependencies
go mod vendor

# Workspace (multi-module)
go work init ./api ./shared
go work use ./cli

错误处理决策树

什么类型的错误？
│
├─ 已知的、预期的条件（如"未找到"）
│  └─ 哨兵错误：var ErrNotFound = errors.New("not found")
│     └─ 调用者检查：errors.Is(err, ErrNotFound)
│
├─ 需要携带结构化数据（状态码、字段名）
│  └─ 自定义错误类型：type ValidationError struct { Field, Message string }
│     └─ 实现 Error() string
│     └─ 调用者检查：errors.As(err, &validErr)
│
├─ 为现有错误添加上下文
│  └─ 包装：fmt.Errorf("load config: %w", err)
│     └─ 保留原始错误供 Is/As 检查
│
├─ 真正不可恢复的（状态损坏、程序员 bug）
│  └─ panic("invariant violated: ...")
│     └─ 库代码中几乎永远不用
│
└─ 并发工作中的多个错误
   └─ errors.Join(err1, err2) 或 multierr 包

错误包装约定

func LoadUser(id int) (*User, error) {
    row, err := db.Query("SELECT ...", id)
    if err != nil {
        return nil, fmt.Errorf("load user %d: %w", id, err)
    }
    return parseUser(row)
}

并发模式

Goroutine + Channel

func fanOut(urls []string) []Result {
    ch := make(chan Result, len(urls))
    for _, url := range urls {
        go func(u string) {
            ch <- fetch(u)
        }(url)
    }
    results := make([]Result, 0, len(urls))
    for range urls {
        results = append(results, <-ch)
    }
    return results
}

errgroup（推荐用于并发 + 错误处理）

import "golang.org/x/sync/errgroup"

func fetchAll(ctx context.Context, urls []string) ([]string, error) {
    g, ctx := errgroup.WithContext(ctx)
    results := make([]string, len(urls))
    for i, url := range urls {
        g.Go(func() error {
            body, err := fetch(ctx, url)
            if err != nil { return err }
            results[i] = body
            return nil
        })
    }
    if err := g.Wait(); err != nil {
        return nil, err
    }
    return results, nil
}

项目结构

project/
├── cmd/           # 入口点
│   └── server/
│       └── main.go
├── internal/      # 私有包
│   ├── handler/
│   ├── service/
│   └── repo/
├── pkg/           # 公共包（谨慎使用）
├── go.mod
└── go.sum

快速参考

| 任务 | 命令 | |------|------| | 运行 | go run ./cmd/server | | 测试 | go test ./... | | 构建 | go build -o bin/app ./cmd/server | | Lint | golangci-lint run | | 性能分析 | go tool pprof | | 竞态检测 | go test -race ./... |

附加资源

• ./references/concurrency-patterns.md - 高级并发模式
• ./references/testing-patterns.md - 表驱动测试、mock
• ./references/http-patterns.md - HTTP 处理器、中间件