写 Go 第一年 vs 第五年：我的代码从“能跑就行”到“不敢删一行”

本文不教语法，只讲真实项目里被坑到报警的实战经验——
有些坑，连官方 linter 都不提醒你，但上线后分分钟教你做人。

---

🧨 1. init()：甜蜜的毒药，写着爽，查 bug 要命

❌ 我干过的“好事”：

// cmd/root.go
func init() {
    rootCmd.AddCommand(versionCmd)
    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file")
}

→ 58 个子命令，58 个 init()，散落在 58 个文件里……
→ 想改个 flag？先 grep -r init .，再祈祷没隐式依赖。

💥 痛点暴击：

• 顺序不可控：file_a.go 和 file_b.go 的 init() 谁先执行？看 Go 编译器心情 😑
• 无法单元测试：你不能 init() 两次，也不能 mock 它。
• GODEBUG=inittrace=1 是 Go 1.16 才给的后悔药（早干嘛去了？）

✅ 正确姿势：

// 显式调用，可控、可测、可读
func SetupCommands(root *cobra.Command) {
    root.AddCommand(NewVersionCommand())
    root.PersistentFlags().StringVar(&cfgFile, "config", "", "config file")
}

📌 原则：除非是查表优化（如 unicode.IsLetter lookup table），否则 init() 请慎用！

---

🔒 2. 全局变量 + 配置 = 高并发下的定时炸弹 ⏳

❌ 经典反模式：

var config *Config

func init() {
    config = LoadConfig()
}

func HandleRequest(w http.ResponseWriter, r *http.Request) {
    if config.Debug {
        log.Printf("Request: %s", r.URL)
    }
    // …
}

→ 本地跑得好好的；
→ 一压测：fatal error: concurrent map read and map write
→ QA：这功能上线能活过 5 分钟？

✅ 解决方案三连：

(1) 显式传参（首选！）

type Server struct {
    config *Config
}

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    if s.config.Debug { ... }
}

(2) context 传简单参数（谨慎！）

ctx := context.WithValue(r.Context(), "debug", config.Debug)
r = r.WithContext(ctx)

⚠️ 别传整个 config！context 是逃生通道，不是行李托运仓！

(3) sync.Once 初始化（只读场景）

var (
    config *Config
    once   sync.Once
)

func GetConfig() *Config {
    once.Do(func() {
        config = loadFromEnv()
    })
    return config
}

---

📦 3. “包洁癖”晚期：58 个命令 = 58 个 package？！

📉 症状：

• cmd/user/create
• cmd/user/list
• cmd/user/delete
• …（还有 55 个）

💀 后果：

• go mod graph 像蜘蛛网
• import "myapp/cmd/user/create" 和 import "myapp/cmd/user/delete" 冲突，被迫 import create "..."
• CI 构建慢 3 倍（每个包单独编译）

✅ 整治方案：

cmd/
├── user.go     // UserCommand struct + NewUserCommand()
├── server.go   // ServerCommand
└── root.go

→ 一个 command = 一个 struct + 方法，文件控制在 200~400 行内
→ 学 net/http：整个 HTTP 栈就一个 package，十几个文件，清晰如诗 📜

🧠 Go 包设计黄金法则：
“按功能聚合，而非按文件类型拆分”
不是 model/, handler/, service/ —— 是 user/, payment/, notification/

---

🔐 4. 滥用 exported 名称：把 internal 当 public 卖

❌ 你是不是也这么干过？

// pkg/db/db.go
func Connect() *sql.DB { ... }      // ✅ 合理
func migrate(db *sql.DB) error { ... } // ❌ 应该小写！但为了测试 export 了……

→ 然后其他 package 开始 db.Migrate() —— 技术债诞生！

✅ 救命稻草：internal/ + //go:linkname（慎用！）

internal/
├── db/
│   ├── db.go        // Connect(), migrate()（小写）
│   └── db_test.go   // 直接调 migrate()
└── user/

→ internal/db 只能被同级或上级 package import
→ API 表面越小，重构自由度越高

🔍 小技巧：用 apidiff 检测破坏性变更！
发布前跑一句：apidiff old/v1.2 new/v1.3，秒知是否要升 major 版本。

---

📦 5. 无脑 import：一个库让二进制从 4MB → 9MB！

❌ 惨案现场：

import _ "github.com/go-git/go-git/v5" // “就加个 git 支持，能有多大？”

→ 实际：嵌入了 git 协议解析、对象存储、packfile 压缩……
→ 二进制膨胀 125%，用户下载慢，CDN 成本涨，自己背锅。

✅ 优雅解法：Build Tags + 条件编译

// +build experimental

package gitimpl

import "github.com/go-git/go-git/v5"

func Clone(url string) error { ... }

// main.go
var (
    cloneFunc func(string) error
)

func init() {
    #ifdef experimental
        cloneFunc = gitimpl.Clone
    #else
        cloneFunc = execGitClone // fallback to `exec.Command("git", ...)`
    #endif
}

→ 默认轻量；go build -tags experimental 才带重武器 🔫

---

🧵 6. Goroutine 多写 = 并发打印乱码？

❌ 终端动画库翻车实录：

go func() {
    fmt.Print("🔥") // 50 个 goroutine 同时 print
}()

→ 输出：🔥🔥🔥🔥🔥🔥🔥（Unicode 撕碎现场）

✅ 解决方案：

(1) sync.Mutex（简单场景）

var mu sync.Mutex
mu.Lock()
fmt.Print("🔥")
mu.Unlock()

(2) 单一 writer goroutine（高吞吐）

msgCh := make(chan string)
go func() {
    for msg := range msgCh {
        fmt.Print(msg)
    }
}()

// 其他 goroutine 只发消息
msgCh <- "🔥"

(3) 用 log 包（自带互斥！）

log.SetFlags(0)
log.Print("🔥") // 线程安全！

🔍 必开技能：go test -race —— 数据竞争检测器，能救命！
（参考：Therac-25 医疗事故，竞态条件真能杀人）

---

📝 7. 注释羞耻症：信了“好代码不用注释”的邪！

❌ 曾经的我：

// returns true if valid
func check(u *User) bool {
    return u.Age > 0 && u.Email != ""
}

→ 三个月后：Age > 0？负年龄是超人？Email 不校验格式？

✅ 现在的我：

// IsValid returns true if the user has a positive age and non-empty email.
// Note: Email format validation is intentionally omitted for performance;
// downstream services (e.g., SendGrid) perform stricter checks.
func (u *User) IsValid() bool {
    return u.Age > 0 && u.Email != ""
}

→ 注释 = 给未来的自己写便签
→ godoc 自动生成 API 文档（go doc -all . 预览）

📚 推荐学习：net/http 源码的注释密度——每一行都在讲故事。

---

🎯 终极总结：Go 老兵的 5 条生存法则

坑点	反模式	✅ 正确姿势
初始化	init() 滥用	显式调用 + 懒加载
配置	全局变量	struct 注入 / context（谨慎）
包结构	1 文件 = 1 package	按领域聚合，控制 export 边界
依赖	无脑 import	build tags + 条件编译
并发	随意 spawn goroutine	-race 检测 + 单 writer 模式

---

🌟 最后一句真心话：
“代码写一次，读一百次；
今天的偷懒，是明天的加班。”

共勉。

---