Go 语言学习宝典
CHAPTER 01 · 快速入门

认识 Go 与环境搭建

一句话总览:Go 是一门「编译成单个二进制、天生为并发和后端服务设计」的静态语言——没有 node_modules,没有虚拟机,go build 出来的文件扔到服务器就能跑。
🍱
生活化类比
部署 Node 项目像搬家带一堆家具:要装运行时、要 npm install、要对齐版本;部署 Go 程序像拎一个自热便当:米饭、菜、加热包全在一个盒子里(静态链接的单二进制),到哪儿拆开就能吃。边界:便当没法「到现场换菜」——Go 编译后不能像 JS 那样热改代码,改一行就得重新 build。

1.1 为什么前端同学值得学 Go

  • 语法极简:25 个关键字(TS 远超这个数),没有 class 继承、没有装饰器,一天能过完语法。
  • 并发是一等公民:go f() 一个关键字起协程,对比 JS 单线程事件循环是完全不同的并发模型。
  • 工具链自带全家桶:格式化 gofmt、测试 go test、依赖 go mod、竞态检测 -race,全部官方内置,没有「选 eslint 还是 biome」的纠结。
  • 云原生生态(Docker、K8s、etcd)几乎全是 Go 写的,做全栈/独立工具后端的主流选择。

1.2 三个命令跑起来

终端 · 从零到跑通
go version              # 确认安装成功(官网下载或包管理器安装)
mkdir hello && cd hello
go mod init example/hello   # 初始化模块,生成 go.mod(≈ package.json)
go run .                # 编译并立刻运行当前目录的 main 包
go build                # 只编译,产出可执行文件 hello(Windows 为 hello.exe)
main.go
package main            // main 包 = 可执行程序入口(库包则用其他名字)

import "fmt"            // 导入标准库格式化包;导入了不用会编译报错!

func main() {           // main 函数 = 程序入口,无参数无返回值
    fmt.Println("Hello, 逗比!")   // 语句结尾不写分号,gofmt 说了算
}
Go 与 Node/TS 的「从源码到运行」路径对比
TS / Node 路径 .ts 源码 tsc 转译 .js 产物 Node + node_modules 目标机要装环境 Go 路径 .go 源码 go build(含链接) 单个二进制(含运行时) 目标机零依赖,直接执行
Go 把「运行时 + 依赖」全部打进一个文件,这就是它部署体验碾压解释型语言的原因。

1.3 go.mod:你的 package.json

前端世界Go 世界说明
package.jsongo.mod模块名 + 依赖版本清单
npm install xxxgo get xxx拉依赖并写入清单
node_modules/全局模块缓存依赖统一缓存,项目目录里没有依赖文件夹
package-lock.jsongo.sum校验和锁定,保证可复现
npx tsc / vitego build / go run官方唯一工具链,无选型焦虑
⚠ 高频陷阱:导入了不用 / 声明了不用
Go 把「import 了没使用」「局部变量声明了没使用」当编译错误而不是警告——从 JS 过来第一天会被拦到怀疑人生。正确姿势:写完顺手 goimports(自动增删 import),临时不用的变量用 _ 丢弃。
✓ 口诀
「mod 管依赖,build 出成品,run 是边编译边跑;交叉编译一句 GOOS=linux go build 就出 Linux 版」。

1.4 随堂自测

QUIZ 1
把 Go 程序部署到一台全新 Linux 服务器,需要做什么?
Go 静态编译,运行时和依赖都链接进二进制里,目标机不需要任何 Go 环境。A/B/D 都是解释型或 VM 语言的部署思路。
QUIZ 2
代码里 import "strings" 但全程没用到 strings 包,结果是?
Go 强制「导入必须使用」,未使用的 import 是编译错误(不是警告),这是保持代码整洁的硬性设计。用 goimports 工具可自动清理。
CHAPTER 02 · 快速入门

变量与基本类型

一句话总览:Go 是静态强类型语言,但 := 让你写起来像动态语言;最独特的设计是「一切变量声明即有零值」——Go 世界里没有 undefined 和随机垃圾值。
🏨
生活化类比
声明变量像入住酒店:var s string 是「订了房还没放行李」,但房间不是毛坯——酒店已默认铺好床(零值:字符串是 ""、数字是 0、布尔是 false)。JS 的 let x; 则是给你一间写着 undefined 的空房。边界:零值不等于「业务上有意义」,指针、map、slice 的零值是 nil,直接用 map 的零值写入会 panic(第 5 章细讲)。

2.1 声明的四种姿势

vars.go
var a int = 10      // 完整声明:var 名字 类型 = 值
var b = 10          // 省略类型:由右侧推断为 int(≈ TS 的类型推断)
var c int           // 只声明:c = 0(零值保底,没有垃圾值)
d := 10             // 短变量声明:最常用,只能在函数内部用

var (               // 批量声明块
    name string = "润曦"
    age  int    = 36
)

const Pi = 3.14159  // 常量:编译期确定,不可取地址
const (
    Sunday = iota   // iota 枚举计数器:0
    Monday          // 自动延续表达式:1
    Tuesday         // 2
)

2.2 基本类型速查(64 位平台)

类型大小零值用途 / 对比 TS
int / uint8 字节0默认整数;JS 的 number 不分整浮,Go 严格分
int32 / int644 / 8 字节0定宽整数,跨平台协议、数据库字段用它
float648 字节0默认浮点,≈ JS number 的精度
bool1 字节false只有 true/false,没有 truthy/falsy!
string—""不可变 UTF-8 字节序列
byte1 字节0uint8 别名,处理原始字节
rune4 字节0int32 别名,一个 Unicode 码点(一个汉字)

2.3 类型转换必须显式

convert.go
var i int = 42
var f float64 = float64(i)   // ✓ 显式转换
// var g float64 = i         // ❌ 编译错误!int 不会偷偷变 float64

n := 7 / 2                   // ⚠ n = 3(int/int 整数除法)
x := 7 / 2.0                 // ✓ x = 3.5(常量 2.0 参与浮点运算)

s := "你好Go"
fmt.Println(len(s))          // ⚠ 8!len 数的是字节:3+3+1+1
fmt.Println(len([]rune(s)))  // ✓ 4:转成 rune 切片才是字符数

if i != 0 { }                // ✓ 条件必须是 bool
// if i { }                  // ❌ 没有 JS 那套 truthy 隐式转换
⚠ 高频陷阱::= 的「假声明真覆盖」
a, err := f() 在同一作用域重复出现时,若 a 已存在,:= 只会复用旧 a、新建 err(只要左侧至少一个新变量)。但在 if/for 内层作用域用 := 会新建同名变量,把外层变量遮蔽(shadow)——外层值纹丝不动,bug 静默发生。正确姿势:内层想改外层变量就用 =,并开启 go vet -shadow 类检查。
✓ 口诀
「函数内 :=,包级 var;零值兜底心不慌;转换必须写明白,len 数字节不数字」。

2.4 随堂自测

QUIZ 1
var s string 声明后不赋值,s 的值是?
Go 所有变量声明即初始化为零值:string 是 "",数字是 0,bool 是 false。nil 只属于指针/slice/map/channel/接口/函数这几类;undefined 是 JS 的概念。
QUIZ 2
len("豆包666") 的结果是?(UTF-8 下一个汉字占 3 字节)
len 对 string 数的是字节:2 个汉字 ×3 + 3 个数字 ×1 = 9。想数字符要 len([]rune(s)),这是 Go 处理中文最常见的坑。
CHAPTER 03 · 快速入门

流程控制与函数

一句话总览:Go 只有 for 一种循环、switch 默认不穿透、函数天生多返回值;defer 是「函数退出前必做的收尾清单」,按后进先出执行。
🧳
生活化类比
defer 像出门前贴在门上的便利贴:「关燃气」「锁窗」「带钥匙」,每写一条 defer 就贴一张,出门(函数 return)时从最后贴的开始撕(LIFO)。哪怕你是被火警赶出去的(panic),便利贴照样逐张执行。边界:便利贴上的内容在贴的那一刻就写死了——defer 的参数在声明时求值,不是执行时。

3.1 for 是唯一循环,if 不带括号

flow.go
for i := 0; i < 3; i++ { }   // 经典三段式(没有 while 关键字)
for cond { }                  // 这就是 while
for { }                       // 这就是 while(true)

nums := []int{10, 20, 30}
for i, v := range nums {      // range ≈ for...of + entries()
    fmt.Println(i, v)         // i 是下标,v 是元素副本
}
for _, v := range nums { }    // 不要下标就用 _ 丢弃

if n := compute(); n > 0 {    // if 可带一条初始化语句,n 只在 if/else 内可见
    fmt.Println(n)
}

switch day {                  // 默认 break!不写 fallthrough 不穿透
case "sat", "sun":            // 一个 case 可列多个值
    fmt.Println("周末")
default:
    fmt.Println("搬砖")
}

3.2 多返回值:Go 的错误处理基石

funcs.go
func div(a, b int) (int, error) {   // 返回两个值:结果 + 错误
    if b == 0 {
        return 0, fmt.Errorf("除数不能为 0")
    }
    return a / b, nil               // nil 表示"没有错误"
}

q, err := div(10, 2)                // 一次接住两个返回值
if err != nil {                     // Go 的标志性节奏:先判 err
    return
}
fmt.Println(q)

func swap(a, b int) (int, int) { return b, a }  // 多返回值让交换不用临时变量

adder := func(x int) func(int) int {  // 闭包:和 JS 一样捕获外层变量
    sum := 0
    return func(y int) int { sum += y; return sum }
}
defer 的压栈与执行顺序(LIFO)
函数体从上往下执行 defer fmt.Println("A") defer fmt.Println("B") defer fmt.Println("C") return // 触发收尾 defer 栈(后进先出) C ← 最先执行 B A ← 最后执行 执行方向 输出:C → B → A panic 时也照常执行
defer 注册时压栈、函数退出时弹栈——所以「先开的资源后关」天然成立(开文件→加锁→…→解锁→关文件)。
⚠ 高频陷阱:defer 的参数在「注册那一刻」定格
i := 0; defer fmt.Println(i); i = 9 输出的是 0 不是 9——参数在 defer 语句执行时就拷贝求值了。后果:以为打印最终状态,实际打印旧值,排查半天。正确姿势:想取退出时的值,包一层闭包 defer func(){ fmt.Println(i) }(),闭包捕获的是变量本身。
⚠ 别在循环里堆 defer
defer 到函数返回才执行,不是循环体结束。循环里开 1 万个文件全 defer 关闭 → 文件句柄耗尽。正确姿势:把循环体抽成小函数,或手动在迭代末尾关闭。
✓ 口诀
「for 一招鲜,switch 不穿透;结果配 err,defer 倒着走」。

3.3 随堂自测

QUIZ 1
x := 1; defer fmt.Println(x); x = 5; return,defer 打印什么?
defer 的参数在注册时立即求值并拷贝,当时 x=1,所以打印 1。想拿退出时的 x,要用闭包 defer func(){ fmt.Println(x) }()。
QUIZ 2
Go 的 switch 匹配到某个 case 并执行完后,默认会?
Go 与 C/JS 相反:case 默认自带 break,想穿透要显式写 fallthrough。所以 Go 的 switch 里几乎见不到 break。
CHAPTER 04 · 复合数据

数组与切片

一句话总览:数组是定长的值类型(很少直接用),切片 slice 才是日常主力——它只是一个「指针 + 长度 + 容量」的小窗口,透过窗口看到的是共享的底层数组。
🎞️
生活化类比
底层数组是一整卷电影胶片(固定 24 格),切片是你手里的取景框:ptr 决定从第几格开始看,len 是当前框住几格,cap 是从起点到胶片末尾还剩几格可用。两个取景框可以框同一段胶片——你改一格,别人的画面也变。append 超出胶片长度时,冲印店直接换一卷更大的新胶片并把旧画面拷过去(扩容搬家),从此两个框各看各的。边界:JS 的 Array 自带独立扩容语义,而 Go 切片的「共享还是分家」取决于有没有触发扩容,这是最大差异。

4.1 数组 vs 切片

slice.go
var arr [3]int = [3]int{1, 2, 3}  // 数组:长度是类型的一部分,[3]int ≠ [4]int
b := arr                          // 数组赋值 = 整体拷贝(值类型!)
b[0] = 99                         // arr 不受影响

s := []int{1, 2, 3}               // 切片:不写长度,日常 99% 用它
t := make([]int, 2, 5)            // make(类型, len, cap):len=2 个零值,cap=5
u := s[1:3]                       // 截取 [1,3):共享底层数组!
u[0] = 99                         // ⚠ s 也变成 {1, 99, 3}

s = append(s, 4)                  // append 可能扩容,必须接住返回值
fmt.Println(len(s), cap(s))       // 长度 vs 容量,两个概念别混
切片头(slice header)与底层数组的关系
s(切片头 24 字节) ptr → 底层数组[1] len = 2 cap = 4 u := s[1:2] len=1 cap=3 同一个 ptr 10 20 30 0 0 窗口外 s 可见(len=2) cap 内的预留位(append 免搬家) 底层数组(真正的数据)
切片本体只有 24 字节(指针+len+cap),传参极轻;但数据是共享的——改窗口里的元素等于改底层数组。

4.2 扩容:什么时候「搬家分家」

append 时若 len < cap,直接写进预留位(仍共享);若 len == cap,分配更大的新数组(小切片约 ×2,大切片约 ×1.25),拷贝旧数据,从此与旧数组决裂。

HANDS-ON DEMO
切片 append 扩容模拟器
从 make([]int, 0, 1) 出发连续 append,观察 len/cap 变化与「搬家」时刻——黄色虚线格是 cap 内的预留位。
⚠ 高频陷阱:append 不接返回值 + 截取后共享污染
① append(s, x) 写成一句不赋值 → 扩容时新数组没人引用,数据静默丢失;必须 s = append(s, x)。② 从大切片截一小段长期持有 → 整个大底层数组无法被 GC 回收(内存泄漏),且后续 append 可能覆写别人的数据。正确姿势:需要独立副本时用 copy 或 slices.Clone。
✓ 口诀
「切片是窗口,数组是胶片;append 必接住,满了就搬家;要分家先 copy」。

4.3 随堂自测

QUIZ 1
s := make([]int, 2, 4); t := append(s, 9); t[0] = 99,s[0] 变成多少?
len=2 < cap=4,append 没触发扩容,t 和 s 共享底层数组,t[0]=99 直接改了 s[0]。若 cap 已满触发搬家,两者才会分家——这正是切片最难直觉化的点。
QUIZ 2
为什么 append(s, x) 必须写成 s = append(s, x)?
append 返回新的切片头(可能 ptr/len/cap 全变了)。不接返回值语法上不报错,但扩容场景下新数据无人引用,造成静默丢数据——比编译错误更危险。
CHAPTER 05 · 复合数据

map 映射

一句话总览:map 是 Go 的哈希表(≈ JS 的 Object/Map),三条铁律:写前必须 make、读不存在的键返回零值、遍历顺序故意随机。
🗄️
生活化类比
map 像一排按名字拼音归档的病历柜:键经哈希函数算出柜号,直接开柜取件,不用从头翻(O(1))。医院故意不按入柜顺序发报表(遍历随机),防止你依赖顺序写出脆弱代码。查一个不存在的病人,柜员不会报错,而是递给你一张空白表(零值)——所以「有这个人但体温是 0」和「没这个人」要用 comma-ok 区分。边界:柜子没有管理员锁,两个医生同时往里塞病历(并发写)会直接拉闸停业(fatal error),不是排队等待。

5.1 基本操作速查

操作写法说明 / 对比 JS
创建m := make(map[string]int)或字面量 map[string]int{"a":1};≈ new Map()
写入m["a"] = 1键必须可比较(slice/map/函数不能当键)
读取v := m["x"]不存在返回零值 0,不是 undefined
判存在v, ok := m["x"]ok 是 bool,区分「零值」和「不存在」
删除delete(m, "a")删不存在的键也不报错
遍历for k, v := range m顺序每次随机,要有序先取键排序
长度len(m)≈ map.size
map.go
scores := map[string]int{"go": 95, "ts": 90}  // 字面量创建,已分配好

scores["rust"] = 80              // 写入/更新
v, ok := scores["java"]          // v=0, ok=false —— comma ok 判存在
if !ok {
    fmt.Println("没学过 java")
}

for name, s := range scores {    // ⚠ 每次运行顺序都可能不同!
    fmt.Println(name, s)
}
delete(scores, "ts")

var m map[string]int             // ⚠ 零值 nil map
_ = m["x"]                       // ✓ 读 nil map 安全,返回零值
// m["x"] = 1                    // ❌ panic: assignment to entry in nil map
⚠ 高频陷阱①:nil map 写入直接 panic
var m map[string]int 只声明了「柜子图纸」没建柜子,读安全、写就 panic。结构体字段里的 map 最容易中招(忘了初始化)。正确姿势:声明即 make,或在构造函数里统一初始化。
⚠ 高频陷阱②:并发写 map = 程序直接崩
两个 goroutine 同时写同一个 map → fatal error: concurrent map writes,这是 runtime 级 fatal,recover 都救不回。正确姿势:加 sync.Mutex、用 sync.Map(读多写少场景),或按 key 分片。上线前跑 go run -race 体检。
✓ 口诀
「写前 make,读用 comma-ok;遍历无序要排序,并发写必加锁」。

5.2 随堂自测

QUIZ 1
m := map[string]int{},执行 v := m["ghost"] 后 v 和程序状态是?
读不存在的键返回该值类型的零值(int 是 0),不报错。要区分「存了 0」和「没这个键」必须用 v, ok := m["ghost"]。nil/undefined 都不是 int 的合法值。
QUIZ 2
两个 goroutine 并发写同一个 map,最可能的结果是?
runtime 检测到并发写 map 会抛 fatal error 直接终止进程,级别高于 panic,recover 拦不住。必须用锁或 sync.Map 保护,-race 能提前暴露问题。
CHAPTER 06 · 复合数据

结构体与方法

一句话总览:Go 没有 class——用 struct 定义数据、把方法「挂」在类型上、用嵌入实现组合;方法改不改得到原对象,完全取决于接收者是值还是指针。
🪪
生活化类比
值接收者像拿身份证复印件去办事:你在复印件上涂改(改字段),原件毫发无损;指针接收者是拿原件本人到场,改的就是真身。嵌入(embedding)则像手机装上镜头模组:手机直接「拥有」模组的拍照能力(方法提升),但手机不是镜头的 subclass——没有继承树,只有拼装。边界:复印件成本随证件厚度涨——struct 很大时值接收每次调用都整体拷贝,性能吃亏。

6.1 定义、方法与「构造函数」

user.go
type User struct {
    Name string `json:"name"`   // 首字母大写 = 导出(public),小写 = 包内私有
    age  int    `json:"age"`    // 反引号里是 tag:给 json 等库看的元信息
}

func NewUser(name string) *User {        // 没有 constructor,约定用 NewXxx
    return &User{Name: name}             // & 取地址,返回指针
}

func (u User) Hello() string {           // 值接收者:拿到的是副本
    return "hi, " + u.Name
}

func (u *User) GrowUp() {                // 指针接收者:能改真身
    u.age++                              // ✓ 生效
}

u := NewUser("润曦")
u.GrowUp()                               // 语法糖:自动取地址 (&u).GrowUp()
值接收者 vs 指针接收者:改的是谁
u (原对象) age = 36 func (u User) Set() 值接收:整份拷贝 副本.age = 40 调用结束副本销毁 ✗ func (u *User) GrowUp() 指针接收:只拷 8 字节地址 u.age++ → 原对象 37 ✓ 通过地址直接写真身
「方法没生效」十有八九是值接收者在改副本——要修改状态就用指针接收者。

6.2 嵌入:组合优于继承

embed.go
type Engine struct{ Power int }
func (e Engine) Start() string { return "引擎点火" }

type Car struct {
    Engine          // 嵌入(不写字段名):Engine 的方法"提升"给 Car
    Brand string
}

c := Car{Engine: Engine{Power: 200}, Brand: "BYD"}
fmt.Println(c.Start())   // ✓ 直接调用,像"继承"了 Start
fmt.Println(c.Power)     // ✓ 字段也提升
// 但这是组合:Car 不是 Engine 的子类型,不能把 Car 当 Engine 传参
// 多态靠接口(第 8 章),不靠类型层级
⚠ 高频陷阱:值接收者改字段 = 白改
func (u User) SetAge(n int) { u.age = n } 编译运行都不报错,但改的是副本,原对象纹丝不动——静默错误最难查。正确姿势:① 会修改状态的方法一律指针接收者;② 同一类型的方法集要么全值要么全指针,混用会导致接口实现判定出意外(第 8 章)。
✓ 口诀
「大写导出小写藏;要改状态用指针;嵌入是拼装不是继承;构造全靠 NewXxx」。

6.3 随堂自测

QUIZ 1
方法 func (c Counter) Inc() { c.n++ } 调用后,原 Counter 的 n 会?
值接收者拿到整个 struct 的拷贝,c.n++ 只改副本,调用结束副本销毁。改成 (c *Counter) 才能修改原对象。编译器不拦这种逻辑错误,所以格外阴险。
QUIZ 2
Go 中「导出」(包外可见,相当于 public)的规则是?
Go 用首字母大小写控制可见性:Name 导出、name 包内私有,没有 public/private 关键字。json 序列化只能读导出字段,小写字段会被静默忽略——两者常一起踩坑。
CHAPTER 07 · 接口与指针

指针与值语义

一句话总览:Go 只有值传递——所谓「引用效果」都是拷贝了指针或拷贝了含指针的头结构;指针就是「写着门牌号的纸条」,且 Go 砍掉了 C 的指针运算,安全得多。
🏠
生活化类比
传值 = 把房子整个复制一栋给对方折腾;传指针 = 给对方一张写着地址的纸条,对方按地址上门改装修,你家真变了。Go 里 slice/map 传参看着像「传引用」,其实传的是复印的纸条(slice 头/哈希表指针的副本)——纸条内容一样,所以能找到同一栋房子;但你把对方手里的纸条涂改(append 扩容换地址),你自己的纸条不变。边界:Go 的纸条不能加减偏移(无指针运算),也不能指向半块砖(不能取字段中间地址乱走)。

7.1 指针 basics

ptr.go
x := 10
p := &x            // & 取地址:p 的类型是 *int
fmt.Println(*p)    // * 解引用:读到 10
*p = 20            // 通过指针改真身 → x 变成 20

var q *int         // 指针零值是 nil
// fmt.Println(*q) // ❌ panic: 解引用 nil 指针(≈ 空指针异常)

func grow(n *int) { *n++ }   // 想在函数里改外部变量 → 传指针
grow(&x)                     // x = 21

u := &User{Name: "润曦"}     // &T{...} 直接造对象拿指针(最常用)
v := new(User)               // new(T):分配零值 T,返回 *T,两者等价
u.Name = "肖俊"              // Go 自动解引用,不用写 (*u).Name
Go 传参真相:一切皆拷贝,拷的东西不同
调用 f(v) 时被拷贝的内容 int / struct / 数组 整个值拷贝 → 函数内改了不影响外面 *T 指针 拷 8 字节地址 → 指向同一对象 slice / map / channel 拷「含指针的头」→ 数据共享的假引用 堆上的同一份数据 User{Name:"润曦", age:36} 地址副本 头里的 ptr 副本
没有真正的「传引用」:指针和 slice/map 能改到外部数据,是因为副本里存着通往同一份数据的地址。

7.2 什么时候用指针

场景建议原因
函数/方法要修改接收的数据用 *T值副本改了白改
struct 很大(几十个字段)用 *T避免每次调用整体拷贝
小值类型 int/bool/小 struct直接传值拷贝比指针间接寻址还便宜,且无共享风险
需要表达「可能没有」用 *T(nil)Go 没有 undefined/null 双轨,nil 指针即「缺省」
含 sync.Mutex 的 struct必须 *T拷贝锁 = 两把不同的锁,锁形同虚设
⚠ 高频陷阱:把 slice 当「引用传参」想改长度
func add(s []int) { s = append(s, 1) } 调用后外面的 s 长度不变——slice 头是拷贝的,append 改的是函数内那份头。后果:数据「加了个寂寞」。正确姿势:返回新 slice 让调用方接住,或传 *[]int(少见)。改元素可以(共享底层数组),改 len/cap 不行。
✓ 口诀
「Go 只有值传递;改真身传指针,slice 改元素行、改长度不行;有锁必传指针」。

7.3 随堂自测

QUIZ 1
func f(s []int){ s = append(s, 9) },对外部 a := []int{1}; f(a) 之后 len(a) 是?
slice 头(ptr/len/cap)按值拷贝进函数,append 修改的是函数内的副本头,外部 a 的 len 不变。要生效必须 return 新 slice 并接住。
QUIZ 2
与 C 语言相比,Go 指针刻意去掉了什么能力来换安全?
Go 保留 & 和 *,但禁止指针算术,也不能把指针随意转成整数地址——越界乱指这类 C 的经典事故在 Go 里写不出来。配合 GC,悬垂指针也基本绝迹。
CHAPTER 08 · 接口与指针

接口与鸭子类型

一句话总览:Go 接口是隐式实现的——不写 implements,只要方法齐了就算实现;接口变量内部是「(动态类型, 动态值)」二元组,这是理解 nil 接口陷阱的钥匙。
🔌
生活化类比
接口像国标插座规格:规定「两孔 + 三孔」(方法签名)。任何电器只要插头长成这样就能插——厂家不需要向插座委员会申报「我实现了国标」(隐式实现)。TS 的 interface 也是结构化匹配,但只活在编译期;Go 接口在运行时还带着类型信息,可以做断言和 type switch。边界:插座只认插头形状不认功率——接口只约束方法集,不约束字段和行为语义。

8.1 定义与隐式实现

iface.go
type Speaker interface {      // 接口 = 方法签名集合
    Speak() string
}

type Dog struct{}
func (d Dog) Speak() string { return "汪!" }   // 没写任何 implements!

type Cat struct{}
func (c *Cat) Speak() string { return "喵~" }  // ⚠ 指针接收者

func announce(s Speaker) { fmt.Println(s.Speak()) }

announce(Dog{})     // ✓ Dog 值实现了方法集
// announce(Cat{})  // ❌ 编译错误:值 Cat 的方法集不含 Speak
announce(&Cat{})    // ✓ *Cat 的方法集包含值接收+指针接收的全部方法

var a any = 42      // any = interface{},能装一切(≈ TS unknown)
n, ok := a.(int)    // 类型断言:取出动态值,ok 判断成败
switch v := a.(type) {   // type switch:按动态类型分流
case int:    fmt.Println("整数", v)
case string: fmt.Println("字符串", v)
}
接口变量的内部结构:(类型, 值) 二元组
var s Speaker = (*Cat)(nil) 接口 s(两个格子) type = *Cat value = nil s == nil → false! type 格子非空,整体就非 nil 真正的 nil 接口 (type=nil, value=nil) 后果:err != nil 判断通过 → 调用方法时对 nil 接收者解引用 → 运行期 panic
「装了一个 nil 指针的接口」不等于「nil 接口」——这是 Go 面试与线上事故的双料常客。

8.2 方法集规则(背这一张表就够)

类型方法集包含能否满足接口
T(值)只有值接收者方法接口若含指针接收方法 → 不满足
*T(指针)值接收 + 指针接收全部方法都能满足

经验法则:类型有指针接收者方法,就统一传指针。常用小接口:fmt.Stringer(String())、io.Reader/Writer(Read/Write)、error(Error())——Go 生态靠一两个方法的小接口拼装出巨大复用性。

⚠ 高频陷阱:返回「typed nil」让 err != nil 永真
func f() error { var p *MyErr; return p }——p 是 nil,但装进 error 接口后 type 格子是 *MyErr,调用方判 err != nil 为 true,进入错误分支后一用就 panic。正确姿势:没错误就显式 return nil,永远不要把 nil 的具体指针装进接口返回。
✓ 口诀
「方法齐即实现,无需申报;指针方法集更全;接口 nil 看两格,没病就 return nil」。

8.3 随堂自测

QUIZ 1
类型 Cat 的方法 Speak 用指针接收者 func (c *Cat) Speak(),把 Cat{}(值)传给 Speaker 接口参数会?
直接调用 c.Speak() 时编译器会自动 &c,但「值装进接口」不会自动取地址——接口检查的是方法集,值类型只含值接收方法。传 &Cat{} 即可。
QUIZ 2
var p *bytes.Buffer = nil; var w io.Writer = p,则 w == nil 的结果是?
接口=(类型,值)二元组,只有两格全空才等于 nil。w 的类型格是 *bytes.Buffer,所以非 nil——这就是 typed nil 陷阱,常导致 err 判断失真。
CHAPTER 09 · 接口与指针

错误处理

一句话总览:Go 把错误当普通返回值(error 接口)而不是异常——if err != nil 是日常节奏;panic/recover 只留给「程序没法继续」的真正灾难,别当 try/catch 用。
📮
生活化类比
JS 的 try/catch 像楼下保安:楼上哪层出事都可能直接跳到你这一层,中间楼层根本不知道发生过什么。Go 的 error 像逐层签收的快递单:每一层函数拿到「问题件」都必须当面签字处理或加注转发(return err / %w 包装),错误路径在代码里清清楚楚。panic 则是整栋楼拉火警——只为地震级事故保留。边界:逐层签收写着啰嗦,但换来「每个失败点都被看见」;这也是 Go 代码 err 判断满天飞的原因。

9.1 error 三板斧:创建、包装、判定

errs.go
var ErrNotFound = errors.New("not found")   // 哨兵错误:包级变量,供调用方比对

func findUser(id int) (*User, error) {
    if id <= 0 {
        return nil, fmt.Errorf("id 非法: %d", id)     // 格式化生成错误
    }
    return nil, ErrNotFound
}

func load(id int) error {
    _, err := findUser(id)
    if err != nil {
        return fmt.Errorf("load 用户 %d 失败: %w", id, err)  // %w 包装保留原错误
    }
    return nil
}

err := load(0)
if errors.Is(err, ErrNotFound) { }   // ✓ 沿包装链找哨兵(== 只能比最外层)
var pe *fs.PathError
if errors.As(err, &pe) { }           // ✓ 沿链找特定类型并取出来
%w 包装链与 errors.Is 的逐层拆包
"load 用户 0 失败: …" 最外层(调用方拿到的) Unwrap "id 非法: 0" 中间层上下文 Unwrap ErrNotFound(哨兵) errors.Is 命中 ✓ 若用 %v 而非 %w:链子断裂,errors.Is 永远 false(错误信息还在,判定能力没了)
%w 是「保留原错误引用」的包装,%v 只是把错误转成字符串——一词之差,判等能力天壤之别。

9.2 panic / recover:仅限灾难现场

panic.go
func safeHandler() {
    defer func() {                       // recover 只在 defer 里有效
        if r := recover(); r != nil {    // 接住 panic,阻止进程崩溃
            fmt.Println("兜底:", r)
        }
    }()
    risky()                              // 里面 panic 了也能被上面接住
}
// 适用场景:HTTP 服务器兜底中间件、解析器内部越界后统一转 error
// 不适用:把 panic 当 throw、用 recover 当 catch 写业务分支
// 注意:recover 只救当前 goroutine!子协程 panic 必须自己兜
⚠ 高频陷阱①:吞错误
data, _ := json.Marshal(v) 用 _ 丢弃 err → 失败时 data 是 nil,后续逻辑拿着空数据继续跑,故障被推迟到更远的地方爆发。正确姿势:每个 err 要么处理、要么包装上抛,实在忽略要写注释说明为什么安全。
⚠ 高频陷阱②:跨 goroutine 指望 recover
主协程的 recover 救不了子 goroutine 的 panic——任何一个协程 panic 未被自己接住,整个进程崩。正确姿势:每个 go func() 内部第一行放自己的 defer+recover。
✓ 口诀
「错误是值不是异常;包装用 %w,判哨兵 Is、取类型 As;panic 只兜灾难,recover 各协程自理」。

9.3 随堂自测

QUIZ 1
中层函数用 fmt.Errorf("ctx: %v", err) 包装后,调用方 errors.Is(err, ErrNotFound) 会?
%v 把原错误格式化成字符串,丢失引用,Unwrap 链断裂;errors.Is 靠链比对而非文本。必须用 %w 才能保留判定能力——这是包装错误的第一铁律。
QUIZ 2
子 goroutine 里发生 panic,主 goroutine 的 defer+recover 能接住吗?
panic 沿当前 goroutine 的调用栈传播,recover 也只能在本协程的 defer 中拦截。未接住的子协程 panic 会终止整个进程,所以每个 go func 都要自带兜底。
CHAPTER 10 · 并发编程前置 · 类型系统补完

泛型(Go 1.18+)

一句话总览:Go 泛型 = 「类型当参数传」,用 [T 约束] 声明;约束(constraint)本质是接口,规定 T 必须会什么——比 TS 泛型更朴素,没有条件类型那些花活。
🥮
生活化类比
泛型函数是月饼模具:刻花逻辑(算法)只写一遍,塞豆沙馅(int)出豆沙月饼,塞莲蓉馅(string)出莲蓉月饼。约束就是模具上的入料规格说明:「馅料必须能比较大小」(cmp.Ordered)——不合规的馅(struct 没定义排序)根本塞不进去,编译期就拦住。边界:模具不能「按馅料自动换刻花」——Go 没有 TS 的条件类型/映射类型,泛型只解决「同一逻辑适配多类型」。

10.1 泛型函数与泛型类型

generic.go
func Max[T cmp.Ordered](a, b T) T {   // T 是类型参数,约束:可排序类型
    if a > b { return a }
    return b
}

Max(3, 7)          // ✓ 类型推断:T = int,不用写 Max[int]
Max("a", "b")      // ✓ T = string
// Max(3, "b")     // ❌ 编译错误:推断不出统一的 T

type Stack[T any] struct{ data []T }  // 泛型类型:任意 T 的栈
func (s *Stack[T]) Push(v T) { s.data = append(s.data, v) }

func Keys[K comparable, V any](m map[K]V) []K {  // 约束可组合
    ks := make([]K, 0, len(m))                   // comparable:可作 map 键
    for k := range m { ks = append(ks, k) }
    return ks
}

10.2 Go vs TS 泛型对照

维度GoTypeScript
声明func F[T any](x T)function f<T>(x: T)
约束[T cmp.Ordered](接口当约束)<T extends {...}>
类型推断实参推断,可显式 F[int]同样支持,且更强
运行时代码GC shape 特化,真实生成代码编译后类型全擦除
高级类型运算没有(无条件/映射类型)Conditional / Mapped / infer
方法加类型参数❌ 方法不能引入新类型参数✓ 方法可以有自己的泛型
⚠ 高频陷阱:为泛型而泛型
只处理一种类型、或接口就能解决多态时硬上泛型 → 代码可读性暴跌、编译变慢。社区共识:「先写具体类型,出现第二份几乎相同的代码再抽泛型」;容器类(slices/maps 工具函数)才是泛型的主场。另一个硬坑:func (s *Stack[T]) Map[U any](...) 编译报错——方法不能新增类型参数,只能写成包级函数。
✓ 口诀
「方括号里装类型,约束就是接口;标准库 slices/maps 先用熟,自己造泛型要克制」。

10.3 随堂自测

QUIZ 1
泛型约束 [K comparable] 的含义是?
comparable 是预声明约束,表示类型支持相等比较(因此能当 map 键);排序是 cmp.Ordered 的事。Go 的约束本质是接口,comparable 是语言内置的特殊接口。
QUIZ 2
与 TS 相比,Go 泛型在运行时的本质区别是?
TS 类型编译后全部擦除;Go 泛型按 GC shape 实例化出真实代码,兼顾性能与代码体积。它不是反射方案,也没有 TS 那种类型级编程能力。
CHAPTER 11 · 并发编程

goroutine 与 GMP 调度

一句话总览:go f() 启动一个初始栈仅约 2KB 的轻量协程,runtime 的 GMP 调度器把成千上万个 G multiplex 到少量系统线程上——这和 JS「单线程 + 事件循环」是两个世界。
🍜
生活化类比
面馆里:G = 订单(一碗面的制作任务,轻量、可以有几万张),P = 灶台(数量默认等于 CPU 核数,握着本地订单队列),M = 厨师(系统线程,真正干活的)。厨师必须先占一个灶台才能做菜(M 绑定 P 才能跑 G);某订单要等炖汤(系统调用阻塞),厨师可以连人带锅端走,灶台让给别的厨师继续出单——这就是阻塞不浪费并行度的关键。边界:JS 事件循环是「一个厨师看 N 口锅,谁开了处理谁」,切换点在 await;Go 是「N 个厨师真同时干活」,且 runtime 能抢占跑太久的 G。

11.1 启动与等待

goroutine.go
func work(id int) { fmt.Println("任务", id) }

func main() {
    var wg sync.WaitGroup          // 等待组:并发世界的"点名册"
    for i := 1; i <= 3; i++ {
        wg.Add(1)                  // ✓ 启动前登记(不能放进协程里)
        go func() {                // Go 1.22+ 循环变量每轮独立,可直接捕获 i
            defer wg.Done()        // 干完销号,defer 保证 panic 也销
            work(i)
        }()
    }
    wg.Wait()                      // 等所有任务销号;main 不等就直接全剧终
}
GMP 调度模型:G 排队、P 持队列、M 干活
P0(灶台 · 逻辑处理器) 本地队列: G1 G2 G3 正在跑: G0 P1 本地队列: G4 G5 正在跑: G6(快被抢占) M0(系统线程) 绑定 P0 执行 G0 M1(系统线程) 绑定 P1 执行 G6 M2:陷入系统调用的厨师 带着阻塞的 G 离开灶台 P 被移交,不浪费并行度 全局队列 + work stealing P 本地队列空了 → 去全局拿 再没有 → 偷别的 P 的一半 G G 初始栈 ≈ 2KB 可增长;线程栈 ≈ 1-8MB 固定 → 十万 G 轻松,十万线程不可能
P 的数量(GOMAXPROCS,默认=核数)决定「同时真正在跑」的 G 上限;M 可以更多,多出来的在等灶台或陷在系统调用里。

11.2 与 JS 并发模型对照

维度Go goroutineJS async/await
执行单位协程(可被抢占)事件循环里的回调段(不可抢占)
并行多核真并行单线程并发(Worker 另算)
切换点函数调用/阻塞/runtime 抢占只在 await/yield
CPU 密集任务直接扔协程,多核分摊会卡死事件循环,需 Worker
数据竞争存在!需要锁/channel/-race单线程天然没有(共享内存除外)
成本约 2KB 栈起,百万级可行Promise 极轻,但没有并行收益
⚠ 高频陷阱①:main 返回 = 全体协程即刻处决
go work() 后 main 直接结束 → 协程一行都可能没跑就随进程消失(不报错、无输出)。JS 里 pending 的 Promise 会撑着事件循环,Go 不会等任何人。正确姿势:WaitGroup / channel 同步,服务程序则让 main 阻塞在 http.ListenAndServe 上。
⚠ 高频陷阱②:goroutine 泄漏
协程阻塞在永远没人读的 channel 上 → 它和它引用的内存永远不回收,量大了 OOM。正确姿势:所有可能阻塞的协程都要有退出路径(context 取消 / channel 关闭 / 超时),用 runtime.NumGoroutine() 监控数量是否只涨不跌。
✓ 口诀
「go 一下就起飞,main 走了全都毁;G 排队 P 发牌 M 干活;起协程必想好它怎么死」。

11.3 随堂自测

QUIZ 1
GMP 模型中,决定「同一时刻最多几个 G 在真正执行代码」的是?
M 必须绑定 P 才能执行 G,所以并行度由 P 数封顶(默认=CPU 核数)。M 可以比 P 多——多出来的陷在系统调用里或待命,并不增加并行执行能力。
QUIZ 2
func main(){ go fmt.Println("hi") } 最可能的输出是?
main 返回即进程退出,所有 goroutine 立即终止,调度器大概率还没来得及跑那个 G。Go 不像 Node 会等 pending 任务,必须显式同步(WaitGroup/channel)。
CHAPTER 12 · 并发编程

channel 通道

一句话总览:channel 是协程间的类型化管道,核心哲学「用通信来共享内存,而不是用共享内存来通信」;无缓冲 channel 的收发是一次必须双方同时到场的握手。
🤝
生活化类比
无缓冲 channel 是当面递文件:你举着文件等(发送阻塞),直到有人伸手接(接收就位),交接瞬间完成,两人各自继续——谁先到谁等。带缓冲 channel 是前台的文件筐:筐没满你放下就走,筐满了才等;筐空了取件的人等。close 相当于宣布「以后不再有新文件」,筐里剩的还能取完,取完再取只会拿到空白纸 + 一张“已打烊”回执(零值, false)。边界:往打烊的筐里塞文件(向已关闭 channel 发送)不是等待,是当场掀桌(panic)。

12.1 收发与关闭的全部规则

ch.go
ch := make(chan int)      // 无缓冲:收发必须同时就绪(同步握手)
buf := make(chan int, 2)  // 缓冲 2:满前发送不阻塞,空前接收阻塞

go func() { ch <- 42 }()  // 发送:箭头指向 chan
v := <-ch                 // 接收:箭头从 chan 指出;没人发就一直等

buf <- 1                  // ✓ 不阻塞(0/2 → 1/2)
buf <- 2                  // ✓ 不阻塞(1/2 → 2/2)
// buf <- 3               // ⚠ 阻塞!筐满了,直到有人取走

close(buf)                // 只由发送方关闭;关闭后不能再发
a, ok := <-buf            // ✓ 取剩余缓冲:a=1, ok=true
// ... 取空后:
z, ok := <-buf            // ✓ 不阻塞:z=0(零值), ok=false 表示已关闭
for v := range buf { }    // range 持续接收,channel 关闭且取空后自动退出
操作nil channel正常 channel已关闭 channel
发送 ch <- v永久阻塞满则阻塞(无缓冲等接收者)panic
接收 <-ch永久阻塞空则阻塞先取剩余值,取空后返回零值不阻塞
close(ch)panic正常panic(重复关闭)
HANDS-ON DEMO
无缓冲 channel 握手模拟器
左边点「发送」模拟协程 A 执行 ch <- n,右边点「接收」模拟协程 B 执行 <-ch。观察谁先到谁阻塞、双方就绪瞬间如何交接。

12.2 select:channel 世界的多路开关

select.go
select {                     // 同时等多个 channel,谁先就绪走谁
case v := <-dataCh:
    fmt.Println("数据", v)
case <-time.After(time.Second):   // 超时分支:1 秒没数据就走这
    fmt.Println("超时")
case <-ctx.Done():                // 取消分支:上游喊停就走这
    return
default:                     // 可选:全都没就绪时立即走这(非阻塞)
    fmt.Println("都没就绪")
}
// 多个 case 同时就绪 → 随机选一个(防饿死)
// 没有 default 且全没就绪 → 阻塞等待
⚠ 高频陷阱:向已关闭的 channel 发送 / 重复 close
两者都直接 panic。多发送者场景下谁都想 close → 必炸。正确姿势:「谁发送谁关闭,只有一个发送者才 close」;多发送者用额外的 stop channel 或 context 通知退出,让 channel 自然被 GC,不 close 也合法。
⚠ 高频陷阱:所有协程都在等 → fatal deadlock
主协程 <-ch 而没有任何协程会发送 → runtime 检测到全员睡觉,抛 fatal error: all goroutines are asleep - deadlock!。注意它只在全部协程都阻塞时才触发,部分泄漏(第 11 章)它查不出来。
✓ 口诀
「无缓冲要握手,有缓冲看筐位;关后收得零值 ok=false,关后发送必 panic;谁发谁关,select 加超时」。

12.3 随堂自测

QUIZ 1
向一个已 close 且缓冲已取空的 channel 执行 v, ok := <-ch,结果是?
关闭且取空的 channel 接收永不阻塞,返回值类型零值 + false,这正是 range channel 能自动结束的原理。panic 的是「向已关闭 channel 发送」和「重复 close」。
QUIZ 2
无缓冲 channel 上,协程 A 先执行 ch <- 1,此刻协程 B 还没执行到 <-ch,A 的状态是?
无缓冲 channel 没有存储空间,发送必须等到接收者同时就绪,数据直接从 A 拷到 B(握手)。这也是它能当同步信号用的原因——「收到值」意味着「对方一定执行到了那一步」。
CHAPTER 13 · 并发编程

sync 与 context

一句话总览:共享状态用 sync 家族保护(Mutex/WaitGroup/atomic/Once),生命周期用 context 控制(取消/超时沿调用树广播)——「锁管数据,ctx 管生死」。
🚦
生活化类比
Mutex 是单人卫生间的门锁:进去反锁(Lock),出来开锁(Unlock),别人只能排队。context 是旅行团的撤退广播:团长喊「行程取消」(cancel),所有分团、小队(子 context)逐级立刻收到,各自收拾返程——没人需要轮询问「还走吗」。边界:门锁只防「同时进」,不防「你忘了锁」(不 Lock 直接改数据锁管不着);广播只通知「该撤了」,不替你撤——代码必须自己在 select/循环里检查 ctx.Done()。

13.1 sync 工具箱选型

工具解决什么典型场景
sync.Mutex同一时刻只许一个协程进临界区保护 map/计数器/缓存
sync.RWMutex读读并行、读写互斥读多写少的配置缓存
sync.WaitGroup等一批协程全部完成并发抓取 N 个 URL 后汇总
sync/atomic单个整数的无锁原子操作高并发计数器(比锁便宜)
sync.Once无论多少协程调用,只执行一次单例初始化、懒加载
sync.Map并发安全 map读多写少、键空间稳定
sync.go
type SafeCounter struct {
    mu sync.Mutex            // 锁和被保护的数据放一起(好习惯)
    n  map[string]int
}

func (c *SafeCounter) Inc(k string) {   // 必须指针接收:锁不能被拷贝!
    c.mu.Lock()
    defer c.mu.Unlock()      // defer 解锁:panic 也不会把锁带进坟墓
    c.n[k]++
}

var count atomic.Int64
count.Add(1)                 // 无锁自增,比 Mutex 快一个量级

13.2 context:取消信号的广播树

ctx.go
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()               // 即使提前完成也要 cancel,释放计时器资源

req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
resp, err := http.DefaultClient.Do(req)   // 超时/取消 → 请求立刻中断

select {                     // 自己的长任务也要主动听广播
case <-ctx.Done():
    return ctx.Err()         // context.DeadlineExceeded 或 Canceled
case result := <-workCh:
    handle(result)
}
context 取消沿树广播:一处 cancel,全树收工
Background(根) 永不取消 WithTimeout(2s) ← cancel! 请求入口:超时或手动取消 查数据库(子 ctx) Done() 关闭 → 查询中断 调下游 API(子 ctx) Done() 关闭 → 请求放弃 红色 = 取消信号 只向下传播,不影响父/兄弟
cancel 父 context,所有子孙的 Done() 同时关闭——一次用户断开连接,能瞬间停掉整条调用链上的所有浪费。
⚠ 高频陷阱:拷贝含锁的 struct
c2 := *c1(c1 含 Mutex)→ 复制出一把状态相同但独立的锁,两个对象各锁各的,共享数据照样裸奔;若复制时锁正被持有,副本永远解不开。后果:数据竞争或死锁。正确姿势:含锁类型一律用指针传递,go vet 的 copylocks 检查会帮你抓。
⚠ 高频陷阱:ctx 传了但没人听
把 ctx 一路传到底却从不检查 ctx.Done() → 取消信号广播了个寂寞,协程照跑,泄漏依旧。正确姿势:循环里每轮 select ctx.Done();阻塞操作用支持 ctx 的 API(如 NewRequestWithContext、QueryContext)。
✓ 口诀
「锁保数据 ctx 保命;Lock 必配 defer Unlock;Add 在 go 之前,cancel 必 defer;上线前 go test -race 走一遍」。

13.3 随堂自测

QUIZ 1
为什么含 sync.Mutex 的结构体方法必须用指针接收者?
锁的互斥靠「大家检查同一把锁」。值拷贝后每个副本自带一把独立锁,等于没锁,数据竞争静默回归。go vet 的 copylocks 检查专门抓这类拷贝。
QUIZ 2
调用父 context 的 cancel() 后,其子 context 会?
取消沿树向下广播到所有子孙。但注意 D 的措辞:ctx 只发信号不强杀——代码必须自己监听 Done() 并退出,这正是「传了不听等于白传」陷阱的根源。
CHAPTER 14 · 工程实战

包与模块管理

一句话总览:「目录 = 包,仓库 = 模块」:go.mod 声明模块路径,import 路径 = 模块路径 + 子目录;Go 在编译期直接禁止循环依赖,逼你把架构理清。
🏢
生活化类比
模块是整栋写字楼(go.mod 里的 module 名就是楼的全址),包是楼里的部门(一个目录一个部门),文件只是部门里的员工——同部门员工互相看不用打招呼(同包直接访问),跨部门要走全称地址(import 模块路径/目录)。internal/ 目录是「仅限本楼员工」的机密部门,楼外公司 import 直接编译报错。边界:两个部门不能互相「全员依赖对方」(循环 import),Go 的态度不是警告而是拒发施工许可证。

14.1 典型项目布局

项目结构(module github.com/runxi/toolbox)
toolbox/
├── go.mod              // module github.com/runxi/toolbox + go 1.25
├── main.go             // package main:程序入口
├── internal/           // 私有包:外部模块 import 会编译报错
│   ├── parser/         // package parser
│   └── store/          // package store
└── pkg/kit/            // 可对外复用的公共包(pkg 只是习惯,非强制)
    └── kit.go          // package kit

// main.go 里这样引用:
import "github.com/runxi/toolbox/internal/parser"  // 全路径,不是相对路径
// 使用:parser.Parse(...)  —— 包名.导出标识符
import 路径的拼装规则与依赖方向
module github.com/runxi/toolbox 模块路径(楼的全址) + /internal/parser(子目录) 目录路径(部门位置) import "…/internal/parser" 包 A ⇄ 包 B 循环依赖 编译错误!解法:抽公共类型到第三个包,或用接口反转依赖
import 永远是「模块路径 + 目录」的绝对地址;依赖必须是单向图,环在编译期就被掐死。

14.2 依赖管理命令

终端 · 依赖日常
go get github.com/gin-gonic/gin@v1.10.0  # 加依赖(@版本 可省=最新)
go mod tidy       # 对齐:代码用到的补上,没用到的删掉(提交前必跑)
go mod download   # 预下载到本地缓存(CI 常用)
go list -m all    # 查看当前模块的全部依赖版本
init 与空白导入
func init() {                   // 包初始化函数:main 之前自动执行
    // 每个包可有多个 init,按文件顺序执行;依赖包先于引用包
}

import _ "github.com/lib/pq"    // 空白导入:不用包内标识符,只为触发它的
                               // init()(数据库驱动注册的经典套路)
⚠ 高频陷阱:循环 import
A import B、B import A → import cycle not allowed,没有商量余地(JS 里循环引用常常「能跑但诡异」,Go 直接不让编译)。正确姿势:① 把共享类型/函数下沉到独立的第三个包;② B 定义接口、A 实现——依赖指向抽象而非彼此。
✓ 口诀
「一目录一包,import 走全址;internal 挡外人,tidy 常对齐;有环抽底层,驱动空白导」。

14.3 随堂自测

QUIZ 1
外部模块试图 import 你项目里的 internal/secret 包,会?
internal 是编译器强制的规则:只有 internal 父目录所在模块内的代码能导入它。这是 Go 唯一的目录级可见性机制,pkg/ 则纯属社区习惯。
QUIZ 2
import _ "github.com/lib/pq" 中下划线的作用是?
Go 禁止「导入不用」,但驱动注册类包恰恰只需要 init() 副作用。空白导入 _ 是官方豁免通道:告诉编译器「我要的就是它的初始化」。
CHAPTER 15 · 工程实战

标准库实战:JSON 与 HTTP

一句话总览:Go 标准库就能打——encoding/json 靠导出字段 + tag 做序列化,net/http 十几行起一个生产可用的服务器,不需要 Express 这类框架也能上线。
🛃
生活化类比
JSON 序列化像海关申报:只有申报单上公开的行李(首字母大写的导出字段)会被检查登记,藏在内兜的(小写字段)海关根本看不见——不是不给你带,是压根不知道存在。tag 是行李上的「对外品名贴纸」:json:"user_name" 让内部叫 UserName 的字段对外显示 user_name。边界:JS 的 JSON.stringify 能序列化一切可枚举属性,Go 的反射只能访问导出字段——这是前端转 Go 最常见的「JSON 怎么是空的」惨案根源。

15.1 JSON:Marshal / Unmarshal

json.go
type User struct {
    Name  string `json:"name"`            // 对外键名 name
    Age   int    `json:"age,omitempty"`   // 零值时省略该字段
    token string                          // ⚠ 小写:序列化时被无视
}

b, err := json.Marshal(User{Name: "润曦", Age: 36})
// b = {"name":"润曦","age":36}

var u User
err = json.Unmarshal(b, &u)   // ✓ 必须传指针!传值改的是副本
if err != nil { /* JSON 格式错 or 类型不匹配 */ }

// 结构不定时用 map 或 any(≈ JSON.parse 的宽松感)
var m map[string]any
json.Unmarshal(b, &m)         // ⚠ 数字统一变 float64,断言时注意

15.2 HTTP:十行服务器 + 带超时的客户端

server.go
func hello(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]string{"msg": "hi"})
}

func main() {
    http.HandleFunc("/hello", hello)       // 路由注册(1.22+ 支持方法匹配)
    http.ListenAndServe(":8080", nil)      // 每个请求自动一个 goroutine!
}
client.go
client := &http.Client{Timeout: 5 * time.Second}  // ✓ 必须设超时
resp, err := client.Get("https://api.example.com")
if err != nil { return err }
defer resp.Body.Close()             // ✓ 必须关 Body,否则连接泄漏

var data Result
err = json.NewDecoder(resp.Body).Decode(&data)   // 流式解码,省内存
JS / NodeGo 等价物关键差异
JSON.stringify(obj)json.Marshal(v)只序列化导出字段,返回 []byte + error
JSON.parse(s)json.Unmarshal(b, &v)必须传指针;类型不匹配返回 error
fetch(url)client.Get(url)要手动关 Body、设超时
Express 路由 + 中间件http.HandleFunc + Handler 包装标准库够用,gin/echo 是锦上添花
单线程处理请求每请求一个 goroutinehandler 里访问共享状态要加锁!
⚠ 高频陷阱①:json.Marshal 出空对象 {}
字段全小写 → 反射看不见 → 输出 {},不报任何错。正确姿势:要序列化的字段首字母大写,对外命名靠 tag。
⚠ 高频陷阱②:http.DefaultClient 无超时 + 忘关 Body
默认客户端永不超时——下游一挂,请求协程无限堆积直到内存耗尽;Body 不 Close 则连接无法复用/释放。正确姿势:自建带 Timeout 的 Client;拿到 resp 第一件事 defer resp.Body.Close()。
✓ 口诀
「大写才出境,tag 定艺名;Unmarshal 传指针;客户端必超时,Body 必 defer 关」。

15.3 随堂自测

QUIZ 1
type T struct{ name string },json.Marshal(T{name:"x"}) 的输出是?
encoding/json 基于反射,只能访问导出(大写)字段,小写字段被静默跳过,得到空对象且不报错。改成 Name string 加 tag 才能正确输出。
QUIZ 2
用 http.DefaultClient 请求一个永远不响应的服务,会发生什么?
DefaultClient 的 Timeout 是 0(无限等)。高并发下每个挂起请求占一个 goroutine 和连接,最终资源耗尽。生产代码必须自建带 Timeout 的 Client 或用 context 控制。
CHAPTER 16 · 工程实战

测试与性能

一句话总览:测试是语言内置能力:_test.go 文件 + go test 就是全部工具链;性能优化的铁律是「先 benchmark/pprof 定位,再动手」,拒绝拍脑袋。
🩺
生活化类比
benchmark 是体检报告(每次操作多少纳秒、分配几次内存),pprof 火焰图是CT 片(哪个函数烧掉了多少 CPU/内存)。先拍片再开刀——凭感觉优化就像不做检查直接上手术台,大概率切错地方。边界:体检要在「空腹标准状态」做——benchmark 机器上别同时跑编译/浏览器,否则数据抖动没法看;单次跑分不作数,要用 benchstat 看多次统计。

16.1 表驱动测试:Go 社区的标准姿势

math_test.go(与被测代码同包同目录)
func TestMax(t *testing.T) {
    cases := []struct {          // 一张表 = 一组用例,加 case 不改逻辑
        name string
        a, b, want int
    }{
        {"都正", 3, 7, 7},
        {"含负", -2, -5, -2},
        {"相等", 4, 4, 4},
    }
    for _, c := range cases {
        t.Run(c.name, func(t *testing.T) {   // 子测试:独立命名可单跑
            if got := Max(c.a, c.b); got != c.want {
                t.Errorf("Max(%d,%d)=%d, want %d", c.a, c.b, got, c.want)
            }
        })
    }
}
终端 · 测试命令全家桶
go test ./...            # 跑当前模块所有包的测试
go test -run TestMax     # 只跑名字匹配的测试
go test -race ./...      # 竞态检测:并发代码上线前必跑!
go test -cover ./...     # 覆盖率统计
go test -bench . -benchmem   # 跑基准测试,附带内存分配数据

16.2 Benchmark 与性能分析路径

bench_test.go
func BenchmarkJoin(b *testing.B) {
    for b.Loop() {               // Go 1.24+ 推荐写法(旧写法 for i<b.N)
        strings.Join([]string{"a", "b"}, "-")   // 被测操作
    }
}
// 输出:BenchmarkJoin-8  30000000  38.2 ns/op  16 B/op  1 allocs/op
//                     核数  执行次数   每次耗时   每次分配  分配次数
症状工具看什么
不知道慢在哪go test -bench 对比ns/op、B/op、allocs/op 三件套
CPU 高pprof CPU profile + 火焰图最宽的函数条 = 最热路径
内存涨pprof heapinuse_space 找持有者,alloc_space 找分配大户
协程数只涨不跌runtime.NumGoroutine() / pprof goroutine阻塞在哪个 channel/锁上
怀疑对象都逃到堆go build -gcflags="-m"逃逸分析:谁被迫堆分配
⚠ 高频陷阱:benchmark 被测代码被编译器优化掉
循环里调用纯函数却不用返回值 → 编译器判定「白算」直接删除,测出 0.5 ns/op 的假神绩。正确姿势:用 b.Loop()(自动防优化),或把结果赋给包级变量 var sink string 骗过编译器。
⚠ 高频陷阱:只测 happy path,-race 从不跑
单测全绿但上线数据竞争——普通测试探不出竞态(时序恰好没错就绿)。正确姿势:CI 里 go test -race 常开;并发代码专门写多协程压同一个对象的测试用例。
✓ 口诀
「测试表驱动,-race 保平安;优化先拍片:bench 三件套,pprof 火焰图;没有数据不动刀」。

16.3 随堂自测

QUIZ 1
benchmark 输出 42 ns/op 24 B/op 2 allocs/op,想降低 GC 压力最该盯哪个?
GC 压力来自堆分配的频率与体量:allocs/op 和 B/op 是直接指标。把每次 2 次分配优化成 0(复用 buffer、栈上化),GC 扫描量随之下降;ns/op 只反映速度不反映分配。
QUIZ 2
普通 go test 全绿,能否说明并发代码没有数据竞争?
竞态是「时序不巧才炸」的问题,普通测试碰巧串行执行就全绿。-race 在运行时插桩记录内存访问的 happens-before 关系,即使这次没炸也能报告潜在竞争;map 并发写这类才会直接 fatal。