go-backend-handbook 1.0.1 → 1.0.2

package/03-concurrency.md

@@ -291,3 +291,5 @@ for i := 0; i < 10; i++ {
 9. goroutine 永远阻塞无法退出，导致内存/句柄上涨。例：向无人接收的无缓冲 channel 发送；`select` 没有 `ctx.Done()` 分支。
 10. Value 无类型安全、隐式依赖、难追踪；业务参数应显式作为函数参数。
 </details>
+
+> 生产环境里的并发批量加载、信号量、不可变快照和可取消分批处理，见[第 20 章](20-production-patterns.md)。

package/08-api-and-rpc.md

@@ -197,3 +197,5 @@ for i := 0; i < 3; i++ {
 9. 对外/浏览器用 HTTP/JSON；内网高性能强契约用 gRPC；需要流式用 gRPC。
 10. 鉴权与越权、参数校验、幂等、超时限流、错误码与文档、脱敏、兼容性。
 </details>
+
+> 服务启动、拦截器链和依赖注入的完整骨架，见[第 20 章](20-production-patterns.md)。

package/09-observability.md

@@ -173,3 +173,5 @@ func Trace(next http.Handler) http.Handler {
 9. 使用本地缓存+默认值继续服务，降级而不是崩溃。
 10. 指标发现异常接口 → trace 找慢 span → 日志看该 trace 的参数和错误。
 </details>
+
+> 日志、指标、追踪如何一起接入，见[第 20 章](20-production-patterns.md#209-模式七配置日志指标一起设计)。

package/12-testing.md

@@ -185,3 +185,5 @@ e2e:         { script: [bash scripts/e2e.sh] }
 9. gofmt、vet、staticcheck、单测（-race）、集成、E2E、构建。
 10. 能复现该 bug 的回归测试，先红后绿。
 </details>
+
+> 可测试的并发模式与对应测试，见[第 20 章](20-production-patterns.md)。

package/20-production-patterns.md

@@ -0,0 +1,570 @@
+# 第 20 章 从生产代码提取可复用模式（脱敏版）
+
+> 目标：把真实服务里反复出现的工程写法，提炼成可以直接搬进自己项目的模式。
+> **本章所有代码都经过脱敏改写**：模块名、包路径、业务名词、接口、表名、域名、账号全部替换为虚构的 `mini-coin` 项目。它们保留的是结构与设计意图，不是任何真实业务实现。
+
+---
+
+## 20.1 为什么不能直接抄生产代码
+
+真实代码里混着四类东西：
+
+| 类别 | 例子 | 风险 |
+|---|---|---|
+| 身份标识 | 公司名、团队名、服务名、模块路径 | 泄露组织信息 |
+| 业务语义 | 产品名、业务标签、表名、字段名、状态码 | 泄露业务设计 |
+| 基础设施 | 内网域名、IP、端口、账号、证书 | 被直接利用 |
+| 数据 | 用户 ID、订单号、金额、日志样本 | 隐私和合规问题 |
+
+脱敏不是"把密码换成 `***`"，而是**把整段上下文替换成一个自洽的虚构项目**，让代码还能运行、还能讲清楚设计。
+
+---
+
+## 20.2 脱敏方法论
+
+按这个顺序改，改完再扫描一遍：
+
+1. **换模块名**：`module example.com/minicoin`
+2. **换包路径**：所有 import 改成虚构路径
+3. **换业务名词**：账户 → `account`，订单 → `recharge_order`，用户 → `uid`
+4. **换接口**：只保留方法形状，路径和字段全部重写
+5. **换基础设施**：域名统一 `example.com`，地址统一 `127.0.0.1`
+6. **换数据**：所有 ID、金额、时间都换成手工构造的样例
+7. **删掉**：真实日志、监控面板 ID、工单号、告警群、内部文档链接
+8. **扫描验证**：用关键词 + 正则 + 人工复核
+
+### 扫描命令
+
+```bash
+grep -rInE '公司名|内部域名|内网IP|token|password|secret' .
+grep -rInE '\b(10|172\.(1[6-9]|2[0-9]|3[01])|192\.168)\.[0-9]+\.[0-9]+' .
+grep -rInE '[A-Za-z0-9_-]{32,}' .   # 可疑长串，人工确认是不是密钥
+```
+
+扫描只能发现"你想到的词"，所以最后一步永远是**人工通读**。
+
+---
+
+## 20.3 模式一：服务启动与优雅退出
+
+一个生产级 Go 服务启动通常按这个顺序：
+
+```text
+解析配置 → 初始化日志 → 初始化存储 → 初始化 tracer
+→ 初始化下游客户端 → 初始化业务服务
+→ 监听端口 → 注册拦截器 → 启动 HTTP 辅助端口
+→ 等待信号 → 优雅关闭
+```
+
+脱敏后的骨架：
+
+```go
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"net"
+	"net/http"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"example.com/minicoin/internal/config"
+	"example.com/minicoin/internal/logging"
+	"example.com/minicoin/internal/service"
+)
+
+func main() {
+	configPath := flag.String("c", "config/dev.json", "config file path")
+	flag.Parse()
+
+	cfg, err := config.Load(*configPath)
+	if err != nil {
+		panic(err)
+	}
+	if err := logging.Init(cfg.Log); err != nil {
+		panic(err)
+	}
+
+	svc, err := service.New(cfg)
+	if err != nil {
+		panic(err)
+	}
+	defer svc.Close()
+
+	lis, err := net.Listen("tcp", cfg.GRPCAddr)
+	if err != nil {
+		panic(err)
+	}
+
+	grpcServer := newGRPCServer(cfg, svc.GRPCAddress())
+	httpServer := newAuxHTTPServer(cfg)
+
+	go func() {
+		if err := httpServer.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			logging.Error("aux http server stopped", "err", err)
+		}
+	}()
+
+	go func() {
+		if err := grpcServer.Serve(lis); err != nil {
+			logging.Error("grpc server stopped", "err", err)
+		}
+	}()
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+	<-ctx.Done()
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	// 先停止接收新请求，再关闭辅助 HTTP 服务。
+	grpcServer.GracefulStop()
+	_ = httpServer.Shutdown(shutdownCtx)
+	svc.Close()
+}
+```
+
+要记住的三件事：
+
+1. **初始化顺序有依赖**：日志要在最前面，业务服务最后；
+2. **每个资源都要有 `Close`**，用 `defer` 兜底；
+3. **优雅退出要有超时**：先停止接收新请求，再等在途请求结束，最后强杀。
+
+> **JS 类比**：像 `process.on('SIGTERM')` 里先 `server.close()` 再 `process.exit()`。区别是 Go 里连接、协程、后台任务都要自己收尾。
+
+---
+
+## 20.4 模式二：拦截器链
+
+gRPC 的拦截器类似 Express 中间件，负责横切关注点：
+
+```go
+server := grpc.NewServer(
+	grpc.ChainUnaryInterceptor(
+		recoveryInterceptor,   // panic 兜底
+		metricsInterceptor,    // 指标
+		tracingInterceptor,    // 链路追踪
+		loggingInterceptor,    // 访问日志
+	),
+)
+```
+
+顺序很重要：
+
+```text
+先 recovery（最外层兜底）
+再 metrics（统计耗时）
+再 tracing（建立 span）
+最后 logging（记录业务字段）
+```
+
+**为什么 recovery 放最外层？** 内层中间件 panic 时，外层才能接住。
+
+一个最小 recovery 拦截器：
+
+```go
+func recoveryInterceptor(
+	ctx context.Context,
+	req any,
+	info *grpc.UnaryServerInfo,
+	handler grpc.UnaryHandler,
+) (resp any, err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			logging.Error("panic in handler",
+				"method", info.FullMethod,
+				"panic", r,
+				"stack", string(debug.Stack()),
+			)
+			err = status.Error(codes.Internal, "internal error")
+		}
+	}()
+	return handler(ctx, req)
+}
+```
+
+**它包不住子协程。** handler 里 `go func(){ ... }()` 的 panic 必须自己 recover，见 20.8。
+
+---
+
+## 20.5 模式三：并发批量加载（保持顺序 + 限制并发）
+
+需求：一次查 30 个账户的汇总，串行太慢，全部并发又怕打爆下游。
+
+错误写法：
+
+```go
+for _, key := range keys {
+	go load(key)          // 并发无上限
+}
+```
+
+正确写法在 `code/mini-coin/internal/patterns/batch.go`：
+
+```go
+func LoadBatch[T any](
+	ctx context.Context,
+	keys []string,
+	concurrency int,
+	load LoadFunc[T],
+) ([]T, error) {
+	results := make([]T, len(keys))
+	errs := make([]error, len(keys))
+	sem := make(chan struct{}, concurrency)
+
+	var wg sync.WaitGroup
+	for i, key := range keys {
+		i, key := i, key
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+
+			select {
+			case sem <- struct{}{}:
+				defer func() { <-sem }()
+			case <-ctx.Done():
+				errs[i] = ctx.Err()
+				return
+			}
+
+			value, err := load(ctx, key)
+			if err != nil {
+				errs[i] = err
+				return
+			}
+			results[i] = value
+		}()
+	}
+	wg.Wait()
+
+	for _, err := range errs {
+		if err != nil {
+			return nil, err
+		}
+	}
+	return results, nil
+}
+```
+
+四个关键点：
+
+| 设计 | 作用 |
+|---|---|
+| 预分配 `results` | 每个协程写自己的下标，**不需要锁** |
+| 带缓冲 channel 当信号量 | 限制同时访问下游的数量 |
+| `errs` 也预分配 | 多个失败不会互相覆盖 |
+| 结束后按顺序检查 `errs` | 返回"输入顺序下第一个错误"，结果可预测 |
+
+### 信号量 vs 固定 worker pool
+
+```text
+信号量：为每个 key 开一个 goroutine，只有 N 个能往下走
+worker pool：只开 N 个 goroutine，循环从 jobs 取任务
+```
+
+| | 信号量 | worker pool |
+|---|---|---|
+| 协程总数 | 等于任务数 | 固定 N 个 |
+| 内存开销 | 任务多时线性增长 | 恒定 |
+| 实现复杂度 | 简单 | 稍复杂 |
+| 适合 | 几十到几百个任务 | 几万条数据、批量任务 |
+
+**任务数量没有上限时，用 worker pool；任务数量有明确上界时，信号量更简单。**
+
+---
+
+## 20.6 模式四：不可变快照替代读写锁
+
+配置、字典、规则列表这类数据：
+
+- 读非常频繁；
+- 写很少（定时刷新）；
+- 允许短暂最终一致。
+
+如果每次读都加 `RWMutex`，读多时锁竞争仍然存在。更好的方案是**整份快照原子替换**：
+
+```go
+type Snapshot struct {
+	Version int64
+	Entries map[string]string
+}
+
+type SnapshotStore struct {
+	value atomic.Value // *Snapshot
+}
+
+func (s *SnapshotStore) Load() *Snapshot {
+	v, ok := s.value.Load().(*Snapshot)
+	if !ok {
+		return nil
+	}
+	return v
+}
+
+func (s *SnapshotStore) Store(next *Snapshot) {
+	s.value.Store(next)
+}
+```
+
+刷新流程：
+
+```text
+查询数据 → 构造完整新快照 → 原子 Store
+```
+
+**铁律：Store 之后绝不能再修改 `Entries`。**
+
+因为读方拿到的就是这份 map，你原地改它，读方会在无锁状态下看到半更新数据，甚至触发并发读写 panic。
+
+> **JS 类比**：React/Redux 里"不要原地改 state，构造新对象再替换引用"。思路一样。
+
+失败时怎么办？
+
+```text
+查询失败 → 不发布半成品，保留旧快照
+查询为空 → 发布空快照（表示数据确实被清空）
+```
+
+这两种情况必须区分，否则"下游挂了"会被误判成"数据全没了"。
+
+---
+
+## 20.7 模式五：上下文感知的分批处理
+
+刷数据、迁移、回填，最怕两件事：
+
+1. 一批太大，锁表或主从延迟爆炸；
+2. 上游取消了，任务还在傻跑。
+
+`DrainPages` 把两件事一起解决：
+
+```go
+func DrainPages(
+	ctx context.Context,
+	delay time.Duration,
+	next func(context.Context) (PageResult, error),
+) error {
+	for {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+
+		page, err := next(ctx)
+		if err != nil {
+			return err
+		}
+		if page.Rows == 0 {
+			return nil
+		}
+
+		if delay > 0 {
+			timer := time.NewTimer(delay)
+			select {
+			case <-ctx.Done():
+				timer.Stop()
+				return ctx.Err()
+			case <-timer.C:
+			}
+		}
+	}
+}
+```
+
+要点：
+
+- **每批之前检查 `ctx.Err()`**；
+- **批间等待用 `select` 而不是 `time.Sleep`**，否则取消后还要睡完；
+- **`timer.Stop()`** 防止 timer 泄漏；
+- **`Rows == 0` 是唯一的正常结束条件**。
+
+用的时候：
+
+```go
+err := patterns.DrainPages(ctx, 50*time.Millisecond,
+	func(ctx context.Context) (patterns.PageResult, error) {
+		return backfillOnePage(ctx, 1000)
+	})
+```
+
+---
+
+## 20.8 模式六：子协程 panic 保护
+
+gRPC 的 recovery 拦截器只包住 handler 主调用链：
+
+```go
+func (s *Server) Handler(ctx context.Context, req *pb.Req) (*pb.Resp, error) {
+	go func() {
+		panic("boom")   // ❌ 整个进程退出
+	}()
+	return &pb.Resp{}, nil
+}
+```
+
+正确做法：
+
+```go
+func SafeGo(handler PanicHandler, fn func()) {
+	go func() {
+		defer func() {
+			if r := recover(); r != nil {
+				handler(r, debug.Stack())
+			}
+		}()
+		fn()
+	}()
+}
+```
+
+使用：
+
+```go
+patterns.SafeGo(func(r any, stack []byte) {
+	logging.Error("panic in background goroutine", "panic", r, "stack", string(stack))
+	metrics.BackgroundPanicTotal.Inc()
+}, func() {
+	doWork()
+})
+```
+
+`recover` 必须写在**发生 panic 的那个 goroutine 的 defer 里**，外层协程 recover 不到内层。
+
+---
+
+## 20.9 模式七：配置、日志、指标一起设计
+
+一个请求出问题时，你需要三样东西：
+
+| 工具 | 回答的问题 |
+|---|---|
+| 日志 | 这一次请求发生了什么 |
+| 指标 | 整体是不是变慢了、错多了 |
+| 链路追踪 | 慢在哪一跳、跨了哪些服务 |
+
+最小接入：
+
+```go
+// 日志：结构化，能按字段检索
+logging.Info("recharge created",
+	"request_id", requestID,
+	"uid", uid,
+	"amount", amount,
+	"cost_ms", cost.Milliseconds(),
+)
+
+// 指标：可聚合、可报警
+rechargeTotal.WithLabelValues("success").Inc()
+rechargeDuration.Observe(cost.Seconds())
+
+// 追踪：把 request_id 放进 span，跨服务传递
+span, ctx := opentracing.StartSpanFromContext(ctx, "create_recharge")
+defer span.Finish()
+```
+
+**三者的字段名要对齐**：日志里的 `request_id`、指标标签、trace 的 tag 用同一个名字，排障时才能串起来。
+
+---
+
+## 20.10 模式八：依赖注入，而不是到处 import 单例
+
+不推荐：
+
+```go
+func (s *Service) Recharge(ctx context.Context, req *Req) error {
+	// 直接依赖全局变量
+	return globalDB.Exec(...)
+}
+```
+
+推荐：
+
+```go
+type Repository interface {
+	CreateOrder(ctx context.Context, order Order) error
+	GetAccount(ctx context.Context, uid string) (Account, error)
+}
+
+type Service struct {
+	repo     Repository
+	clock    Clock
+	metrics  *Metrics
+}
+
+func NewService(repo Repository, clock Clock, metrics *Metrics) *Service {
+	return &Service{repo: repo, clock: clock, metrics: metrics}
+}
+```
+
+好处：
+
+- 测试时替换成内存实现，不用连真实数据库；
+- 依赖关系显式，读代码就知道它依赖什么；
+- 不会出现"跑单测还要起一整套中间件"。
+
+---
+
+## 20.11 脱敏后的完整代码在哪
+
+本章的可运行代码在：
+
+```text
+code/mini-coin/internal/patterns/
+├── batch.go
+├── snapshot.go
+├── drain.go
+├── safego.go
+└── patterns_test.go
+```
+
+运行：
+
+```bash
+cd code/mini-coin
+go test ./internal/patterns -v
+go test ./... -race     # 建议在 CI 或新容器里跑
+```
+
+这些代码全部是虚构的，但结构直接来自生产实践：信号量限流、预分配槽位、按输入顺序返回错误、不可变快照、可取消的分批处理、子协程 panic 保护。
+
+---
+
+## 20.12 习题
+
+### 🟢 基础题
+
+**1.** `LoadBatch` 为什么不需要给 `results` 加锁？
+
+**2.** 为什么 `DrainPages` 的批间等待不能直接用 `time.Sleep`？
+
+**3.** `Snapshot.Store` 之后为什么不能再修改 `Entries`？
+
+### 🟡 动手题
+
+**4.** 给 `LoadBatch` 加一个"并发上限必须 ≥ 1"的校验，并写测试验证 `concurrency = 0` 时的行为。
+
+**5.** 把 `DrainPages` 改造成"最多处理 N 页就停"的版本，并补测试。
+
+**6.** 用 `httptest` 模拟一个会 panic 的后台任务，验证 `SafeGo` 能捕获 panic 且不影响主进程。
+
+### 🔴 综合题
+
+**7.** 用 `LoadBatch` 实现"批量查 100 个账户余额，最多 8 个并发，任一失败返回错误"，并写表驱动测试覆盖：全部成功、部分失败、上下文取消三种情况。
+
+**8.** 给 `SnapshotStore` 写一个并发测试：一个 goroutine 持续 `Store`，多个 goroutine 持续 `Load`，在 `-race` 下运行应无数据竞争。
+
+---
+
+## 20.13 参考答案要点
+
+1. 每个 goroutine 只写 `results[i]`，下标互不相同，是不同的内存位置，不需要同步。
+2. `time.Sleep` 无法被取消，上游超时后还要睡完；应该用 `select` 同时监听 `ctx.Done()` 和 timer。
+3. 读方无锁直接使用 map；原地修改会让读方看到半更新状态，并发读写还会 panic。正确做法是构造新 map 再整体替换。
+4. 在函数开头把 `concurrency <= 0` 归一到 1，并用测试断言不会死锁、结果正确。
+5. 增加 `maxPages` 参数，每处理一页递减，到 0 返回 `nil`。
+6. `SafeGo` 内部 `defer recover`，handler 里 `close(done)`，测试用 `select` 等待。
+7. 用 `LoadBatch` 包装查询函数；错误顺序按输入下标检查；取消场景用 `context.WithCancel`。
+8. 写测试时用 `sync.WaitGroup` 起读写协程，在 CI 里跑 `go test -race`。

package/README.md

@@ -70,6 +70,7 @@
 | [17](17-deploy-ops.md) | 部署与运维 | Docker/K8s/Nginx/云/发布回滚 |
 | [18](18-ai-assisted.md) | AI 辅助后端开发 | 用 AI 提效但不挖坑 |
 | [19](19-appendix.md) | 附录：容量估算与速查表 | 面试/评审能用的数字 |
+| [20](20-production-patterns.md) | 从生产代码提取可复用模式（脱敏版） | 服务启动、拦截器、批量并发、快照、分批处理、SafeGo |
 
 习题与答案：每章末尾有「习题」与「参考答案」。完整代码见 [`code/mini-coin`](code/mini-coin)。
 

package/code/mini-coin/internal/patterns/batch.go

@@ -0,0 +1,79 @@
+// Package patterns 收录生产服务里反复出现的并发、生命周期与发布模式。
+// 本包全部是教学用的虚构代码，不含任何真实业务标识。
+package patterns
+
+import (
+	"context"
+	"fmt"
+	"sync"
+)
+
+// LoadFunc 定义单个 key 的加载函数。
+type LoadFunc[T any] func(ctx context.Context, key string) (T, error)
+
+// LoadBatch 并发加载多个 key，并保持结果与输入顺序一致。
+//
+//   - 最多 concurrency 个加载同时执行，用带缓冲 channel 当信号量；
+//   - 每个 goroutine 只写自己的下标，不需要加锁；
+//   - 所有任务结束后，按输入顺序返回第一个错误。
+//
+// 注意：函数会为每个 key 创建一个 goroutine。key 数量特别大时，
+// 应改用固定 worker pool，而不是只靠信号量限制并发。
+func LoadBatch[T any](
+	ctx context.Context,
+	keys []string,
+	concurrency int,
+	load LoadFunc[T],
+) ([]T, error) {
+	results := make([]T, len(keys))
+	if len(keys) == 0 {
+		return results, nil
+	}
+	if concurrency <= 0 {
+		concurrency = 1
+	}
+	if concurrency > len(keys) {
+		concurrency = len(keys)
+	}
+
+	errs := make([]error, len(keys))
+	sem := make(chan struct{}, concurrency)
+	var wg sync.WaitGroup
+
+	for i, key := range keys {
+		i, key := i, key
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+
+			select {
+			case sem <- struct{}{}:
+				defer func() { <-sem }()
+			case <-ctx.Done():
+				errs[i] = ctx.Err()
+				return
+			}
+
+			if err := ctx.Err(); err != nil {
+				errs[i] = err
+				return
+			}
+
+			value, err := load(ctx, key)
+			if err != nil {
+				errs[i] = fmt.Errorf("load %q: %w", key, err)
+				return
+			}
+			results[i] = value
+		}()
+	}
+
+	wg.Wait()
+
+	for _, err := range errs {
+		if err != nil {
+			return nil, err
+		}
+	}
+	return results, nil
+}

package/code/mini-coin/internal/patterns/drain.go

@@ -0,0 +1,50 @@
+package patterns
+
+import (
+	"context"
+	"time"
+)
+
+// PageResult 表示一页的处理结果。
+type PageResult struct {
+	Rows int
+}
+
+// DrainPages 逐页处理数据，支持上下文取消和批间等待。
+//
+// next 每次读取并处理下一批；返回 Rows == 0 表示处理完成。
+// 每批之间等待 delay，避免持续给数据库和从库复制造成压力。
+func DrainPages(
+	ctx context.Context,
+	delay time.Duration,
+	next func(context.Context) (PageResult, error),
+) error {
+	for {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+
+		page, err := next(ctx)
+		if err != nil {
+			return err
+		}
+
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		if page.Rows == 0 {
+			return nil
+		}
+		if delay <= 0 {
+			continue
+		}
+
+		timer := time.NewTimer(delay)
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			return ctx.Err()
+		case <-timer.C:
+		}
+	}
+}

package/code/mini-coin/internal/patterns/patterns_test.go

@@ -0,0 +1,75 @@
+package patterns
+
+import (
+	"context"
+	"errors"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestLoadBatchKeepsOrder(t *testing.T) {
+	keys := []string{"c", "a", "b"}
+	got, err := LoadBatch(context.Background(), keys, 2, func(_ context.Context, key string) (string, error) {
+		return key + "-value", nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"c-value", "a-value", "b-value"}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("index %d: got %q want %q", i, got[i], want[i])
+		}
+	}
+}
+
+func TestLoadBatchReturnsFirstInputError(t *testing.T) {
+	firstErr := errors.New("first")
+	secondErr := errors.New("second")
+	_, err := LoadBatch(context.Background(), []string{"a", "b"}, 2, func(_ context.Context, key string) (string, error) {
+		if key == "a" {
+			return "", firstErr
+		}
+		return "", secondErr
+	})
+	if !errors.Is(err, firstErr) {
+		t.Fatalf("got %v want %v", err, firstErr)
+	}
+}
+
+func TestDrainPagesCanBeCancelledDuringDelay(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+	defer cancel()
+	err := DrainPages(ctx, time.Second, func(context.Context) (PageResult, error) {
+		return PageResult{Rows: 1}, nil
+	})
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("got %v want deadline exceeded", err)
+	}
+}
+
+func TestSnapshotStore(t *testing.T) {
+	store := NewSnapshotStore(&Snapshot{Version: 1, Entries: map[string]string{"a": "1"}})
+	store.Store(&Snapshot{Version: 2, Entries: map[string]string{"a": "2"}})
+	if got := store.Load(); got == nil || got.Version != 2 || got.Entries["a"] != "2" {
+		t.Fatalf("unexpected snapshot: %#v", got)
+	}
+}
+
+func TestSafeGoRecoversPanic(t *testing.T) {
+	var called int32
+	done := make(chan struct{})
+	SafeGo(func(any, []byte) {
+		atomic.StoreInt32(&called, 1)
+		close(done)
+	}, func() { panic("boom") })
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("panic handler was not called")
+	}
+	if atomic.LoadInt32(&called) != 1 {
+		t.Fatal("handler not called")
+	}
+}

package/code/mini-coin/internal/patterns/safego.go

@@ -0,0 +1,23 @@
+package patterns
+
+import "runtime/debug"
+
+// PanicHandler 处理子协程 panic。生产环境应在这里记日志、打点并报警。
+type PanicHandler func(recovered any, stack []byte)
+
+// SafeGo 启动一个带 panic 保护的 goroutine。
+//
+// gRPC 的 recovery interceptor 只包住 handler 主调用链，包不住 handler
+// 内部新开的 goroutine，所以子协程必须自己 recover。
+func SafeGo(handler PanicHandler, fn func()) {
+	go func() {
+		defer func() {
+			if r := recover(); r != nil {
+				if handler != nil {
+					handler(r, debug.Stack())
+				}
+			}
+		}()
+		fn()
+	}()
+}

package/code/mini-coin/internal/patterns/snapshot.go

@@ -0,0 +1,40 @@
+package patterns
+
+import "sync/atomic"
+
+// Snapshot 是一份不可变配置快照。
+//
+// 约定：Store 之后绝不能再修改 Entries。刷新方每次构造一份完整的新快照，
+// 然后整体替换指针；读方拿到的永远是一份自洽的数据。
+type Snapshot struct {
+	Version int64
+	Entries map[string]string
+}
+
+// SnapshotStore 用 atomic.Value 发布不可变快照，读路径无锁。
+type SnapshotStore struct {
+	value atomic.Value // *Snapshot
+}
+
+// NewSnapshotStore 创建快照存储，可以带一份初始快照。
+func NewSnapshotStore(initial *Snapshot) *SnapshotStore {
+	s := &SnapshotStore{}
+	if initial != nil {
+		s.value.Store(initial)
+	}
+	return s
+}
+
+// Load 返回当前快照。没有快照时返回 nil。
+func (s *SnapshotStore) Load() *Snapshot {
+	v, ok := s.value.Load().(*Snapshot)
+	if !ok {
+		return nil
+	}
+	return v
+}
+
+// Store 原子发布一份新快照。调用方必须先构造完整快照，发布后不得再修改。
+func (s *SnapshotStore) Store(next *Snapshot) {
+	s.value.Store(next)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "go-backend-handbook",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Go 后端开发全景讲义：语言、并发、数据库、缓存、消息队列、gRPC、监控告警、测试、性能、安全、部署与完整开发流程",
   "keywords": [
     "go",