Go on 姚玉亮的网络日志

基于 pond 的 goroutine 池在文档向量化中的应用

Fri, 23 May 2025 10:30:00 +0800

一个 for 循环，几千个 goroutine

数据集管理服务里，一个数据集可能有上千份文档，每份文档切出几十到上百个 chunk，每个 chunk 都要调一次 embedding 接口。最朴素的写法是 for 循环里直接 go func()。结果可以想象：几千个 goroutine 同时打向远程 embedding 服务，对方 QPS 瞬间被打满，自己内存也跟着暴涨，错误没法统一收集，想取消也停不下来。

我们需要的就是一个有上限、能等结果、能感知 context 取消的池。手写 worker channel 试过，errgroup 也试过，最后在数据集管理服务里用了 pond（github.com/alitto/pond）。倒不是它有什么魔法，主要是 API 简洁，池大小、任务队列、等待、错误聚合都内置了。

两级并发，两个池

向量化天然是两级并发：文档级和 chunk 级。我们干脆用两个 pond 池隔离开，免得两层的 goroutine 互相争抢。

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


type Vectorizer struct {
 docPool *pond.Pool // 文档级，控制同时处理的文档数
 chunkPool *pond.Pool // chunk 级，控制 embedding 并发
 client EmbeddingClient
}

func NewVectorizer(client EmbeddingClient) *Vectorizer {
 return &Vectorizer{
 // 文档级并发较低，主要受 IO 和内存限制
 docPool: pond.New(8, 1000),
 // chunk 级并发受 embedding 服务 QPS 限制
 chunkPool: pond.New(32, 5000),
 client: client,
 }
}

单文档内的 chunk 向量化，用 pond 的 Submit 分发，Wait 等所有 chunk 干完：

 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 (v *Vectorizer) embedChunks(ctx context.Context, chunks []*Chunk) ([]*VectorChunk, error) {
 results := make([]*VectorChunk, len(chunks))
 var firstErr error
 var mu sync.Mutex

 group := pool.Group()
 for i, c := range chunks {
 i, c := i, c
 group.Submit(func() {
 vec, err := v.client.Embed(ctx, c.Text)
 if err != nil {
 mu.Lock()
 if firstErr == nil {
 firstErr = err
 }
 mu.Unlock()
 return
 }
 results[i] = &VectorChunk{Chunk: c, Vector: vec}
 })
 }
 group.Wait()
 return results, firstErr
}

批量处理文档时，外层由 docPool 控并发，每份文档内部再用 chunkPool。两层池的容量按下游 embedding 服务的限流配额来定：chunk 池大小不超过服务允许的并发数，从源头就不给它触发限流的机会。

需要有序结果的场景，按索引写 results[i]。goroutine 谁先跑完无所谓，最终切片照样和输入对齐。

六个坑

先说 panic。pond 默认会 recover 任务里的 panic，进程不会挂，但有个副作用：panic 信息容易被吞。所以每个任务里我们又加了一层自己的 recover，把 stack 记到 Zap 日志，空指针这类问题才有得查。

容量别跟 CPU 核数挂钩。embedding 是 IO 密集型，goroutine 大部分时间在等网络，池大小应该按下游配额和 P95 延迟算，照着 runtime.NumCPU() 定没有道理。我们用 32，是因为 embedding 服务单 key 的并发上限大概就在这个量级。

context 一定要传进去。批量任务跑到一半，用户取消了或者某个文档失败了，剩下的任务得能停下来。pond v2 的 Group 支持绑定 context，取消后没开始的任务不再执行；正在跑的任务靠我们传进去的 ctx 感知取消，对应的 HTTP 请求也会中断。

错误这块我们改过一版。早期只返回 firstErr，结果一批里有几十个 chunk 失败，日志里只看得见一个错误，排查时误以为是个例。现在失败计数和前几条错误摘要都进日志，监控上对着失败比例告警。

还有个 Go 的经典老坑：闭包捕获循环变量。results 切片在 Submit 前一次性分配好，这个做法本身没问题；但 Go 1.22 之前循环变量会被复用，goroutine 里必须 i, c := i, c 拷贝一份。

最后是池的生命周期。Vectorizer 在服务启动时创建、关闭时 pool.Stop().Wait() 停掉。别每个请求都 pond.New，建池有开销，复用的意义也就没了。

回头看

向量化是典型的高并发 IO 场景，关键不在"起更多 goroutine"，而在把并发数压到下游能承受的范围内。pond 用很小的 API 成本提供了池化、等待、错误聚合和 context 取消，比手写 channel 加 WaitGroup 省心。数据集管理服务用的就是文档级、chunk 级两个池，吞吐保住了，embedding 服务也没被打垮。

封面图：gliak00 / Flickr · CC BY-SA 2.0

Go 事务通过 Context 透传由 DAO 层感知的设计

Fri, 30 Aug 2024 10:30:00 +0800

把 tx 当参数传，签名全毁了

统一认证中心的 Service/DAO 分层里，多表原子写躲不掉：创建应用要同时写 apps、app_credentials、audit_logs；给用户授权要写 user_roles 和 role_permissions 快照。少写哪张都不行。

最直接的写法是 Service 层开 db.Transaction(func(tx *gorm.DB) error { ... })，把 tx 当参数往下传给 DAO。能用，但 DAO 方法签名全得带上 tx *gorm.DB，和普通查询混在一起很难看；嵌套调用一多，代码里到处是 tx 透传。我想要的是：DAO 签名保持干净，自己知道"现在在不在事务里"。

把事务塞进 Context

思路是让 context.Context 顺路把事务句柄带下去。Service 开事务时把 tx 放进 ctx，DAO 从 ctx 取：取到就用 tx，取不到就用默认 db。DAO 签名只需要 ctx context.Context，跟普通 RPC 风格一致。

具体拆成两个小件。TxManager 提供 WithTx(ctx, fn)：内部 db.WithContext(ctx).Transaction 开事务，tx 存进 ctx，fn 成功就提交，出错或 panic 就回滚。DAO 侧一个 GetDB(ctx) 辅助函数，优先从 ctx 捞事务句柄。为了类型安全，context key 用自定义类型，不用字符串。

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


type ctxKey struct{}
var txKey = ctxKey{}

type TxManager struct {
 db *gorm.DB
}

func (m *TxManager) WithTx(ctx context.Context, fn func(ctx context.Context) error) error {
 return m.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 txCtx := context.WithValue(ctx, txKey, tx)
 return fn(txCtx)
 })
}

// GetDB 从 ctx 提取事务句柄，没有事务则用默认 db
func GetDB(ctx context.Context, def *gorm.DB) *gorm.DB {
 if tx, ok := ctx.Value(txKey).(*gorm.DB); ok && tx != nil {
 return tx.WithContext(ctx)
 }
 return def.WithContext(ctx)
}

DAO 使用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


type AppDAO struct {
 db *gorm.DB
}

func (d *AppDAO) Create(ctx context.Context, app *App) error {
 return GetDB(ctx, d.db).Create(app).Error
}

func (d *AppDAO) CreateCredential(ctx context.Context, cred *AppCredential) error {
 return GetDB(ctx, d.db).Create(cred).Error
}

Service 组合：

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


func (s *AppService) CreateApp(ctx context.Context, req CreateAppReq) (int64, error) {
 appID, _ := s.sf.NextID()
 err := s.txm.WithTx(ctx, func(ctx context.Context) error {
 if err := s.appDAO.Create(ctx, &App{ID: appID, Name: req.Name}); err != nil {
 return err
 }
 if err := s.appDAO.CreateCredential(ctx, &AppCredential{
 AppID: appID, AppSecret: hashSecret(req.Secret),
 }); err != nil {
 return err
 }
 return s.auditDAO.Log(ctx, "app.create", appID)
 })
 return appID, err
}

坑都在事务边界外

GORM 的 Transaction 回调里 panic 会被 recover 并回滚，但 recover 管不到别的 goroutine：fn 里起了 goroutine，它的 panic 不会触发回滚，而且它拿着的 ctx 还指向原来的 tx，那时事务可能已经提交或回滚了。所以事务内别把 ctx 传给异步任务，异步用 context.Background() 另起。

嵌套调 WithTx 是可以的，GORM 基于 savepoint 实现嵌套事务。但内层回滚只回到 savepoint，不会连累外层整体回滚；内层的 error 要是被吞了，外层照样提交。error 老老实实 return 上去。

还有几条小的。*gorm.DB 别长期存在结构体里跨请求复用，GORM 的 Session 机制会复用语句状态；每次从 ctx 取出来后调一下 WithContext(ctx) 是安全的。

这套模式也有代价：事务边界隐式藏在 ctx 里，新人读代码看不出某个 DAO 调用在不在事务中。我们靠 Code Review 把关，Service 方法注释里标明事务边界。

至于"context 该不该携带请求范围之外的数据"这个老争论：事务句柄确实是请求范围内的，又需要跨层透传，这个场景用 ctx 比把 tx 塞进每个方法签名实用。我站 ctx 这边。

后来

Context 透传事务之后，DAO 层保持只依赖 ctx 的干净签名，Service 用 WithTx 把业务逻辑一包，原子性就有了。配合 GORM 自带的 savepoint 嵌套事务，统一认证中心里大部分多表写操作都走这套模式，可读性和可测试性都比手动透传 tx 强。

Wire 依赖注入实战：Service/DAO 分层与接口解耦

Sun, 14 Jul 2024 10:30:00 +0800

main 函数先垮掉

统一认证中心、统一支付平台这些项目刚起步的时候，main 函数没什么讲究：先 new DB，再 new DAO，再 new Service，再 new Controller，一层层往下 new。手写初始化，直观，也够用。

坏在项目会膨胀。构造函数参数越攒越多，依赖关系慢慢织成一张网，改一个底层组件，得顺着构造链改一整圈。单测想 mock 一个 DAO 也痛苦，mock 塞不进构造链。

我想要的其实就两条：把对象的创建和使用分开；保持编译期类型安全。运行时反射那种 DI 我不接受，依赖错了要等启动才炸出来。Google Wire 正好对上这两条。

Wire 管拼装，代码管声明

分层还是老三样：Handler 到 Service 到 DAO。规矩一条：每层依赖下一层的接口，不依赖具体实现。DAO 定义接口，线上跑的是 GormDAO 实现；Service 只认 DAO 接口，测试时想换成什么就换什么。

Wire 这边分工也简单。每个类型怎么构造，用 Provider 函数声明；整张依赖图怎么拼，交给 Injector，编译期生成 wire_gen.go。没有运行时反射，依赖缺了、错了，编译器先说话。

Provider 我们按模块收拢成 ProviderSet，比如 auth 模块的 Service、DAO、Provider 放一个 set，顶层一个 wire.Build 全部汇总。

构造函数直接返回接口

构造函数返回具体类型、上层依赖接口时，得靠 wire.Bind 显式绑一下，多一道手续。我们的做法是让构造函数直接返回接口类型，Bind 基本就用不上了。

单测也不需要 Wire 参与。手写个 mock 塞进构造函数就行：NewUserService(&mockUserDAO{}, &mockSMS{})。

 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


// dao/user_dao.go
type UserDAO interface {
 GetByID(ctx context.Context, id int64) (*User, error)
}

type userDAO struct {
 db *gorm.DB
}

func NewUserDAO(db *gorm.DB) UserDAO {
 return &userDAO{db: db}
}

// service/user_service.go
type UserService struct {
 userDAO dao.UserDAO
 sms SMSProvider
}

func NewUserService(u dao.UserDAO, s SMSProvider) *UserService {
 return &UserService{userDAO: u, sms: s}
}

// wire.go
//go:build wireinject

func InitApp() *App {
 wire.Build(
 NewDB,
 dao.NewUserDAO,
 NewTencentSMSProvider,
 service.NewUserService,
 handler.NewUserHandler,
 NewApp,
 )
 return nil
}

三个坑

第一个是依赖循环。ServiceA 依赖 ServiceB，ServiceB 又间接绕回 ServiceA，Wire 不会帮你绕，直接报错。现在回头看这反而是好事，它逼着我们重新审视分层：把共享逻辑下沉到独立的内部包，或者用接口在同一层解耦。

第二个是接口绑定找不到实现，前面说的"构造函数直接返回接口"就是用来绕开它的。

第三个在 CI。wire_gen.go 必须提交到仓库，不然哪天 CI 环境里没装 wire 命令，编译直接挂。我们在 Makefile 里加了 make wire 步骤，改了 wire.go 手动跑一次生成。

值不值得上

引入 Wire 之后，依赖关系从隐式变成了显式：构造链由生成的代码管着，Service 只依赖接口，单测随便换 mock，编译期检查也比运行时 DI 让人安心。配合 Service/DAO 分层和 ProviderSet 模块化，项目涨到几十个组件，main 函数依然干净。

值不值得为此引一个框架，我的判断看规模：几十个 Service 的中大型项目收益明显；小项目手写初始化可能反而更快，别为了用而用。这套做法后来成了我们团队所有 Go 后端项目的标准做法。

封面图：Unhindered by Talent / Flickr · CC BY-SA 2.0

Excelize 流式导出百万级支付对账数据

Fri, 09 Feb 2024 10:30:00 +0800

导出一次，OOM 一次

统一支付平台每月初要给商户出对账单，大商户一个月的流水能到百万行量级。最早的版本用 excelize.NewFile + SetSheetRow 一行行写，跑一次导出，内存直接吃掉几个 G，OOM 被杀是常事，运营还老过来催：“怎么还没生成好？”

我当时要做的，就是把这个导出改造成稳定跑百万行、内存可控、耗时可接受。选型上我们本来就在用 xuri/excelize，它的 StreamWriter 就是为这种场景设计的。真正的问题不在库，在于整条链路都得改成流式。

读、写、传，全改成流式

核心思路三条：

数据库游标分页读取，用 ID 翻页而不是 OFFSET，避开深分页；
Excelize StreamWriter 按行写入，写完立即刷盘，不在内存里攒所有行；
文件边写边传 S3/MinIO，用 io.Pipe 把 Excelize 的输出直接对接 SDK 的上传流，不落本地磁盘。

再用 goroutine 把"读 DB"和"写 Excel"做成生产者-消费者，通道容量控制在几千行，背压自然形成。

落到代码上

StreamWriter 的基础用法是这样，关键是记得 Flush 结束：

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


f := excelize.NewFile()
defer f.Close()

sw, err := f.NewStreamWriter("Sheet1")
if err != nil {
 return err
}
styleID, _ := f.NewStyle(&excelize.Style{Font: &excelize.Font{Bold: true}})
_ = sw.SetRow("A1", []interface{}{
 excelize.Cell{Value: "订单号", StyleID: styleID},
 excelize.Cell{Value: "交易时间", StyleID: styleID},
 excelize.Cell{Value: "金额", StyleID: styleID},
 excelize.Cell{Value: "手续费", StyleID: styleID},
 excelize.Cell{Value: "状态", StyleID: styleID},
})

生产者按 ID 游标翻页：

 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


func streamOrders(ctx context.Context, db *gorm.DB, merchantID string, month string,
 ch chan<- []Order) error {
 defer close(ch)
 var lastID int64
 const pageSize = 2000
 for {
 var rows []Order
 err := db.WithContext(ctx).
 Where("merchant_id = ? AND month = ? AND id > ?", merchantID, month, lastID).
 Order("id ASC").Limit(pageSize).Find(&rows).Error
 if err != nil {
 return err
 }
 if len(rows) == 0 {
 return nil
 }
 select {
 case ch <- rows:
 case <-ctx.Done():
 return ctx.Err()
 }
 lastID = rows[len(rows)-1].ID
 if len(rows) < pageSize {
 return nil
 }
 }
}

消费者拿到一批就调 SetRow，注意行号要自己维护：

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


rowIdx := 2
for batch := range ch {
 for _, o := range batch {
 cell := []interface{}{
 o.OutTradeNo,
 o.CreatedAt.Format("2006-01-02 15:04:05"),
 o.Amount.StringFixed(2),
 o.Fee.StringFixed(2),
 o.Status,
 }
 cellRef, _ := excelize.CoordinatesToCellName(1, rowIdx)
 if err := sw.SetRow(cellRef, cell); err != nil {
 return err
 }
 rowIdx++
 }
}
if err := sw.Flush(); err != nil {
 return err
}

最关键的一步是边写边传 S3。io.Pipe 把 Write 变成 Reader：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


pr, pw := io.Pipe()
go func() {
 err := f.Write(pw)
 pw.CloseWithError(err)
}()

_, err = s3Client.PutObject(ctx, &s3.PutObjectInput{
 Bucket: aws.String(bucket),
 Key: aws.String(key),
 Body: pr,
})

f.Write(pw) 会在 StreamWriter 刷盘时往 Pipe 里写，S3 SDK 那头并发读，全程磁盘上不产生临时文件。

五个坑

第一，单个 sheet 行数上限。Excel 一个 sheet 最多 1048576 行，写到 100 万行时主动新建 Sheet2、Sheet3，表头重复写一次。StreamWriter 在 sheet 之间切换要先 Flush 旧的再 NewStreamWriter 新的。

第二，时间格式和数字格式。直接写字符串虽然省事，但商户拿到后没法在 Excel 里求和。金额我加了数字格式：

1
2
3


moneyStyle, _ := f.NewStyle(&excelize.Style{NumFmt: 2}) // 0.00
_ = sw.SetColStyle("C", moneyStyle)
_ = sw.SetColStyle("D", moneyStyle)

第三，GORM 的游标内存。即使分页 2000，GORM 默认会把结果映射到结构体切片，只要及时释放引用，GC 能正常回收。但要注意别在循环外持有 rows 的引用，否则整批都不释放。

第四，Pipe 的错误传播。如果 S3 上传失败，pr 会先被关闭，但 f.Write(pw) 那一侧还在写，必须通过 pw.CloseWithError(err) 让它感知到，否则 goroutine 泄漏。生产里我还加了一个 context.AfterFunc 做兜底。

第五，耗时与内存的权衡。4C8G 的 Pod 里测下来，百万行导出稳定在 100MB 内存以内，耗时约 40 秒。想再快，可以按商户分 shard 并行导出多个文件再合并，但运维复杂度上来了，当前规模没必要。

改造之后

改造后对账导出再没 OOM 过，运营也不再追着要文件。回头看，百万行 Excel 导出的关键是整条链路都流式：数据库流式读、Excel 流式写、对象存储流式传，任何一环攒在内存里都会爆。Excelize 的 StreamWriter 已经把最难的 XML 分片写做掉了，应用层只要把生产和消费解耦，加上背压，就能稳定跑下来。

封面图：NYC Wanderer / Flickr · CC BY-SA 2.0

Gin 中间件实战：JWT 认证与请求日志异步落盘 MongoDB

Thu, 23 Nov 2023 10:30:00 +0800

审计日志一条不能丢

宠物医疗 SaaS 的 B/S 版后端需要统一的认证和审计。所有 API 请求都要校验 JWT，把用户和医院上下文提取出来；同时合规要求所有请求日志落盘，请求方法、路径、参数、响应状态码、耗时、操作者，一样不能少，保留半年备查。

同步写日志会拖慢接口响应。日志结构嵌套深、量又大，放 MySQL 里查询和归档都别扭，我选了 MongoDB，通过 channel 异步写，不阻塞主请求。

把身份塞进 Context

JWT 中间件用 golang-jwt/jwt/v5，从 Authorization 头解析 token，校验签名和过期时间，再把用户 ID、医院 ID、角色注入 gin.Context，后面的 handler 直接取用：

 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


type Claims struct {
 UserID int64 `json:"uid"`
 HospID int64 `json:"hid"`
 RoleCode string `json:"rol"`
 jwt.RegisteredClaims
}

func JWTAuth(signingKey []byte) gin.HandlerFunc {
 return func(c *gin.Context) {
 tokenStr := c.GetHeader("Authorization")
 if len(tokenStr) > 7 && tokenStr[:7] == "Bearer " {
 tokenStr = tokenStr[7:]
 }
 if tokenStr == "" {
 c.AbortWithStatusJSON(401, gin.H{"code": 401, "msg": "missing token"})
 return
 }

 claims := &Claims{}
 token, err := jwt.ParseWithClaims(tokenStr, claims, func(t *jwt.Token) (interface{}, error) {
 if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
 return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
 }
 return signingKey, nil
 })
 if err != nil || !token.Valid {
 c.AbortWithStatusJSON(401, gin.H{"code": 401, "msg": "invalid token"})
 return
 }

 c.Set("uid", claims.UserID)
 c.Set("hid", claims.HospID)
 c.Set("rol", claims.RoleCode)
 c.Next()
 }
}

校验的时候要连签名算法一起校验，代码里那个 HMAC 断言就是干这个的，防 alg 混淆攻击。

channel 满了就写文件

日志中间件用 ResponseWriter 包装器捕获响应状态码和响应体大小，通过一个带缓冲 channel 把日志投递给后台 writer。

这里有个和埋点上报不一样的前提。埋点丢几条无所谓，审计日志一条不能丢。所以同样是非阻塞投递，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
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
64
65


type AccessLog struct {
 TraceID string `bson:"trace_id"`
 UserID int64 `bson:"user_id"`
 HospID int64 `bson:"hosp_id"`
 Method string `bson:"method"`
 Path string `bson:"path"`
 Query string `bson:"query"`
 ClientIP string `bson:"client_ip"`
 StatusCode int `bson:"status_code"`
 Latency time.Duration `bson:"latency"`
 ReqSize int `bson:"req_size"`
 RespSize int `bson:"resp_size"`
 ErrMsg string `bson:"err_msg,omitempty"`
 CreatedAt time.Time `bson:"created_at"`
}

type bodyWriter struct {
 gin.ResponseWriter
 size int
}

func (w *bodyWriter) Write(b []byte) (int, error) {
 n, err := w.ResponseWriter.Write(b)
 w.size += n
 return n, err
}

func AccessLogMiddleware(logCh chan<- *AccessLog, fallback *os.File) gin.HandlerFunc {
 return func(c *gin.Context) {
 start := time.Now()
 bw := &bodyWriter{ResponseWriter: c.Writer}
 c.Writer = bw

 c.Next()

 entry := &AccessLog{
 TraceID: c.GetString("trace_id"),
 Method: c.Request.Method,
 Path: c.Request.URL.Path,
 Query: c.Request.URL.RawQuery,
 ClientIP: c.ClientIP(),
 StatusCode: c.Writer.Status(),
 Latency: time.Since(start),
 ReqSize: int(c.Request.ContentLength),
 RespSize: bw.size,
 CreatedAt: start,
 }
 if uid, ok := c.Get("uid"); ok {
 entry.UserID = uid.(int64)
 }
 if hid, ok := c.Get("hid"); ok {
 entry.HospID = hid.(int64)
 }
 if len(c.Errors) > 0 {
 entry.ErrMsg = c.Errors.String()
 }

 select {
 case logCh <- entry:
 default:
 // channel 满，降级写本地文件，保证审计日志不丢
 json.NewEncoder(fallback).Encode(entry)
 }
 }
}

后台 writer 攒批写 MongoDB，用的是 BulkWrite：

 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


func LogWriter(ctx context.Context, coll *mongo.Collection, ch <-chan *AccessLog) {
 batch := make([]mongo.WriteModel, 0, 200)
 ticker := time.NewTicker(500 * time.Millisecond)
 defer ticker.Stop()

 flush := func() {
 if len(batch) == 0 {
 return
 }
 _, err := coll.BulkWrite(ctx, batch)
 if err != nil {
 log.Printf("mongo bulk write error: %v", err)
 }
 batch = batch[:0]
 }

 for {
 select {
 case e := <-ch:
 m := mongo.NewInsertOneModel().SetDocument(e)
 batch = append(batch, m)
 if len(batch) >= 200 {
 flush()
 }
 case <-ticker.C:
 flush()
 case <-ctx.Done():
 flush()
 return
 }
 }
}

四个坑

第一个坑是请求体。最开始我直接把 c.Request.Body 读出来记日志，读完之后后续 handler 再读就是空的：body 是个流，读一次就没了。要用 io.NopCloser 加 bytes.Buffer 复制一份放回去。另外大 body 必须截断，只记前 1KB，不然日志体积很快失控。

第二个是敏感字段。密码、身份证、手机号不能明文进日志。我在序列化前对 query 和 body 里的 password、id_card、phone 做了掩码。这事必须在入口做，等数据入了库再补救就晚了，合规也不认。

第三个是 MongoDB 写入延迟。BulkWrite 攒到 200 条批量写，平时延迟很稳，但副本集发生主从切换时写入会短暂失败。flush 失败就把批次写回本地文件，一个补传任务定期扫描重放，保证审计数据最终不丢。

第四个是 JWT 的注销。JWT 无状态，token 在过期前没法主动作废。我们在 Redis 里维护黑名单：退出登录或改密码时把 jti 加进去，TTL 设成剩余有效期。代价是每个请求多一次 Redis 查询，我觉得值。

后来

这两个中间件后来成了我所有 Go Web 项目的基础组件。回头看，主流程都不难，难的全是边角：body 读完要放回，日志要异步但不能丢，token 要能注销，敏感字段要在入口脱敏。边角处理好了，才算能用。

封面图：Tawheed Manzoor / Flickr · CC BY 2.0

Go channels 在用户行为异步上报中的应用与踩坑

Mon, 23 Oct 2023 10:30:00 +0800

埋点把数据库打满了

我之前负责的经营数据分析平台，需要采集医生在 Web 端的行为埋点：页面停留、功能点击、病历查看这些。最开始埋点接口是同步写库，结果高峰期数据库连接被打满。更麻烦的是，埋点写入失败还会影响主业务接口的响应。

业务方的诉求倒是很明确：埋点实时性要求不高，分钟级延迟可以接受，但主链路绝对不能被拖慢。

我决定用 buffered channel 加后台 worker 做异步上报。

一个 channel，一组 worker

整体结构很简单：HTTP handler 把埋点事件扔进一个 buffered channel，立即返回 200；后台启动一组 worker goroutine 从 channel 消费，批量写入数据库。要调的参数就两个，channel 容量和 worker 数量，按吞吐能力定。我们初始设了 10000 缓冲、10 个 worker。

 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


type Event struct {
 UserID int64
 Action string
 Page string
 Timestamp time.Time
 Extra map[string]interface{}
}

type Reporter struct {
 ch chan *Event
 db *gorm.DB
 worker int
}

func NewReporter(db *gorm.DB, bufSize, worker int) *Reporter {
 r := &Reporter{
 ch: make(chan *Event, bufSize),
 db: db,
 worker: worker,
 }
 for i := 0; i < worker; i++ {
 go r.consume(i)
 }
 return r
}

func (r *Reporter) Report(e *Event) {
 select {
 case r.ch <- e:
 default:
 // channel 满了直接丢弃，避免阻塞主链路
 log.Printf("event dropped, channel full: %s", e.Action)
 }
}

关键在 Report 方法用了 select + default：channel 满了直接丢弃事件而不是阻塞。埋点数据丢几条不影响业务，但主接口卡住就是事故。

worker 批量消费，攒满 100 条或 200ms 超时就刷一次库：

 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


func (r *Reporter) consume(workerID int) {
 batch := make([]*Event, 0, 100)
 ticker := time.NewTicker(200 * time.Millisecond)
 defer ticker.Stop()

 flush := func() {
 if len(batch) == 0 {
 return
 }
 // 每个 worker 独立恢复 panic，避免一个崩溃全停
 defer func() {
 if rec := recover(); rec != nil {
 log.Printf("worker %d panic: %v", workerID, rec)
 batch = batch[:0]
 }
 }()
 if err := r.db.Table("user_event").Create(&batch).Error; err != nil {
 log.Printf("batch insert failed: %v", err)
 }
 batch = batch[:0]
 }

 for {
 select {
 case e := <-r.ch:
 batch = append(batch, e)
 if len(batch) >= 100 {
 flush()
 }
 case <-ticker.C:
 flush()
 }
 }
}

三个坑

第一个坑是 goroutine panic 导致 worker 静默退出。最初没有在 consume 里加 recover，一次空指针就让某个 worker 挂了。消费速度掉了，但没有任何告警，缓冲慢慢堆满之后事件全部被丢弃。现在每个 worker 的 flush 都有独立 recover，另外加了一个监控：channel 长度超过容量 80% 就报警。

第二个坑是优雅关闭。服务重启时 channel 里可能还有没消费完的事件，直接退出就丢了。我加了一个 Close 方法，先关闭 channel 触发 worker 把剩余数据刷完，再用 sync.WaitGroup 等待所有 worker 退出，最多等 5 秒：

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


func (r *Reporter) Close() {
 close(r.ch)
 done := make(chan struct{})
 go func() {
 r.wg.Wait()
 close(done)
 }()
 select {
 case <-done:
 case <-time.After(5 * time.Second):
 log.Println("reporter close timeout")
 }
}

这里有个容易漏的细节：channel 关闭后，worker 还能从已关闭的 channel 里读出剩余数据，读完会进入零值循环，所以 consume 的 for 里要用 e, ok := <-r.ch，ok 为 false 才退出。这个细节我第一次写的时候漏了，worker 会永远卡在零值事件上。

第三个是背压策略的选择。用 default 丢弃是最简单的背压，其实也可以在 channel 满时降级写本地文件、后续补传。我们评估后觉得埋点允许少量丢失，没做文件补传，但在监控里把丢弃数做成了指标。

后来

buffered channel 做异步上报，在 Go 里是很朴素的方案，但"简单"不等于"随便写"。非阻塞发送、批量写入、panic 恢复、优雅关闭、channel 水位监控，这五样缺一不可。这套模式后来也被我复用到了操作日志和通知推送场景。

封面图：conner395 / Flickr · CC BY 2.0