Golangs on 山高月小

CSP（Communicating Sequential Processes）详解

Thu, 22 Oct 2026 12:07:40 +0800

CSP（通信顺序进程）详解

CSP（通信顺序进程）是由图灵奖得主托尼·霍尔提出的并发系统代数理论‌，核心思想是通过独立进程间的显式消息通信替代共享内存，从根源上降低并发编程的复杂度。

📜 理论起源与发展

1978年，英国计算机科学家 ‌托尼·霍尔‌ 首次正式阐述CSP理论，1985年出版同名专著《Communicating Sequential Processes》。

1984年，霍尔与合作者提出TCSP理论，扩展出事件隐蔽、递归等核心算子，形成完整的基于事件的代数演算系统。

CSP 是 Tony Hoare（图灵奖得主，快速排序的发明者）在 1978 年发表的一篇同名论文中提出的并发编程理论模型。它的核心主张极其简洁：

不要通过共享内存来通信，而应该通过通信来共享内存。

“Do not communicate by sharing memory; instead, share memory by communicating.”

这句话后来成为 Go 语言并发哲学的灵魂，也是 Go 官方文档里反复强调的设计原则。理解 CSP，才能理解为什么 Go 的并发原语长成 goroutine + channel + select 这个样子。

一、CSP 要解决什么问题

在 CSP 出现之前，并发编程的主流范式是共享内存 + 锁。多个线程读写同一块内存，靠互斥锁、信号量、条件变量保证正确性。这种范式的问题在实践中暴露得非常充分：

问题	表现
竞态条件（Race Condition）	结果依赖线程调度的时序，偶发、难复现
死锁（Deadlock）	两个线程各持一把锁、互相等对方的锁
锁粒度难把握	锁太粗性能差，锁太细正确性难保证
可读性差	锁的获取/释放散落在各处，逻辑不连贯

CSP 提出的思路是从根本上取消共享内存这个媒介：每个并发实体（在 CSP 里叫"进程"，在 Go 里叫 goroutine）拥有私有的状态，它们之间只能通过消息传递来交换数据。既然没有共享内存，就不需要锁，竞态和死锁问题在模型层面被大幅消解。

二、CSP 的核心抽象

CSP 理论模型里有三个基本要素：

2.1 进程（Process）

一个独立的、顺序执行的实体。它有自己的局部状态，按照既定逻辑一步步执行。在 Go 里，这就是 goroutine——一个由运行时调度的轻量级执行单元。

2.2 通道（Channel）

进程之间唯一的通信媒介。通道是有类型的、单向或双向的、可阻塞的消息队列。发送方把数据放入通道，接收方从通道取出数据。CSP 的关键在于：

通道是同步点：无缓冲通道上的发送和接收必须"会合"才继续，这天然形成了一种"握手"式的同步。
通道是唯一的数据通路：进程不共享内存，数据从发送方"移动"到接收方，而不是被两边同时看到。

Go 的 chan T 就是通道的直接实现。

2.3 选择（Choice / Select）

进程可以同时等待多个通道操作，哪个先就绪就走哪个分支。这是 CSP 的"守卫命令"（guarded command）在工程上的落地。Go 的 select 语句就是它的实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


select {
case msg := <-ch1:
    // ch1 有数据
case ch2 <- data:
    // ch2 可以发送
case <-timeout:
    // 超时
default:
    // 没有就绪的，走默认分支（非阻塞）
}

select 让"等待多个通信事件"成为一等公民，这是 CSP 区别于简单队列模型的标志性能力。

三、CSP 在 Go 中的完整映射

CSP 概念	Go 实现	说明
进程	`goroutine`	`go f()` 启动，运行时调度，栈动态增长
通道	`chan T`	有缓冲/无缓冲，可关闭，有方向类型 `chan<-` / `<-chan`
守卫选择	`select`	多路复用，支持 `default` 非阻塞和 `timeout`
同步会合	无缓冲通道的收发	发送方阻塞直到接收方就绪，反之亦然
异步解耦	有缓冲通道	缓冲满/空时才阻塞
进程终止	关闭通道 / `context` 取消	接收方通过 `v, ok := <-ch` 感知关闭

关键点：Go 的 channel 不是简单的"线程安全队列"，它是 CSP 同步语义的载体。无缓冲通道的阻塞行为是设计意图，不是性能缺陷——它强制两个 goroutine 在某个时刻"对齐"，这种对齐本身就是一种同步原语，可以替代很多场景下的锁。

四、为什么"通过通信共享内存"更好

用一个经典对比来理解。假设两个 goroutine 要"谁先到谁设置一个标志"：

共享内存 + 锁的写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var mu sync.Mutex
var done bool

// goroutine A
mu.Lock()
if !done {
    done = true
    // 做事情
}
mu.Unlock()

这里 done 是共享状态，mu 保护它，任何新增访问点都必须记得加锁。锁的保护范围和生命周期是人工维护的契约，容易漏。

CSP 的写法（用 channel 的关闭语义表达"只发生一次"）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


done := make(chan struct{})

// goroutine A
select {
case <-done:
    // 已经有人做过了
default:
    close(done)  // 只有 close 成功的人"赢得"了这次机会
    // 做事情
}

数据（“是否已完成"这个信息）通过 done 通道的关闭事件传递，而不是通过一个共享的布尔变量。没有锁，正确性由通道的关闭语义（close 只能成功一次）保证。

再看你之前代码里的实际例子——信号处理的 sigCh：

1
2
3
4
5
6


sigCh := make(chan os.Signal, 1)
signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
go func() {
    sig := <-sigCh       // 阻塞等待信号
    cancel()             // 通过 context 通知
}()

信号从操作系统（一个"进程”）通过 sigCh（通道）传给处理 goroutine（另一个"进程"），数据是"信号"这个值。main 逻辑不共享任何"信号标志位"，而是通过 ctx.Done() 这个通道的关闭事件感知退出。整条链路没有一把锁，这正是 CSP 风格的典型体现。

五、CSP vs 其他并发模型

模型	核心机制	代表语言	优点	缺点
CSP	通道传递消息，进程私有状态	Go、Occam	无锁、易推理、同步语义明确	通道设计不当也会死锁；大量细粒度通道有开销
Actor 模型	每个 Actor 有邮箱，异步消息	Erlang、Elixir、Akka	天然分布式、容错强（监督树）	消息无序、无全局同步点，调试复杂
共享内存 + 锁	互斥锁保护共享数据	C/C++/Java 传统写法	直接、灵活、性能可控	竞态、死锁、可读性差
async/await	单线程事件循环 + 协程	JS、Python	无锁、适合 IO 密集	阻塞操作会卡整个循环，CPU 密集不适用

CSP 和 Actor 的关键区别：CSP 的通道是同步会合（无缓冲时发送方要等接收方），Actor 的邮箱是异步投递（发完就走）。CSP 里"谁接收"由通道的静态连接决定，Actor 里"发给哪个 Actor"是运行时动态路由。Go 的 channel 更接近 CSP，但通过缓冲通道也提供了部分异步能力，是一个折中实现。

CSP 和共享内存的关系：CSP 并非完全禁止共享内存——Go 里你依然可以用 sync.Mutex、atomic。CSP 是一种优先推荐的范式，不是强制约束。Go 官方文档的说法是：“channel 用于在 goroutine 之间传递数据的所有权；mutex 用于保护 goroutine 内部的数据结构”。两者各司其职，不是非此即彼。

六、CSP 的局限性与实践中要注意的地方

CSP 不是银弹，用它写代码依然会踩坑：

1. 通道也会死锁

两个 goroutine 互相等待对方从通道接收，就死锁了。Go 运行时有死锁检测（所有 goroutine 都阻塞时 panic），但只在"完全无进展"时触发，复杂的多通道场景可能检测不到。

2. 通道不是"免费"的

每个通道操作都有调度开销，大量极细粒度的通道通信（比如每个元素一个通道）性能可能不如一把锁保护一个切片。CSP 适合粗粒度、有明确交接语义的通信。

3. “共享内存"换了形式也可能回来

如果通过通道传递的是指针或 map 引用，接收方拿到后修改它，本质上还是在共享内存。CSP 的"私有状态"要求传递的是值或所有权转移，传指针会破坏这个前提。

4. select 的公平性

select 在多个 case 同时就绪时随机选择一个，不保证顺序。如果需要严格的优先级，得自己用嵌套 select 或额外逻辑实现。

5. 取消与超时需要额外机制

CSP 原生没有"取消"概念，Go 用 context 补上了这块。context.Done() 本身也是一个通道（<-chan struct{}），本质上还是用 CSP 的思想实现取消传播。

七、回到你的代码：CSP 视角的解读

回顾之前的 StateGraph 工程，几处设计都可以用 CSP 的语言来解释：

信号处理：sigCh 是操作系统与程序之间的通道，signal.Notify 注册的是"谁来接收”，消费 goroutine 通过阻塞接收实现同步。

并行扇出：weather、geo、github 三个节点在 langgraphgo 内部由独立的 goroutine 执行，它们各自返回状态副本（copyState），这是"私有状态"的体现；框架在合并时通过 Reducer 把结果"通信"回主状态，而不是让三个 goroutine 直接写同一个 map——这正是"通过通信共享内存"的实践。

人工中断：GraphInterrupt 本质上是把"暂停点"的状态通过返回值"传递"给调用方，调用方决策后再把状态"传回"恢复执行。状态在两次调用之间不是被共享的，而是被移交的。

HTTP 日志的 sync.Mutex：这里用的恰恰是共享内存 + 锁。因为日志文件是一个被多个 goroutine 并发写入的单一资源，用 Mutex 保护它比"每个请求一个通道再串行化写"更简单直接。这印证了前面说的：CSP 和锁不是对立，而是分工。通道适合"传递数据所有权"，锁适合"保护共享资源"。

八、总结

CSP 的价值不在于它提供了多少新原语，而在于它重新定义了并发实体之间的关系：从"竞争同一块内存"变成"通过通道交换消息"。这个视角转换带来的收益是：

正确性更容易推理：没有隐藏的共享状态，每个 goroutine 的行为只依赖它收到的消息
同步语义显式化：无缓冲通道的阻塞行为本身就是同步点，不需要额外的锁或条件变量
组合性更好：select 让多路通信的组合表达得非常自然，这是锁模型很难优雅实现的

Go 把 CSP 从理论变成了工程现实——goroutine 足够轻、channel 足够快、select 足够灵活，三者组合让 CSP 风格成为 Go 并发代码的默认写法。但正如所有模型一样，它有自己的适用边界：用通道传递数据和信号，用锁保护内部数据结构，用 context 传播取消——这三者配合，才是 Go 并发编程的完整图景。

Template text/template 完全学习

Tue, 13 Oct 2026 11:32:20 +0800

Go 语言 `text/template` 完全指南

text/template 是 Go 标准库自带的模板引擎，专门用于生成任意文本输出（HTML、配置文件、代码、Prompt 等）。下面从零讲到进阶，每个知识点都配可运行代码。

一、为什么需要模板引擎？

假设你要生成一段 Prompt：

1
2


// 字符串拼接
prompt := "你是一个" + role + "助手。请用" + style + "风格回答。"

一旦需求变复杂——要根据条件加 few-shot 示例、要循环生成示例、要做 A/B 实验——字符串拼接就变得难以维护。

模板引擎把"文案"和"逻辑"分离：

你是一个{{ .Role }}助手。请用{{ .Style }}风格回答。

代码只负责提供数据，模板负责渲染。

二、最小可运行示例

`main.go`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


package main

import (
	"os"
	"text/template"
)

func main() {
	tmpl := template.Must(template.New("hello").Parse("你好，{{ .Name }}！你今年 {{ .Age }} 岁。\n"))

	data := map[string]any{
		"Name": "小明",
		"Age":  18,
	}

	if err := tmpl.Execute(os.Stdout, data); err != nil {
		panic(err)
	}
}

运行：

1

go run main.go

输出：

你好，小明！你今年 18 岁。

这就是模板的核心三步：Parse → Execute → 输出。

三、三个核心概念

概念	说明
Template	解析后的模板对象，可重复使用
Data	传给模板的数据，可以是 map、struct、基本类型
Execute	把模板与数据结合，写入 `io.Writer`

关键点：

Parse 只做一次，Execute 可以反复调用（并发安全）。
Execute 的第二个参数就是模板里的 .（点）。

四、模板语法详解

1. 输出变量 `{{ .字段 }}`

1
2
3
4


tmpl := template.Must(template.New("x").Parse("{{ .Name }} 在 {{ .City }}\n"))
data := map[string]string{"Name": "小明", "City": "杭州"}
tmpl.Execute(os.Stdout, data)
// 输出：小明 在 杭州

2. struct 作为数据

1
2
3
4
5
6
7
8


type User struct {
	Name string
	Age  int
}

tmpl := template.Must(template.New("x").Parse("{{ .Name }} 今年 {{ .Age }} 岁\n"))
tmpl.Execute(os.Stdout, User{Name: "小明", Age: 18})
// 输出：小明 今年 18 岁

推荐用 struct：字段名写错会在编译期报错，比 map 更安全。

3. 条件判断 `{{ if }}` `{{ else }}` `{{ end }}`

1
2
3
4
5
6


const t = `{{ if .IsVIP }}尊贵的 VIP 用户{{ else }}普通用户{{ end }}，你好！
`
tmpl := template.Must(template.New("x").Parse(t))

tmpl.Execute(os.Stdout, map[string]bool{"IsVIP": true})
tmpl.Execute(os.Stdout, map[string]bool{"IsVIP": false})

输出：

尊贵的 VIP 用户，你好！
普通用户，你好！

if 会判断值是否为"零值"：false、0、""、nil、空切片都是假。

4. 循环 `{{ range }}`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


const t = `示例：
{{ range .Examples }}输入：{{ .Input }}
输出：{{ .Output }}
{{ end }}`

data := map[string]any{
	"Examples": []map[string]string{
		{"Input": "这家餐厅很棒", "Output": "正面"},
		{"Input": "太失望了", "Output": "负面"},
		{"Input": "今天天气不错", "Output": "中性"},
	},
}

tmpl := template.Must(template.New("x").Parse(t))
tmpl.Execute(os.Stdout, data)

输出：

示例：
输入：这家餐厅很棒
输出：正面
输入：太失望了
输出：负面
输入：今天天气不错
输出：中性

range 里 . 变成当前元素，所以 {{ .Input }} 取当前元素的字段。

5. 循环里的索引

1
2
3
4
5


const t = `{{ range $i, $v := .Items }}{{ $i }}: {{ $v }}
{{ end }}`

tmpl := template.Must(template.New("x").Parse(t))
tmpl.Execute(os.Stdout, map[string]any{"Items": []string{"a", "b", "c"}})

输出：

0: a
1: b
2: c

6. 变量 `{{ $x := ... }}`

1
2
3
4


const t = `{{ $name := .Name }}你好，{{ $name }}！{{ $name }}，欢迎回来。
`
tmpl := template.Must(template.New("x").Parse(t))
tmpl.Execute(os.Stdout, map[string]string{"Name": "小明"})

输出：

你好，小明！小明，欢迎回来。

变量在 {{ end }} 后失效，也可以在 range 外定义、内部使用。

7. 管道 `{{ . | func }}`

1
2
3
4


const t = `{{ .Name | printf "%s先生" }}{{ .Text | len }} 个字
`
tmpl := template.Must(template.New("x").Parse(t))
tmpl.Execute(os.Stdout, map[string]string{"Name": "小明", "Text": "你好世界"})

输出：

小明先生4 个字

管道把前一个结果作为后一个函数的最后一个参数。

8. 内建函数一览

函数	作用	示例
`len`	长度	`{{ .Text \| len }}`
`index`	索引	`{{ index .Items 0 }}`
`printf`	格式化	`{{ printf "%d" .Age }}`
`print` / `println`	打印	`{{ print .Name }}`
`eq` / `ne`	等于/不等于	`{{ if eq .A .B }}`
`lt` / `le` / `gt` / `ge`	比较	`{{ if gt .Age 18 }}`
`and` / `or` / `not`	逻辑	`{{ if and .A .B }}`
`urlquery`	URL 转义	`{{ .Q \| urlquery }}`
`html`	HTML 转义	`{{ .T \| html }}`
`js`	JS 转义	`{{ .T \| js }}`

9. 去除空白 `{{-` 和 `-}}`

模板里的换行和缩进会原样输出。用 - 可以吃掉两侧空白：

1
2
3
4
5


const t = `示例：
{{- range .Examples }}
输入：{{ .Input }}
{{- end }}
`

输出会去掉 range 和 end 行产生的空行。

10. 注释 `{{/* ... */}}`

1
2


const t = `{{/* 这是注释，不会输出 */}}你好，{{ .Name }}
`

五、多模板与嵌套

1. 定义命名模板 `{{ define }}`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const t = `
{{ define "greeting" }}你好，{{ .Name }}！{{ end }}
{{ define "body" }}欢迎使用本系统。{{ end }}

{{ template "greeting" . }}
{{ template "body" . }}
`

tmpl := template.Must(template.New("x").Parse(t))
tmpl.Execute(os.Stdout, map[string]string{"Name": "小明"})

输出：

你好，小明！
欢迎使用本系统。

2. 模板里调用模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


const t = `
{{ define "example" }}输入：{{ .Input }}
输出：{{ .Output }}
{{ end }}

示例：
{{ range .Examples }}{{ template "example" . }}{{ end }}
`

data := map[string]any{
	"Examples": []map[string]string{
		{"Input": "很好", "Output": "正面"},
		{"Input": "太差", "Output": "负面"},
	},
}

tmpl := template.Must(template.New("x").Parse(t))
tmpl.Execute(os.Stdout, data)

输出：

示例：
输入：很好
输出：正面
输入：太差
输出：负面

六、从文件加载模板

真实项目里模板通常放在文件里。

目录结构

.
├── main.go
└── tmpl/
    ├── greeting.tmpl
    └── example.tmpl

`tmpl/greeting.tmpl`

你好，{{ .Name }}！欢迎使用。

`tmpl/example.tmpl`

示例：
{{- range .Examples }}
输入：{{ .Input }}
输出：{{ .Output }}
{{- end }}

`main.go`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


package main

import (
	"os"
	"text/template"
)

func main() {
	// 加载单个文件
	t1 := template.Must(template.ParseFiles("tmpl/greeting.tmpl"))
	t1.Execute(os.Stdout, map[string]string{"Name": "小明"})

	// 加载多个文件
	t2 := template.Must(template.ParseGlob("tmpl/*.tmpl"))
	// 指定用哪个模板渲染
	t2.ExecuteTemplate(os.Stdout, "example.tmpl", map[string]any{
		"Examples": []map[string]string{
			{"Input": "很好", "Output": "正面"},
			{"Input": "太差", "Output": "负面"},
		},
	})
}

关键点：用 ParseFiles / ParseGlob 加载多文件时，模板名就是文件名。渲染时用 ExecuteTemplate(w, "文件名", data) 指定用哪个。

七、自定义函数

模板可以注册自定义函数，扩展表达能力。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


package main

import (
	"os"
	"strings"
	"text/template"
)

func main() {
	funcs := template.FuncMap{
		"upper": strings.ToUpper,
		"trunc": func(n int, s string) string {
			if len(s) <= n {
				return s
			}
			return s[:n] + "..."
		},
		"add": func(a, b int) int { return a + b },
	}

	const t = `{{ .Name | upper }} 
{{ .Text | trunc 10 }}
1 + 2 = {{ add 1 2 }}
`

	tmpl := template.Must(template.New("x").Funcs(funcs).Parse(t))

	tmpl.Execute(os.Stdout, map[string]string{
		"Name": "xiaoming",
		"Text": "这是一段很长的文本内容需要截断",
	})
}

输出：

XIAOMING 
这是一段很长的文...
1 + 2 = 3

注意：

自定义函数必须在 Parse 之前用 Funcs 注册。
函数只能返回一个值或 (值, error)；返回 error 时，模板执行会中止并报错。
函数名是模板里用的名字，可以和 Go 函数名不同。

八、错误处理

Parse 和 Execute 都可能出错，生产代码必须处理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


tmpl, err := template.New("x").Parse("{{ .NotExist }}")
if err != nil {
	// 解析错误：语法问题
	log.Fatal(err)
}

err = tmpl.Execute(os.Stdout, map[string]string{"Name": "x"})
if err != nil {
	// 执行错误：字段不存在
	log.Fatal(err)
}

用 template.Must 可以在出错时直接 panic，适合初始化阶段：

1

tmpl := template.Must(template.New("x").Parse("..."))

规则：启动时加载模板用 Must，运行时 Execute 用 if err != nil。

九、`text/template` vs `html/template`

维度	`text/template`	`html/template`
用途	纯文本、代码、配置文件、Prompt	生成 HTML
输出转义	不转义	自动 HTML 转义
防 XSS	不负责	自动防 XSS
函数集	通用	增加 HTML 相关函数
用法	基本相同	基本相同

规则：

生成 HTML → 用 html/template
生成 Prompt、配置文件、代码 → 用 text/template

它们的模板语法完全一致，只是转义策略不同。

十、完整可运行示例：Prompt 模板引擎

把上面所有知识点串起来，做一个 Prompt 工程里常见的例子。

目录结构

.
├── main.go
├── config.json
└── prompts/
    └── classify.tmpl

`config.json`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
  "role": "文本情感分类助手",
  "labels": ["正面", "负面", "中性"],
  "style": "简洁",
  "examples": [
    {"Input": "这家餐厅很棒", "Output": "正面"},
    {"Input": "太失望了", "Output": "负面"},
    {"Input": "今天天气不错", "Output": "中性"}
  ]
}

`prompts/classify.tmpl`

你是一个{{ .Role }}。请对用户输入的文本进行分类。

{{- if .Labels }}
可选标签：{{ range $i, $l := .Labels }}{{ if $i }}、{{ end }}{{ $l }}{{ end }}
{{- end }}

风格要求：{{ .Style }}

{{- if .Examples }}
示例：
{{- range .Examples }}
输入：{{ .Input }}
输出：{{ .Output }}
{{- end }}
{{- end }}

输入：{{ .Input }}
输出：

`main.go`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


package main

import (
	"encoding/json"
	"fmt"
	"os"
	"strings"
	"text/template"
)

type Example struct {
	Input  string `json:"input"`
	Output string `json:"output"`
}

type Config struct {
	Role     string    `json:"role"`
	Labels   []string  `json:"labels"`
	Style    string    `json:"style"`
	Examples []Example `json:"examples"`
}

type PromptData struct {
	Role     string
	Labels   []string
	Style    string
	Examples []Example
	Input    string
}

func main() {
	// 1. 读取配置
	cfgBytes, err := os.ReadFile("config.json")
	if err != nil {
		panic(err)
	}
	var cfg Config
	if err := json.Unmarshal(cfgBytes, &cfg); err != nil {
		panic(err)
	}

	// 2. 加载模板
	tmpl := template.Must(template.ParseFiles("prompts/classify.tmpl"))

	// 3. 渲染
	data := PromptData{
		Role:     cfg.Role,
		Labels:   cfg.Labels,
		Style:    cfg.Style,
		Examples: cfg.Examples,
		Input:    "Go 语言的并发模型非常优雅，我很喜欢。",
	}

	var sb strings.Builder
	if err := tmpl.Execute(&sb, data); err != nil {
		panic(err)
	}

	fmt.Println(sb.String())
}

运行

1

go run main.go

输出

你是一个文本情感分类助手。请对用户输入的文本进行分类。

可选标签：正面、负面、中性

风格要求：简洁

示例：
输入：这家餐厅很棒
输出：正面
输入：太失望了
输出：负面
输入：今天天气不错
输出：中性

输入：Go 语言的并发模型非常优雅，我很喜欢。
输出：

这个例子覆盖了：

struct 作为数据
if 条件
range 循环
嵌套 if + range
$i 索引变量
空白控制 {{- / -}}
从文件加载模板

十一、常见坑与最佳实践

坑	说明	建议
字段不存在	`{{ .NotExist }}` 执行时报错	用 struct 而非 map，编译期发现拼写
空白太多	换行缩进原样输出	用 `{{-` 和 `-}}` 控制
`Parse` 只做一次	循环里重复 Parse 很浪费	Parse 一次，Execute 多次
并发安全	`Execute` 是并发安全的	一个 tmpl 可被多 goroutine 复用
自定义函数顺序	必须 Parse 前注册	`New().Funcs(...).Parse(...)`
HTML 场景误用	`text/template` 不防 XSS	HTML 输出改用 `html/template`
模板名混淆	`ParseFiles` 时模板名=文件名	用 `ExecuteTemplate` 指定

十二、函数速查表

函数	说明
`and` `or` `not`	逻辑运算
`eq` `ne` `lt` `le` `gt` `ge`	比较
`len`	长度
`index`	索引
`slice`	切片
`print` `printf` `println`	格式化
`urlquery`	URL 查询转义
`html` `js` `urlquery`	转义
`call`	调用函数值

十三、一句话总结

text/template 用 Parse 解析模板、Execute 渲染数据，支持变量、条件、循环、管道、嵌套、自定义函数，把"文案"与"逻辑"分离。它语法简单、标准库自带、无依赖，是 Go 生成任意文本（包括 Prompt）的首选。

上面的完整示例可以直接 go run，覆盖了日常使用 90% 的场景。需要更复杂的场景（如热加载、多模板继承）时，再叠加 ParseGlob 和 define / template 即可。

Template 系统性学习

Tue, 13 Oct 2026 11:05:20 +0800

Go Template 系统性学习指南

Go 标准库的模板引擎是服务端渲染和数据驱动的文本生成工具，核心设计理念是将表现层与数据模型分离。Go 用同一套语法提供了两个包：text/template 用于通用文本生成，html/template 用于 HTML 输出并自带上下文感知的自动转义安全机制。网络服务中生成 HTML 必须使用 html/template。

一、基础用法：三步流程

模板使用的核心流程固定为三步：定义/解析模板 → 准备数据 → 执行渲染。

1.1 从字符串解析

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


package main

import (
    "os"
    "text/template"
)

type Inventory struct {
    Material string
    Count    uint
}

func main() {
    // 步骤1：解析模板
    tmpl := template.Must(template.New("test").
        Parse("{{.Count}} items are made of {{.Material}}"))

    // 步骤2：准备数据
    sweaters := Inventory{"wool", 17}

    // 步骤3：执行渲染
    tmpl.Execute(os.Stdout, sweaters)
    // 输出：17 items are made of wool
}

template.Must 是对 Parse 错误的 panic 包装，适合在包初始化阶段使用。模板中只能访问结构体的导出字段（首字母大写），小写字段在模板侧不可达，会导致执行期报错或呈现零值。

1.2 从文件解析

1
2
3
4
5
6
7
8


// 解析单个文件
t, err := template.ParseFiles("templates/layout.html")

// 解析多个文件（常用于主模板+子模板）
t, err := template.ParseFiles("templates/layout.html", "templates/header.html")

// 使用 Glob 模式批量解析
t, err := template.ParseGlob("templates/*.html")

1.3 数据访问方式

1
2
3
4
5
6
7
8


// 结构体字段访问
t.Execute(w, struct{ Name string }{"Alice"})  // {{.Name}}

// map 键访问（无大小写限制）
t.Execute(w, map[string]string{"name": "Bob"}) // {{.name}} 或 {{.Name}} 均可

// 点（.）表示当前作用域的值
// 在根模板中，{{.}} 就是 Execute 传入的整个数据

二、模板语法核心

2.1 注释

1
2
3


{{/* 这是注释，不会输出 */}}

{{- /* 注释，同时修剪前后空白 */ -}}

2.2 条件判断

Go 模板中，以下值被视为“假”：false、0、nil、空字符串、空切片/映射/数组。

1
2
3
4
5


{{if .Attended}}
    很高兴您能参加婚礼。
{{else}}
    很遗憾您未能参加。
{{end}}

if 支持 else if，也常与内置比较函数配合：

1

{{if eq .Status "active"}} 活跃 {{else if gt .Score 90}} 优秀 {{end}}

常用比较函数：eq（等于）、ne（不等于）、lt（小于）、gt（大于）、le（小于等于）、ge（大于等于）。

2.3 循环 range

range 支持 slice、array、map、channel。内部 {{.}} 为当前元素；可通过变量捕获索引/键和值。

1
2
3
4
5
6
7
8
9


// 遍历切片：下标 + 值
{{range $idx, $email := .Emails}}
    第 {{$idx}} 项: {{$email}}
{{end}}

// 遍历 map：key + value
{{range $key, $value := .MapContent}}
    {{$key}}: {{$value}}
{{end}}

range 在空集合时不执行，. 不会改变。若只需值，使用 {{range .Items}} 即可。

2.4 with 改变作用域

with 将点临时切换到某个值，适合简化深层字段访问：

1
2
3


{{with .Gift}}
    感谢您送的 {{.}}。
{{end}}

若 .Gift 为“假值”，with 块不执行。

2.5 变量

1
2


{{$v := .SomeValue}}      {{/* 声明并赋值 */}}
{{$v = "new value"}}      {{/* 重新赋值（Go 1.11+） */}}

变量在 range 和 with 改变点作用域后仍然可读，这是保留根数据引用的常用手段。

2.6 管道

管道语义类似 UNIX：{{ a | f | g }} 等价于 g(f(a))。前一个函数的结果作为下一个函数的最后一个参数。

1
2


{{ .Personal | printf "[%s]" }}
{{ .Name | upper | printf "用户: %s" }}

管道让展示层的轻量格式化（如 printf）保持在模板内，避免把“仅为排版服务”的逻辑塞进业务层。

2.7 空白修剪

模板中的换行和缩进会原样输出，这在生成代码或结构化文本时往往需要精确控制。

{{- ：修剪左侧紧邻文本的尾部空白
-}} ：修剪右侧紧邻文本的前导空白

1
2
3
4
5
6
7
8
9


// 不修剪时，range 循环会引入多余换行
{{range .Items}}
    {{.}}
{{end}}

// 双向修剪，保持紧凑输出
{{- range .Items -}}
    {{.}}
{{- end -}}

注意：{{- 3}} 修剪左侧空白后解析为数字 3；而 {{-3}} 会被解析为负数 -3 的操作。修剪符后的空格必须存在。

三、自定义函数

template.FuncMap 用于将 Go 函数注册到模板命名空间中。必须先调用 Funcs() 注册函数，再调用 Parse()，否则 AST 中出现的未知标识符会导致 Parse 失败。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


funcMap := template.FuncMap{
    "upper":      strings.ToUpper,
    "formatDate": func(t time.Time) string {
        return t.Format("2006-01-02")
    },
    "safeHTML": func(s string) template.HTML {
        return template.HTML(s)  // 慎重使用！
    },
}

tmpl := template.Must(
    template.New("example").
        Funcs(funcMap).
        Parse(`{{ .User | upper }} - {{ .Time | formatDate }}`),
)

自定义函数应只做展示层的纯格式化或轻量映射（日期格式、单位转换、字符串处理）。复杂分支、聚合和权限决策应放在 Go 代码中，不要塞入模板。

四、嵌套模板与布局

4.1 define / template / block

{{define "name"}} 定义命名模板，{{template "name" .}} 调用它并传入数据。

const layout = `
{{define "base"}}


</span><span class="cp">{{</span><span class="na">.Title</span><span class="cp">}}</span><span class="s">
{{template "content" .}}

{{end}}`

const page = `
{{define "content"}}
{{.Heading}}
{{.Body}}
{{end}}`

加载顺序很重要：Go 模板引擎按加载顺序查找模板，如果多个文件定义了同名模板，只有第一个被使用。因此不同页面的内容模板应使用不同的名称。

4.2 block 用于可覆盖的默认实现

{{block "name" .}}...{{end}} 等价于“定义默认模板 + 调用它”。子模板可以通过 {{define "name"}} 覆盖默认实现。

1
2
3
4
5


// 主模板
const master = `Names:{{block "list" .}}{{range .}}{{println "-" .}}{{end}}{{end}}`

// 子模板覆盖
const overlay = `{{define "list"}}{{join . ", "}}{{end}}`

调用 masterTmpl.Execute 输出默认列表；克隆后解析 overlay 再执行，则输出用逗号连接的结果。

4.3 Gin 框架中的嵌套模板

在 Gin 中，通常用 LoadHTMLGlob 加载所有模板，配合 {{define}} 组织布局：

r := gin.Default()
r.LoadHTMLGlob("templates/**/*")

// templates/layout/base.html
// {{define "base"}}
// {{.title}}
// {{template .content .}}
// {{end}}

// templates/pages/home.html
// {{define "home-content"}}首页内容
{{end}}

// 处理器中
c.HTML(http.StatusOK, "base", gin.H{
    "title":   "Home",
    "content": "home-content",  // 动态指定要渲染的子模板名
})

如果子模板名称是动态传入的变量，标准的 {{template .content .}} 语法不支持变量作为模板名，需要通过自定义函数（如示例中的 DynamicTemplate）来间接实现。

五、HTML 安全：html/template 的自动转义

html/template 与 text/template 共享 API，但增加了上下文感知的自动转义。这是 Go 模板最重要的安全特性。

5.1 自动转义演示

1
2
3
4
5
6
7
8
9


// text/template：直接输出，产生 XSS
t, _ := template.New("foo").Parse(`Hello, {{.}}!`)
t.Execute(out, "")
// 输出：Hello, !

// html/template：自动转义，安全
t, _ := htmltemplate.New("foo").Parse(`Hello, {{.}}!`)
t.Execute(out, "")
// 输出：Hello, <script>alert('xss')</script>!

转义是上下文感知的：同一个 {{.}} 出现在 HTML 文本、属性、JavaScript、CSS、URL 中时，会应用不同的转义规则。例如：

1
2
3


<a href="/search?q={{.}}">{{.}}a>

<a href="/search?q={{. | urlescaper | attrescaper}}">{{. | htmlescaper}}a>

5.2 安全模型

html/template 的安全模型假设模板作者是可信的，而 Execute 传入的数据不可信。不应在模板中直接拼接用户输入。如果确实需要输出可信的 HTML 片段，使用 template.HTML 类型显式标记，但这绕过了自动转义，必须确保内容来源完全可控，绝不可用于用户输入。

六、性能优化

6.1 核心原则：启动时解析，请求时只执行

Parse 包含 I/O 和编译成本，禁止在每个 HTTP 请求中调用 Parse。应在 init() 或程序启动阶段解析一次，请求路径只做 Execute。

1
2
3
4
5
6
7
8


// ✅ 正确：包级别初始化
var reportTmpl = template.Must(
    template.ParseFiles("templates/report.html"),
)

func handler(w http.ResponseWriter, r *http.Request) {
    reportTmpl.Execute(w, data)  // 只执行，不解析
}

6.2 并发安全

模板一旦解析完成，Execute 可以安全地并发调用。但如果多个 goroutine 共享同一个 io.Writer，输出可能交错。每个请求应使用独立的 Writer（如 http.ResponseWriter）。

6.3 需要不同数据隔离时使用 Clone

如果需要在同一套模板基础上为不同请求做数据隔离的变体，使用 Clone() 创建副本。

6.4 避免不必要的转义开销

html/template 的自动转义会带来一定的性能开销。如果输出的是纯文本（如生成代码、配置文件），使用 text/template 可以避免转义成本。只有在生成 HTML 时才应使用 html/template。

七、测试策略

模板测试的核心是构造数据 → 执行 → 断言输出。推荐的模式是表驱动测试。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


func TestLetterTemplate(t *testing.T) {
    const letter = `Dear {{.Name}},{{if .Attended}} 感谢您的到来。{{else}} 很遗憾您未能出席。{{end}}`

    tests := []struct {
        name     string
        data     Recipient
        contains string
    }{
        {
            name:     "attended",
            data:     Recipient{Name: "Mildred", Attended: true},
            contains: "感谢您的到来",
        },
        {
            name:     "not attended",
            data:     Recipient{Name: "John", Attended: false},
            contains: "很遗憾您未能出席",
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            tmpl := template.Must(template.New("letter").Parse(letter))
            var buf bytes.Buffer
            if err := tmpl.Execute(&buf, tt.data); err != nil {
                t.Fatal(err)
            }
            if !strings.Contains(buf.String(), tt.contains) {
                t.Errorf("output %q does not contain %q", buf.String(), tt.contains)
            }
        })
    }
}

对于 HTML 模板，还应测试特殊字符是否被正确转义，以及子模板的嵌套执行是否正确。

八、实战：完整 HTTP 服务示例

package main

import (
    "html/template"
    "log"
    "net/http"
    "time"
)

type User struct {
    Name      string
    Age       int
    JoinedAt  time.Time
    IsPremium bool
}

var tmpl = template.Must(
    template.New("user").
        Funcs(template.FuncMap{
            "formatDate": func(t time.Time) string {
                return t.Format("2006-01-02")
            },
        }).
        Parse(`


用户信息

{{.Name}}
年龄：{{.Age}}
注册日期：{{.JoinedAt | formatDate}}
{{if .IsPremium}}
    尊贵会员
{{else}}
    普通用户
{{end}}

`),
)

func userHandler(w http.ResponseWriter, r *http.Request) {
    user := User{
        Name:      "张三",
        Age:       28,
        JoinedAt:  time.Now(),
        IsPremium: true,
    }
    if err := tmpl.Execute(w, user); err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

func main() {
    http.HandleFunc("/", userHandler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

模板在包级别解析一次，请求路径只执行 Execute；自定义 formatDate 函数在 Parse 之前通过 Funcs 注册；html/template 自动对 {{.Name}} 等内容进行 HTML 转义。

九、最佳实践总结

解析时机：模板在启动时解析一次，绝不在请求路径中重复解析。使用 template.Must 在初始化阶段暴露解析错误。

函数注册顺序：Funcs() 必须在 Parse() 之前调用，否则解析阶段就会失败。

选择正确的包：生成 HTML 用 html/template；生成代码、配置、纯文本用 text/template。绝不能用 text/template 渲染用户可见的 HTML 页面。

安全边界：将 template.HTML、template.JS、template.CSS 视为“危险类型”。它们绕过自动转义，只应用于来源完全可控的内容，严禁包裹用户输入。

逻辑归属：模板只负责展示。复杂条件分支、数据聚合、权限判断放在 Go 代码中完成，模板接收的是“已经准备好的展示数据”。

模板命名：嵌套模板中不同页面的内容块使用唯一名称，避免加载顺序导致同名模板被覆盖的隐蔽 bug。

空白控制：生成结构化文本（代码、JSON、YAML）时，在 range、if、end 动作上使用 - 修剪符精确控制输出格式，避免多余换行破坏结构。

并发写入：多 goroutine 并发执行同一模板时，为每个执行者提供独立的 io.Writer，避免输出交错。

Goroutine sync.Mutex 互斥锁详解

Tue, 13 Oct 2026 09:49:26 +0800

Go 语言 `sync.Mutex` 互斥锁详解

sync.Mutex 是 Go 标准库 sync 包提供的互斥锁，用来保护共享资源，防止多个 goroutine 同时读写导致数据竞争。

一、为什么需要互斥锁？

先看一个没有锁的经典问题：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


package main

import (
	"fmt"
	"sync"
)

func main() {
	counter := 0
	var wg sync.WaitGroup

	for i := 0; i < 1000; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			counter++   // ⚠️ 数据竞争
		}()
	}

	wg.Wait()
	fmt.Println("counter =", counter)
}

多次运行，输出经常小于 1000，比如 987、993、1000 不固定。原因：

counter++ 不是原子操作，实际是三步：读值 → 加一 → 写回
多个 goroutine 同时执行时，可能两个都读到 5，都写回 6，结果少加了一次

用 go run -race main.go 会明确报出 DATA RACE。

加锁就能解决：

1
2
3
4
5
6
7
8


var mu sync.Mutex

go func() {
	defer wg.Done()
	mu.Lock()
	counter++
	mu.Unlock()
}()

多次运行都稳定输出 counter = 1000。

二、基本用法

sync.Mutex 只有两个方法：

方法	作用
`Lock()`	加锁，若已被其他 goroutine 持有则阻塞等待
`Unlock()`	解锁，唤醒一个正在等待的 goroutine

必须成对出现，Lock 后一定要 Unlock，否则其他 goroutine 会永久阻塞（死锁）。

推荐写法：defer 解锁

1
2
3


mu.Lock()
defer mu.Unlock()
// ... 临界区代码

即使临界区里 panic 或 return，defer 也能保证解锁，避免死锁。

sync.Mutex 零值可用，不需要显式初始化：

1
2
3
4


var mu sync.Mutex   // ✅ 直接可用
mu.Lock()
// ...
mu.Unlock()

三、典型示例：并发安全的计数器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


package main

import (
	"fmt"
	"sync"
)

type SafeCounter struct {
	mu sync.Mutex
	n  int
}

func (c *SafeCounter) Inc() {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.n++
}

func (c *SafeCounter) Value() int {
	c.mu.Lock()
	defer c.mu.Unlock()
	return c.n
}

func main() {
	c := &SafeCounter{}
	var wg sync.WaitGroup

	for i := 0; i < 1000; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			c.Inc()
		}()
	}

	wg.Wait()
	fmt.Println("counter =", c.Value())   // 稳定输出 1000
}

要点：

锁和它保护的数据放在同一个结构体里，是 Go 的惯用法
方法内部加锁，调用者无需关心锁的存在
通过指针接收者调用，避免复制结构体（也就避免了复制锁）

四、回到你的项目：日志写入

你的 internal/logger/logger.go 里已经用到了这个模式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


var (
	logDir string
	mu     sync.Mutex
)

func Write(entry string) error {
	mu.Lock()
	defer mu.Unlock()

	filename := fmt.Sprintf("http_%s.log", time.Now().Format("2006-01-02"))
	path := filepath.Join(logDir, filename)

	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
	if err != nil {
		return fmt.Errorf("打开日志文件失败: %w", err)
	}
	defer f.Close()

	_, err = f.WriteString(entry)
	return err
}

为什么这里需要锁？

如果你以后改成并发调用多个 LLM（比如同时跑 5 个 Prompt 做对比），多个 goroutine 会同时调用 logger.Write
没有锁的话，两条日志内容可能在文件里交错，比如：

[请求 URL] https://api.openai.com/v1/[请求方法] POST

加锁后，一次只允许一个 goroutine 写文件，日志内容完整

注意：os.File 的 Write 本身在 Linux 上是原子的，但我们的日志入口做了"打开文件 → 写入 → 关闭"三步，中间可能被打断，所以锁是必要的。

五、常见错误

错误 1：忘记解锁

1
2
3
4
5


mu.Lock()
if err != nil {
	return err   // ❌ 忘了 Unlock，其他 goroutine 永远阻塞
}
mu.Unlock()

修正：始终用 defer mu.Unlock() 紧跟 Lock()。

1
2
3
4
5


mu.Lock()
defer mu.Unlock()
if err != nil {
	return err
}

错误 2：复制包含锁的结构体

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


type Counter struct {
	mu sync.Mutex
	n  int
}

func (c Counter) Inc() {   // ❌ 值接收者，复制了锁
	c.mu.Lock()
	defer c.mu.Unlock()
	c.n++
}

值接收者会复制整个结构体，包括 Mutex。复制后的锁是另一个锁，保护不了原来的数据。

修正：用指针接收者。

1
2
3
4
5


func (c *Counter) Inc() {   // ✅ 指针接收者
	c.mu.Lock()
	defer c.mu.Unlock()
	c.n++
}

错误 3：重入死锁

sync.Mutex 不可重入。同一个 goroutine 已经持有锁，再次 Lock 会永久阻塞。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


func (c *SafeCounter) A() {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.B()   // ❌ B 里又 Lock，死锁
}

func (c *SafeCounter) B() {
	c.mu.Lock()   // 阻塞
	defer c.mu.Unlock()
	// ...
}

修正：拆分内部方法，不要在持有锁的情况下调用会再次加锁的方法。

1
2
3
4
5
6
7
8
9


func (c *SafeCounter) A() {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.bLocked()   // ✅ 内部方法，不再加锁
}

func (c *SafeCounter) bLocked() {
	// 不加锁，假定调用者已持有锁
}

错误 4：锁的粒度过大

1
2
3
4
5


mu.Lock()
defer mu.Unlock()

data := fetchFromNetwork()     // ❌ 网络请求耗时 2 秒
cache[key] = data

锁里做耗时操作（网络、磁盘、大计算），会让其他 goroutine 长时间等待，性能急剧下降。

修正：只在真正操作共享数据时加锁。

1
2
3
4
5


data := fetchFromNetwork()     // ✅ 网络请求不加锁

mu.Lock()
cache[key] = data
mu.Unlock()

六、进阶：`sync.RWMutex` 读写锁

如果读多写少，用 sync.RWMutex 性能更好：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


type Cache struct {
	mu sync.RWMutex
	m  map[string]string
}

func (c *Cache) Get(key string) (string, bool) {
	c.mu.RLock()          // 读锁，多个 goroutine 可同时持有
	defer c.mu.RUnlock()
	v, ok := c.m[key]
	return v, ok
}

func (c *Cache) Set(key, value string) {
	c.mu.Lock()           // 写锁，独占
	defer c.mu.Unlock()
	c.m[key] = value
}

锁类型	方法	并发性
读锁	`RLock` / `RUnlock`	多个读可并行
写锁	`Lock` / `Unlock`	独占，读写互斥

使用场景：

读多写少（如缓存）→ RWMutex
读写均衡或写多 → Mutex

不要为了"看起来更快"而盲目用 RWMutex，它的内部实现比 Mutex 复杂，写多时反而更慢。

七、进阶：`defer` 的代价

defer 有轻微开销。如果在极端热路径（每秒调用数百万次），可以手动解锁：

1
2
3


mu.Lock()
c.n++
mu.Unlock()

但大多数场景下，可读性和安全性比微小性能更重要，推荐用 defer。

八、如何检测数据竞争

Go 内置了 race detector：

1
2
3


go run -race main.go
go test -race ./...
go build -race

只要有数据竞争，运行时会打印：

==================
WARNING: DATA RACE
Write at 0x00c000014178 by goroutine 7:
  main.main.func1()
      main.go:15 +0x3c
...
==================

开发阶段建议始终带 -race，发现问题远比线上诡异 bug 好排查。

九、什么时候不需要 `Mutex`？

不是所有并发场景都要加锁，以下情况可以用更轻量的方案：

场景	方案
单个整数/指针的原子读写	`sync/atomic`
只需要执行一次	`sync.Once`
等待一组 goroutine 完成	`sync.WaitGroup`
只读共享数据（初始化后不再改）	无需加锁
goroutine 间通信	`channel`
简单的 map 并发访问	`sync.Map`（特定场景）

Go 的哲学：不要通过共享内存来通信，而要通过通信来共享内存。

如果能用 channel 优雅解决，就优先用 channel；Mutex 适合保护一块明确的小临界区。

十、一个完整可运行的例子

综合演示：多 goroutine 并发写入一个 map，用 Mutex 保护。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


package main

import (
	"fmt"
	"sync"
)

type Counter struct {
	mu sync.Mutex
	m  map[string]int
}

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

func (c *Counter) Add(key string) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.m[key]++
}

func (c *Counter) Snapshot() map[string]int {
	c.mu.Lock()
	defer c.mu.Unlock()
	snapshot := make(map[string]int, len(c.m))
	for k, v := range c.m {
		snapshot[k] = v
	}
	return snapshot
}

func main() {
	c := NewCounter()
	var wg sync.WaitGroup

	words := []string{"go", "rust", "go", "python", "go", "rust"}

	for _, w := range words {
		for i := 0; i < 1000; i++ {
			wg.Add(1)
			go func(word string) {
				defer wg.Done()
				c.Add(word)
			}(w)
		}
	}

	wg.Wait()

	for k, v := range c.Snapshot() {
		fmt.Printf("%-8s %d\n", k, v)
	}
}

输出：

go       3000
rust     2000
python   1000

用 go run -race main.go 运行也不会有任何警告。

十一、一句话总结

sync.Mutex 是保护共享数据的最小工具：Lock 进入临界区，defer Unlock 保证退出；锁和数据放在同一个结构体里，用指针接收者操作；临界区要尽量小；开发时始终带 -race。

在你的 Prompt 工程里，日志写入、token 统计累加、多会话管理这些都是典型的加锁场景。目前的 logger.Write 已经用对了模式，可以直接参考。

Goroutine Context 详细讲解

Mon, 12 Oct 2026 11:21:07 +0800

Go Context 详细讲解

context 是 Go 官方用来在 goroutine 之间传递取消信号、超时、截止时间和请求范围数据的标准库。它解决了并发编程中的核心问题：如何优雅地通知一组 goroutine 停止工作。

一、为什么需要 Context

1.1 没有 Context 的痛点

1
2
3
4
5
6


// 假设一个 HTTP 请求启动了 3 个 goroutine 处理子任务
func handler(w http.ResponseWriter, r *http.Request) {
    go fetchFromDB()      // 用户断开连接，它还在跑
    go callExternalAPI()  // 超时了，它还在跑
    go writeToCache()     // 没人需要结果了，它还在跑
}

问题：

用户取消请求，goroutine 收不到通知，继续浪费资源
无法设置统一超时
无法在调用链中传递请求 ID、用户身份等数据
goroutine 泄漏

1.2 Context 的设计哲学

“一个请求，一棵 goroutine 树，一个 Context。”

Context 是树形结构，根节点是 context.Background() 或 context.TODO()
父 Context 取消 → 所有子 Context 全部取消（级联）
Context 是并发安全的，可被多个 goroutine 同时使用
Context 应该作为函数的第一个参数，命名为 ctx

二、Context 接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


type Context interface {
    // 返回 deadline 和是否设置了 deadline
    Deadline() (deadline time.Time, ok bool)

    // 返回一个 channel，在 Context 被取消时关闭
    Done() <-chan struct{}

    // 返回取消原因（在 Done 关闭后才有意义）
    Err() error

    // 获取 key 对应的值
    Value(key any) any
}

关键点：

Done() 返回的 channel 在取消/超时时关闭
Err() 返回 context.Canceled 或 context.DeadlineExceeded
没有取消时，Done() 返回 nil（会永久阻塞）

三、四种创建方式

3.1 根 Context

1
2


ctx := context.Background() // 通常用于 main、初始化、测试
ctx := context.TODO()       // 不确定用哪个时，占位

两者都是空的、永不取消的 Context。生产代码中只用 Background，TODO 只是标记待办。

3.2 WithCancel：手动取消

1
2


ctx, cancel := context.WithCancel(parentCtx)
defer cancel() // 必须调用，否则泄漏

3.3 WithTimeout：超时取消

1
2


ctx, cancel := context.WithTimeout(parentCtx, 2*time.Second)
defer cancel()

3.4 WithDeadline：到某时刻取消

1
2


ctx, cancel := context.WithDeadline(parentCtx, time.Now().Add(2*time.Second))
defer cancel()

3.5 WithValue：携带数据

1

ctx = context.WithValue(parentCtx, key, value)

四、基础示例

4.1 WithCancel 基本用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


package main

import (
    "context"
    "fmt"
    "time"
)

func worker(ctx context.Context, id int) {
    for {
        select {
        case <-ctx.Done():
            fmt.Printf("worker %d 收到取消信号: %v\n", id, ctx.Err())
            return
        default:
            fmt.Printf("worker %d 工作中...\n", id)
            time.Sleep(500 * time.Millisecond)
        }
    }
}

func main() {
    ctx, cancel := context.WithCancel(context.Background())

    go worker(ctx, 1)
    go worker(ctx, 2)

    time.Sleep(2 * time.Second)
    fmt.Println("main: 发送取消信号")
    cancel() // 通知所有子 goroutine

    time.Sleep(500 * time.Millisecond)
    fmt.Println("main: 退出")
}

输出：

worker 1 工作中...
worker 2 工作中...
worker 1 工作中...
worker 2 工作中...
main: 发送取消信号
worker 1 收到取消信号: context canceled
worker 2 收到取消信号: context canceled
main: 退出

4.2 WithTimeout 超时控制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


package main

import (
    "context"
    "fmt"
    "time"
)

func slowOperation(ctx context.Context) (string, error) {
    select {
    case <-time.After(3 * time.Second):
        return "操作完成", nil
    case <-ctx.Done():
        return "", ctx.Err()
    }
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()

    result, err := slowOperation(ctx)
    if err != nil {
        fmt.Println("失败:", err) // 失败: context deadline exceeded
        return
    }
    fmt.Println("成功:", result)
}

4.3 级联取消（树形结构）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


package main

import (
    "context"
    "fmt"
    "time"
)

func main() {
    root, cancelRoot := context.WithCancel(context.Background())
    defer cancelRoot()

    child1, cancelChild1 := context.WithCancel(root)
    defer cancelChild1()

    child2, _ := context.WithCancel(root)

    go func() {
        <-child1.Done()
        fmt.Println("child1 被取消:", child1.Err())
    }()

    go func() {
        <-child2.Done()
        fmt.Println("child2 被取消:", child2.Err())
    }()

    time.Sleep(100 * time.Millisecond)
    fmt.Println("取消 root")
    cancelRoot() // 级联取消 child1 和 child2

    time.Sleep(200 * time.Millisecond)
}

输出：

取消 root
child1 被取消: context canceled
child2 被取消: context canceled

规则：取消父节点 → 所有子节点自动取消；取消子节点 → 不影响父节点。

五、WithValue 传值

5.1 基本用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


package main

import (
    "context"
    "fmt"
)

// key 必须是不导出的自定义类型，避免冲突
type contextKey string

const (
    userIDKey    contextKey = "userID"
    requestIDKey contextKey = "requestID"
)

func handleRequest(ctx context.Context) {
    if userID, ok := ctx.Value(userIDKey).(string); ok {
        fmt.Println("用户:", userID)
    }
    if reqID, ok := ctx.Value(requestIDKey).(string); ok {
        fmt.Println("请求 ID:", reqID)
    }
}

func main() {
    ctx := context.Background()
    ctx = context.WithValue(ctx, userIDKey, "user-123")
    ctx = context.WithValue(ctx, requestIDKey, "req-456")

    handleRequest(ctx)
}

输出：

用户: user-123
请求 ID: req-456

5.2 为什么 key 不能用 string？

1
2
3
4
5
6
7


// ❌ 错误：不同包可能用相同 string 键冲突
ctx = context.WithValue(ctx, "userID", "123")

// ✅ 正确：用自定义类型
type ctxKey int
const userIDKey ctxKey = 0
ctx = context.WithValue(ctx, userIDKey, "123")

5.3 WithValue 的适用场景

✅ 适合：

请求 ID、trace ID（链路追踪）
用户身份、租户 ID
认证 token
跨 API 边界的请求范围元数据

❌ 不适合：

传递函数参数（应该显式传参）
传递可选参数
传递可变状态

官方原话：“Use context values only for request-scoped data that transits processes and APIs, not for passing optional parameters to functions.”

六、在 goroutine 中正确使用

6.1 模式一：worker 监听 ctx

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


func worker(ctx context.Context, jobs <-chan Job) {
    for {
        select {
        case <-ctx.Done():
            return
        case job, ok := <-jobs:
            if !ok {
                return
            }
            process(job)
        }
    }
}

6.2 模式二：启动多个 goroutine 并统一取消

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


package main

import (
    "context"
    "fmt"
    "sync"
    "time"
)

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    var wg sync.WaitGroup

    for i := 1; i <= 5; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            for {
                select {
                case <-ctx.Done():
                    fmt.Printf("worker %d 退出\n", id)
                    return
                default:
                    time.Sleep(300 * time.Millisecond)
                }
            }
        }(i)
    }

    time.Sleep(1 * time.Second)
    cancel()
    wg.Wait()
    fmt.Println("所有 worker 已退出")
}

6.3 模式三：ErrGroup（推荐）

golang.org/x/sync/errgroup 结合了 WaitGroup 和 Context，任何 goroutine 出错会取消其他 goroutine：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


package main

import (
    "context"
    "fmt"
    "time"

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

func main() {
    g, ctx := errgroup.WithContext(context.Background())

    g.Go(func() error {
        select {
        case <-time.After(3 * time.Second):
            return nil
        case <-ctx.Done():
            return ctx.Err()
        }
    })

    g.Go(func() error {
        time.Sleep(1 * time.Second)
        return fmt.Errorf("出错了") // 会取消其他 goroutine
    })

    if err := g.Wait(); err != nil {
        fmt.Println("errgroup 结束:", err)
    }
}

七、实战场景

7.1 HTTP 请求超时

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


func fetchURL(url string) (string, error) {
    ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
    defer cancel()

    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return "", err
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    return string(body), nil
}

7.2 HTTP Server 中传递 Context

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context() // HTTP 请求自带的 Context

    // 用户断开连接时 ctx 会自动取消
    result, err := doSomething(ctx)
    if err != nil {
        if errors.Is(err, context.Canceled) {
            // 客户端断开
            return
        }
        http.Error(w, err.Error(), 500)
        return
    }
    w.Write([]byte(result))
}

func doSomething(ctx context.Context) (string, error) {
    select {
    case <-ctx.Done():
        return "", ctx.Err()
    case <-time.After(5 * time.Second):
        return "done", nil
    }
}

7.3 数据库查询超时

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


func queryDB(ctx context.Context) error {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()

    rows, err := db.QueryContext(ctx, "SELECT * FROM users")
    if err != nil {
        return err
    }
    defer rows.Close()
    // ...
    return nil
}

7.4 链式调用取消

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


func serviceA(ctx context.Context) error {
    return serviceB(ctx) // 传递 ctx
}

func serviceB(ctx context.Context) error {
    return serviceC(ctx)
}

func serviceC(ctx context.Context) error {
    select {
    case <-ctx.Done():
        return ctx.Err() // 任意一层取消，全部返回
    case <-time.After(1 * time.Second):
        return nil
    }
}

7.5 后台任务 + 优雅关闭

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    // 监听系统信号
    sigCh := make(chan os.Signal, 1)
    signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)

    go func() {
        <-sigCh
        fmt.Println("\n收到退出信号")
        cancel()
    }()

    fmt.Println("服务已启动，Ctrl+C 退出")
    <-ctx.Done()
    fmt.Println("正在清理...")
    time.Sleep(500 * time.Millisecond)
    fmt.Println("已退出")
}

八、常见陷阱

8.1 忘记调用 cancel（goroutine 泄漏）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// ❌ 即使操作提前结束，Context 也不会释放
func bad() {
    ctx, _ := context.WithTimeout(context.Background(), time.Hour)
    doSomething(ctx)
}

// ✅
func good() {
    ctx, cancel := context.WithTimeout(context.Background(), time.Hour)
    defer cancel()
    doSomething(ctx)
}

规则：永远 defer cancel()，即使不超时也要调用。

8.2 把 Context 存到 struct 里

1
2
3
4
5
6
7
8


// ❌ Context 应该作为函数参数传递
type Service struct {
    ctx context.Context
}

// ✅
type Service struct{}
func (s *Service) Do(ctx context.Context) error { ... }

8.3 用 Context 传普通参数

1
2
3
4
5


// ❌
ctx = context.WithValue(ctx, "userID", 123)

// ✅ 显式传参
func getUser(ctx context.Context, userID int) (*User, error)

8.4 在 select 中忽略 ctx

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// ❌ 无法取消
for {
    select {
    case job := <-jobs:
        process(job)
    }
}

// ✅
for {
    select {
    case <-ctx.Done():
        return
    case job := <-jobs:
        process(job)
    }
}

8.5 检查 ctx.Err() 的时机

1
2
3
4
5


select {
case <-ctx.Done():
    // 此时 ctx.Err() 才有值
    fmt.Println(ctx.Err()) // context.Canceled 或 context.DeadlineExceeded
}

8.6 取消不会杀死 goroutine

Context 只是信号，需要 goroutine 主动检查 ctx.Done() 并退出：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


go func() {
    for {
        select {
        case <-ctx.Done():
            return // 必须主动返回
        default:
            // 注意：如果这里有阻塞操作，仍需该操作支持 ctx
        }
    }
}()

九、Context 底层结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


type emptyCtx int // Background / TODO

type cancelCtx struct {
    Context
    mu       sync.Mutex
    done     atomic.Value // chan struct{}
    children map[canceler]struct{}
    err      error
}

type timerCtx struct {
    cancelCtx
    timer    *time.Timer
    deadline time.Time
}

type valueCtx struct {
    Context
    key, val any
}

关键机制：

cancelCtx 维护子节点列表，取消时遍历通知所有子节点
timerCtx 内嵌 cancelCtx，额外带 timer 和 deadline
valueCtx 是链表结构，Value() 沿链向上查找
Done() 返回的 channel 懒加载，只有在第一次调用时才创建

十、Context 使用清单

规则	说明
第一个参数	`func Do(ctx context.Context, ...)`
不要存 struct	Context 作为参数传递
命名 ctx	参数统一叫 `ctx`
必 defer cancel	即使提前返回也要释放
nil 用 TODO	不确定时用 `context.TODO()`
不放 nil	不要传 nil Context
key 用自定义类型	避免包间冲突
只放请求范围数据	不放参数、可选值
Done 用 select	配合 select 监听取消

十一、Context 的替代与补充

场景	推荐
单个 goroutine 取消	`context.WithCancel`
多个 goroutine 统一取消	`errgroup` + context
纯等待完成	`sync.WaitGroup`（不需要 ctx）
只有超时	`time.After`（不需要 ctx）
需要传值 + 取消	`context.WithValue` + `WithTimeout`

十二、完整实战：带超时的并发请求

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


package main

import (
    "context"
    "fmt"
    "sync"
    "time"

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

type Result struct {
    Source string
    Data   string
}

func fetch(ctx context.Context, source string, delay time.Duration) (*Result, error) {
    select {
    case <-time.After(delay):
        return &Result{Source: source, Data: source + "-data"}, nil
    case <-ctx.Done():
        return nil, fmt.Errorf("%s: %w", source, ctx.Err())
    }
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 1500*time.Millisecond)
    defer cancel()

    g, ctx := errgroup.WithContext(ctx)

    sources := map[string]time.Duration{
        "db":      300 * time.Millisecond,
        "cache":   200 * time.Millisecond,
        "api":     2 * time.Second, // 会超时
    }

    var mu sync.Mutex
    results := make(map[string]string)

    for name, delay := range sources {
        name, delay := name, delay
        g.Go(func() error {
            r, err := fetch(ctx, name, delay)
            if err != nil {
                return err
            }
            mu.Lock()
            results[r.Source] = r.Data
            mu.Unlock()
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        fmt.Println("有任务失败:", err)
    }

    fmt.Println("已完成的任务:")
    for k, v := range results {
        fmt.Printf("  %s: %s\n", k, v)
    }
}

输出示例：

有任务失败: api: context deadline exceeded
已完成的任务:
  cache: cache-data
  db: db-data

十三、核心要点总结

Context 是取消信号传播树，父取消 → 子全取消
取消 ≠ 杀死 goroutine，必须 goroutine 主动检查 Done()
永远 defer cancel()，防止泄漏
Context 作为第一个参数，不存 struct
WithValue 只放请求范围数据（trace ID、用户身份），不传参数
HTTP / DB / RPC 都原生支持 Context，直接传下去
errgroup 是 context + goroutine 的最佳实践组合
WithValue 的 key 用自定义类型，避免冲突

进一步展开：

errgroup 源码与高级用法（SetLimit、TryGo）
context 源码分析（cancelCtx 的传播机制）
分布式链路追踪（OpenTelemetry + context）
gRPC 中的 Context 传递

Goroutine Select

Mon, 12 Oct 2026 09:55:20 +0800

Go `select` 详解与可运行示例

一、本质：select 是什么

select 是 Go 里唯一的多路 channel 操作原语。它让一个 goroutine 同时等待多个 channel 操作，哪个先就绪就走哪个。没有它，你要么串行阻塞在单个 channel 上，要么自己开 goroutine 轮询。

一句话定位：switch 是对值的分支，select 是对通道就绪状态的分支。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


select {
case v := <-ch1:    // ch1 有数据可读
    handle(v)
case ch2 <- x:      // ch2 有接收者就绪
    // 发送成功
case <-time.After(time.Second):  // 超时
    // ...
default:            // 所有 case 都没就绪
    // 不阻塞，立即走这里
}

二、语法与语义规则

规则 1：case 必须是 channel 操作

合法：<-ch、ch <- v、v, ok := <-ch。非法：普通表达式、函数调用（case f(): 不行）、常量比较。

规则 2：多个 case 同时就绪时，伪随机选一个

1
2
3
4


select {
case <-ch1:
case <-ch2:
}

两个都就绪时，runtime 用 cheaprandn 随机选。这是有意设计，避免固定顺序导致某个 case 永远饿死。所以不要依赖 select 的分支顺序写业务逻辑。

规则 3：没有 `default` 时，全部不就绪则阻塞当前 goroutine

阻塞期间 goroutine 进 _Gwaiting，会让出 P，M 去跑别的 G。不占 CPU。

规则 4：有 `default` 时，全部不就绪则立即执行 default

default 让 select 变成非阻塞的。这是"尝试一次，不行就算了"的标准写法。

规则 5：`select {}` 永久阻塞

空 select 永远阻塞，用于让 main goroutine 永不退出（配合其他 goroutine 干活）：

1
2
3
4


func main() {
    go worker()
    select {}   // 永久阻塞，不会死锁 panic（因为有 worker 在跑）
}

但如果没有任何其他 goroutine，select {} 会触发 fatal error: all goroutines are asleep - deadlock。

规则 6：nil channel 上的 case 永远不就绪

1
2
3
4
5


var ch chan int   // nil
select {
case <-ch:        // 这个 case 永远不会被选中
    ...
}

这是禁用某个分支的利器（后文详述）。

规则 7：`break` 跳出的是 `select`，不是外层 `for`

1
2
3
4
5
6


for {
    select {
    case <-done:
        break      // ⚠️ 只跳出 select，for 继续转
    }
}

要用 return、goto、或者带标签的 break loop 才能跳出循环。

三、运行时机制：`selectgo`

编译器把 select 编译成对 runtime.selectgo 的调用。核心流程：

selectgo(cases):
  ① 生成 pollorder（随机打乱的 case 顺序）
  ② 生成 lockorder（按 channel 地址排序，防死锁）
  ③ 第一轮：按 pollorder 遍历，逐个尝试非阻塞收发
      ├─ 有就绪的 → 直接执行该 case，返回
      └─ 没有 → 继续
  ④ 有 default → 执行 default，返回
  ⑤ 没有 default → 把所有 case 的 sudog 挂到各 channel 的等待队列上
      → gopark() 阻塞
  ⑥ 被某个 channel 的就绪事件唤醒 → 从队列摘除所有 sudog → 返回被选中的 case

两个关键设计：

pollorder 随机：保证公平，避免固定顺序饥饿
lockorder 按地址排序：多个 case 涉及多个 channel 的锁时，统一按地址顺序加锁，避免两个 goroutine 以相反顺序加锁导致死锁

case 数量上限：select 最多 65536 个 case（uint16 索引），实际中远用不到，但要知道有这个上限。

性能：无就绪 case 且需要阻塞时，每个 case 都要分配 sudog、挂队列，开销明显高于单个 channel 操作。select 适合"少数几个 channel"，不适合"海量 channel 轮询"。

四、经典模式（每个都可直接 `go run`）

示例 1：基础多路复用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


package main

import (
	"fmt"
	"time"
)

func main() {
	ch1 := make(chan string)
	ch2 := make(chan string)

	go func() {
		time.Sleep(100 * time.Millisecond)
		ch1 <- "来自 ch1"
	}()
	go func() {
		time.Sleep(200 * time.Millisecond)
		ch2 <- "来自 ch2"
	}()

	for i := 0; i < 2; i++ {
		select {
		case v := <-ch1:
			fmt.Println("收到:", v)
		case v := <-ch2:
			fmt.Println("收到:", v)
		}
	}
}

预期输出：

收到: 来自 ch1
收到: 来自 ch2

要点：select 同时等两个 channel，谁先到处理谁。ch1 先发（100ms），所以先走 ch1 分支。

示例 2：超时控制（最常用）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


package main

import (
	"fmt"
	"time"
)

func slowOp() <-chan string {
	ch := make(chan string)
	go func() {
		time.Sleep(2 * time.Second)   // 模拟慢操作
		ch <- "结果"
	}()
	return ch
}

func main() {
	start := time.Now()

	select {
	case v := <-slowOp():
		fmt.Println("成功:", v, "耗时:", time.Since(start))
	case <-time.After(500 * time.Millisecond):
		fmt.Println("超时! 耗时:", time.Since(start))
	}
}

预期输出：

超时! 耗时: 500.xxxms

要点：

time.After(d) 返回一个 channel，d 之后收到一个值
慢操作 2 秒，超时 500ms，select 走超时分支
注意：time.After 底层 timer 在触发前不会释放，高频循环里用 time.NewTimer + Reset 更省资源（后文陷阱详述）

示例 3：非阻塞收发（`default`）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


package main

import "fmt"

func main() {
	ch := make(chan int, 1)

	// 第一次：channel 空，发送成功
	select {
	case ch <- 1:
		fmt.Println("发送 1 成功")
	default:
		fmt.Println("发送 1 失败（通道满）")
	}

	// 第二次：channel 已满（cap=1），发送走 default
	select {
	case ch <- 2:
		fmt.Println("发送 2 成功")
	default:
		fmt.Println("发送 2 失败（通道满）")
	}

	// 接收：有数据，成功
	select {
	case v := <-ch:
		fmt.Println("接收到:", v)
	default:
		fmt.Println("通道空，无数据")
	}

	// 再次接收：空了，走 default
	select {
	case v := <-ch:
		fmt.Println("接收到:", v)
	default:
		fmt.Println("通道空，无数据")
	}
}

预期输出：

发送 1 成功
发送 2 失败（通道满）
接收到: 1
通道空，无数据

要点：default 让操作变成"尝试一次"——这就是"非阻塞发送/接收"的标准写法。

示例 4：优雅退出（context + 信号）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


package main

import (
	"context"
	"fmt"
	"time"
)

func worker(ctx context.Context, id int) {
	ticker := time.NewTicker(200 * time.Millisecond)
	defer ticker.Stop()

	for {
		select {
		case <-ctx.Done():
			fmt.Printf("worker %d 退出: %v\n", id, ctx.Err())
			return
		case <-ticker.C:
			fmt.Printf("worker %d 干活中...\n", id)
		}
	}
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())

	for i := 1; i <= 3; i++ {
		go worker(ctx, i)
	}

	time.Sleep(700 * time.Millisecond)
	fmt.Println(">>> 发出取消信号")
	cancel()

	time.Sleep(500 * time.Millisecond)
	fmt.Println(">>> main 退出")
}

预期输出（时序大致如此）：

worker 1 干活中...
worker 2 干活中...
worker 3 干活中...
worker 1 干活中...
worker 2 干活中...
worker 3 干活中...
worker 1 干活中...
worker 2 干活中...
worker 3 干活中...
>>> 发出取消信号
worker 1 退出: context canceled
worker 2 退出: context canceled
worker 3 退出: context canceled
>>> main 退出

要点：

ctx.Done() 是广播：cancel() 后所有 select 在这个 case 上的 goroutine 同时收到
这是 Go 服务里标准退出模式：每个长任务都 select 监听 ctx.Done()
defer ticker.Stop() 防止资源泄漏

示例 5：用 nil channel 动态禁用分支

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


package main

import (
	"fmt"
	"time"
)

func main() {
	ch1 := make(chan string)
	ch2 := make(chan string)

	go func() { ch1 <- "ch1 数据" }()
	go func() { ch2 <- "ch2 数据" }()

	// 先启用两个通道
	c1, c2 := ch1, ch2

	for i := 0; i < 2; i++ {
		select {
		case v := <-c1:
			fmt.Println("处理:", v)
			c1 = nil   // 禁用 ch1 分支，后续 select 忽略它
		case v := <-c2:
			fmt.Println("处理:", v)
			c2 = nil
		}
	}
	fmt.Println("两个通道都已处理完毕")
}

预期输出：

处理: ch1 数据
处理: ch2 数据
两个通道都已处理完毕

要点：c1 = nil 之后，case v := <-c1 在 select 里永远不就绪——这是动态开关分支的标准技巧。常见于"关闭某个数据源后只从剩下的源读"的场景。

示例 6：优先级 select（防止低优先级饿死）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


package main

import (
	"fmt"
	"time"
)

func main() {
	high := make(chan string, 10)
	low := make(chan string, 10)

	// 塞入数据
	for i := 0; i < 3; i++ {
		high <- fmt.Sprintf("高优先级-%d", i)
	}
	for i := 0; i < 5; i++ {
		low <- fmt.Sprintf("低优先级-%d", i)
	}
	close(high)

	for i := 0; i < 8; i++ {
		// 第一层 select：优先尝试 high
		select {
		case v, ok := <-high:
			if ok {
				fmt.Println("处理:", v)
				continue
			}
			// high 已关闭，走下面
		default:
			// high 没就绪，落到第二层
		}

		// 第二层 select：处理 low 或等待 high
		select {
		case v, ok := <-high:
			if ok {
				fmt.Println("处理:", v)
			}
		case v := <-low:
			fmt.Println("处理:", v)
		}
		time.Sleep(10 * time.Millisecond)
	}
}

预期输出（前 3 条必为高优先级）：

处理: 高优先级-0
处理: 高优先级-1
处理: 高优先级-2
处理: 低优先级-0
处理: 低优先级-1
处理: 低优先级-2
处理: 低优先级-3
处理: 低优先级-4

要点：select 本身不支持优先级，但可以用两层 select 模拟：第一层带 default 尝试高优先级，没就绪再进第二层等。代价是代码复杂，且默认分支有 CPU 空转风险——第二层里的 time.Sleep 就是为了缓解空转（生产代码里更推荐用 time.Ticker 或合理设置 default 的退出条件）。

示例 7：for-select 循环（最常见的结构）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


package main

import (
	"fmt"
	"time"
)

func main() {
	jobs := make(chan int, 5)
	done := make(chan struct{})

	// 消费者
	go func() {
		for {
			select {
			case j, ok := <-jobs:
				if !ok {
					fmt.Println("jobs 已关闭，消费者退出")
					return
				}
				fmt.Println("处理任务:", j)
			case <-done:
				fmt.Println("收到退出信号，消费者退出")
				return
			}
		}
	}()

	// 生产 3 个任务
	for i := 1; i <= 3; i++ {
		jobs <- i
	}

	time.Sleep(100 * time.Millisecond)
	close(done)   // 触发消费者退出
	time.Sleep(100 * time.Millisecond)
	fmt.Println("main 退出")
}

预期输出：

处理任务: 1
处理任务: 2
处理任务: 3
收到退出信号，消费者退出
main 退出

要点：

for { select { ... } } 是 Go 并发代码的基本骨架
每个 case 都要有明确的退出路径（return 或 break loop）
用 v, ok := <-ch 感知关闭
不要用 break 跳出 for——break 只跳 select（前文规则 7）

示例 8：select 随机性演示

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


package main

import (
	"fmt"
	"time"
)

func main() {
	ch1 := make(chan int, 1)
	ch2 := make(chan int, 1)
	ch1 <- 1
	ch2 <- 2

	counts := map[int]int{}
	for i := 0; i < 1000; i++ {
		select {
		case v := <-ch1:
			counts[v]++
			ch1 <- 1
		case v := <-ch2:
			counts[v]++
			ch2 <- 2
		}
	}
	fmt.Printf("ch1 被选中 %d 次, ch2 被选中 %d 次\n", counts[1], counts[2])
	time.Sleep(10 * time.Millisecond)
}

预期输出（数字接近 500/500）：

ch1 被选中 约500 次, ch2 被选中 约500 次

要点：两个 channel 始终有数据，select 随机选。跑多次会发现比例接近 1:1，但不是严格交替。不要依赖 select 的顺序写逻辑。

示例 9：合并多个 channel（fan-in）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


package main

import (
	"fmt"
	"sync"
	"time"
)

func producer(name string, n int) <-chan string {
	ch := make(chan string)
	go func() {
		defer close(ch)
		for i := 0; i < n; i++ {
			ch <- fmt.Sprintf("%s-%d", name, i)
			time.Sleep(50 * time.Millisecond)
		}
	}()
	return ch
}

func merge(chs ...<-chan string) <-chan string {
	out := make(chan string)
	var wg sync.WaitGroup
	for _, ch := range chs {
		wg.Add(1)
		go func(c <-chan string) {
			defer wg.Done()
			for v := range c {
				out <- v
			}
		}(ch)
	}
	go func() {
		wg.Wait()
		close(out)
	}()
	return out
}

func main() {
	a := producer("A", 3)
	b := producer("B", 3)

	for v := range merge(a, b) {
		fmt.Println("收到:", v)
	}
	fmt.Println("全部完成")
}

预期输出（A/B 交错，顺序不定）：

收到: A-0
收到: B-0
收到: A-1
收到: B-1
收到: A-2
收到: B-2
全部完成

要点：这是不依赖 select 的 fan-in——每个源一个 goroutine 往同一个 out 写。sync.WaitGroup + close 是上一轮讨论的"多生产者关闭"标准模式。merge 内部每个 goroutine 的 for range 是阻塞读，天然实现了"谁有数据谁先写"，效果等价于 select 多路复用，但代码更清晰、可扩展（N 个源不用写 N 个 case）。

示例 10：带缓冲 channel + select 的批处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


package main

import (
	"fmt"
	"time"
)

func main() {
	events := make(chan int, 100)

	// 生产事件
	go func() {
		for i := 1; i <= 20; i++ {
			events <- i
			time.Sleep(20 * time.Millisecond)
		}
		close(events)
	}()

	ticker := time.NewTicker(100 * time.Millisecond)
	defer ticker.Stop()

	var batch []int
	for {
		select {
		case v, ok := <-events:
			if !ok {
				if len(batch) > 0 {
					fmt.Println("最后一批:", batch)
				}
				fmt.Println("全部完成")
				return
			}
			batch = append(batch, v)
			if len(batch) >= 5 {
				fmt.Println("批量处理:", batch)
				batch = batch[:0]
			}
		case <-ticker.C:
			if len(batch) > 0 {
				fmt.Println("定时刷新:", batch)
				batch = batch[:0]
			}
		}
	}
}

预期输出（大致）：

定时刷新: [1 2 3 4]
批量处理: [5 6 7 8 9]
批量处理: [10 11 12 13 14]
批量处理: [15 16 17 18 19]
最后一批: [20]
全部完成

要点：select 同时监听"数据到达"和"定时器触发"，实现双条件批处理——要么凑够 5 个，要么 100ms 到了就刷。这是生产级批量处理的标准骨架（日志聚合、数据库批量写都用这个模式）。

五、陷阱清单

⚠️ 陷阱 1：`time.After` 在循环里的资源泄漏

1
2
3
4
5
6
7
8
9


// ❌ 每秒泄漏一个 timer
for {
    select {
    case v := <-ch:
        handle(v)
    case <-time.After(time.Second):   // 每次循环都创建新 timer
        timeout()
    }
}

time.After 创建的 timer 在触发前不会被 GC，即使 select 走了别的分支。高频循环里会累积大量 timer，内存持续上涨。

修复：用 time.NewTimer + 手动 Reset：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// ✅ 复用 timer
timer := time.NewTimer(time.Second)
defer timer.Stop()
for {
    if !timer.Stop() {
        <-timer.C
    }
    timer.Reset(time.Second)
    select {
    case v := <-ch:
        handle(v)
    case <-timer.C:
        timeout()
    }
}

⚠️ 陷阱 2：`default` 导致 CPU 空转

1
2
3
4
5
6
7
8
9


// ❌ 死循环空转，CPU 100%
for {
    select {
    case v := <-ch:
        handle(v)
    default:
        // 什么都不做，立即进入下一轮
    }
}

default 让 select 不阻塞，循环转得飞快，CPU 打满。

修复：要么去掉 default（阻塞等），要么在 default 里加 runtime.Gosched() 或 time.Sleep，要么用 time.Ticker 节流。

⚠️ 陷阱 3：`break` 跳出的是 select，不是 for

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// ❌ break 只跳出 select，for 继续转
for {
    select {
    case <-done:
        break          // 以为跳出 for，其实只跳出 select
    }
}
// ✅ 用 return 或标签
loop:
for {
    select {
    case <-done:
        break loop
    }
}

⚠️ 陷阱 4：关闭的 channel 在 select 里一直就绪

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


ch := make(chan int)
close(ch)
for {
    select {
    case v, ok := <-ch:
        if !ok {
            return   // 必须判断 ok，否则 select 每次都选这个 case
        }
    case x := <-other:
        handle(x)
    }
}

关闭的 channel 永远可以立即读到零值，所以 case <-ch 在 select 里永远就绪，会疯狂抢走其他 case 的机会。必须用 v, ok := 判断，ok 为 false 时把 ch 设为 nil 或退出。

⚠️ 陷阱 5：nil channel 用于禁用，但别拿它做"空转"

1
2
3
4
5


var ch chan int   // nil
select {
case <-ch:        // 永远不就绪 ✅ 用来禁分支
case <-other:     // 正常工作
}

这是特性不是 bug。但如果所有 case 都是 nil channel 且没有 default，就永久阻塞（和 select {} 一样）。

⚠️ 陷阱 6：select 里对同一 channel 多个 case

1
2
3
4
5


// ❌ 两个 case 操作同一 channel，行为混乱
select {
case v := <-ch:
case ch <- 1:
}

虽然语法合法，但实际语义很难推理（一读一写同时竞争），生产代码应避免。每个 channel 在 select 里最多出现一次。

⚠️ 陷阱 7：select 的 case 太多

超过 65536 个 case 编译期报错。即使没到上限，case 越多，selectgo 的轮询和锁开销越大。“等很多个 channel” 应该用 fan-in 模式聚合成一个 channel，而不是写几百个 case。

六、性能与最佳实践速查

场景	推荐写法
等少数几个 channel	`select` 直接多路复用
等很多个 channel	fan-in 聚合（示例 9），别写 N 个 case
超时	`time.After`（低频）/ `time.NewTimer`（循环内）
非阻塞尝试	`select + default`
优先级	两层 select（示例 6），注意 default 空转
动态启用/禁用分支	把变量设为 `nil`
循环等待 + 退出	`for { select { case <-ctx.Done(): return; ... } }`
关闭的 channel	`v, ok := <-ch` 判断 ok，ok=false 时退出或置 nil
广播退出	`close(done)` 或 `cancel()`，不要发 N 个值

七、总结

心智模型三句话：

select 是 channel 的 switch——对"哪个 channel 就绪"做分支，不是对值做分支
就绪随机选——这是公平性保证，不要依赖分支顺序
default 改阻塞语义——有 default 就是"尝试一次"，没 default 就是"阻塞等待"

四条铁律：

每个 case 都要有退出路径（return / break label / 置 nil），否则就是泄漏或死循环
关闭的 channel 永远就绪，必须 v, ok := 判断
default 要慎用，空转 CPU 是生产事故的常见源头
循环里的 time.After 会泄漏 timer，用 NewTimer + Reset

一句话：

select 让你一个 goroutine 同时监听多个通道，是 Go 写"响应式"逻辑的基石——超时、取消、多路复用、非阻塞尝试、优先级调度，全都靠它。但它的随机性和"关闭通道永远就绪"两个特性，决定了你必须在每个 case 里显式处理"这个分支是否还该活着"，否则不是死锁就是 CPU 打满。

十二、select 底层原理（简要）

编译器会把 select 转换为运行时调用：

1
2


// 伪代码
func selectgo(cas0 *scase, order0 *uint16, ncases int) (int, bool)

流程：

生成 scase 数组，每个 case 描述一个 channel 操作
加锁所有涉及 channel（按地址排序避免死锁）
遍历所有 case，找出就绪的
若多个就绪 → 用 fastrand 随机选一个
若都未就绪 → 当前 goroutine 挂起到所有 channel 的等待队列
有 default 则直接走 default

要点：

有 default：不挂起，直接返回
无 default：将当前 goroutine 加入所有相关 channel 的 sendq/recvq
被唤醒后从所有队列移除自己

十三、实战：完整示例 - 带超时、取消、重试的任务调度

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


package main

import (
    "context"
    "fmt"
    "math/rand"
    "time"
)

func fetch(ctx context.Context, id int) (string, error) {
    result := make(chan string, 1)

    go func() {
        // 模拟网络请求
        time.Sleep(time.Duration(rand.Intn(500)) * time.Millisecond)
        result <- fmt.Sprintf("数据-%d", id)
    }()

    select {
    case r := <-result:
        return r, nil
    case <-ctx.Done():
        return "", ctx.Err()
    }
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()

    for i := 1; i <= 5; i++ {
        select {
        case <-ctx.Done():
            fmt.Println("整体超时，退出")
            return
        default:
        }

        data, err := fetch(ctx, i)
        if err != nil {
            fmt.Println("任务", i, "失败:", err)
            continue
        }
        fmt.Println("任务", i, "成功:", data)
    }

    fmt.Println("全部完成")
}

十四、select 使用清单

场景	写法
等待多个 channel	`select { case <-a: case <-b: }`
非阻塞读取	加 `default`
超时控制	`case <-time.After(d):`
循环超时	`time.NewTimer` + `Reset`
退出信号	`case <-done:` 配合 `close(done)`
取消	`case <-ctx.Done():`
禁用某 case	把 channel 置 nil
合并多 channel	for + select + `ch = nil`
高优先级	嵌套 select

十五、最佳实践总结

✅ 循环内用 select + for 持续监听
✅ 超时优先用 context.Context，time.After 仅用于单次
✅ 退出用 close(done) 广播，不要发送多个值
✅ ch = nil 是禁用 case 的惯用技巧
✅ 多 case 随机是特性，不是 bug；要优先级用嵌套 select
❌ 循环里别用 time.After，会泄漏定时器
❌ 别在 select 中 close 已经关闭的 channel
❌ 无限循环 + 无 default + 所有 channel 阻塞 → deadlock

进一步展开：

select 源码解析（runtime.selectgo 的具体实现）
context 与 select 配合的深入用法
高并发场景下 select 的性能优化与替代方案

Goroutine Channel

Mon, 12 Oct 2026 09:31:48 +0800

Go Channel 详细讲解

Channel 是 Go 并发编程的核心，它是 goroutine 之间通信的管道，遵循 “不要通过共享内存来通信，而要通过通信来共享内存” 的设计哲学。

一、Channel 基础概念

1.1 什么是 Channel

Channel 是一个类型化的管道，可以通过它发送和接收值：

1
2
3


ch := make(chan int)     // 无缓冲 channel
ch <- 42                 // 发送
x := <-ch                // 接收

1.2 创建方式

1
2
3
4
5
6
7
8


// 无缓冲 channel（同步）
ch1 := make(chan int)

// 有缓冲 channel（异步，容量为 3）
ch2 := make(chan string, 3)

// 声明（nil channel，无法使用，会永久阻塞）
var ch3 chan int

1.3 三种操作

操作	语法	说明
发送	`ch <- v`	向 channel 写入
接收	`v := <-ch`	从 channel 读出
关闭	`close(ch)`	关闭 channel

二、无缓冲 vs 有缓冲

2.1 无缓冲 Channel（同步）

无缓冲 channel 的发送和接收必须同时准备好，否则阻塞。这叫"同步通信"。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


package main

import (
    "fmt"
    "time"
)

func main() {
    ch := make(chan int)

    go func() {
        fmt.Println("准备发送")
        ch <- 100 // 阻塞，直到有人接收
        fmt.Println("发送完成")
    }()

    time.Sleep(time.Second)
    fmt.Println("准备接收")
    v := <-ch
    fmt.Println("接收到:", v)
}

输出：

准备发送
准备接收
接收到: 100
发送完成

2.2 有缓冲 Channel（异步）

缓冲区未满时可发送，未空时可接收。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


package main

import "fmt"

func main() {
    ch := make(chan int, 3)

    ch <- 1
    ch <- 2
    ch <- 3
    fmt.Println("缓冲区:", len(ch), "容量:", cap(ch))

    // ch <- 4  // 会阻塞！缓冲区已满

    fmt.Println(<-ch) // 1
    fmt.Println(<-ch) // 2
    fmt.Println(<-ch) // 3
}

关键 API：

len(ch)：当前缓冲的元素个数
cap(ch)：缓冲区容量

三、关闭 Channel 与 range 遍历

3.1 关闭 Channel

1

close(ch)

规则：

只能由发送方关闭
关闭后不能再发送（panic）
关闭后仍可接收剩余数据
对已关闭 channel 再关闭会 panic

3.2 接收的两个返回值

1
2
3


v, ok := <-ch
// ok == true  : 正常接收
// ok == false : channel 已关闭且无数据

3.3 range 遍历

range 会自动检测 channel 关闭，收到所有数据后退出循环。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


package main

import "fmt"

func producer(ch chan int) {
    for i := 1; i <= 5; i++ {
        ch <- i
    }
    close(ch) // 必须关闭，否则 range 会死锁
}

func main() {
    ch := make(chan int)
    go producer(ch)

    for v := range ch {
        fmt.Println("收到:", v)
    }
    fmt.Println("channel 已关闭")
}

四、单向 Channel

用于限制 channel 的使用方向，提高类型安全。

1
2
3


chan int    // 双向
chan<- int  // 只写
<-chan int  // 只读

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


package main

import "fmt"

// 只写
func send(ch chan<- int) {
    for i := 0; i < 3; i++ {
        ch <- i
    }
    close(ch)
}

// 只读
func receive(ch <-chan int) {
    for v := range ch {
        fmt.Println(v)
    }
}

func main() {
    ch := make(chan int)
    go send(ch)
    receive(ch)
}

双向 channel 可隐式转换为单向，反之不行。

五、select 多路复用

select 让 goroutine 同时等待多个 channel 操作。

5.1 基础用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


select {
case v := <-ch1:
    fmt.Println("来自 ch1:", v)
case v := <-ch2:
    fmt.Println("来自 ch2:", v)
case ch3 <- 10:
    fmt.Println("写入 ch3")
default:
    fmt.Println("无就绪操作")
}

5.2 超时控制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


package main

import (
    "fmt"
    "time"
)

func main() {
    ch := make(chan int)

    select {
    case v := <-ch:
        fmt.Println("收到:", v)
    case <-time.After(2 * time.Second):
        fmt.Println("超时了")
    }
}

5.3 非阻塞读取

1
2
3
4
5
6


select {
case v := <-ch:
    fmt.Println("收到:", v)
default:
    fmt.Println("没有数据")
}

六、常见模式

6.1 生产者-消费者

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


package main

import (
    "fmt"
    "sync"
)

func producer(id int, ch chan<- int, wg *sync.WaitGroup) {
    defer wg.Done()
    for i := 0; i < 3; i++ {
        ch <- id*10 + i
    }
}

func main() {
    ch := make(chan int, 10)
    var wg sync.WaitGroup

    // 3 个生产者
    for i := 1; i <= 3; i++ {
        wg.Add(1)
        go producer(i, ch, &wg)
    }

    // 等待所有生产者后关闭
    go func() {
        wg.Wait()
        close(ch)
    }()

    // 消费者
    for v := range ch {
        fmt.Println("消费:", v)
    }
}

6.2 Worker Pool（工作池）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


package main

import (
    "fmt"
    "sync"
)

func worker(id int, jobs <-chan int, results chan<- int, wg *sync.WaitGroup) {
    defer wg.Done()
    for j := range jobs {
        results <- j * j
    }
}

func main() {
    jobs := make(chan int, 100)
    results := make(chan int, 100)

    var wg sync.WaitGroup
    // 启动 3 个 worker
    for w := 1; w <= 3; w++ {
        wg.Add(1)
        go worker(w, jobs, results, &wg)
    }

    // 发送任务
    for i := 1; i <= 9; i++ {
        jobs <- i
    }
    close(jobs)

    // 等 worker 结束再关闭结果
    go func() {
        wg.Wait()
        close(results)
    }()

    for r := range results {
        fmt.Println("结果:", r)
    }
}

6.3 扇入扇出（Fan-in / Fan-out）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// Fan-out：多个 goroutine 消费同一个 channel
// Fan-in：多个 channel 合并到一个

func fanIn(chs ...<-chan int) <-chan int {
    out := make(chan int)
    var wg sync.WaitGroup
    for _, ch := range chs {
        wg.Add(1)
        go func(c <-chan int) {
            defer wg.Done()
            for v := range c {
                out <- v
            }
        }(ch)
    }
    go func() {
        wg.Wait()
        close(out)
    }()
    return out
}

6.4 用 channel 实现信号量

1
2
3
4
5
6
7
8
9


sem := make(chan struct{}, 3) // 最多 3 个并发

for i := 0; i < 10; i++ {
    sem <- struct{}{}  // 获取
    go func(i int) {
        defer func() { <-sem }() // 释放
        // ... 业务逻辑
    }(i)
}

七、常见陷阱

7.1 死锁

1
2
3
4


func main() {
    ch := make(chan int)
    ch <- 1  // 死锁！没人接收
}

报错： fatal error: all goroutines are asleep - deadlock!

7.2 向已关闭 channel 发送

1
2
3


ch := make(chan int)
close(ch)
ch <- 1  // panic: send on closed channel

7.3 重复关闭

1
2
3


ch := make(chan int)
close(ch)
close(ch)  // panic: close of closed channel

7.4 nil channel

对 nil channel 的发送和接收会永久阻塞：

1
2
3
4


var ch chan int
<-ch      // 永久阻塞
ch <- 1   // 永久阻塞
close(ch) // panic

💡 select 中可用 nil channel 来"禁用"某个 case。

7.5 goroutine 泄漏

1
2
3
4
5
6
7


func bad() {
    ch := make(chan int)
    go func() {
        ch <- 1 // 如果没人接收，goroutine 永久阻塞
    }()
    // 忘了接收
}

解决： 使用缓冲、使用 context 取消、确保有接收方。

八、Channel 底层原理（简要）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


type hchan struct {
    qcount   uint           // 当前元素数量
    dataqsiz uint           // 缓冲区大小
    buf      unsafe.Pointer // 环形缓冲区
    elemsize uint16
    closed   uint32
    sendx    uint           // 发送索引
    recvx    uint           // 接收索引
    recvq    waitq          // 等待接收的 goroutine 队列
    sendq    waitq          // 等待发送的 goroutine 队列
    lock     mutex
}

要点：

有缓冲 channel 底层是环形队列
等待的 goroutine 被挂到 recvq / sendq
无缓冲发送时，直接把数据从 sender 拷贝到 receiver（“接力”）
所有操作都需要加锁，因此高频通信可考虑其他方式

九、Channel vs 其他同步机制

场景	推荐
goroutine 间传数据	Channel
只做互斥保护	`sync.Mutex`
等待多个任务完成	`sync.WaitGroup`
一次性通知	`close(ch)` 或 `sync.Once`
状态共享、缓存	`sync.Map` / 原子操作

性能提示：

无缓冲 channel ≈ 一次 goroutine 切换成本
有缓冲 channel 更快（减少阻塞）
极高吞吐场景可考虑 sync/atomic 或分片锁

十、最佳实践总结

✅ 谁发送，谁关闭（谁负责 close）
✅ 用 range 或 v, ok := <-ch 安全接收
✅ 使用 select + time.After 做超时
✅ 用 context.Context 处理取消信号
✅ Worker Pool 用 WaitGroup + close 组合
❌ 不要向已关闭的 channel 发送
❌ 不要依赖 channel 做广播（用 close 或 context）
❌ 不要用 channel 代替简单的互斥锁

Goroutine详细：sync.WaitGroup

Sun, 11 Oct 2026 22:51:47 +0800

sync.WaitGroup 是什么.

sync.WaitGroup 是 Go 标准库中用于等待一组 goroutine 完成的同步原语。它解决的核心问题是：主 goroutine 需要知道其他多个 goroutine 何时全部执行完毕。

基本用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


var wg sync.WaitGroup

for i := 0; i < 3; i++ {
    wg.Add(1)          // 计数 +1
    go func(id int) {
        defer wg.Done() // 计数 -1
        // 做一些工作
    }(i)
}

wg.Wait() // 阻塞，直到计数归零

为什么需要 Add 和 Done

WaitGroup 内部维护一个计数器，它的语义是"还有多少个任务没完成"：

Add(delta)：告诉 WaitGroup “我要开始 delta 个任务了”，计数器增加。
Done()：等价于 Add(-1)，表示"我完成了 1 个任务"，计数器减少。
Wait()：阻塞当前 goroutine，直到计数器归零。

拆成两个方法而不是一个"注册+运行"的 API，是因为任务的启动和完成在时间上是分离的：

你需要在启动 goroutine 之前就 Add，否则可能出现 goroutine 已经跑完并 Done 了、但 Add 还没执行的竞态，导致计数器错乱甚至 Wait 永远不返回。
Done 必须在任务真正结束时调用，通常配合 defer，保证即使 panic 或提前 return 也能正确减计数。

关键细节

Add 必须在 Wait 之前、且在 goroutine 启动前调用

1
2
3
4
5
6
7


// 错误：可能在 Wait 已返回后才 Add
go func() {
    wg.Add(1)  // 竞态！
    defer wg.Done()
    // ...
}()
wg.Wait()

正确写法是在 go 语句之前 wg.Add(1)。

计数器不能变成负数：Done 调用次数多于 Add 会 panic。

WaitGroup 不可复制：它内部含 noCopy 标记，传参要用指针 *sync.WaitGroup。

复用：等 Wait 返回、计数器归零后，可以再次 Add 复用同一个 WaitGroup（但要注意此时不能有并发的 Wait）。

和其他原语的区别

原语	用途
`sync.WaitGroup`	等待一组任务全部完成
`sync.Mutex`	互斥访问共享资源
channel	更通用的通信/同步，可实现类似 WaitGroup 的效果但更灵活

简单说，Add/Done 的设计是为了把"声明任务数量"和"标记任务结束"这两个时机分开，既保证计数正确，又让完成通知可以自然地用 defer 表达。

Goroutine详细：并发编程详细讲解

Sat, 10 Oct 2026 10:02:47 +0800

Go 并发编程详细讲解

Go 的并发模型基于 CSP（Communicating Sequential Processes），核心思想是：不要通过共享内存来通信，而要通过通信来共享内存。

下面从基础到进阶，系统讲解 Go 并发的所有核心概念，每个概念都配上可运行的示例。

一、Goroutine：轻量级线程

1.1 基础用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


package main

import (
	"fmt"
	"time"
)

func say(s string) {
	for i := 0; i < 3; i++ {
		fmt.Println(s, i)
		time.Sleep(100 * time.Millisecond)
	}
}

func main() {
	go say("world")   // 启动一个 goroutine
	say("hello")      // 主 goroutine 继续执行

	time.Sleep(500 * time.Millisecond) // 等 goroutine 跑完
}

关键点：

go 关键字启动一个 goroutine，立即返回，不阻塞。
主 goroutine 结束时，所有其他 goroutine 都会被强制终止。所以 main 里需要 Sleep 或同步机制等待。
Goroutine 初始栈只有 2KB，可动态增长，所以可以轻松启动数十万个。

1.2 为什么 goroutine 比线程轻

对比项	线程	Goroutine
初始栈大小	1-8 MB	2 KB
切换成本	内核态切换，微秒级	用户态切换，纳秒级
数量级	几千	百万级
调度	操作系统	Go runtime（GMP 模型）

1.3 用 WaitGroup 等待

time.Sleep 不靠谱，生产代码用 sync.WaitGroup：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


package main

import (
	"fmt"
	"sync"
)

func main() {
	var wg sync.WaitGroup

	for i := 0; i < 5; i++ {
		wg.Add(1)          // 计数 +1
		go func(n int) {
			defer wg.Done() // 计数 -1（defer 保证一定执行）
			fmt.Println("worker", n)
		}(i)               // 注意：i 作为参数传入，避免闭包捕获问题
	}

	wg.Wait()              // 阻塞直到计数归零
	fmt.Println("全部完成")
}

易错点：不要写成 go func() { ... }(i) 里的 i 直接捕获。Go 1.22 之前循环变量是共享的，需要用参数传入或 i := i 复制。Go 1.22 起每次迭代都是新变量，但显式传参更清晰。

二、Channel：goroutine 之间的通信管道

Channel 是 Go 并发的核心。可以把它想象成一条类型安全的队列。

2.1 无缓冲 Channel

1
2
3
4
5
6
7


ch := make(chan int)   // 无缓冲

go func() {
	ch <- 42           // 发送：阻塞直到有人接收
}()
v := <-ch              // 接收：阻塞直到有人发送
fmt.Println(v)         // 42

特点：发送和接收必须同时就绪，否则阻塞。这叫同步通信。

2.2 有缓冲 Channel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


ch := make(chan int, 3)  // 缓冲大小 3

ch <- 1                  // 不阻塞
ch <- 2                  // 不阻塞
ch <- 3                  // 不阻塞
// ch <- 4               // 会阻塞，缓冲满了

fmt.Println(<-ch)        // 1
fmt.Println(<-ch)        // 2
fmt.Println(<-ch)        // 3

特点：缓冲未满时发送不阻塞，缓冲非空时接收不阻塞。缓冲满了发送阻塞，缓冲空了接收阻塞。

2.3 关闭 Channel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


ch := make(chan int, 3)
ch <- 1
ch <- 2
close(ch)

// 方式一：range 自动结束
for v := range ch {
	fmt.Println(v)   // 1, 2，然后循环自动结束
}

// 方式二：逗号 ok 判断
v, ok := <-ch
if !ok {
	fmt.Println("channel 已关闭")
}

规则：

只有发送方应该关闭 channel，接收方关闭会 panic。
关闭后不能发送，但可以继续接收剩余数据。
重复关闭会 panic。
向 nil channel 发送/接收会永久阻塞。

2.4 Channel 作为同步信号

1
2
3
4
5
6
7
8
9


done := make(chan struct{})   // struct{} 不占内存

go func() {
	// 做一些工作
	fmt.Println("工作完成")
	close(done)                // 或 done <- struct{}{}
}()

<-done                         // 等待完成

struct{} 是零大小类型，作为纯信号使用时比 bool 更省内存。

2.5 Channel 方向

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


func producer(out chan<- int) {   // 只发送
	for i := 0; i < 5; i++ {
		out <- i
	}
	close(out)
}

func consumer(in <-chan int) {    // 只接收
	for v := range in {
		fmt.Println(v)
	}
}

func main() {
	ch := make(chan int)
	go producer(ch)
	consumer(ch)
}

方向约束让编译器帮你检查错误，是良好的 API 设计习惯。

三、Select：多路复用

select 让一个 goroutine 同时等待多个 channel 操作。

3.1 基础用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


select {
case v := <-ch1:
	fmt.Println("收到 ch1:", v)
case ch2 <- 42:
	fmt.Println("发送到 ch2")
case <-time.After(time.Second):
	fmt.Println("超时")
default:
	fmt.Println("都没有就绪，立即执行")
}

规则：

多个 case 同时就绪时，随机选一个（防止饥饿）。
有 default 时不阻塞；没有 default 时阻塞直到某个 case 就绪。

3.2 超时控制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


func fetchData() (string, error) {
	ch := make(chan string, 1)

	go func() {
		time.Sleep(2 * time.Second)  // 模拟慢操作
		ch <- "data"
	}()

	select {
	case v := <-ch:
		return v, nil
	case <-time.After(1 * time.Second):
		return "", fmt.Errorf("超时")
	}
}

3.3 非阻塞接收

1
2
3
4
5
6


select {
case v := <-ch:
	fmt.Println("收到:", v)
default:
	fmt.Println("没有数据")
}

3.4 退出信号

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


func worker(stop <-chan struct{}) {
	for {
		select {
		case <-stop:
			fmt.Println("收到退出信号")
			return
		default:
			// 正常工作
			time.Sleep(100 * time.Millisecond)
		}
	}
}

四、Context：取消与超时

context 是 Go 官方推荐的跨 goroutine 传递取消信号和超时的机制。

4.1 四种 Context

1
2
3
4
5


ctx := context.Background()                          // 根 context，永不取消
ctx, cancel := context.WithCancel(parent)            // 手动取消
ctx, cancel := context.WithTimeout(parent, 3*time.Second)  // 超时取消
ctx, cancel := context.WithDeadline(parent, time.Now().Add(3*time.Second)) // 截止时间
defer cancel()                                        // 必须调用，防止资源泄漏

4.2 取消传播

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


func main() {
	ctx, cancel := context.WithCancel(context.Background())

	go worker(ctx, "A")
	go worker(ctx, "B")

	time.Sleep(2 * time.Second)
	cancel()   // 取消信号传播到所有子 goroutine

	time.Sleep(500 * time.Millisecond)
}

func worker(ctx context.Context, name string) {
	for {
		select {
		case <-ctx.Done():
			fmt.Println(name, "退出:", ctx.Err())
			return
		default:
			fmt.Println(name, "工作中")
			time.Sleep(500 * time.Millisecond)
		}
	}
}

4.3 配合 HTTP 请求

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func callAPI(ctx context.Context) error {
	req, _ := http.NewRequestWithContext(ctx, "GET", "https://api.example.com", nil)
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err  // 如果 ctx 被取消，err 会是 context.Canceled
	}
	defer resp.Body.Close()
	// ...
	return nil
}

4.4 Context 使用原则

原则	说明
作为函数第一个参数	`func Do(ctx context.Context, ...)`
不放进 struct	Context 应该随调用链传递，不是对象状态
只用于取消、超时、传值	不要用它传业务参数
`cancel()` 必须调用	`defer cancel()` 防止 goroutine 泄漏
`context.Value` 少用	只用于 request-scoped 的元数据（如 traceID、用户身份）

五、sync 包：共享内存同步

虽然 Go 提倡用 channel 通信，但有些场景用共享内存更自然。

5.1 Mutex：互斥锁

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


type Counter struct {
	mu sync.Mutex
	n  int
}

func (c *Counter) Inc() {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.n++
}

func (c *Counter) Value() int {
	c.mu.Lock()
	defer c.mu.Unlock()
	return c.n
}

5.2 RWMutex：读写锁

读多写少的场景，允许多个读者并发：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


type Cache struct {
	mu sync.RWMutex
	m  map[string]string
}

func (c *Cache) Get(k string) (string, bool) {
	c.mu.RLock()          // 读锁，可多个 goroutine 同时持有
	defer c.mu.RUnlock()
	v, ok := c.m[k]
	return v, ok
}

func (c *Cache) Set(k, v string) {
	c.mu.Lock()           // 写锁，独占
	defer c.mu.Unlock()
	c.m[k] = v
}

5.3 Once：只执行一次

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


var (
	instance *DB
	once     sync.Once
)

func GetDB() *DB {
	once.Do(func() {
		instance = &DB{}   // 只执行一次，其他 goroutine 阻塞等待
	})
	return instance
}

单例模式的标准实现，比手动加锁更安全。

5.4 sync.Map：并发安全的 Map

普通 map 并发读写会 panic。sync.Map 适合读多写少、key 相对固定的场景：

1
2
3
4
5
6
7
8
9


var m sync.Map

m.Store("key", "value")
v, ok := m.Load("key")
m.Delete("key")
m.Range(func(k, v any) bool {
	fmt.Println(k, v)
	return true
})

注意：sync.Map 不是万能替代。大部分场景用 sync.RWMutex + map 性能更好。sync.Map 只在特定场景（如缓存、注册表）有优势。

5.5 sync.Pool：对象复用

减少 GC 压力，适合频繁创建销毁的对象：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


var bufPool = sync.Pool{
	New: func() any {
		return new(bytes.Buffer)
	},
}

func process() {
	buf := bufPool.Get().(*bytes.Buffer)
	defer func() {
		buf.Reset()
		bufPool.Put(buf)
	}()
	buf.WriteString("data")
	// ...
}

注意：sync.Pool 里的对象可能在任意 GC 时被回收，不能用于持久化状态。

六、经典并发模式

6.1 Worker Pool（工作池）

控制并发数量，避免资源耗尽：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


func workerPool() {
	jobs := make(chan int, 100)
	results := make(chan int, 100)

	// 启动 3 个 worker
	var wg sync.WaitGroup
	for w := 0; w < 3; w++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for j := range jobs {
				results <- j * j   // 处理任务
			}
		}()
	}

	// 发送任务
	go func() {
		for i := 0; i < 10; i++ {
			jobs <- i
		}
		close(jobs)
	}()

	// 等待 worker 完成后关闭 results
	go func() {
		wg.Wait()
		close(results)
	}()

	// 收集结果
	for r := range results {
		fmt.Println(r)
	}
}

6.2 Fan-out / Fan-in（扇出扇入）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// Fan-out：一个输入分发给多个 worker
// Fan-in：多个 worker 输出汇聚成一个 channel

func fanIn(chs ...<-chan int) <-chan int {
	out := make(chan int)
	var wg sync.WaitGroup
	for _, ch := range chs {
		wg.Add(1)
		go func(c <-chan int) {
			defer wg.Done()
			for v := range c {
				out <- v
			}
		}(ch)
	}
	go func() {
		wg.Wait()
		close(out)
	}()
	return out
}

6.3 Pipeline（流水线）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


func gen(nums ...int) <-chan int {
	out := make(chan int)
	go func() {
		for _, n := range nums {
			out <- n
		}
		close(out)
	}()
	return out
}

func square(in <-chan int) <-chan int {
	out := make(chan int)
	go func() {
		for n := range in {
			out <- n * n
		}
		close(out)
	}()
	return out
}

func main() {
	// gen → square → 输出
	for v := range square(gen(1, 2, 3, 4, 5)) {
		fmt.Println(v)   // 1, 4, 9, 16, 25
	}
}

6.4 限流（Semaphore）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func limited() {
	sem := make(chan struct{}, 3)   // 最多 3 个并发
	var wg sync.WaitGroup

	for i := 0; i < 10; i++ {
		wg.Add(1)
		go func(n int) {
			defer wg.Done()
			sem <- struct{}{}        // 获取令牌
			defer func() { <-sem }() // 释放令牌

			fmt.Println("处理", n)
			time.Sleep(time.Second)
		}(i)
	}
	wg.Wait()
}

用 golang.org/x/sync/semaphore 可以支持带权重的限流。

6.5 errgroup：带错误传播的并发

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


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

func fetchAll(ctx context.Context, urls []string) error {
	g, ctx := errgroup.WithContext(ctx)

	for _, url := range urls {
		url := url
		g.Go(func() error {
			return fetch(ctx, url)   // 任一失败会取消 ctx
		})
	}
	return g.Wait()   // 返回第一个错误
}

errgroup 是并发任务编排的利器，比手写 WaitGroup + channel 简洁得多。

七、数据竞争与检测

7.1 竞争示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


func main() {
	n := 0
	var wg sync.WaitGroup

	for i := 0; i < 1000; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			n++   // 数据竞争！
		}()
	}
	wg.Wait()
	fmt.Println(n)   // 通常小于 1000
}

7.2 用 -race 检测

1
2


go run -race main.go
go test -race ./...

-race 会在运行时检测数据竞争，输出冲突的读写位置。生产构建不要开 -race（性能损失约 10 倍），但开发和 CI 一定要开。

7.3 修复方式

方式一：加锁

1
2
3
4


var mu sync.Mutex
mu.Lock()
n++
mu.Unlock()

方式二：用 atomic

1
2


var n int64
atomic.AddInt64(&n, 1)

方式三：用 channel

1
2
3


ch := make(chan int)
go func() { ch <- 1 }()
n += <-ch

八、GMP 调度模型

理解 Go 调度的核心：

组件	含义
G (Goroutine)	用户态协程，包含栈、指令指针等
M (Machine)	操作系统线程
P (Processor)	逻辑处理器，持有可运行 G 的本地队列

调度流程：

每个 P 有一个本地运行队列，M 绑定 P 后从中取 G 执行。
本地队列空时，M 会从全局队列或其他 P 的队列窃取 G（work stealing）。
G 遇到阻塞系统调用时，M 会释放 P，让其他 M 绑定 P 继续执行。
网络 I/O 由 netpoller 处理，不阻塞 M。

关键参数：

GOMAXPROCS：P 的数量，默认等于 CPU 核数。
runtime.NumGoroutine()：当前 goroutine 数量，用于排查泄漏。

九、常见坑与最佳实践

9.1 Goroutine 泄漏

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// 错误：goroutine 永远阻塞
func bad() {
	ch := make(chan int)
	go func() {
		ch <- 42   // 没人接收，永久阻塞
	}()
	// 函数返回，goroutine 泄漏
}

// 正确：用 context 或 buffered channel
func good(ctx context.Context) {
	ch := make(chan int, 1)   // 缓冲 1，发送不阻塞
	go func() {
		select {
		case ch <- 42:
		case <-ctx.Done():
		}
	}()
}

9.2 循环变量捕获

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// Go 1.22 之前：所有 goroutine 打印 5
for i := 0; i < 5; i++ {
	go func() { fmt.Println(i) }()
}

// 修复方式一：传参
for i := 0; i < 5; i++ {
	go func(n int) { fmt.Println(n) }(i)
}

// 修复方式二：局部变量
for i := 0; i < 5; i++ {
	i := i
	go func() { fmt.Println(i) }()
}

Go 1.22 起循环变量每次迭代都是新的，不再有此问题。

9.3 关闭已关闭的 Channel

1
2
3


// 错误：重复关闭 panic
close(ch)
close(ch)   // panic: close of closed channel

用 sync.Once 保证只关一次：

1
2


var once sync.Once
once.Do(func() { close(ch) })

9.4 向已关闭的 Channel 发送

1
2


close(ch)
ch <- 1   // panic: send on closed channel

规则：只有发送方关闭，且关闭后不再发送。

9.5 用 Buffered Channel 避免泄漏

如果 goroutine 发送后可能没人接收，用缓冲 channel：

1
2


ch := make(chan int, 1)   // 缓冲 1，发送方不会阻塞
go func() { ch <- 42 }()

9.6 超时与重试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


func retry(ctx context.Context, fn func() error) error {
	for i := 0; i < 3; i++ {
		if err := fn(); err == nil {
			return nil
		}
		select {
		case <-ctx.Done():
			return ctx.Err()
		case <-time.After(time.Duration(i+1) * time.Second):
		}
	}
	return fmt.Errorf("重试 3 次仍失败")
}

十、决策指南：用 Channel 还是 Mutex

场景	推荐
传递数据所有权	Channel
分发任务给多个 worker	Channel
通知事件（signal）	Channel
保护共享状态（计数器、缓存）	Mutex / RWMutex
单例初始化	sync.Once
对象池	sync.Pool
并发 map	sync.Map 或 RWMutex + map

简单判断：如果你在问"谁拥有这份数据"，用 Channel；如果你在问"谁能同时访问这份数据"，用 Mutex。

十一、AI 应用中的并发模式

结合你之前的项目，几个实际场景：

11.1 流式响应 + 超时

1
2
3
4
5
6
7
8
9


func streamWithTimeout(ctx context.Context, client *llm.Client) error {
	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
	defer cancel()

	_, err := client.ChatStream(ctx, msgs, func(tok string) {
		fmt.Print(tok)
	})
	return err
}

11.2 并发调用多个模型对比

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


func compareModels(ctx context.Context, prompt string, models []string) (map[string]string, error) {
	g, ctx := errgroup.WithContext(ctx)
	results := sync.Map{}

	for _, m := range models {
		m := m
		g.Go(func() error {
			client := llm.NewClient(baseURL, apiKey, m, httpClient)
			reply, err := client.Chat(ctx, []llm.Message{{Role: "user", Content: prompt}})
			if err != nil {
				return err
			}
			results.Store(m, reply)
			return nil
		})
	}

	if err := g.Wait(); err != nil {
		return nil, err
	}

	out := map[string]string{}
	results.Range(func(k, v any) bool {
		out[k.(string)] = v.(string)
		return true
	})
	return out, nil
}

11.3 Token 计数限流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


type TokenLimiter struct {
	sem chan struct{}
}

func NewTokenLimiter(maxConcurrent int) *TokenLimiter {
	return &TokenLimiter{sem: make(chan struct{}, maxConcurrent)}
}

func (l *TokenLimiter) Acquire(ctx context.Context) error {
	select {
	case l.sem <- struct{}{}:
		return nil
	case <-ctx.Done():
		return ctx.Err()
	}
}

func (l *TokenLimiter) Release() {
	<-l.sem
}

十二、总结

主题	核心要点
Goroutine	轻量、go 关键字、主 goroutine 退出会杀死所有
Channel	无缓冲同步、有缓冲异步、关闭规则、方向约束
Select	多路复用、超时、default 非阻塞
Context	取消传播、超时、作为第一个参数
sync 包	Mutex/RWMutex/Once/Pool/Map
经典模式	Worker Pool、Fan-in/out、Pipeline、Semaphore、errgroup
数据竞争	用 -race 检测，加锁或 atomic 修复
GMP	G=协程、M=线程、P=逻辑处理器，work stealing
常见坑	goroutine 泄漏、循环变量、重复关闭、死锁
决策	传数据用 channel，护状态用 mutex

一句话：Go 并发的精髓是 “用 channel 传递数据，用 context 传递取消，用 sync 保护状态”。理解这三者的适用场景，就能写出健壮的并发程序。

Golangs on 山高月小

CSP（Communicating Sequential Processes）详解

CSP（通信顺序进程）详解

一、CSP 要解决什么问题

二、CSP 的核心抽象

2.1 进程（Process）

2.2 通道（Channel）

2.3 选择（Choice / Select）

三、CSP 在 Go 中的完整映射

四、为什么"通过通信共享内存"更好

五、CSP vs 其他并发模型

六、CSP 的局限性与实践中要注意的地方

七、回到你的代码：CSP 视角的解读

八、总结

Template text/template 完全学习

Go 语言 text/template 完全指南

一、为什么需要模板引擎？

二、最小可运行示例

main.go

三、三个核心概念

四、模板语法详解

1. 输出变量 {{ .字段 }}

2. struct 作为数据

3. 条件判断 {{ if }} {{ else }} {{ end }}

4. 循环 {{ range }}

5. 循环里的索引

6. 变量 {{ $x := ... }}

7. 管道 {{ . | func }}

8. 内建函数一览

9. 去除空白 {{- 和 -}}

10. 注释 {{/* ... */}}

五、多模板与嵌套

1. 定义命名模板 {{ define }}

2. 模板里调用模板

六、从文件加载模板

目录结构

tmpl/greeting.tmpl

tmpl/example.tmpl

main.go

七、自定义函数

八、错误处理

九、text/template vs html/template

十、完整可运行示例：Prompt 模板引擎

目录结构

config.json

prompts/classify.tmpl

main.go

运行

输出

十一、常见坑与最佳实践

十二、函数速查表

十三、一句话总结

Template 系统性学习

Go Template 系统性学习指南

一、基础用法：三步流程

1.1 从字符串解析

1.2 从文件解析

1.3 数据访问方式

二、模板语法核心

2.1 注释

2.2 条件判断

2.3 循环 range

2.4 with 改变作用域

2.5 变量

2.6 管道

2.7 空白修剪

三、自定义函数

四、嵌套模板与布局

4.1 define / template / block

{{.Heading}}

4.2 block 用于可覆盖的默认实现

4.3 Gin 框架中的嵌套模板

五、HTML 安全：html/template 的自动转义

5.1 自动转义演示

5.2 安全模型

六、性能优化

6.1 核心原则：启动时解析，请求时只执行

6.2 并发安全

6.3 需要不同数据隔离时使用 Clone

6.4 避免不必要的转义开销

Go 语言 `text/template` 完全指南

`main.go`

1. 输出变量 `{{ .字段 }}`

3. 条件判断 `{{ if }}` `{{ else }}` `{{ end }}`

4. 循环 `{{ range }}`

6. 变量 `{{ $x := ... }}`

7. 管道 `{{ . | func }}`

9. 去除空白 `{{-` 和 `-}}`

10. 注释 `{{/* ... */}}`

1. 定义命名模板 `{{ define }}`

`tmpl/greeting.tmpl`

`tmpl/example.tmpl`

`main.go`

九、`text/template` vs `html/template`

`config.json`

`prompts/classify.tmpl`

`main.go`

Go 语言 `sync.Mutex` 互斥锁详解

六、进阶：`sync.RWMutex` 读写锁

七、进阶：`defer` 的代价

九、什么时候不需要 `Mutex`？

Go `select` 详解与可运行示例

规则 3：没有 `default` 时，全部不就绪则阻塞当前 goroutine