go-stdlib-style

name	go-stdlib-style
description	Go 标准库编码风格 Skill。蒸馏自 golang/go 标准库源码、Effective Go、 Rob Pike 的 Go Proverbs、Russ Cox 的设计文档、Go Code Review Comments 官方指南。 触发词：「Go 标准库风格」「idiomatic Go」「地道 Go」「go stdlib style」「Rob Pike 风格」。 适用：Go 库开发、CLI 工具、网络服务、系统工具。

Go 标准库 · 编码 DNA

"Clear is better than clever." — Rob Pike, Go Proverbs "A little copying is better than a little dependency." — Rob Pike

角色定义

此 Skill 激活后，你写出的 Go 代码应该让标准库 contributor 在 code review 时感觉 「这代码像是从 net/http 里拿出来的」，而不是「这是 Java 开发者写的 Go」。

这意味着：简单、显式、接口小、无魔法。

---

命名 DNA

6 条直觉规则：

1. 包名：单词、小写、不下划线、不 camelCase

   // ✅
   package http
   package json
   package sync
   
   // ❌
   package httpUtils
   package http_client
   package HTTPServer
   

   包名是命名空间，使用时 http.Get，不是 httpClient.Get。

2. 导出名不重复包名

   // ✅ 使用时是 http.Request，不是 http.HTTPRequest
   package http
   type Request struct { ... }
   func Get(url string) (*Response, error) { ... }
   
   // ❌ 冗余
   type HTTPRequest struct { ... }
   func HTTPGet(url string) (*HTTPResponse, error) { ... }
   

3. 接口名 = 方法名 + er（单方法接口）

   // ✅ Go 的核心约定
   type Reader interface { Read(p []byte) (n int, err error) }
   type Writer interface { Write(p []byte) (n int, err error) }
   type Stringer interface { String() string }
   type Handler interface { ServeHTTP(ResponseWriter, *Request) }
   
   // ❌ 动词/形容词命名接口
   type Readable interface { ... }
   type DataProcessor interface { ... }
   

4. 变量名短而精，作用域小则短

   // ✅ 局部变量
   for i, v := range items { ... }
   r, err := http.Get(url)
   buf := make([]byte, 1024)
   
   // ✅ 包级变量
   var defaultClient = &Client{}
   var ErrNotFound = errors.New("not found")
   
   // ❌ 过长（Go 不是 Java）
   for index, value := range itemList { ... }
   httpResponseReader, requestError := httpClient.MakeGetRequest(requestUrl)
   

5. 错误变量叫 err，不叫 error 或 e

   // ✅
   n, err := r.Read(buf)
   if err != nil {
       return err
   }
   

6. 常量和包级变量不用全大写（除了真正的常量）

   // ✅
   const maxRetries = 3
   var defaultTimeout = 30 * time.Second
   
   // ❌ （Go 不是 C）
   const MAX_RETRIES = 3
   var DEFAULT_TIMEOUT = 30 * time.Second
   

---

结构偏好

接口设计：接口越小越好

// ✅ 单方法接口，组合使用
type Reader interface { Read(p []byte) (n int, err error) }
type Writer interface { Write(p []byte) (n int, err error) }
type ReadWriter interface {
    Reader
    Writer
}

// ❌ 胖接口（难以实现，难以测试）
type Storage interface {
    Read() ([]byte, error)
    Write([]byte) error
    Delete(key string) error
    List() ([]string, error)
    Stats() Stats
    Flush() error
}

函数设计：

// ✅ 接受接口，返回具体类型
func NewScanner(r io.Reader) *Scanner { ... }  // 接受 Reader 接口

// ✅ 错误永远是最后一个返回值
func Open(name string) (*File, error) { ... }

// ✅ 选项用 struct，不用过多参数
type DialOption struct {
    Timeout   time.Duration
    KeepAlive time.Duration
    Resolver  Resolver
}
func DialContext(ctx context.Context, network, address string, opt ...DialOption) (Conn, error)
// 或更 Go 风格的 functional options

错误处理：显式、不忽略、包上下文

// ✅ 每个错误都处理
f, err := os.Open(filename)
if err != nil {
    return fmt.Errorf("open config file: %w", err)  // 用 %w 包装，保留原始错误
}
defer f.Close()

// ✅ 错误信息小写，不加标点（它是被包装的，不是最终输出）
return fmt.Errorf("parse response: %w", err)   // ✅
return fmt.Errorf("Parse Response: %w", err)   // ❌ 大写
return fmt.Errorf("parse response: %w.", err)  // ❌ 加句号

// ❌ 忽略错误（除非真的不重要且有注释说明）
f, _ := os.Open(filename)

并发：

// ✅ 用 channel 传数据，不共享内存
func producer(ch chan<- int) {
    for i := 0; i < 10; i++ {
        ch <- i
    }
    close(ch)
}

// ✅ sync.Mutex 保护共享状态，锁和被保护的数据放一起
type Cache struct {
    mu    sync.Mutex  // 锁紧跟着被保护的字段
    items map[string]Item
}

// ✅ context 作为第一个参数传递
func (c *Client) Do(ctx context.Context, req *Request) (*Response, error) { ... }

---

注释哲学

Go 的注释规则极其简单，但要求严格：

// ✅ 导出符号必须有注释，且以符号名开头
// Reader is the interface that wraps the basic Read method.
type Reader interface { ... }

// Open opens the named file for reading.
// If successful, methods on the returned file can be used for reading;
// the associated file descriptor has mode O_RDONLY.
// If there is an error, it will be of type *PathError.
func Open(name string) (*File, error) { ... }

// ErrNotExist indicates that a file or directory does not exist.
var ErrNotExist = errors.New("file does not exist")

// ❌ 注释不以符号名开头（go doc 解析失败）
// This opens a file.
func Open(name string) (*File, error) { ... }

// ❌ 废话注释
// i is an integer counter
i := 0

//go: 指令注释：

//go:generate stringer -type=Weekday
//go:noescape  // 告诉编译器参数不逃逸到堆
//nolint:errcheck  // 关闭 linter（要有充分理由）

---

反模式（绝不这样写）

1. panic 用于业务逻辑

   // ❌ panic 不是错误处理
   func GetUser(id int) *User {
       user := db.Find(id)
       if user == nil {
           panic("user not found")
       }
       return user
   }
   // ✅ 返回 error
   func GetUser(id int) (*User, error) { ... }
   

2. 接受具体类型而不是接口（限制了可测试性）

   // ❌ 接受具体类型，无法 mock
   func Process(c *http.Client) { ... }
   // ✅ 接受接口
   func Process(c interface { Do(*http.Request) (*http.Response, error) }) { ... }
   

3. init() 函数做复杂初始化 — init 难以测试、难以控制执行顺序

4. 全局变量暴露可变状态 — 包级全局变量应该是不可变的（常量或配置）

5. interface{} / any 满天飞 — Go 1.18+ 用泛型，不用空接口甩锅

   // ❌
   func Store(key string, value interface{}) { ... }
   // ✅ 泛型
   func Store[V any](key string, value V) { ... }
   

6. 忽略 defer 的错误

   defer f.Close()  // ❌ 文件写入后 Close 出错会丢数据
   defer func() {
       if err := f.Close(); err != nil {
           log.Printf("close file: %v", err)
       }
   }()  // ✅
   

7. 错误信息大写或加句号 — 会破坏 fmt.Errorf("open: %w", err) 的拼接效果

---

校验测试

1. gofmt 检查：gofmt -d . 有输出吗？有就是格式不对（gofmt 是宗教）
2. 接口检查：接收参数能换成接口吗？换了之后可测试性提升吗？
3. 错误路径检查：grep -n "_, err" *.go —— 有没有忽略的错误？

---

来源

• golang/go 标准库源码（net/http、io、sync、encoding/json）
• Effective Go
• Go Code Review Comments
• Rob Pike：Go Proverbs
• Russ Cox 设计文档：Research!rsc