golang-patterns Skill 多维度简评

类别：后端 / Go 惯用法 仓库：affaan-m/everything-claude-code 维护者：Affaan Mustafa / ECC 社区 理论基础：Effective Go + Google Go Style Guide

一、核心定位与价值

Go 是一门强调惯例的语言——同样一个功能，可以有 5 种写法，但只有 1-2 种是 idiomatic。golang-patterns Skill 强制让 AI 生成的 Go 代码遵守 Go 社区标准：

• 简洁明了的函数实现，避免”聪明”但晦涩的写法
• 类型设计零值可用（如 struct 字段默认值即为有效状态）
• 函数参数优先接受接口，返回具体类型
• 错误处理标准化（自动包裹上下文、定义哨兵错误）
• 并发模式惯用（worker pool、errgroup、context 取消）
• 接口设计（小而专注）
• 标准项目结构（cmd/internal/pkg/api）

适用场景

• 写新的 Go 函数、类型、包
• 代码审查 / 重构（Go Reviewer Agent 配合）
• 设计新包 / 模块
• 团队协作统一 Go 代码规范

不适用场景

• Go 之外的任何语言
• 已经是非常 idiomatic 的资深 Gopher
• 嵌入式 Go（TinyGo 限制）

二、核心模式库

2.1 函数实现模式

模式 1：简洁 + 错误包裹

// ❌ AI 写之前的"裸"返回
func GetUser(id string) (*User, error) {
    return db.FindUser(id)
}

// ✅ Skill 强制包裹
func GetUser(ctx context.Context, id string) (*User, error) {
    user, err := db.FindUser(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("get user %s: %w", id, err)
    }
    return user, nil
}

Skill 强制：

• 函数第一参数是 context.Context（HTTP handler 除外）
• 错误用 fmt.Errorf + %w 包裹
• 错误信息含变量值

模式 2：可选参数（Functional Options）

// ❌ BAD: 长参数列表
func NewServer(host string, port int, timeout time.Duration, maxConns int, tlsCert string, tlsKey string) (*Server, error)

// ✅ GOOD: Functional Options
type Option func(*Server)

func WithHost(host string) Option { return func(s *Server) { s.host = host } }
func WithPort(port int) Option { return func(s *Server) { s.port = port } }
func WithTimeout(d time.Duration) Option { return func(s *Server) { s.timeout = d } }

func NewServer(opts ...Option) (*Server, error) {
    s := &Server{
        host:    "localhost",
        port:    8080,
        timeout: 30 * time.Second,
    }
    for _, opt := range opts {
        opt(s)
    }
    return s, nil
}

// Usage
server, _ := NewServer(
    WithHost("0.0.0.0"),
    WithPort(9090),
    WithTimeout(60*time.Second),
)

2.2 类型设计

模式 3：零值可用

// ❌ BAD: 必须先初始化
type BadCounter struct {
    counts map[string]int
}

c := &BadCounter{}
c.counts = make(map[string]int)

// ✅ GOOD: 零值即可用
type Counter struct {
    mu     sync.Mutex
    counts map[string]int
}

func NewCounter() *Counter {
    return &Counter{counts: make(map[string]int)}
}

// 或用 sync.Map
type SafeCounter struct {
    counts sync.Map
}

模式 4：参数接接口，返回具体类型

// ✅ GOOD: 输入接口，输出具体
func ProcessData(r io.Reader) (*Result, error) {
    // 接受任何 io.Reader（灵活）
    // 返回具体类型 *Result（调用方知道字段）
    data, err := io.ReadAll(r)
    if err != nil {
        return nil, err
    }
    return &Result{Data: data}, nil
}

原则：

• “Be conservative in what you do, be liberal in what you accept”（Postel 法则）
• 接口接受 → 调用方灵活
• 返回具体 → 不强迫调用方做 type assertion

2.3 错误处理

模式 5：哨兵错误（Sentinel Errors）

// 定义
var (
    ErrNotFound      = errors.New("resource not found")
    ErrAlreadyExists = errors.New("resource already exists")
    ErrUnauthorized  = errors.New("unauthorized")
)

// 返回
func FindUser(id string) (*User, error) {
    if id == "" {
        return nil, ErrNotFound
    }
    // ...
}

// 调用方检查
if errors.Is(err, ErrNotFound) {
    return c.JSON(404, ...)
}

模式 6：自定义错误类型（带上下文）

type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
}

// 返回
if name == "" {
    return nil, &ValidationError{Field: "name", Message: "cannot be empty"}
}

// 调用方断言
var verr *ValidationError
if errors.As(err, &verr) {
    log.Printf("validation error on field %s", verr.Field)
}

模式 7：错误链（%w）

func LoadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("read config: %w", err)  // %w 保留原错误
    }
    // ...
}

// 客户端可以解开链
if errors.Is(err, os.ErrNotExist) {
    return defaultConfig
}

2.4 并发模式

模式 8：errgroup

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

func ProcessBatch(ctx context.Context, items []Item) error {
    g, ctx := errgroup.WithContext(ctx)

    for _, item := range items {
        item := item
        g.Go(func() error {
            return processItem(ctx, item)
        })
    }

    return g.Wait()  // 返回第一个错误
}

模式 9：Worker Pool

func WorkerPool(jobs <-chan Job, results chan<- Result, numWorkers int) {
    var wg sync.WaitGroup
    for i := 0; i < numWorkers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                results <- process(job)
            }
        }()
    }
    wg.Wait()
    close(results)
}

模式 10：Context 取消

func LongRunningTask(ctx context.Context) error {
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()  // 客户端断开，立即返回
        default:
            // 干活
            if err := doWork(ctx); err != nil {
                return err
            }
        }
    }
}

模式 11：避免 Goroutine 泄漏

// ❌ BAD: goroutine 可能永远不退出
go func() {
    for {
        ch <- work()  // 没人接收就死锁
    }
}()

// ✅ GOOD: 用 buffered channel + 监听 ctx
go func(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            return
        case ch <- work():
        }
    }
}(ctx)

2.5 接口设计

模式 12：小而专注

// ❌ BAD: 胖接口
type UserRepository interface {
    Create(...)
    Update(...)
    Delete(...)
    Find(...)
    List(...)
    Count(...)
    // ... 20 个方法
}

// ✅ GOOD: 多个小接口
type UserCreator interface {
    Create(ctx context.Context, u *User) error
}
type UserFinder interface {
    Find(ctx context.Context, id string) (*User, error)
}
type UserLister interface {
    List(ctx context.Context, filter Filter) ([]*User, error)
}

模式 13：接口定义在使用方

// 在使用方定义接口（不要在实现方）
package http

type UserStore interface {  // 在 http 包定义
    Find(ctx context.Context, id string) (*User, error)
}

type UserHandler struct {
    store UserStore
}

// userRepo (在 db 包实现) 自动满足

好处：避免”包循环依赖”，接口自然只暴露需要的方法。

2.6 标准项目结构

myproject/
├── cmd/                    # 主程序入口
│   └── server/
│       └── main.go
├── internal/              # 私有代码（不可被外部 import）
│   ├── auth/
│   ├── user/
│   └── ...
├── pkg/                   # 公共库（可被外部 import）
│   └── utils/
├── api/                   # API 协议定义
│   ├── proto/
│   └── openapi.yaml
├── testdata/              # 测试数据
├── configs/               # 配置文件
├── deployments/           # K8s / Docker Compose
├── docs/                  # 文档
├── go.mod
├── go.sum
├── Makefile
└── README.md

三、完整工作流

3.1 触发词（自动应用）

• “Go function” / “Go 函数”
• “Go goroutine” / “协程”
• “Go interface” / “接口”
• “Go struct” / “结构体”
• “Go error handling”
• “Go project structure”

3.2 Skill 引导 Claude 输出

[用户] 写一个 HTTP handler 获取用户信息

[Skill 引导 Claude 输出]
1. 函数第一参数 ctx
2. 错误包裹用 %w
3. 接口定义在使用方
4. 用 sentry 或 zap 记录错误
5. JSON 序列化用 struct tag
6. HTTP 状态码语义化
7. 写表驱动测试

func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    id := chi.URLParam(r, "id")

    user, err := h.svc.FindUser(ctx, id)
    if err != nil {
        if errors.Is(err, service.ErrNotFound) {
            http.Error(w, "user not found", http.StatusNotFound)
            return
        }
        h.logger.Error("find user failed", "error", err, "id", id)
        http.Error(w, "internal error", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

四、实战场景

场景 1：代码审查

需求：用 /go-review 命令审查 PR。 Skill 输出：

• 函数第一参数是 context.Context？
• 错误用 %w 包裹？
• 接口小而专注？
• 零值可用？
• 避免包级可变全局？
• goroutine 监听 ctx 取消？

场景 2：新包设计

需求：设计一个限流器包。 Skill 输出：

• 包名 ratelimit（小写、单词）
• 公开 API：Limiter 接口 + NewTokenBucket / NewSlidingWindow
• 内部实现隐藏
• 表驱动测试覆盖

场景 3：性能优化

需求：1000 个任务并发跑，加速。 Skill 输出：

• errgroup + 限流（避免打爆下游）
• context 取消机制
• 错误聚合
• graceful shutdown

五、5 条实战技巧

1. go vet ./... + golangci-lint run 强制规范
2. gofmt -w . 无条件格式化
3. go test -race ./... 检测数据竞争
4. pprof CPU/内存 profile
5. CI 跑 go mod verify 验证依赖完整性

六、6 条反合理化

七、真实踩坑案例

案例 1：Goroutine 泄漏

现象：服务跑 1 天后内存爆。 根因：goroutine 内 for { ch <- work() } 没人接收，但 select 没监听 ctx。 解决：用 buffered channel + ctx 取消。

案例 2：interface{} 与 type assertion

现象：v.(int) 频繁 panic。 根因：type assertion 失败会 panic。 解决：用 v, ok := i.(int) 双返回值。

案例 3：sync.Mutex 死锁

现象：服务 hang 死。 根因：A 锁等 B 锁，B 锁等 A 锁。 解决：

• 锁顺序一致
• 用 sync.Mutex 包装 RWMutex
• 加 -race 检测

案例 4：defer 在循环中

现象：1000 个文件描述符没释放。 根因：for _, f := range files { f, _ := os.Open(...); defer f.Close() }，defer 在函数退出时才执行。 解决：把循环体抽成函数，或手动 Close。

// ❌ BAD
func Process(files []string) error {
    for _, path := range files {
        f, _ := os.Open(path)
        defer f.Close()  // 函数退出时一起关闭
        process(f)
    }
    return nil
}

// ✅ GOOD
func Process(files []string) error {
    for _, path := range files {
        if err := processFile(path); err != nil {
            return err
        }
    }
    return nil
}

func processFile(path string) error {
    f, err := os.Open(path)
    if err != nil { return err }
    defer f.Close()
    return process(f)
}

案例 5：错误被吞掉

现象：if err != nil { return nil } 直接吞错误。 根因：追求代码简洁。 解决：至少 log 一下 log.Printf("warning: %v", err)。

案例 6：包级 map 并发写

现象：concurrent map writes panic。 根因：未保护的 map 多 goroutine 写。 解决：用 sync.Map 或加锁。

案例 7：channel close 多次

现象：close(ch); close(ch) panic。 根因：关闭已关闭的 channel。 解决：用 sync.Once 保护 close。

案例 8：值接收者 vs 指针接收者混用

现象：某些方法修改字段不生效。 根因：方法有的是值接收者，有的是指针接收者。 解决：所有方法统一指针接收者（除非 type 是 map/chan/func 等）。

案例 9：context 放在 struct 里

现象：struct 持有 context。 根因：context 应该第一参数。 解决：struct 不持有 context，通过方法传入。

案例 10：裸返回（naked return）

现象：func f() (result int, err error) { return } 难读。 根因：naked return 在长函数中容易混淆。 解决：显式 return result, err。

八、Q&A

Q: 跟 golang-testing 区别？ A: golang-patterns 关注代码惯用法；golang-testing 关注测试模式（表驱动、覆盖率、fuzzing）。

Q: 跟 go-reviewer Agent 关系？ A: Skill 提供”应该怎么写”的知识；Agent 自动审查代码并给出建议。

Q: 必须装在 Go 项目？ A: 是。Skill 只对 .go 文件触发。

Q: 触发后 Claude 立即改代码？ A: 不会。Skill 先让 Claude”理解”该用什么模式，再生成代码。

Q: 自定义模式？ A: 可在 .claude/rules/golang/ 中追加团队专属模式。

Q: 中文支持？ A: 注释和变量名可中文，Skill 指令是英文。

Q: 老 Go 项目适用？ A: 适合，配合 golang-testing 渐进式改造。

九、与其他 Skills 配合

完整工作流：

/go-review (代码审查)
  ↓
golang-patterns (匹配规范)
  ↓
输出优化建议
  ↓
人工确认
  ↓
golang-testing (生成测试)
  ↓
verification-loop (验证)

十、性能基准

10.1 并发加速比

10.2 内存占用

十一、安装

# Claude Code
/plugin marketplace add affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-code
cp -r everything-claude-code/rules/common ~/.claude/rules/
cp -r everything-claude-code/rules/golang ~/.claude/rules/

# 通用
npx skills add affaan-m/everything-claude-code --skill golang-patterns

十二、总结

核心价值：

• Go 社区惯用法强制应用
• 避免 AI 生成”Java 风格”Go 代码
• 与 ECC 整个生态集成
• 提升团队代码一致性

适用人群：

• Go 后端开发者
• 微服务架构师
• 云原生项目
• 用 AI 工具（Claude Code / Cursor）辅助开发

投入产出比：⭐⭐⭐⭐（4/5）—— Go 团队必装。

何时不要用：

• 没用 Go
• 不写并发代码
• 一次性脚本

配套文档：golang-testing 测试 | backend-patterns 后端 | postgres-patterns 数据库

参考资料

1. affaan-m/everything-claude-code GitHub
2. Effective Go
3. Google Go Style Guide
4. Go Concurrency Patterns - Go Blog
5. golang.org/x/sync/errgroup