1. 概览

1.1 状态与分类

• nil：只声明、未通过 make 初始化。
• open：已经 make，可以正常通信。
• closed：已经调用 close，不再接受发送。

再结合容量，channel 可分为无缓冲和有缓冲两类。

1.2 核心行为矩阵

2. 生命周期

2.1 初始化

1
2
3

var nilCh chan int          // nil channel
unbuffered := make(chan int)
buffered := make(chan int, 3)

channel 的容量创建后不能改变。

1
2

n := -1
ch := make(chan int, n) // runtime panic: makechan: size out of range

len(ch) 的语义只限于返回当前缓冲区中的元素个数，不代表 channel 的完整状态。例如：

• 对无缓冲 channel，len(ch) 恒为 0，但 send/receive 是否阻塞取决于是否有配对的接收/发送方正在等待，不能从 len(ch) 推断。
• 对有缓冲 channel，len(ch) 只是某一时刻的快照；检查它之后、执行 send/receive 之前，其他 goroutine 可能已经改变了 channel 状态。

因此不能用 len(ch) 来判断下一次 send 或 receive 是否会阻塞。

2.2 nil channel

1
2
3
4
5

var ch chan int

ch <- 1   // 永久阻塞
v := <-ch // 永久阻塞
close(ch) // panic

nil channel 不等同于 closed channel：

• nil channel 永远无法完成通信。
• closed channel 的接收操作立即完成。

2.3 无缓冲 channel

1

ch := make(chan int)

发送方和接收方必须会合：

1
2
3
4
5

go func() {
    ch <- 42
}()

v := <-ch

ch <- 42 只有在另一个 goroutine 已经或即将执行接收时才能完成。反方向也一样：接收方会等待发送方。

如果在同一个 goroutine 中发送后才接收：

1
2
3
4

ch := make(chan int)

ch <- 42
fmt.Println(<-ch)

发送操作无法完成，程序会出现：

1

fatal error: all goroutines are asleep - deadlock!

正确写法需要另一个 goroutine，或使用缓冲区。

2.4 有缓冲 channel

1
2
3
4
5

ch := make(chan int, 2)

ch <- 1 // 不阻塞
ch <- 2 // 不阻塞
ch <- 3 // 缓冲区已满，阻塞

发送在缓冲区满时阻塞；接收在缓冲区空时阻塞：

1

fmt.Println(<-ch) // 取出 1，释放一个位置

可以将其理解为固定容量队列，但 channel 还包含同步和唤醒语义。

2.5 关闭 channel

关闭表示“之后不会再发送新值”：

1

close(ch)

关闭不会清空缓冲区。接收方先获得剩余数据，然后持续获得元素类型的零值。

1
2
3
4
5
6
7
8
9

ch := make(chan int, 2)
ch <- 10
ch <- 20
close(ch)

fmt.Println(<-ch) // 10
fmt.Println(<-ch) // 20
fmt.Println(<-ch) // 0
fmt.Println(<-ch) // 0

区分“发送了零值”和“channel 已排空并关闭”，可使用 comma-ok：

1
2
3
4
5

v, ok := <-ch

if !ok {
    // channel 已关闭且缓冲区已排空
}

缓冲区还有数据时，即使 channel 已关闭，ok 仍为 true：

1
2
3
4
5
6

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

v, ok := <-ch // 0, true：这是发送过的零值
v, ok = <-ch  // 0, false：关闭后的零值

3. 特殊行为

3.1 range 行为

1
2
3

for v := range ch {
    fmt.Println(v)
}

等价于反复接收，直到 channel 已关闭且缓冲区排空：

1
2
3
4
5
6
7

for {
    v, ok := <-ch
    if !ok {
        break
    }
    fmt.Println(v)
}

如果发送方从不关闭 channel，接收方会在取完最后一个值后继续等待：

1
2
3
4
5
6
7

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

for v := range ch {
    fmt.Println(v)
}
// 取出 1 后阻塞，因为 ch 没有关闭

channel 不需要为了垃圾回收而关闭。只有接收方需要知道“不会再有数据”时才需要关闭。

3.2 多发送方与多接收方

一个值只会被一个接收者获得。下面的例子中，两个接收者竞争缓冲区里的一个值：

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

ch := make(chan int, 1)
var wg sync.WaitGroup

wg.Go(func() {
    v, ok := <-ch
    fmt.Println("receiver 1:", v, ok)
})
wg.Go(func() {
    v, ok := <-ch
    fmt.Println("receiver 2:", v, ok)
})

ch <- 42
close(ch)
wg.Wait()

可能的输出：

1
2

receiver 1: 42 true
receiver 2: 0 false

42 只被其中一个接收者拿到；另一个被 close(ch) 唤醒后得到零值。

关闭 channel 会唤醒所有阻塞的接收者：

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

ch := make(chan int)
var wg sync.WaitGroup

for i := 0; i < 3; i++ {
    id := i
    wg.Go(func() {
        _, ok := <-ch
        fmt.Printf("receiver %d ok=%v\n", id, ok)
    })
}

// 等待接收者都阻塞在 <-ch 上（仅作示例，实际代码不要依赖 sleep）
time.Sleep(50 * time.Millisecond)
close(ch)
wg.Wait()

输出：

1
2
3

receiver 0 ok=false
receiver 1 ok=false
receiver 2 ok=false

缓冲数据仍然只会分配给其中某一个接收者；排空后，所有接收者都能立即得到零值和 ok=false。

多个发送方同时发送时，接收顺序与 goroutine 的启动顺序无关，因为实际调度是随机的。因此不能依赖代码中的书写顺序来判断实际接收顺序：

1
2

go func() { ch <- 1 }()
go func() { ch <- 2 }()

可能先收到 1，也可能先收到 2。

一般约定是：

创建和关闭 channel 的责任通常属于发送方；存在多个发送方时，应由一个协调者统一关闭。

不要让多个发送者自行判断并关闭：

1
2
3

if shouldClose {
    close(ch) // 其他发送者可能仍在发送或也准备关闭
}

并发执行 send 与 close 没有安全保证，可能产生数据竞争或 send on closed channel。

3.3 select 的边界行为

select 同时监听多个 channel 操作，哪个 case 就绪就执行哪个。下面是一个典型结构：

1
2
3
4
5
6

select {
case v := <-input:
    use(v)
case output <- result:
case <-ctx.Done():
}

本节讨论 select 在 nil channel、closed channel 等边界条件下的行为。

3.3.1 nil channel case 会被禁用

1
2
3
4
5
6
7
8

var ch chan int

select {
case <-ch:
    // 永远不会选中
default:
    // 执行这里
}

这可以用于动态启用或禁用 case：

1
2
3

if !enabled {
    ch = nil
}

3.3.2 closed channel 的接收 case 始终就绪

1
2
3
4
5
6
7

close(ch)

select {
case v, ok := <-ch:
    // 立即执行，ok=false
default:
}

如果循环中的 select 没有处理 ok，closed channel 可能导致忙循环：

1
2
3
4
5
6
7

for {
    select {
    case v := <-ch:
        process(v) // ch 关闭后不断处理零值
    default:
    }
}

处理方式之一是退出：

1
2
3
4

case v, ok := <-ch:
    if !ok {
        return
    }

或者将它设为 nil，禁用这个 case：

1
2
3
4
5

case v, ok := <-ch:
    if !ok {
        ch = nil
        continue
    }

3.3.3 向 closed channel 发送的 case

1
2
3
4
5
6
7

close(ch)

select {
case ch <- 1:
    // 如果该 case 被选中，会 panic
default:
}

select 不会替发送方安全地忽略 closed channel。必须通过所有权和同步保证发送时 channel 仍开放。

3.3.4 多个 case 同时就绪

如果多个 case 同时可执行，Go 会选择其中一个，不能依赖固定优先级：

1
2
3
4

select {
case <-a:
case <-b:
}

3.3.5 所有 case 都不可执行

• 有 default：立即执行 default。
• 没有 default：当前 goroutine 阻塞。
• 空 select {}：永久阻塞。

3.4 关闭作为广播信号

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

start := make(chan struct{})

go func() {
    <-start
    work()
}()

go func() {
    <-start
    work()
}()

close(start)

关闭 channel 后，所有 <-start 都立即完成，因此适合作为一次性广播信号。

如果只发送一次：

1

start <- struct{}{}

对于无缓冲 channel，一次发送只会唤醒一个接收者。

struct{} 不携带实际数据，常用于纯信号 channel：

1

chan struct{}

3.5 channel 方向

函数参数可以限制 channel 操作：

1
2
3
4
5
6
7
8

func producer(out chan<- int) {
    out <- 1
    close(out) // send-only channel 可以关闭
}

func consumer(in <-chan int) {
    fmt.Println(<-in)
}

以下操作编译失败：

1
2
3
4

func consumer(in <-chan int) {
    in <- 1   // 不能发送
    close(in) // 不能关闭 receive-only channel
}

方向限制主要用于表达所有权并防止误用。

3.6 会引发 panic 的操作

panic 不是 channel 正常生命周期的一部分，而是错误使用导致的运行时异常。下面列出三类常见场景。

3.6.1 向 closed channel 发送

1
2

close(ch)
ch <- 1 // panic: send on closed channel

3.6.2 重复关闭

1
2

close(ch)
close(ch) // panic: close of closed channel

3.6.3 关闭 nil channel

1
2

var ch chan int
close(ch) // panic: close of nil channel

这些是普通 runtime panic，可以通过 recover 捕获，但不应依赖 recover 管理 channel 生命周期。

与之相对，程序整体死锁会产生如下 fatal error：

1

fatal error: all goroutines are asleep - deadlock!

它属于 runtime fatal error，不能用常规 recover 恢复。

4. 同步保证

channel 不只是数据队列，也建立 goroutine 之间的 happens-before 关系。

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

var value int
done := make(chan struct{})

go func() {
    value = 42
    close(done)
}()

<-done
fmt.Println(value) // 能观察到 value = 42

关闭 done 发生在接收方观察到关闭之前，因此前面的写入对接收方可见。

因此 channel 常用于任务完成通知。多个 goroutine 同时访问其他共享变量时，仍需要确保所有访问都被 channel、锁或其他同步机制正确排序。

5. 参考

• The Go Programming Language Specification — channel 类型、send/receive/close 的语义定义。
• The Go Memory Model — channel 建立的 happens-before 关系。
• Effective Go — Channels — 官方推荐的 channel 使用模式。

6. 延伸阅读

• Go Blog: Share Memory By Communicating — channel 作为同步与通信工具的设计思路。
• Go Blog: Go Concurrency Patterns: Pipelines and cancellation — 多发送方/接收方、关闭责任等工程实践。
• Go Blog: Advanced Go Concurrency Patterns — select、nil channel 禁用 case 等模式。
• golang.org/x/sync/errgroup — 带错误收集和取消的 goroutine 组。
• github.com/sourcegraph/conc — 提供 WaitGroup、Pool 等结构化并发工具（Go 1.20+）。

并发问题

初始化的典型写法是 check-then-create：先查“管理员是否存在”，不存在则插入。AI 实现的初版方案里，存在多实例并行启动时的并发问题，两个副本的执行时序可以交错成这样：

sequenceDiagram
    participant A as 副本 A
    participant D as 数据库
    participant B as 副本 B
    A->>D: SELECT ... WHERE username='admin' → 不存在
    B->>D: SELECT ... WHERE username='admin' → 不存在
    A->>D: INSERT users ('admin') → 成功
    B->>D: INSERT users ('admin') → ✗ 唯一键冲突

后到的副本 bootstrap 报错，实例崩溃重启。重启后看到管理员已存在就会跳过，理论上可以自愈，但发布期间会伴随崩溃循环和错误日志。

我指出这个问题后，AI 先用 advisory lock（悲观锁）实现了基线版本，把正确性解决了。随后我提出对锁的两点顾虑——绑定 MySQL 方言、以及锁超时带来的启动失败模型——并要求评估乐观锁和 upsert 两种不依赖锁的方案。这两种方案各有前提：乐观锁要求被修改的行已经存在并带有版本字段，upsert 要求目标表有真正生效的唯一索引。

验证悲观锁基线时的双副本冒烟带来了一个计划外的发现：终态检查时，user_auth_methods 里存在两条 local 密码方法，密码还不一样。用户表正常、方法表却重复，原因见本文第四节。

乐观锁：不适用于插入竞态

乐观锁（optimistic locking）假设冲突很少发生：不阻止任何人操作，而是在提交修改时检查“我读取的数据在我动手期间有没有被别人改过”。经典实现是给表加一列版本号：

1
2
3
4
5
6
7
8

-- 读取时记下版本
SELECT role_id, name, version FROM roles WHERE role_id = 42;
-- version = 7

-- 更新时把版本作为条件：只有我看到的那个版本还在，更新才生效
UPDATE roles SET name = 'admin-v2', version = version + 1
WHERE role_id = 42 AND version = 7;
-- RowsAffected = 1：成功；= 0：期间有人改过，重读重试

它叫“乐观”，是因为全程不加锁，冲突以“更新失败后重试”的方式事后发现。适合读多写少、冲突可重试的场景（比如未来的角色权限编辑）。

但它解决的是并发更新同一行。初始化竞态是并发插入不存在的行——行还不存在，没有版本号可比较，CAS 无从谈起。这也是我在评审中排除它的原因：对数据模型的前提（行已存在、有版本列）在这个场景不成立。

悲观锁（advisory lock）：有效，但引入依赖

悲观锁（pessimistic locking）相反：假设冲突一定会发生，先把资源锁住，让别人排队。数据库里的行锁（SELECT ... FOR UPDATE）、表锁都属此类。正确性直接，代价是引入了等待。

我们要锁的不是某行数据（行还不存在），而是“初始化”这个动作本身。这正好对应 MySQL 的命名咨询锁（named advisory lock）：一把与任何表无关、按名字获取的全局锁，语义是“同名锁同一时刻只有一个连接能持有”。基本用法：

1
2
3

SELECT GET_LOCK('authx_bootstrap_seed', 10);  -- 1 = 拿到；0 = 10 秒超时；NULL = 出错
-- ... 临界区：初始化 ...
SELECT RELEASE_LOCK('authx_bootstrap_seed');  -- 释放（连接断开也会自动释放）

实际使用中有三个细节需要注意：

1. 加锁和解锁必须在同一条连接上。锁的持有者是连接；用连接池随手执行两条语句，可能落在两条连接上，导致锁没有生效、或锁无法被释放。我们的实现是显式持有一条专用连接，直到临界区结束：

   1 2 3 4 5 6 7 8 9

   conn, _ := sqlDB.Conn(ctx) // 专用连接，不是池里随便拿一条 if err := conn.QueryRowContext(ctx, "SELECT GET_LOCK(?, ?)", name, timeoutSec).Scan(&locked); err != nil { return err } defer func() { conn.QueryRowContext(ctx, "SELECT RELEASE_LOCK(?)", name) conn.Close() }()

2. 返回值三种都要处理：1 = 拿到，0 = 超时，NULL = 出错（如锁名超过 64 字符）。

3. 解锁路径必须覆盖所有退出分支（包括 panic）——defer 是唯一可靠的方式。

golang-migrate 也使用同样的机制保证多实例迁移不冲突（它的 MySQL 驱动里同样是 SELECT GET_LOCK(?, 10)，见参考链接）。基线实现后，双副本冒烟结果：0 失败、恰好 1 个管理员、1 条密码方法，正确性得到验证。

但这个方案有两个无法回避的代价：

1. 绑定底层数据库选型。GET_LOCK 是手写的 MySQL 方言，没有任何抽象层。PostgreSQL 虽有 pg_advisory_lock，但名称、语义、超时行为都不同，日后要兼容就是债务。
2. 悲观锁的失败模型。锁意味着等待，等待意味着超时，超时意味着副本启动失败并进入崩溃循环——只是从“撞唯一键崩溃”换成了“等锁超时崩溃”。概率不高，但这个故障模式是我们主动引入的。

DDIA 第 9 章《分布式系统的麻烦》对这类失效模式有更系统的讨论：网络延迟和进程暂停都可能导致持锁实例无法及时续租，锁超时后被其他实例获得，进而产生并发写入（参考：DDIA 第 9 章）。

upsert：由唯一索引保证原子性

唯一索引本身就是数据库内置的串行点，违反约束的插入会被数据库原子地拒绝。upsert 把“冲突了怎么办”变成插入语句自身语义的一部分：

1
2
3
4
5
6
7
8
9

-- MySQL：GORM MySQL driver 生成主键自赋值，冲突行保持不动
INSERT INTO users (tenant_id, type, username, status)
VALUES (0, 1, 'admin', 1)
ON DUPLICATE KEY UPDATE user_id = user_id;

-- PostgreSQL
INSERT INTO users (tenant_id, type, username, status)
VALUES (0, 1, 'admin', 1)
ON CONFLICT (tenant_id, username) DO NOTHING;

整个操作在数据库内部是原子的，不存在“查到插入之间”的窗口——竞态从语义上被消除，不需要任何锁。

工程上不直接写方言 SQL：GORM 的 clause.OnConflict 会按驱动生成对应方言（MySQL → ON DUPLICATE KEY UPDATE，PostgreSQL → ON CONFLICT DO NOTHING），应用代码保持方言中立：

1
2
3

tx := db.Clauses(clause.OnConflict{DoNothing: true}).Create(user)
// 在当前 MySQL DSN 配置下，RowsAffected == 1 表示插入，
// RowsAffected == 0 表示冲突行保持不变。

单行管理员初始化使用 RowsAffected 判断本实例是否插入了初始密码，以决定是否输出一次性初始凭证。服务账号使用批量 upsert，不依据 RowsAffected 判断具体新增项：批量语句只返回汇总值，并发执行时无法据此确定每个名称由哪个实例插入。

前提只有一个：唯一索引必须真的生效。用户表没问题（(tenant_id, username) 一直在工作），问题出在方法表。

MySQL 唯一索引中的 NULL

user_auth_methods 的唯一索引是 (method_type, identity_provider_id, external_user_id)。原方案为没有外部身份源的 local 密码方法写入 NULL。用两行 SQL 就能看到后果：

1
2
3
4

INSERT INTO user_auth_methods (method_type, identity_provider_id, external_user_id)
VALUES ('local', NULL, '');  -- 成功
INSERT INTO user_auth_methods (method_type, identity_provider_id, external_user_id)
VALUES ('local', NULL, '');  -- 依然成功！唯一索引没有拦截

原因：MySQL（遵循 SQL 标准）认为 NULL 不等于 NULL——唯一索引中任何一列为 NULL，整行都不参与判重，索引因此失效。这就是双副本冒烟中两条 local 方法并存的原因（MySQL 官方文档对这一行为的说明见参考链接）。

修复索引有几个候选：

• UNIQUE(user_id, method_type)，不可行。 它假设一个用户每种方法只有一个，但 passkey 是典型的多设备多凭证（手机一个、笔记本一个），这个索引会误伤未来的合法业务。
• 生成列做部分唯一索引。 MySQL 支持（IF(method_type='local', user_id, NULL) 加唯一索引，利用“NULL 不判重”反向构造，只有 local 行参与判重），方案精确，但引入方言化的 schema 复杂度——和避开方言的目标相矛盾。
• 写 0 而不是 NULL（最终选择）。无身份源的方法把 identity_provider_id 存为 0，列定义同步调整为 NOT NULL DEFAULT 0，索引对所有方法类型生效。配套约定 external_user_id 的取值：local/totp 写 user_id 字符串（天然全局唯一，避开跨租户同名用户的碰撞），passkey 写 credential_id。

批量初始化服务账号

服务账号列表先排序、去重，再通过多行 upsert 分批写入。排序使并发副本按相同顺序获取唯一索引锁；分批限制单条 SQL 的大小，GORM 在当前配置下用事务包裹多个批次。

同一批可以同时包含已有账号和新增账号：已有名称命中 (tenant_id, username) 唯一索引后保持不变，新增名称被插入。新旧版本副本并行启动时，数据库终态是原有集合与各版本配置集合的并集。启动配置只负责增量预创建，不负责更新、禁用、重命名或删除已有账号。

写入完成后按租户和名称批量回读，确认所有配置名称都存在且 type=service_account。若名称已被自然人用户占用，bootstrap 返回配置冲突，不修改已有用户。

最终方案与验证

• store 层为管理员和认证方法提供单行 IfAbsent 方法，用 RowsAffected 判断是否由本实例插入：

  1 2 3 4 5 6 7

  func (s *Store) CreateUserIfAbsent(ctx context.Context, user *User) (bool, error) { tx := s.db.WithContext(ctx).Clauses(clause.OnConflict{DoNothing: true}).Create(user) if tx.Error != nil { return false, fmt.Errorf("failed to create user if absent: %w", translateErr(tx.Error)) } return tx.RowsAffected == 1, nil }

• service account 使用批量 IfAbsent 方法，不返回逐行创建结果；bootstrap 在批量回读验证后记录聚合的 ensured 日志；

• bootstrap 初始化使用 upsert：管理员插入后按唯一键回读，无论输赢都拿到最终状态；local 方法按 identity_provider_id=0、external_user_id=user_id 字符串写入；

• 验证覆盖单行 IfAbsent、服务账号批量新增与重复执行、新旧列表增量合并、名称类型冲突，以及双副本启动终态。

什么时候仍然需要锁

锁并非在所有场景都不适用，只是在这个场景被更合适的工具取代了。如果未来出现这些初始化任务，锁（或事务）会回来：

• 跨多行、多表的原子初始化（无法归结为单行唯一约束）；
• 无法建立唯一索引的场景（如按时间窗、按条件去重）；
• 需要“全局只许一个实例执行”的运维动作（如全库数据回填）。

其中“全局只许一个实例执行”在分布式系统中本质上是共识问题，DDIA 第 10 章《一致性与共识》讨论了在故障存在时如何通过共识算法实现这一点（参考：DDIA 第 10 章）。

原则是：能用唯一约束把正确性交给数据库的，就不要自己拿锁。悲观锁可以快速建立正确性基线，但基线成立之后，仍值得回头找一个不依赖它的方案。

参考链接

• MySQL Locking Functions: GET_LOCK() — MySQL Documentation
• MySQL CREATE INDEX: UNIQUE 索引与 NULL — MySQL Documentation
• golang-migrate/migrate — GitHub
• GORM: Upsert / On Conflict — GORM Guides

推荐阅读

• DDIA（第二版）第 9 章：分布式系统的麻烦——系统梳理网络延迟、时钟偏移、进程暂停等部分失效问题，以及分布式锁与租约的失效模式（含隔离令牌 fencing token），是本文悲观锁失败模型一节的理论背景。
• DDIA（第二版）第 10 章：一致性与共识——讨论线性一致性与共识算法，即在故障存在时如何让分布式系统对外表现得像单一可靠系统，是「全局只许一个实例执行」这一类需求的理论基础。