@umacloud/knowledge 1.0.1

package/development/01-standards/golang-complete.md

@@ -0,0 +1,1565 @@
+---
+id: golang-complete
+title: Go 语言完整工程指南
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [complete, development, golang, 并发模型, 性能优化, 接口设计, 标准库精选, 核心语法]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Go 语言完整工程指南
+
+> UmaDev Knowledge Base | Domain: development | Type: standards
+
+## 1. 概述
+
+### 1.1 设计哲学
+
+Go 由 Robert Griesemer、Rob Pike 和 Ken Thompson 在 Google 设计，核心哲学：
+
+- **简洁胜于灵巧** — 语法关键字仅 25 个，没有继承、没有异常、没有宏
+- **组合优于继承** — 通过嵌入（embedding）和接口实现多态
+- **显式优于隐式** — 错误必须显式处理，类型转换必须显式声明
+- **并发是一等公民** — goroutine + channel 是语言内建原语
+- **工具链即标准** — gofmt / go vet / go test 是语言生态不可分割的部分
+
+### 1.2 适用场景
+
+| 场景 | 匹配度 | 说明 |
+|------|--------|------|
+| 云原生微服务 | 极高 | Kubernetes / Docker / Prometheus 均用 Go 编写 |
+| CLI 工具 | 极高 | 单二进制、交叉编译、启动快 |
+| 网络代理/中间件 | 极高 | 高并发 + 低延迟 |
+| 数据管道 / ETL | 高 | goroutine 天然适合 fan-out/fan-in |
+| Web API 服务 | 高 | 标准库 net/http 已足够生产使用 |
+| 嵌入式 / GUI | 低 | 生态较弱 |
+| 科学计算 / ML | 低 | 缺少成熟矩阵/张量库 |
+
+---
+
+## 2. 核心语法
+
+### 2.1 类型系统
+
+```go
+// 基本类型
+var (
+    b   bool       = true
+    i   int        = 42        // 平台相关位宽 (32/64)
+    i64 int64      = 1 << 40
+    f   float64    = 3.14159
+    c   complex128 = 3 + 4i
+    s   string     = "hello"   // 不可变 UTF-8 字节序列
+    r   rune       = '中'      // int32 别名，表示 Unicode 码点
+    bt  byte       = 0xFF      // uint8 别名
+)
+
+// 零值规则：数值=0，布尔=false，字符串=""，指针/切片/map/channel/interface=nil
+```
+
+### 2.2 结构体与方法
+
+```go
+type User struct {
+    ID        int64     `json:"id" db:"id"`
+    Name      string    `json:"name" db:"name"`
+    Email     string    `json:"email" db:"email"`
+    CreatedAt time.Time `json:"created_at" db:"created_at"`
+}
+
+// 值接收者 — 不修改原始值
+func (u User) DisplayName() string {
+    return fmt.Sprintf("%s <%s>", u.Name, u.Email)
+}
+
+// 指针接收者 — 可修改原始值，避免大结构体拷贝
+func (u *User) SetEmail(email string) {
+    u.Email = email
+}
+
+// 嵌入（组合）
+type Admin struct {
+    User              // 匿名嵌入，提升 User 的字段和方法
+    Permissions []string
+}
+
+admin := Admin{
+    User:        User{ID: 1, Name: "root"},
+    Permissions: []string{"read", "write", "delete"},
+}
+fmt.Println(admin.DisplayName()) // 直接调用 User 的方法
+```
+
+### 2.3 切片、Map 与内部机制
+
+```go
+// 切片底层结构：{pointer, length, capacity}
+s := make([]int, 0, 16) // len=0, cap=16
+s = append(s, 1, 2, 3)  // len=3, cap=16，无扩容
+// 扩容策略(Go 1.18+)：<256 翻倍；>=256 增长 25% + 192
+
+// Map — 基于哈希表，无序
+m := map[string]int{"a": 1, "b": 2}
+// 检查 key 是否存在
+if v, ok := m["c"]; ok {
+    fmt.Println(v)
+}
+// 注意：map 的零值是 nil，向 nil map 写入会 panic
+```
+
+### 2.4 包管理与模块
+
+```go
+// go.mod — 模块定义
+module github.com/company/myservice
+
+go 1.22
+
+require (
+    github.com/gin-gonic/gin v1.9.1
+    google.golang.org/grpc v1.62.0
+)
+
+// 内部包约定：internal/ 目录只对父模块可见
+// myservice/
+//   internal/
+//     auth/       <- 外部模块不可 import
+//   pkg/
+//     client/     <- 公开 API
+```
+
+```bash
+go mod init github.com/company/myservice
+go mod tidy          # 同步依赖
+go mod vendor        # 生成 vendor/
+go mod graph         # 打印依赖图
+go get -u ./...      # 升级所有直接依赖
+```
+
+---
+
+## 3. 并发模型
+
+### 3.1 Goroutine
+
+```go
+// goroutine 初始栈仅 2-8 KB，可轻松创建数十万个
+go func() {
+    fmt.Println("running in goroutine")
+}()
+
+// 注意：main 退出时所有 goroutine 被强制终止
+```
+
+### 3.2 Channel
+
+```go
+// 无缓冲 — 发送和接收同步阻塞
+ch := make(chan int)
+
+// 有缓冲 — 缓冲区满时发送阻塞，空时接收阻塞
+ch := make(chan int, 100)
+
+// 方向限定（函数签名中使用）
+func producer(out chan<- int) { out <- 42 }
+func consumer(in <-chan int)  { v := <-in; _ = v }
+
+// 关闭 channel
+close(ch) // 只有发送方应该关闭；关闭后接收返回零值+false
+
+// range 读取直到 channel 关闭
+for v := range ch {
+    process(v)
+}
+```
+
+### 3.3 Select 多路复用
+
+```go
+select {
+case msg := <-msgCh:
+    handle(msg)
+case err := <-errCh:
+    log.Error(err)
+case <-time.After(5 * time.Second):
+    log.Warn("timeout")
+case <-ctx.Done():
+    return ctx.Err()
+}
+
+// 非阻塞尝试
+select {
+case msg := <-ch:
+    handle(msg)
+default:
+    // ch 为空，立即返回
+}
+```
+
+### 3.4 sync 包核心原语
+
+```go
+// WaitGroup — 等待一组 goroutine 完成
+var wg sync.WaitGroup
+for i := 0; i < 10; i++ {
+    wg.Add(1)
+    go func(id int) {
+        defer wg.Done()
+        process(id)
+    }(i)
+}
+wg.Wait()
+
+// Mutex — 互斥锁
+var mu sync.Mutex
+mu.Lock()
+sharedMap["key"] = "value"
+mu.Unlock()
+
+// RWMutex — 读写锁（多读单写）
+var rwmu sync.RWMutex
+rwmu.RLock()   // 读锁，允许并发读
+data := sharedMap["key"]
+rwmu.RUnlock()
+
+rwmu.Lock()    // 写锁，独占
+sharedMap["key"] = "newValue"
+rwmu.Unlock()
+
+// Once — 确保初始化只执行一次
+var once sync.Once
+var instance *Database
+func GetDB() *Database {
+    once.Do(func() {
+        instance = connectDB()
+    })
+    return instance
+}
+```
+
+### 3.5 sync.Pool
+
+```go
+// sync.Pool — 减少频繁分配的 GC 压力
+var bufPool = sync.Pool{
+    New: func() interface{} {
+        return new(bytes.Buffer)
+    },
+}
+
+func processRequest(data []byte) {
+    buf := bufPool.Get().(*bytes.Buffer)
+    defer func() {
+        buf.Reset()
+        bufPool.Put(buf)
+    }()
+    buf.Write(data)
+    // 使用 buf ...
+}
+// 注意：Pool 中对象可能在任意 GC 周期被回收，不要存储有状态对象
+```
+
+### 3.6 errgroup
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func fetchAll(ctx context.Context, urls []string) ([]Response, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    results := make([]Response, len(urls))
+
+    for i, url := range urls {
+        i, url := i, url // 捕获循环变量（Go <1.22 必需）
+        g.Go(func() error {
+            resp, err := fetch(ctx, url)
+            if err != nil {
+                return fmt.Errorf("fetch %s: %w", url, err)
+            }
+            results[i] = resp
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err // 返回第一个错误，并取消 ctx
+    }
+    return results, nil
+}
+```
+
+### 3.7 Context 传播与取消
+
+```go
+// 创建带取消的 context
+ctx, cancel := context.WithCancel(context.Background())
+defer cancel() // 确保资源释放
+
+// 带超时
+ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+defer cancel()
+
+// 带截止时间
+ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(1*time.Hour))
+defer cancel()
+
+// 传递值（仅用于请求范围的元数据，如 traceID / userID）
+type ctxKey string
+const traceIDKey ctxKey = "traceID"
+
+ctx = context.WithValue(ctx, traceIDKey, "abc-123")
+traceID := ctx.Value(traceIDKey).(string)
+
+// 监听取消信号
+func longRunningTask(ctx context.Context) error {
+    for {
+        select {
+        case <-ctx.Done():
+            return ctx.Err() // context.Canceled 或 context.DeadlineExceeded
+        default:
+            // 继续工作
+            doWork()
+        }
+    }
+}
+
+// Context 传播规则：
+// 1. context.Background() 仅在 main / 顶层入口使用
+// 2. 所有 I/O 和跨进程调用必须传递 ctx
+// 3. 不要把 context 存到 struct 中，始终作为函数第一个参数
+```
+
+---
+
+## 4. 错误处理
+
+### 4.1 error 接口
+
+```go
+// error 是内建接口
+type error interface {
+    Error() string
+}
+
+// 最简创建
+err := errors.New("connection refused")
+err := fmt.Errorf("invalid port: %d", port)
+```
+
+### 4.2 自定义错误
+
+```go
+type NotFoundError struct {
+    Resource string
+    ID       string
+}
+
+func (e *NotFoundError) Error() string {
+    return fmt.Sprintf("%s with id %s not found", e.Resource, e.ID)
+}
+
+// 让错误实现 Unwrap() 支持错误链
+type AppError struct {
+    Code    int
+    Message string
+    Err     error
+}
+
+func (e *AppError) Error() string { return e.Message }
+func (e *AppError) Unwrap() error { return e.Err }
+```
+
+### 4.3 Sentinel Errors
+
+```go
+// 定义包级别的哨兵错误
+var (
+    ErrNotFound     = errors.New("not found")
+    ErrUnauthorized = errors.New("unauthorized")
+    ErrConflict     = errors.New("conflict")
+)
+
+// 使用哨兵错误
+func GetUser(id string) (*User, error) {
+    user, err := repo.Find(id)
+    if err != nil {
+        if errors.Is(err, sql.ErrNoRows) {
+            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
+        }
+        return nil, fmt.Errorf("query user: %w", err)
+    }
+    return user, nil
+}
+```
+
+### 4.4 errors.Is 与 errors.As
+
+```go
+// errors.Is — 沿错误链检查是否匹配某个值
+if errors.Is(err, ErrNotFound) {
+    http.Error(w, "Not Found", 404)
+}
+
+// errors.As — 沿错误链提取某个类型
+var appErr *AppError
+if errors.As(err, &appErr) {
+    log.Printf("code=%d msg=%s", appErr.Code, appErr.Message)
+}
+
+// 错误包装与链（%w 动词）
+original := errors.New("disk full")
+wrapped := fmt.Errorf("save file: %w", original)
+doubleWrapped := fmt.Errorf("process request: %w", wrapped)
+
+errors.Is(doubleWrapped, original) // true
+```
+
+### 4.5 错误处理最佳实践
+
+```go
+// 1. 添加上下文再返回
+if err != nil {
+    return fmt.Errorf("createOrder(userID=%s): %w", userID, err)
+}
+
+// 2. 只在顶层记录日志，底层只包装返回
+// 3. 不要 log 后又 return err（会导致重复日志）
+// 4. panic 仅用于不可恢复的程序错误（如 nil 解引用不应出现的不变量违反）
+// 5. 库代码永远不要 panic，应返回 error
+```
+
+---
+
+## 5. 接口设计
+
+### 5.1 小接口原则
+
+```go
+// Go 标准库的经典小接口
+type Reader interface { Read(p []byte) (n int, err error) }
+type Writer interface { Write(p []byte) (n int, err error) }
+type Closer interface { Close() error }
+type Stringer interface { String() string }
+
+// 组合小接口
+type ReadWriteCloser interface {
+    Reader
+    Writer
+    Closer
+}
+
+// 经验法则：接口方法数 <= 3；超过则考虑拆分
+```
+
+### 5.2 接口断言与 any
+
+```go
+// any 是 interface{} 的别名（Go 1.18+）
+func printValue(v any) {
+    switch val := v.(type) {
+    case int:
+        fmt.Printf("int: %d\n", val)
+    case string:
+        fmt.Printf("string: %s\n", val)
+    case fmt.Stringer:
+        fmt.Printf("stringer: %s\n", val.String())
+    default:
+        fmt.Printf("unknown: %v\n", val)
+    }
+}
+
+// 接口断言（带检查）
+if s, ok := v.(fmt.Stringer); ok {
+    fmt.Println(s.String())
+}
+```
+
+### 5.3 接口设计原则
+
+```go
+// 1. 在消费方定义接口，不在实现方
+// bad: package storage 定义 Storage 接口并同时实现
+// good: package handler 定义它需要的接口
+
+type UserRepository interface { // 定义在 handler 包中
+    FindByID(ctx context.Context, id string) (*User, error)
+    Save(ctx context.Context, user *User) error
+}
+
+// 2. 接受接口，返回结构体
+func NewOrderService(repo OrderRepository, notifier Notifier) *OrderService {
+    return &OrderService{repo: repo, notifier: notifier}
+}
+
+// 3. 隐式接口满足 — 不需要 implements 关键字
+// 编译期验证接口满足
+var _ UserRepository = (*PostgresUserRepo)(nil)
+```
+
+---
+
+## 6. 泛型（Go 1.18+）
+
+### 6.1 类型参数与约束
+
+```go
+// 泛型函数
+func Map[T any, U any](s []T, f func(T) U) []U {
+    result := make([]U, len(s))
+    for i, v := range s {
+        result[i] = f(v)
+    }
+    return result
+}
+
+// 使用
+names := Map(users, func(u User) string { return u.Name })
+
+// 自定义约束
+type Number interface {
+    ~int | ~int8 | ~int16 | ~int32 | ~int64 |
+    ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 |
+    ~float32 | ~float64
+}
+
+func Sum[T Number](nums []T) T {
+    var total T
+    for _, n := range nums {
+        total += n
+    }
+    return total
+}
+
+// ~ 波浪号表示包含底层类型，如 type Celsius float64 也能匹配 ~float64
+```
+
+### 6.2 泛型类型
+
+```go
+// 泛型数据结构
+type Stack[T any] struct {
+    items []T
+}
+
+func (s *Stack[T]) Push(v T)        { s.items = append(s.items, v) }
+func (s *Stack[T]) Pop() (T, bool)  {
+    if len(s.items) == 0 {
+        var zero T
+        return zero, false
+    }
+    v := s.items[len(s.items)-1]
+    s.items = s.items[:len(s.items)-1]
+    return v, true
+}
+
+// 泛型约束接口
+type Ordered interface {
+    ~int | ~float64 | ~string
+}
+
+func Max[T Ordered](a, b T) T {
+    if a > b { return a }
+    return b
+}
+
+// 标准库约束包
+import "golang.org/x/exp/constraints" // 或 Go 1.21+ 的 cmp 包
+import "cmp"
+
+func Min[T cmp.Ordered](a, b T) T {
+    if a < b { return a }
+    return b
+}
+```
+
+### 6.3 类型推断
+
+```go
+// Go 编译器通常可推断类型参数，无需显式指定
+result := Map(numbers, double)       // 推断 T=int, U=int
+sorted := slices.SortFunc(users, func(a, b User) int {
+    return cmp.Compare(a.Name, b.Name)
+})
+```
+
+---
+
+## 7. 性能优化
+
+### 7.1 内存分配优化
+
+```go
+// 1. 预分配切片
+items := make([]Item, 0, expectedSize) // 避免反复扩容
+
+// 2. 使用 strings.Builder 拼接字符串
+var b strings.Builder
+b.Grow(1024) // 预分配
+for _, s := range parts {
+    b.WriteString(s)
+}
+result := b.String()
+
+// 3. 避免不必要的 []byte <-> string 转换
+// 4. 使用指针接收者避免大结构体拷贝
+// 5. 对热路径考虑使用 sync.Pool
+```
+
+### 7.2 逃逸分析
+
+```go
+// 变量是否分配到堆由编译器逃逸分析决定
+// 查看逃逸分析结果：
+// go build -gcflags="-m" ./...
+
+// 导致逃逸的常见原因：
+// 1. 返回局部变量的指针
+func newUser() *User { u := User{}; return &u } // u 逃逸到堆
+
+// 2. 赋值给接口类型
+var w io.Writer = os.Stdout // 值可能逃逸
+
+// 3. 闭包捕获的变量
+// 4. 切片 append 触发扩容后数据迁移
+
+// 减少逃逸的技巧：
+// - 使用值类型而非指针（小结构体 <= 64 bytes）
+// - 避免不必要的接口装箱
+// - 预分配 buffer 并通过参数传入而非函数内创建
+```
+
+### 7.3 pprof 性能分析
+
+```go
+import (
+    "net/http"
+    _ "net/http/pprof" // 注册 pprof 端点
+)
+
+func main() {
+    // 生产服务中启用 pprof（仅内网）
+    go func() {
+        log.Println(http.ListenAndServe("localhost:6060", nil))
+    }()
+}
+```
+
+```bash
+# CPU 分析（采集 30 秒）
+go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
+
+# 内存分析
+go tool pprof http://localhost:6060/debug/pprof/heap
+
+# Goroutine 分析（排查泄漏）
+go tool pprof http://localhost:6060/debug/pprof/goroutine
+
+# 常用交互命令
+# top10        — 最耗资源的 10 个函数
+# list funcName — 逐行分析
+# web          — 生成火焰图（需安装 graphviz）
+```
+
+### 7.4 trace 工具
+
+```bash
+# 收集 trace 数据
+curl -o trace.out http://localhost:6060/debug/pprof/trace?seconds=5
+go tool trace trace.out
+
+# trace 能可视化：goroutine 调度、GC 暂停、网络/系统调用阻塞
+```
+
+### 7.5 Benchmark 基准测试
+
+```go
+func BenchmarkJSONMarshal(b *testing.B) {
+    user := User{ID: 1, Name: "test", Email: "test@example.com"}
+    b.ResetTimer()
+    b.ReportAllocs() // 报告内存分配次数
+
+    for i := 0; i < b.N; i++ {
+        json.Marshal(user)
+    }
+}
+
+// 子基准测试
+func BenchmarkHash(b *testing.B) {
+    sizes := []int{64, 256, 1024, 4096}
+    for _, size := range sizes {
+        b.Run(fmt.Sprintf("size=%d", size), func(b *testing.B) {
+            data := make([]byte, size)
+            b.ResetTimer()
+            for i := 0; i < b.N; i++ {
+                sha256.Sum256(data)
+            }
+        })
+    }
+}
+```
+
+```bash
+go test -bench=. -benchmem ./...
+go test -bench=BenchmarkHash -count=5 -benchtime=3s ./...
+
+# 对比两次结果
+go install golang.org/x/perf/cmd/benchstat@latest
+benchstat old.txt new.txt
+```
+
+---
+
+## 8. 标准库精选
+
+### 8.1 net/http
+
+```go
+// 生产级 HTTP 服务器
+srv := &http.Server{
+    Addr:         ":8080",
+    Handler:      mux,
+    ReadTimeout:  5 * time.Second,
+    WriteTimeout: 10 * time.Second,
+    IdleTimeout:  120 * time.Second,
+}
+
+// 中间件模式
+func loggingMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        start := time.Now()
+        next.ServeHTTP(w, r)
+        log.Printf("%s %s %v", r.Method, r.URL.Path, time.Since(start))
+    })
+}
+
+// Go 1.22+ 路由增强
+mux := http.NewServeMux()
+mux.HandleFunc("GET /users/{id}", getUser)
+mux.HandleFunc("POST /users", createUser)
+mux.HandleFunc("DELETE /users/{id}", deleteUser)
+
+func getUser(w http.ResponseWriter, r *http.Request) {
+    id := r.PathValue("id")
+    // ...
+}
+
+// 生产级 HTTP 客户端（设置超时！）
+client := &http.Client{
+    Timeout: 10 * time.Second,
+    Transport: &http.Transport{
+        MaxIdleConns:        100,
+        MaxIdleConnsPerHost: 10,
+        IdleConnTimeout:     90 * time.Second,
+    },
+}
+```
+
+### 8.2 encoding/json
+
+```go
+type APIResponse struct {
+    Code    int             `json:"code"`
+    Message string          `json:"message"`
+    Data    json.RawMessage `json:"data,omitempty"` // 延迟解析
+}
+
+// 自定义 JSON 序列化
+type Timestamp time.Time
+
+func (t Timestamp) MarshalJSON() ([]byte, error) {
+    return json.Marshal(time.Time(t).Unix())
+}
+
+func (t *Timestamp) UnmarshalJSON(data []byte) error {
+    var unix int64
+    if err := json.Unmarshal(data, &unix); err != nil {
+        return err
+    }
+    *t = Timestamp(time.Unix(unix, 0))
+    return nil
+}
+
+// 流式解析大 JSON
+decoder := json.NewDecoder(r.Body)
+decoder.DisallowUnknownFields() // 严格模式
+if err := decoder.Decode(&req); err != nil {
+    http.Error(w, "invalid json", 400)
+    return
+}
+```
+
+### 8.3 database/sql
+
+```go
+import (
+    "database/sql"
+    _ "github.com/lib/pq" // PostgreSQL 驱动
+)
+
+// 连接池配置
+db, err := sql.Open("postgres", dsn)
+if err != nil {
+    log.Fatal(err)
+}
+db.SetMaxOpenConns(25)
+db.SetMaxIdleConns(10)
+db.SetConnMaxLifetime(5 * time.Minute)
+db.SetConnMaxIdleTime(1 * time.Minute)
+
+// 带 context 查询
+func (r *UserRepo) FindByID(ctx context.Context, id int64) (*User, error) {
+    var u User
+    err := r.db.QueryRowContext(ctx,
+        "SELECT id, name, email FROM users WHERE id = $1", id,
+    ).Scan(&u.ID, &u.Name, &u.Email)
+    if err == sql.ErrNoRows {
+        return nil, ErrNotFound
+    }
+    return &u, err
+}
+
+// 事务
+func (r *OrderRepo) CreateOrder(ctx context.Context, order *Order) error {
+    tx, err := r.db.BeginTx(ctx, nil)
+    if err != nil {
+        return err
+    }
+    defer tx.Rollback() // 如果 Commit 已调用，Rollback 为 no-op
+
+    _, err = tx.ExecContext(ctx, "INSERT INTO orders ...")
+    if err != nil {
+        return err
+    }
+    _, err = tx.ExecContext(ctx, "UPDATE inventory ...")
+    if err != nil {
+        return err
+    }
+    return tx.Commit()
+}
+```
+
+### 8.4 context 包（详见 3.7 节）
+
+### 8.5 io 包
+
+```go
+// io.Reader / io.Writer 是 Go 最重要的抽象
+// 组合 Reader
+r := io.LimitReader(resp.Body, 1<<20) // 限制读取 1MB
+r = io.TeeReader(r, &buf)             // 同时写入 buf
+
+// 高效复制
+written, err := io.Copy(dst, src)              // 自动使用 buffer
+written, err := io.CopyN(dst, src, 1024)       // 复制 N 字节
+written, err := io.CopyBuffer(dst, src, buf)   // 使用指定 buffer
+
+// ReadAll（注意内存，生产中优先用流式处理）
+data, err := io.ReadAll(resp.Body)
+```
+
+---
+
+## 9. Web 框架对比
+
+### 9.1 Gin vs Fiber vs Echo
+
+| 特性 | Gin | Fiber | Echo |
+|------|-----|-------|------|
+| 底层 | net/http | fasthttp | net/http |
+| 性能 | 高 | 极高 | 高 |
+| 生态 | 最大 | 增长中 | 成熟 |
+| 中间件 | 丰富 | 丰富 | 丰富 |
+| 路由 | radix tree | 前缀树 | radix tree |
+| 学习成本 | 低 | 低(类Express) | 低 |
+| net/http兼容 | 完全 | 不兼容 | 完全 |
+| 推荐场景 | 通用首选 | 极致性能 | 企业API |
+
+### 9.2 Gin 示例
+
+```go
+r := gin.Default() // 包含 Logger + Recovery 中间件
+
+// 路由组 + 中间件
+api := r.Group("/api/v1", authMiddleware())
+{
+    api.GET("/users", listUsers)
+    api.GET("/users/:id", getUser)
+    api.POST("/users", createUser)
+    api.PUT("/users/:id", updateUser)
+    api.DELETE("/users/:id", deleteUser)
+}
+
+func getUser(c *gin.Context) {
+    id := c.Param("id")
+    user, err := userService.FindByID(c.Request.Context(), id)
+    if err != nil {
+        if errors.Is(err, ErrNotFound) {
+            c.JSON(404, gin.H{"error": "user not found"})
+            return
+        }
+        c.JSON(500, gin.H{"error": "internal error"})
+        return
+    }
+    c.JSON(200, user)
+}
+
+// 参数绑定与验证
+type CreateUserRequest struct {
+    Name  string `json:"name" binding:"required,min=2,max=50"`
+    Email string `json:"email" binding:"required,email"`
+    Age   int    `json:"age" binding:"gte=0,lte=150"`
+}
+
+func createUser(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(400, gin.H{"error": err.Error()})
+        return
+    }
+    // ...
+}
+```
+
+---
+
+## 10. 微服务开发
+
+### 10.1 gRPC + Protobuf
+
+```protobuf
+// proto/user.proto
+syntax = "proto3";
+package user;
+option go_package = "github.com/company/myservice/proto/user";
+
+service UserService {
+    rpc GetUser(GetUserRequest) returns (UserResponse);
+    rpc ListUsers(ListUsersRequest) returns (stream UserResponse);
+    rpc CreateUser(CreateUserRequest) returns (UserResponse);
+}
+
+message GetUserRequest {
+    string id = 1;
+}
+
+message UserResponse {
+    string id = 1;
+    string name = 2;
+    string email = 3;
+    int64 created_at = 4;
+}
+```
+
+```go
+// 服务端实现
+type userServer struct {
+    pb.UnimplementedUserServiceServer
+    repo UserRepository
+}
+
+func (s *userServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.UserResponse, error) {
+    user, err := s.repo.FindByID(ctx, req.Id)
+    if err != nil {
+        return nil, status.Errorf(codes.NotFound, "user not found: %v", err)
+    }
+    return &pb.UserResponse{
+        Id:    user.ID,
+        Name:  user.Name,
+        Email: user.Email,
+    }, nil
+}
+
+// 启动 gRPC 服务器
+lis, _ := net.Listen("tcp", ":50051")
+grpcServer := grpc.NewServer(
+    grpc.UnaryInterceptor(grpc_middleware.ChainUnaryServer(
+        grpc_recovery.UnaryServerInterceptor(),
+        grpc_zap.UnaryServerInterceptor(logger),
+    )),
+)
+pb.RegisterUserServiceServer(grpcServer, &userServer{repo: repo})
+grpcServer.Serve(lis)
+```
+
+### 10.2 服务发现与断路器
+
+```go
+// 使用 go-kit 或 hashicorp/consul 进行服务发现
+
+// 断路器 — sony/gobreaker
+cb := gobreaker.NewCircuitBreaker(gobreaker.Settings{
+    Name:        "userService",
+    MaxRequests: 3,                    // 半开状态最大请求数
+    Interval:    10 * time.Second,     // 统计窗口
+    Timeout:     30 * time.Second,     // 开路到半开的等待时间
+    ReadyToTrip: func(counts gobreaker.Counts) bool {
+        return counts.ConsecutiveFailures > 5
+    },
+    OnStateChange: func(name string, from, to gobreaker.State) {
+        log.Printf("breaker %s: %s -> %s", name, from, to)
+    },
+})
+
+result, err := cb.Execute(func() (interface{}, error) {
+    return client.GetUser(ctx, userID)
+})
+```
+
+### 10.3 健康检查与优雅退出
+
+```go
+func main() {
+    srv := &http.Server{Addr: ":8080", Handler: mux}
+
+    // 启动
+    go func() {
+        if err := srv.ListenAndServe(); err != http.ErrServerClosed {
+            log.Fatalf("listen: %v", err)
+        }
+    }()
+
+    // 等待中断信号
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+    log.Println("shutting down...")
+
+    // 优雅退出，给 30 秒处理剩余请求
+    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+    if err := srv.Shutdown(ctx); err != nil {
+        log.Fatalf("shutdown: %v", err)
+    }
+    log.Println("server stopped")
+}
+```
+
+---
+
+## 11. 测试
+
+### 11.1 testing 包基础
+
+```go
+func TestUserService_Create(t *testing.T) {
+    t.Parallel() // 标记可并行执行
+
+    svc := NewUserService(mockRepo)
+    user, err := svc.Create(context.Background(), "Alice", "alice@example.com")
+
+    if err != nil {
+        t.Fatalf("unexpected error: %v", err)
+    }
+    if user.Name != "Alice" {
+        t.Errorf("got name=%q, want %q", user.Name, "Alice")
+    }
+}
+```
+
+### 11.2 Table-Driven Tests
+
+```go
+func TestValidateEmail(t *testing.T) {
+    tests := []struct {
+        name    string
+        email   string
+        wantErr bool
+    }{
+        {"valid email", "user@example.com", false},
+        {"no at sign", "userexample.com", true},
+        {"no domain", "user@", true},
+        {"empty", "", true},
+        {"unicode local", "用户@example.com", false},
+        {"multiple at", "a@b@c.com", true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            t.Parallel()
+            err := ValidateEmail(tt.email)
+            if (err != nil) != tt.wantErr {
+                t.Errorf("ValidateEmail(%q) error=%v, wantErr=%v", tt.email, err, tt.wantErr)
+            }
+        })
+    }
+}
+```
+
+### 11.3 httptest
+
+```go
+func TestGetUserHandler(t *testing.T) {
+    // 创建测试服务器
+    handler := NewRouter(mockService)
+    ts := httptest.NewServer(handler)
+    defer ts.Close()
+
+    resp, err := http.Get(ts.URL + "/api/users/123")
+    if err != nil {
+        t.Fatal(err)
+    }
+    defer resp.Body.Close()
+
+    if resp.StatusCode != 200 {
+        t.Errorf("status=%d, want 200", resp.StatusCode)
+    }
+
+    var user User
+    json.NewDecoder(resp.Body).Decode(&user)
+    if user.ID != "123" {
+        t.Errorf("got id=%s, want 123", user.ID)
+    }
+}
+
+// 测试单个 handler（不需要完整服务器）
+func TestCreateUserHandler(t *testing.T) {
+    body := strings.NewReader(`{"name":"Alice","email":"alice@test.com"}`)
+    req := httptest.NewRequest("POST", "/api/users", body)
+    req.Header.Set("Content-Type", "application/json")
+    w := httptest.NewRecorder()
+
+    createUserHandler(w, req)
+
+    if w.Code != 201 {
+        t.Errorf("status=%d, want 201", w.Code)
+    }
+}
+```
+
+### 11.4 testify 与 gomock
+
+```go
+// testify — 断言库
+import "github.com/stretchr/testify/assert"
+
+func TestOrder(t *testing.T) {
+    order, err := createOrder(ctx, items)
+    assert.NoError(t, err)
+    assert.Equal(t, "pending", order.Status)
+    assert.Len(t, order.Items, 3)
+    assert.Contains(t, order.Items, expectedItem)
+    assert.WithinDuration(t, time.Now(), order.CreatedAt, time.Second)
+}
+
+// gomock — 接口 Mock
+//go:generate mockgen -source=repository.go -destination=mock_repository.go -package=service
+
+func TestUserService_Get(t *testing.T) {
+    ctrl := gomock.NewController(t)
+    mockRepo := NewMockUserRepository(ctrl)
+
+    mockRepo.EXPECT().
+        FindByID(gomock.Any(), "user-1").
+        Return(&User{ID: "user-1", Name: "Alice"}, nil)
+
+    svc := NewUserService(mockRepo)
+    user, err := svc.Get(context.Background(), "user-1")
+    assert.NoError(t, err)
+    assert.Equal(t, "Alice", user.Name)
+}
+```
+
+---
+
+## 12. 工具链
+
+### 12.1 go mod
+
+```bash
+go mod init github.com/company/project  # 初始化模块
+go mod tidy                              # 同步依赖（移除无用+补充缺失）
+go mod vendor                            # 生成 vendor/
+go mod graph                             # 打印依赖图
+go mod why github.com/some/dep           # 查看依赖为何被引入
+go mod edit -replace old=new@v1.0.0      # 替换依赖
+go list -m -json all                     # JSON 格式列出所有依赖
+```
+
+### 12.2 go vet 与 golangci-lint
+
+```bash
+# go vet — 内建静态分析
+go vet ./...
+
+# golangci-lint — 聚合 100+ linter
+# .golangci.yml 推荐配置
+```
+
+```yaml
+# .golangci.yml
+run:
+  timeout: 5m
+
+linters:
+  enable:
+    - errcheck        # 检查未处理的错误
+    - govet           # 内建 vet 检查
+    - staticcheck     # 高级静态分析
+    - unused          # 未使用的代码
+    - gosimple        # 代码简化建议
+    - ineffassign     # 无效赋值
+    - gocritic        # 风格与性能建议
+    - revive          # golint 替代
+    - misspell        # 拼写检查
+    - prealloc        # 切片预分配建议
+    - bodyclose       # HTTP body 未关闭
+    - noctx           # HTTP 请求缺少 context
+    - exhaustive      # switch 穷举检查
+
+linters-settings:
+  govet:
+    enable-all: true
+  revive:
+    rules:
+      - name: unexported-return
+        disabled: true
+```
+
+```bash
+golangci-lint run ./...
+golangci-lint run --fix ./...  # 自动修复部分问题
+```
+
+### 12.3 go generate
+
+```go
+//go:generate stringer -type=Status
+//go:generate mockgen -source=service.go -destination=mock_service.go
+//go:generate protoc --go_out=. --go-grpc_out=. proto/user.proto
+
+type Status int
+
+const (
+    StatusPending  Status = iota
+    StatusActive
+    StatusInactive
+)
+```
+
+```bash
+go generate ./...
+```
+
+---
+
+## 13. 部署
+
+### 13.1 交叉编译
+
+```bash
+# Go 原生支持交叉编译
+GOOS=linux GOARCH=amd64 go build -o myapp-linux-amd64 ./cmd/myapp
+GOOS=darwin GOARCH=arm64 go build -o myapp-darwin-arm64 ./cmd/myapp
+GOOS=windows GOARCH=amd64 go build -o myapp.exe ./cmd/myapp
+
+# 静态链接（无 CGO 依赖）
+CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o myapp ./cmd/myapp
+# -s 去掉符号表  -w 去掉 DWARF 调试信息  → 二进制缩小 ~25%
+
+# 注入版本信息
+go build -ldflags="-X main.version=1.2.3 -X main.commit=$(git rev-parse --short HEAD)" ./cmd/myapp
+```
+
+### 13.2 Docker 多阶段构建
+
+```dockerfile
+# ---- 构建阶段 ----
+FROM golang:1.22-alpine AS builder
+
+RUN apk add --no-cache git ca-certificates
+
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -ldflags="-s -w -X main.version=${VERSION}" \
+    -o /app/server ./cmd/server
+
+# ---- 运行阶段 ----
+FROM scratch
+# 或 FROM gcr.io/distroless/static-debian12（包含 CA 证书和时区数据）
+
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+COPY --from=builder /app/server /server
+
+EXPOSE 8080
+USER 65534:65534
+ENTRYPOINT ["/server"]
+```
+
+```bash
+# 最终镜像通常 < 15 MB
+docker build -t myapp:latest .
+docker run -p 8080:8080 myapp:latest
+```
+
+### 13.3 静态链接注意事项
+
+```text
+CGO_ENABLED=0 生成完全静态链接的二进制，优点：
+- 可使用 scratch / distroless 最小镜像
+- 无系统库依赖，跨发行版部署
+- 安全扫描表面最小
+
+注意：如果使用了需要 CGO 的库（如 go-sqlite3），需要用 musl-gcc 交叉编译
+或选择纯 Go 替代库（如 modernc.org/sqlite）
+```
+
+---
+
+## 14. 常见陷阱
+
+### 14.1 Goroutine 泄漏
+
+```go
+// BAD — channel 永远没人读，goroutine 永远阻塞
+func leaky() {
+    ch := make(chan int)
+    go func() {
+        result := expensiveComputation()
+        ch <- result // 永远阻塞，因为没有接收者
+    }()
+    // 函数返回，ch 无人接收
+}
+
+// GOOD — 用 context 或 buffered channel 防止泄漏
+func safe(ctx context.Context) (int, error) {
+    ch := make(chan int, 1) // 缓冲区=1，即使没人读也不阻塞
+    go func() {
+        ch <- expensiveComputation()
+    }()
+    select {
+    case result := <-ch:
+        return result, nil
+    case <-ctx.Done():
+        return 0, ctx.Err()
+    }
+}
+
+// 检测泄漏：用 runtime.NumGoroutine() 或 goleak 库
+import "go.uber.org/goleak"
+func TestMain(m *testing.M) {
+    goleak.VerifyTestMain(m)
+}
+```
+
+### 14.2 Map 并发读写
+
+```go
+// BAD — map 并发读写会 panic: concurrent map writes
+// Go 运行时在检测到并发 map 操作时会直接 fatal（不是 panic，无法 recover）
+
+// GOOD 方案一：sync.Mutex
+type SafeMap struct {
+    mu sync.RWMutex
+    m  map[string]int
+}
+
+func (s *SafeMap) Get(key string) (int, bool) {
+    s.mu.RLock()
+    defer s.mu.RUnlock()
+    v, ok := s.m[key]
+    return v, ok
+}
+
+func (s *SafeMap) Set(key string, val int) {
+    s.mu.Lock()
+    defer s.mu.Unlock()
+    s.m[key] = val
+}
+
+// GOOD 方案二：sync.Map（适合读多写少或 key 稳定的场景）
+var cache sync.Map
+cache.Store("key", "value")
+if v, ok := cache.Load("key"); ok {
+    fmt.Println(v)
+}
+```
+
+### 14.3 defer 陷阱
+
+```go
+// 陷阱一：循环中的 defer
+// BAD — defer 在函数退出时才执行，循环中会积累大量 defer
+func processFiles(paths []string) error {
+    for _, path := range paths {
+        f, err := os.Open(path)
+        if err != nil { return err }
+        defer f.Close() // 所有文件直到函数返回才关闭！
+    }
+    return nil
+}
+
+// GOOD — 封装到子函数
+func processFiles(paths []string) error {
+    for _, path := range paths {
+        if err := processOneFile(path); err != nil {
+            return err
+        }
+    }
+    return nil
+}
+func processOneFile(path string) error {
+    f, err := os.Open(path)
+    if err != nil { return err }
+    defer f.Close()
+    // ...
+    return nil
+}
+
+// 陷阱二：defer 参数求值时机
+x := 1
+defer fmt.Println(x) // 打印 1，不是 2
+x = 2
+// 解法：用闭包
+defer func() { fmt.Println(x) }() // 打印 2
+```
+
+### 14.4 nil 接口 vs nil 指针
+
+```go
+// Go 接口内部有两个字段：(type, value)
+// 只有 type 和 value 都为 nil 时，接口才 == nil
+
+type MyError struct{ Msg string }
+func (e *MyError) Error() string { return e.Msg }
+
+func getError() error {
+    var p *MyError = nil
+    return p // 返回的 error 接口：(type=*MyError, value=nil)，不等于 nil！
+}
+
+err := getError()
+fmt.Println(err == nil) // false！
+
+// GOOD — 直接返回 nil
+func getError() error {
+    var p *MyError = nil
+    if p == nil {
+        return nil // 返回 (type=nil, value=nil)
+    }
+    return p
+}
+```
+
+### 14.5 闭包变量捕获
+
+```go
+// BAD (Go < 1.22) — 循环变量被闭包共享
+for _, item := range items {
+    go func() {
+        process(item) // 所有 goroutine 可能都用最后一个 item
+    }()
+}
+
+// GOOD (Go < 1.22) — 显式传参
+for _, item := range items {
+    item := item // 重新绑定到新变量
+    go func() {
+        process(item)
+    }()
+}
+
+// Go 1.22+ — 循环变量每次迭代都是新变量，此问题已修复
+// 但在 go.mod 中 go 版本 < 1.22 时仍需注意
+```
+
+### 14.6 切片陷阱
+
+```go
+// 子切片与原切片共享底层数组
+original := []int{1, 2, 3, 4, 5}
+sub := original[1:3] // [2, 3]
+sub[0] = 99
+fmt.Println(original) // [1, 99, 3, 4, 5] — 被修改了！
+
+// GOOD — 完整复制
+sub := make([]int, 2)
+copy(sub, original[1:3])
+
+// 或使用三索引切片限制容量
+sub := original[1:3:3] // len=2, cap=2，append 不会影响原数组
+```
+
+---
+
+## 15. 项目结构推荐
+
+```text
+myservice/
+├── cmd/
+│   └── server/
+│       └── main.go           # 入口，仅做依赖注入和启动
+├── internal/                  # 私有代码，外部不可 import
+│   ├── handler/               # HTTP/gRPC handler
+│   ├── service/               # 业务逻辑
+│   ├── repository/            # 数据访问
+│   ├── model/                 # 领域模型
+│   └── middleware/            # 中间件
+├── pkg/                       # 公共库，可被外部 import
+│   ├── httputil/
+│   └── logger/
+├── api/                       # API 定义（OpenAPI / Proto）
+│   └── proto/
+├── migrations/                # 数据库迁移
+├── configs/                   # 配置文件模板
+├── scripts/                   # 构建/部署脚本
+├── Dockerfile
+├── Makefile
+├── go.mod
+├── go.sum
+└── .golangci.yml
+```
+
+---
+
+## Agent Checklist
+
+以下检查项供 AI Agent 在代码审查和生成时参考：
+
+### 必查项 (MUST)
+
+- [ ] 所有 error 都已处理，没有 `_ = err` 或忽略返回值
+- [ ] 所有 HTTP 请求使用了带超时的 `context.Context`
+- [ ] `http.Client` 和 `http.Server` 都设置了 `Timeout`
+- [ ] 所有 goroutine 有明确的退出机制（context / channel / WaitGroup）
+- [ ] map 在并发场景使用了 `sync.Mutex` 或 `sync.Map`
+- [ ] `defer f.Close()` 在循环中没有使用（应封装到子函数）
+- [ ] 返回 error 接口时没有返回类型化的 nil 指针
+- [ ] `database/sql` 连接池参数已配置（MaxOpen / MaxIdle / ConnMaxLifetime）
+- [ ] `resp.Body.Close()` 在所有 HTTP 响应路径中都有调用（包括错误路径）
+- [ ] Dockerfile 使用多阶段构建，最终镜像基于 scratch 或 distroless
+
+### 应查项 (SHOULD)
+
+- [ ] 使用 `errors.Is` / `errors.As` 而非 `==` 比较或类型断言
+- [ ] 错误信息包含上下文（哪个函数、哪个参数）
+- [ ] 使用 `strings.Builder` 而非 `+` 拼接多个字符串
+- [ ] 切片预分配了容量 `make([]T, 0, expectedLen)`
+- [ ] 接口方法数 <= 3，超过则拆分
+- [ ] 使用 `t.Parallel()` 加速测试
+- [ ] table-driven test 覆盖边界情况
+- [ ] `golangci-lint` 配置中启用了 errcheck / govet / staticcheck / bodyclose / noctx
+- [ ] gRPC 服务使用了 recovery / logging interceptor
+- [ ] 日志使用结构化 logger（zap / slog）而非 `log.Printf`
+
+### 可查项 (MAY)
+
+- [ ] 热路径使用 `sync.Pool` 复用 buffer
+- [ ] 使用 `go build -ldflags="-s -w"` 减小二进制体积
+- [ ] Benchmark 覆盖核心算法，使用 `benchstat` 对比
+- [ ] 使用 `goleak.VerifyTestMain` 检测 goroutine 泄漏
+- [ ] 使用三索引切片 `s[low:high:max]` 防止子切片污染原数组
+- [ ] Context.Value 仅用于请求范围元数据，不用于传递业务参数
+
+---
+
+**知识ID**: `golang-complete`
+**领域**: development
+**类型**: standards
+**难度**: intermediate-advanced
+**质量分**: 97
+**维护者**: dev-team@umadev.com
+**最后更新**: 2026-03-28