Go on JasperSao的博客

Go 项目反推：Feed 流系统实战——Feed 流设计

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——数据库与 GORM，这一篇继续拆解 feedsystem_video_go 的核心 Feed 流：从推拉模型到游标分页，再到热榜、关注流、话题流与缓存策略。

什么是 Feed 流

打开抖音/微博，往下刷，不断出来新内容，这就是 Feed 流。

这个项目的 4 种 Feed 流

类型	说明	排序方式
最新视频	全站最新发布的视频	按时间倒序
热榜	最热门的视频	按热度排序
关注流	只看关注的人发的视频	按时间倒序
话题流	某个话题下的视频	按时间倒序

推模型 vs 拉模型

拉模型（这个项目用的）

发视频：只写Video表（不做额外操作）
刷视频：实时查询Video表（拉取数据）

数据流动：用户刷的时候才从 DB 拉。

推模型

发视频：写Video表 + 把视频ID推送到所有粉丝的Feed列表里
刷视频：直接从自己的Feed列表读（不用查DB）

数据流动：发的时候就推给粉丝了，粉丝刷的时候直接读。

推拉结合

普通用户发视频 → 推送给粉丝（粉丝少，推送成本低）
大V发视频 → 不推送，粉丝读的时候实时拉取

对比

	拉模型	推模型	推拉结合
发视频成本	低	高（大V要推给几百万粉丝）	中
刷视频成本	高（每次都要查DB）	低（直接读列表）	中
实时性	实时	略有延迟	中
复杂度	简单	复杂	最复杂
场景	用户量小	用户量大	抖音/微博

这个项目用拉模型，因为是学习项目，用户量小，拉模型简单够用。

游标分页 vs 页码分页

页码分页

第1页：GET /feed?page=1&size=10
第2页：GET /feed?page=2&size=10

对应 SQL：

SELECT * FROM videos ORDER BY create_time DESC LIMIT 5 OFFSET 0 -- 第1页
SELECT * FROM videos ORDER BY create_time DESC LIMIT 5 OFFSET 5 -- 第2页

问题：数据变化时可能重复或漏数据

数据库：[100, 90, 80, 70, 60, 50, 40, 30]

第1页（page=1, size=3）：跳过0条，取3条 → [100, 90, 80]

插入新视频110，数据库变成：[110, 100, 90, 80, 70, 60, 50, 40, 30]

第2页（page=2, size=3）：跳过3条，取3条 → [80, 70, 60]

视频80重复出现了！

为什么？因为 OFFSET 是基于"位置"的，不是基于"数据"的。新视频插入后，原来第 4 个位置的视频 80 变成了第 5 个，但 OFFSET 还是 3，所以又取到了。

游标分页（这个项目用的）

第1页：GET /feed?limit=10
 返回：video_list + next_time=1000

第2页：GET /feed?limit=10&latest_time=1000
 返回：video_list + next_time=900

对应 SQL：

SELECT * FROM videos ORDER BY create_time DESC LIMIT 10
SELECT * FROM videos WHERE create_time < 1000 ORDER BY create_time DESC LIMIT 10

为什么游标分页不会重复？

第1页：WHERE create_time < now() LIMIT 3
 返回 [100, 90, 80]
 next_time = 80的时间

插入110

第2页：WHERE create_time < 80的时间 LIMIT 3
 返回 [70, 60, 50]

没有重复！

游标是基于数据的值（时间），不是位置。新视频插入不影响查询条件。

对比

	页码分页	游标分页
请求方式	page=2	latest_time=1000
数据变化时	可能重复或漏数据	不会重复
SQL	OFFSET 跳过	WHERE 条件过滤
场景	后台管理系统	Feed 流、时间线

游标分页的实现

服务器代码

func (repo *FeedRepository) ListLatest(ctx context.Context, limit int, latestBefore time.Time) ([]*video.Video, error) {
 query := repo.db.WithContext(ctx).Model(&video.Video{}).Order("create_time DESC")

 // 关键：如果有游标，加上WHERE条件
 if !latestBefore.IsZero() {
 query = query.Where("create_time < ?", latestBefore)
 }

 query.Limit(limit).Find(&videos)
 return videos, nil
}

游标怎么生成的

// 取本页最后一条视频的时间作为游标
var nextTime int64
if len(baseVideos) > 0 {
 nextTime = baseVideos[len(baseVideos)-1].CreateTime.UnixMilli()
}

本页最后一条视频的时间 = 下一页的起点。

响应结构

type ListLatestResponse struct {
 VideoList []FeedVideoItem `json:"video_list"`
 NextTime int64 `json:"next_time"` // 游标
 HasMore bool `json:"has_more"` // 还有没有更多
}

完整流程

客户端：GET /feed?limit=10
 ↓
服务器：SELECT * FROM videos ORDER BY create_time DESC LIMIT 10
 ↓
返回：video_list + next_time = 本页最后一条的时间
 ↓
客户端：GET /feed?limit=10&latest_time=next_time
 ↓
服务器：SELECT * FROM videos WHERE create_time < next_time ORDER BY create_time DESC LIMIT 10
 ↓
返回：video_list + next_time = 新的游标
 ↓
...循环，直到 has_more = false

热榜实现

热榜排序算法

query := repo.db.WithContext(ctx).Model(&video.Video{}).
 Order("popularity DESC, create_time DESC, id DESC")

排序规则：热度高的优先，热度相同按时间倒序，时间也相同按 ID 倒序。

热度分数怎么算的

func UpdatePopularityCache(ctx context.Context, cache *rediscache.Client, id uint, change int64) {
 now := time.Now().UTC().Truncate(time.Minute)
 windowKey := cache.Key("hot:video:1m:%s", now.Format("200601021504"))
 member := strconv.FormatUint(uint64(id), 10)

 cache.ZincrBy(opCtx, windowKey, member, float64(change)) // 热度+change
 cache.Expire(opCtx, windowKey, 2*time.Hour)
}

每次点赞/评论/关注，热度+1。

热榜查询流程（冷热分离）

func (f *FeedService) ListByPopularity(ctx context.Context, limit int, reqAsOf int64, offset int, ...) {
 // 1. 确定时间窗口（最近60分钟）
 asOf := time.Now().UTC().Truncate(time.Minute)

 // 2. 生成60个ZSET的key
 keys := make([]string, 0, 60)
 for i := 0; i < 60; i++ {
 keys = append(keys, f.rediscache.Key("hot:video:1m:%s", asOf.Add(-time.Duration(i)*time.Minute).Format("200601021504")))
 }

 // 3. 合并成一个ZSET（快照）
 dest := f.rediscache.Key("hot:video:merge:1m:%s", asOf.Format("200601021504"))
 f.rediscache.ZUnionStore(opCtx, dest, keys, "SUM")

 // 4. 从合并后的ZSET取top N
 members, _ := f.rediscache.ZRevRange(opCtx, dest, start, stop)

 // 5. 根据ID去查视频详情
 videos, _ := f.repo.GetByIDs(ctx, ids)

 return videos
}

快照 key 是什么

快照 key 就是"合并结果的缓存"。

没有快照key：
 用户A请求 → 合并60个ZSET → 返回
 用户B请求 → 合并60个ZSET → 返回
 100个用户请求 → 合并100次 → 浪费！

有快照key：
 用户A请求 → 合并60个ZSET → 存到快照key → 返回
 用户B请求 → 发现快照key已存在 → 直接用 → 返回
 100个用户请求 → 只合并1次 → 省资源！

代码：

dest := f.rediscache.Key("hot:video:merge:1m:%s", asOf.Format("200601021504"))
exists, _ := f.rediscache.Exists(opCtx, dest)
if !exists {
 f.rediscache.ZUnionStore(opCtx, dest, keys, "SUM")
 f.rediscache.Expire(opCtx, dest, 2*time.Minute)
}
members, _ := f.rediscache.ZRevRange(opCtx, dest, start, stop)

快照 key 2 分钟后过期，下次请求重新合并，拿到最新数据。

关注流实现

核心代码

func (repo *FeedRepository) ListByFollowing(ctx context.Context, limit int, viewerAccountID uint, latestBefore time.Time) ([]*video.Video, error) {
 var videos []*video.Video
 query := repo.db.WithContext(ctx).Model(&video.Video{}).Order("create_time DESC")

 if viewerAccountID > 0 {
 // 子查询：找到我关注的所有人
 followingSubQuery := repo.db.WithContext(ctx).
 Model(&social.Social{}).
 Select("vlogger_id").
 Where("follower_id = ?", viewerAccountID)

 // 只查这些人发的视频
 query = query.Where("author_id IN (?)", followingSubQuery)
 }

 if !latestBefore.IsZero() {
 query = query.Where("create_time < ?", latestBefore)
 }

 query.Limit(limit).Find(&videos)
 return videos, nil
}

等价 SQL

SELECT * FROM videos
WHERE author_id IN (
 SELECT vlogger_id FROM socials WHERE follower_id = 123 -- 我关注的人
)
AND create_time < 1000 -- 游标
ORDER BY create_time DESC
LIMIT 10

子查询是什么

子查询就是"查询里的查询"，拆成两步理解：

第1步（子查询）：
 SELECT vlogger_id FROM socials WHERE follower_id = 123
 → 结果：[456, 789]（用户A关注的人）

第2步（主查询）：
 SELECT * FROM videos WHERE author_id IN (456, 789)
 → 结果：视频100（B发的）、视频200（C发的）

子查询是一次 SQL 搞定，数据库内部优化，比两条 SQL 更快。

流程

用户A关注了B和C
 ↓
子查询：从social表找到 [456, 789]
 ↓
主查询：从video表找 author_id 是 456 或 789 的视频
 ↓
返回：视频100（B发的）、视频200（C发的）
 ↓
用户D的视频300不会出现（A没关注D）

话题流实现

核心代码

func (repo *FeedRepository) ListByTag(ctx context.Context, tagName string, limit int) ([]*video.Video, error) {
 var videos []*video.Video
 err := repo.db.WithContext(ctx).Model(&video.Video{}).Table("videos").
 Joins("JOIN video_tags ON video_tags.video_id = videos.id").
 Joins("JOIN tags ON tags.id = video_tags.tag_id").
 Where("tags.name = ?", tagName).
 Order("videos.create_time desc").
 Limit(limit).
 Find(&videos).Error
 return videos, err
}

等价 SQL

SELECT videos.* FROM videos
JOIN video_tags ON video_tags.video_id = videos.id
JOIN tags ON tags.id = video_tags.tag_id
WHERE tags.name = 'Go语言'
ORDER BY videos.create_time DESC
LIMIT 10

三张表的关系

tags表：
┌────┬──────────┐
│ id │ name │
├────┼──────────┤
│ 1 │ Go语言 │
│ 2 │ Python │
└────┴──────────┘

video_tags表（多对多关联）：
┌──────────┬─────────┐
│ video_id │ tag_id │
├──────────┼─────────┤
│ 100 │ 1 │ ← 视频100有"Go语言"标签
│ 100 │ 2 │ ← 视频100也有"Python"标签
│ 200 │ 1 │ ← 视频200有"Go语言"标签
└──────────┴─────────┘

videos表：
┌────┬──────────┐
│ id │ title │
├────┼──────────┤
│ 100 │ Go入门 │
│ 200 │ 并发编程 │
└────┴──────────┘

查询流程

1. 从tags表找到"Go语言"的id = 1
2. 从video_tags表找到tag_id = 1的video_id = [100, 200]
3. 从videos表找到id = [100, 200]的视频

JOIN一次搞定。

三级缓存架构

这个项目在 Feed 查询里用了三级缓存：

请求 → L1本地缓存 → L2 Redis → L3 MySQL
 ↓ 快 ↓ 较快 ↓ 慢
 纳秒级 毫秒级 毫秒级

代码

type FeedService struct {
 localcache *cache.Cache // L1：本地缓存（进程内存，3秒过期）
 rediscache *rediscache.Client // L2：Redis缓存
 repo *FeedRepository // L3：MySQL
}

// L1：本地缓存
localcache: cache.New(3*time.Second, 5*time.Second)

// L2：Redis缓存（50ms超时）
cacheCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)

// L3：MySQL
videos, err := f.repo.GetByIDs(ctx, ids)

查询流程

请求来了
 ↓
查L1本地缓存（进程内存）
 ├── 命中 → 直接返回（最快）
 └── 没命中
 ↓
 查L2 Redis（50ms超时）
 ├── 命中 → 写回L1 → 返回
 └── 没命中
 ↓
 查L3 MySQL
 → 写回L2 Redis → 写回L1 → 返回

singleflight 防并发

什么是 singleflight

Go 内置的工具，保证同一个请求只执行一次，其他并发请求等着用结果。

场景

100个用户同时请求热榜
 ↓
没有singleflight：
 用户1：查DB → 返回
 用户2：查DB → 返回
 ...
 用户100：查DB → 返回
 DB被查了100次！

有singleflight：
 用户1：查DB → 返回
 用户2-100：等着 → 用户1查完后直接用结果
 DB只被查了1次！

代码

type FeedService struct {
 requestGroup singleflight.Group
}

v, err, _ := f.requestGroup.Do(sfKey, func() (interface{}, error) {
 return f.repo.GetByIDs(ctx, []uint{videoID})
})

第 1 个请求：执行 func，查 DB
其他请求：同一个 sfKey，等着，拿到同样的结果

sfKey 是什么

请求的唯一标识：

sfKey := f.rediscache.Key("sf:entity:%d", videoID)
// 结果："sf:entity:123"

同一个视频 ID 的请求，sfKey 相同，会共享结果。

和分布式锁的对比

	分布式锁	singleflight
作用范围	多台机器	单机内
实现	Redis	Go 内存
复杂度	高	低
场景	分布式系统	单机内防并发

面试要点总结

Q: 推模型和拉模型的区别？

A: 推是发视频时推送给粉丝，拉是刷视频时实时查 DB。推的读快写慢，拉的读慢写快。抖音用推拉结合。

Q: 游标分页和页码分页的区别？

A: 游标用 WHERE 条件过滤，不会重复；页码用 OFFSET 跳过，数据变化时可能重复。Feed 流用游标分页。

Q: 热榜怎么实现的？

A: ZSET 按分钟分窗口，点赞时热度+1，查询时合并 60 个窗口算总分，快照 key 缓存合并结果。

Q: 关注流怎么实现的？

A: 子查询找关注列表，再查这些人发的视频。一次 SQL 搞定。

Q: 话题流怎么实现的？

A: 三表 JOIN（videos + video_tags + tags），查某个标签下的视频。

Q: 什么是 singleflight？

A: Go 内置工具，保证同一个请求只执行一次，其他并发请求等着用结果。和分布式锁类似，但作用于单机内。

Q: 三级缓存是什么？

A: L1 本地缓存（进程内存）→ L2 Redis → L3 MySQL。先查快的，没命中再查慢的。

Go 项目反推：Feed 流系统实战——SSE 实时推送与分片上传

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——Feed 流设计，这一篇继续拆解 feedsystem_video_go 的两个关键能力：用 SSE 实时推送通知，以及用分片上传和断点续传处理大文件。

阶段6：SSE实时推送

SSE 是什么

SSE = Server-Sent Events，服务器主动给客户端推送消息。

就像外卖 APP 的订单状态：

你下单 → 服务器推送"商家已接单"
 → 服务器推送"骑手已取餐"
 → 服务器推送"骑手已送达"

客户端不用一直问"好了没？好了没？"，服务器有消息就主动推。

SSE vs WebSocket

	SSE	WebSocket
方向	服务器 → 客户端（单向）	双向
协议	HTTP	独立协议
复杂度	简单	复杂
场景	通知、状态更新、新闻推送	聊天、游戏、实时协作

这个项目用 SSE 推送通知（点赞、评论、关注），因为只需要服务器→客户端，不需要客户端→服务器。

为什么用 SSE 不用轮询

方案	做法	问题
轮询	客户端每隔几秒问一次"有新消息吗？"	浪费资源、实时性差、大部分请求返回空
SSE	服务器有消息就推，没有就等着	省资源、实时性高

项目里 SSE 用在哪

用户A给用户B的视频点赞
 ↓
LikeWorker处理点赞事件
 ↓
NotificationWorker收到MQ消息
 ↓
创建Notification记录，写入DB
 ↓
SSEHub.Push(userID, notification)
 ↓
用户B的浏览器收到推送，实时显示"xxx点赞了你的视频"

SSEHub 数据结构

type SSEHub struct {
 mu sync.RWMutex
 clients map[uint][]chan *Notification // userID -> 多个通知channel
 db *gorm.DB
}

数据结构：

map[uint][]chan *Notification

用户1 → [channel1, channel2] （可能多个设备）
用户2 → [channel3]
用户3 → [channel4, channel5, channel6] （三个设备）

代码实现

Notification 表结构

type Notification struct {
 ID uint
 RecipientID uint // 接收者ID
 SenderID uint // 发送者ID
 Type string // 通知类型：like、comment、follow
 TargetID uint // 目标ID（视频ID、用户ID）
 Content string // 通知内容
 IsRead bool // 是否已读
 CreatedAt time.Time
}

SSEHub 核心方法

// 订阅：用户连接时调用
func (h *SSEHub) Subscribe(userID uint) chan *Notification {
 ch := make(chan *Notification, 20) // 缓冲区20
 h.mu.Lock() // 写锁
 h.clients[userID] = append(h.clients[userID], ch)
 h.mu.Unlock()
 return ch
}

// 取消订阅：用户断开时调用
func (h *SSEHub) Unsubscribe(userID uint, ch chan *Notification) {
 h.mu.Lock() // 写锁
 defer h.mu.Unlock()
 chs := h.clients[userID]
 for i, c := range chs {
 if c == ch {
 chs = append(chs[:i], chs[i+1:]...)
 if len(chs) == 0 {
 delete(h.clients, userID)
 } else {
 h.clients[userID] = chs
 }
 close(c)
 return
 }
 }
}

// 推送：有新通知时调用
func (h *SSEHub) Push(userID uint, n *Notification) {
 h.mu.RLock() // 读锁
 defer h.mu.RUnlock()
 chs, ok := h.clients[userID]
 if !ok {
 return
 }
 for _, ch := range chs {
 select {
 case ch <- n: // 往channel里塞消息
 default: // 塞不进去就跳过（防阻塞）
 }
 }
}

SSEHandler - 处理 SSE 连接

func (h *SSEHub) SSEHandler(c *gin.Context) {
 userID, ok := sseAccountID(c)
 if !ok {
 c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid account"})
 return
 }

 // 设置SSE响应头
 c.Writer.Header().Set("Content-Type", "text/event-stream")
 c.Writer.Header().Set("Cache-Control", "no-cache")
 c.Writer.Header().Set("Connection", "keep-alive")
 c.Writer.WriteHeader(http.StatusOK)

 // 订阅通知
 ch := h.Subscribe(userID)
 defer h.Unsubscribe(userID, ch)

 ctx := c.Request.Context()
 flusher, _ := c.Writer.(http.Flusher)

 for {
 select {
 case <-ctx.Done(): // 客户端断开
 return
 case n, ok := <-ch: // 收到通知
 if !ok {
 return
 }
 b, _ := json.Marshal(n)
 fmt.Fprintf(c.Writer, "data: %s\n\n", b) // SSE格式
 if flusher != nil {
 flusher.Flush() // 立刻发送给客户端
 }
 case <-time.After(30 * time.Second): // 心跳
 fmt.Fprintf(c.Writer, ": keepalive\n\n")
 if flusher != nil {
 flusher.Flush()
 }
 }
 }
}

Push 为什么用 RLock 不用 Lock

什么是读写锁（RWMutex）

普通锁（Mutex）：同一时刻只能一个人进去，不管是读还是写。

读写锁（RWMutex）：

多个人可以同时读（RLock）
写的时候只能一个人进去，其他人不能读也不能写（Lock）

对比

操作	做什么	用什么锁
Push	读 map，往 channel 塞消息	RLock（读锁）
Subscribe	往 map 里加一个 channel	Lock（写锁）
Unsubscribe	从 map 里删一个 channel	Lock（写锁）

为什么 Push 能用 RLock

Push 只做两件事：

从 map 里找到用户的 channel（读）
往 channel 里塞消息（不改 map）

map 结构没变，所以多个 Push 可以同时进行。

一句话：读用 RLock（可以并发），写用 Lock（必须独占）。

场景对比

场景：100个用户同时收到通知

用普通锁（Mutex）：
 Push1加锁 → 推送 → 解锁
 Push2加锁 → 推送 → 解锁
 ... 一个一个来，慢

用读写锁（RWMutex）：
 Push1加RLock → 推送
 Push2加RLock → 推送
 Push3加RLock → 推送
 ... 100个同时推，快

心跳机制

什么是心跳

SSE 连接可能因为网络问题断开，客户端不知道。

解决方案：每 30 秒发一次空消息（keepalive），告诉客户端"我还活着"。

case <-time.After(30 * time.Second):
 fmt.Fprintf(c.Writer, ": keepalive\n\n")
 flusher.Flush()

为什么需要心跳

没有心跳：
 客户端连接服务器 → 网络抖动 → 连接断了
 客户端不知道断了 → 一直等 → 漏掉通知

有心跳：
 客户端连接服务器 → 每30秒收到keepalive
 30秒没收到 → 知道断了 → 重新连接

select 里的 default 防阻塞

for _, ch := range chs {
 select {
 case ch <- n: // 往channel里塞消息
 default: // 塞不进去就跳过
 }
}

channel 缓冲区满了（20条），塞不进去怎么办？

没有 default：阻塞等着，Push 卡住，其他用户的推送也卡住
有 default：直接跳过，不等，保证其他用户能正常收到推送

这是防阻塞设计：一个用户的消息堆积不影响其他用户。

NotificationWorker 处理流程

func (w *NotificationWorker) process(ctx context.Context, d amqp.Delivery) error {
 routingKey := d.RoutingKey

 var notif *Notification

 switch {
 case routingKey == "like.like":
 // 解析点赞事件
 // 查询视频作者ID
 // 如果是自己给自己点赞，不通知
 notif = &Notification{RecipientID: authorID, SenderID: evt.UserID, Type: "like", Content: "点赞了你的视频"}

 case routingKey == "comment.publish":
 // 解析评论事件
 // 查询视频作者ID
 // 如果是自己评论自己，不通知
 notif = &Notification{RecipientID: authorID, SenderID: evt.AuthorID, Type: "comment", Content: "评论了你的视频"}

 case routingKey == "social.follow":
 // 解析关注事件
 notif = &Notification{RecipientID: evt.VloggerID, SenderID: evt.FollowerID, Type: "follow", Content: "关注了你"}
 }

 if notif == nil {
 return nil
 }

 // 写入DB
 w.db.Create(notif)

 // 实时推送给用户
 w.hub.Push(notif.RecipientID, notif)

 return nil
}

接口设计

接口	方法	作用
`/stream`	GET	SSE 连接，实时接收通知
`/list`	POST	查询通知列表（最近 50 条）
`/markRead`	POST	标记已读
`/unreadCount`	POST	查询未读数量

阶段7：分片上传

为什么需要分片上传

视频文件可能很大（几十 MB 到 200MB），一次上传的问题：

一次上传100MB：
 网络抖动 → 上传到99%断了 → 重头再来
 用户体验极差

分片上传：

100MB文件，分成5MB一片，共20片
 第1片上传成功 ✓
 第2片上传成功 ✓
 ...
 第17片网络断了 ✗
 重新连接 → 只需要重新上传第17片，1-16不用重传

分片上传流程

整体流程

1. 客户端：计算文件MD5 → 调用Init接口 → 获得upload_id + 已上传分片列表
2. 客户端：逐片上传（跳过已上传的） → 每片带MD5校验
3. 客户端：全部上传完 → 调用Complete接口 → 服务器合并分片 → 返回视频URL

流程图

客户端 服务器
 | |
 |--- Init(文件名, 大小, MD5) ----------->|
 |<-- upload_id + 已上传列表 -------------|
 | |
 |--- UploadChunk(分片0, MD5) ----------->| 保存到临时目录
 |<-- chunk_index: 0 ----------------------|
 | |
 |--- UploadChunk(分片1, MD5) ----------->| 保存到临时目录
 |<-- chunk_index: 1 ----------------------|
 | |
 | ...（中间可能断线重连） |
 | |
 |--- Complete(upload_id) --------------->| 合并所有分片
 |<-- url: 视频地址 -----------------------|

核心数据结构

ChunkUploadSession（上传会话）

const ChunkSize = 5 << 20 // 5 MB

type ChunkUploadSession struct {
 UploadID string // 上传会话ID（随机生成）
 AccountID uint // 上传者ID
 Filename string // 原始文件名
 FileSize int64 // 文件总大小
 ChunkSize int64 // 每片大小（默认5MB）
 TotalChunks int // 总片数
 FileHash string // 整个文件的MD5
 UploadedBits []bool // 每片是否已上传（位图）
}

UploadedBits 是什么

UploadedBits: []bool{true, true, true, false, false}

这个数组表示：

分片 0：已上传 ✓
分片 1：已上传 ✓
分片 2：已上传 ✓
分片 3：未上传
分片 4：未上传

用 bool 数组而不是存已上传的分片列表，好处是：

判断某片是否已上传：O(1)，直接 index
判断是否全部上传完：遍历一次，O(n)

两个辅助方法

// 返回已上传的分片索引列表
func (s *ChunkUploadSession) UploadedChunks() []int {
 var indices []int
 for i, uploaded := range s.UploadedBits {
 if uploaded {
 indices = append(indices, i)
 }
 }
 return indices
}

// 判断是否全部上传完
func (s *ChunkUploadSession) IsComplete() bool {
 for _, b := range s.UploadedBits {
 if !b {
 return false
 }
 }
 return true
}

会话存在哪：Redis

上传会话存在 Redis，不是 MySQL，原因是：

存储	读写速度	持久化	适合存什么
Redis	微秒级	可配置过期	临时状态（上传进度）
MySQL	毫秒级	永久	持久数据（用户信息、视频记录）

上传会话是临时的（24 小时过期），用 Redis 更合适。

Redis Key 设计

// 上传会话
func (h *ChunkUploadHandler) sessionKey(uploadID string) string {
 return h.cache.Key("chunk_upload:%s", uploadID)
}

// 文件哈希 → upload_id 的映射（用于断点续传）
func (h *ChunkUploadHandler) hashKey(accountID uint, fileHash string) string {
 return h.cache.Key("chunk_upload_hash:%d:%s", accountID, fileHash)
}

两个 Key 的作用：

chunk_upload:<upload_id>：存完整的上传会话
chunk_upload_hash:<account_id>:<file_hash>：文件哈希到 upload_id 的映射，用于断点续传

四个接口详解

接口 1：InitChunkUpload（初始化上传）

func (h *ChunkUploadHandler) InitChunkUpload(c *gin.Context)

做了什么：

校验请求参数（文件名、大小、哈希、总片数）
检查文件大小是否超过 200MB 限制
断点续传检查：用文件哈希查 Redis，如果找到之前的会话，直接返回
创建新会话，存入 Redis
返回 upload_id + 已上传列表（新上传为空）

断点续传的实现：

// 检查是否有同文件的旧会话
hashKey := h.hashKey(accountID, req.FileHash)
existingID, err := h.cache.GetBytes(c.Request.Context(), hashKey)
if err == nil && len(existingID) > 0 {
 session, sessErr := h.getSession(c, string(existingID))
 if sessErr == nil {
 // 找到了！返回旧的upload_id和已上传列表
 c.JSON(http.StatusOK, gin.H{
 "upload_id": session.UploadID,
 "uploaded_chunks": session.UploadedChunks(),
 })
 return
 }
}

为什么用文件哈希做断点续传？

用户上传 video.mp4（100MB，MD5: abc123）
 → Init，upload_id: xxx，开始上传
 → 上传了15片，浏览器关闭

用户重新选择同一个 video.mp4
 → Init，参数里带同样的 file_hash: abc123
 → 服务器查Redis：chunk_upload_hash:<uid>:abc123 → xxx
 → 找到旧会话！返回已上传的15片
 → 客户端跳过这15片，只上传剩下的5片

接口 2：UploadChunk（上传单片）

func (h *ChunkUploadHandler) UploadChunk(c *gin.Context)

做了什么：

从表单获取 upload_id、chunk_index、chunk_hash
查 Redis 获取会话
校验：会话存在、是本人上传、分片索引合法
幂等检查：如果这片已经上传过，直接返回成功（不重复处理）
读取上传的文件内容，计算 MD5
哈希校验：对比客户端传的 chunk_hash 和实际计算的 MD5
保存分片到临时目录：.run/uploads/tmp/<upload_id>/<chunk_index>
更新 Redis 中的会话状态

幂等设计：

if session.UploadedBits[req.ChunkIndex] {
 c.JSON(http.StatusOK, gin.H{"chunk_index": req.ChunkIndex})
 return
}

如果分片已上传过，直接返回成功，不重复处理。这保证了重试的安全性。

哈希校验：

hash := md5.New()
io.Copy(hash, chunkFile)
actualHash := fmt.Sprintf("%x", hash.Sum(nil))

if actualHash != req.ChunkHash {
 c.JSON(http.StatusBadRequest, gin.H{"error": "chunk hash mismatch"})
 return
}

每个分片都有 MD5 校验，防止传输过程中数据损坏。

分片存储位置：

.run/uploads/tmp/
 └── <upload_id>/
 ├── 0 ← 第0片
 ├── 1 ← 第1片
 ├── 2 ← 第2片
 └── ...

接口 3：ChunkStatus（查询上传状态）

func (h *ChunkUploadHandler) ChunkStatus(c *gin.Context)

返回：upload_id + 已上传分片列表 + 总片数。

用于客户端轮询或断线后查询进度。

接口 4：CompleteChunkUpload（完成上传）

func (h *ChunkUploadHandler) CompleteChunkUpload(c *gin.Context)

做了什么：

校验会话、校验是否本人
检查是否所有分片都已上传（IsComplete()）
如果有未上传的分片，返回错误和缺失信息
合并分片：按顺序读取所有分片，写入最终文件
清理临时文件和 Redis 会话
返回视频 URL

合并过程：

tmpDir := filepath.Join(".run", "uploads", "tmp", req.UploadID)
for i := 0; i < session.TotalChunks; i++ {
 chunkPath := filepath.Join(tmpDir, fmt.Sprintf("%d", i))
 cf, _ := os.Open(chunkPath)
 io.Copy(finalFile, cf) // 按顺序拼接
 cf.Close()
}

最终文件位置：

.run/uploads/
 └── videos/
 └── <account_id>/
 └── <date>/
 └── <random>.mp4

清理：

// 删除临时分片
os.RemoveAll(tmpDir)

// 删除Redis会话
h.cache.Del(ctx, sessionKey)
h.cache.Del(ctx, hashKey)

安全设计

文件大小限制

const maxSize = 200 << 20 // 200MB
if req.FileSize > maxSize {
 c.JSON(http.StatusBadRequest, gin.H{"error": "file size exceeds 200MB limit"})
 return
}

权限校验

每个接口都检查：会话存在 + 是本人操作。

accountID, _ := jwt.GetAccountID(c)
if session.AccountID != accountID {
 c.JSON(http.StatusForbidden, gin.H{"error": "forbidden"})
 return
}

分片哈希校验

每个分片上传时都验证 MD5，防止数据损坏。

接口总结

接口	方法	作用
`/chunk/init`	POST	初始化上传，返回 upload_id
`/chunk/upload`	POST	上传单个分片
`/chunk/status`	POST	查询上传状态
`/chunk/complete`	POST	完成上传，合并分片

面试要点总结

Q: SSE 是什么？

A: Server-Sent Events，服务器主动推送消息给客户端，单向，基于 HTTP。场景：通知、状态更新、新闻推送。

Q: SSE 和 WebSocket 怎么选？

A: 只要服务器推用 SSE（简单），需要双向通信用 WebSocket（复杂）。这个项目用 SSE 推送通知，因为只需要服务器→客户端。

Q: 为什么用 SSE 不用轮询？

A: 轮询客户端每隔几秒问一次，浪费资源、实时性差。SSE 服务器有消息就推，省资源、实时性高。

Q: 心跳机制是什么？

A: 每 30 秒发一次空消息（keepalive），告诉客户端"我还活着"。客户端 30 秒没收到，知道连接断了，重新连接。

Q: Push 为什么用 RLock？

A: Push 只读 map 不改 map，用读锁可以多个 Push 并发。Subscribe/Unsubscribe 要改 map，用写锁必须独占。

Q: select 里的 default 是干什么的？

A: 防阻塞。channel 满了塞不进去就跳过，保证一个用户的消息堆积不影响其他用户。

Q: 为什么要分片上传？

A: 大文件一次上传，网络断了要重头来。分片后断点续传，只需重传失败的分片。

Q: 断点续传怎么实现？

A: 用文件 MD5 做唯一标识，Init 时查 Redis 是否有同文件的旧会话。有就返回已上传列表，客户端跳过这些分片。

Q: 上传会话存在哪？为什么？

A: 存 Redis，因为是临时状态（24 小时过期），读写快。MySQL 存持久数据。

Q: 怎么保证分片数据没损坏？

A: 每片上传时计算 MD5，和客户端传的 chunk_hash 对比，不匹配就拒绝。

Q: 分片重复上传怎么办？

A: 幂等设计——检查 UploadedBits，已上传的分片直接返回成功，不重复处理。

Q: 会话里 UploadedBits 是什么？

A: bool 数组，每个元素对应一个分片是否已上传。长度等于总片数，直接用下标访问，O(1) 判断某片是否已上传。

Go 项目反推：Feed 流系统实战——工程化

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——SSE 实时推送与分片上传，这一篇回到工程全景，梳理 feedsystem_video_go 的容器编排、配置管理、性能分析、持续集成与本地启动流程。

Docker Compose（容器编排）

什么是 Docker Compose

把所有服务打包成容器，一键启动。

没有 Docker Compose：

手动启动MySQL → 手动启动Redis → 手动启动RabbitMQ → 手动启动Backend → 手动启动Worker → 手动启动Frontend
每次都要敲6条命令，还要记住启动顺序

有 Docker Compose：

docker compose up -d
一键启动所有服务

这个项目的 Docker Compose

services:
 mysql: # 数据库
 redis: # 缓存
 rabbitmq: # 消息队列
 backend: # API进程
 worker: # Worker进程
 frontend: # 前端

相关文件：~/dev/projects/feedsystem_video_go/docker-compose.yml

depends_on + healthcheck（保证启动顺序）

depends_on 是什么

告诉 Docker：某个服务依赖其他服务，要等依赖的服务启动后才能启动自己。

backend:
 depends_on:
 mysql:
 condition: service_healthy  # MySQL健康了才启动backend
 redis:
 condition: service_healthy  # Redis健康了才启动backend
 rabbitmq:
 condition: service_healthy  # RabbitMQ健康了才启动backend

healthcheck 是什么

判断服务是否"健康"（真正能接受连接）。

mysql:
 healthcheck:
 test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -uroot -p123456"]
 interval: 5s  # 每5秒检查一次
 timeout: 5s  # 超时5秒
 retries: 20 # 重试20次

MySQL 启动后，每 5 秒 ping 一次，连续 ping 成功才算"健康"。

为什么要 healthcheck

没有healthcheck：
 MySQL容器启动了 → backend立刻启动
 但MySQL还没初始化完 → backend连接失败 → 崩溃

有healthcheck：
 MySQL容器启动了 → 等MySQL真正能接受连接 → backend再启动

所有服务的 healthcheck

服务	healthcheck 测试	作用
mysql	`mysqladmin ping`	确认 MySQL 能接受连接
redis	`redis-cli ping`	确认 Redis 能接受连接
rabbitmq	`rabbitmq-diagnostics ping`	确认 RabbitMQ 能接受连接
backend	`wget http://127.0.0.1:8080/healthz`	确认 API 进程正常
worker	`pgrep worker`	确认 Worker 进程存在
frontend	`wget http://127.0.0.1:80/`	确认前端能访问

配置管理（优先级）

配置文件位置

~/dev/projects/feedsystem_video_go/backend/configs/
├── config.yaml # 本地开发用（MySQL端口3306）
├── config.compose-local.yaml # Docker Compose本地用（MySQL端口3307）
└── config.docker.yaml # Docker部署用（容器内部通信）

三个配置文件的区别

文件	MySQL 端口	用途
config.yaml	3306	本地开发，MySQL 装在本机
config.compose-local.yaml	3307	Docker Compose，MySQL 容器映射到 3307
config.docker.yaml	3306	Docker 部署，容器内部通信

配置加载优先级

环境变量 > .env文件 > YAML文件

来源	举例	优先级
环境变量	`export MYSQL_DATABASE=feedsystem`	最高
.env 文件	`MYSQL_DATABASE=feedsystem`	中
YAML 文件	`database.dbname: feedsystem`	最低

为什么要这样设计

开发环境：
 用YAML文件，配置写死在代码里，方便开发

Docker部署：
 用环境变量覆盖，不用改配置文件

 docker run -e MYSQL_DATABASE=feedsystem -e JWT_SECRET=*** ...

环境变量覆盖的好处

场景	做法
本地开发	用 YAML 文件的默认配置
Docker 部署	用环境变量覆盖数据库地址、密码等
生产环境	用环境变量覆盖，敏感信息不写进代码

启动时指定配置文件

# 本地开发
cd backend && CONFIG_PATH=configs/config.yaml go run ./cmd

# Docker Compose本地
cd backend && CONFIG_PATH=configs/config.compose-local.yaml go run ./cmd

API 进程和 Worker 进程为什么要分开

两个进程

cmd/
├── main.go # API进程（处理HTTP请求）
└── worker/
 └── main.go # Worker进程（消费MQ消息）

各自做什么

	API 进程	Worker 进程
职责	处理 HTTP 请求	消费 MQ 消息
入口	`go run ./cmd`	`go run ./cmd/worker`
启动方式	接收 HTTP 请求	订阅 MQ 队列

为什么要分开

1. 职责不同

API进程：用户发请求 → 处理 → 返回响应（要求快）
Worker进程：从MQ取消息 → 更新DB、推送通知（可以慢）

2. 独立扩展

场景：API扛不住了

没分开：只能整体加机器
分开后：只加API机器，Worker不动

场景：Worker扛不住了

分开后：只加Worker机器，API不动

3. 故障隔离

Worker崩了：不影响API，用户还能正常访问
API崩了：不影响Worker，后台任务还在处理

4. 资源分配不同

API进程：需要低延迟，分配更多CPU
Worker进程：可以容忍高延迟，分配更多内存

Docker Compose 里的配置

backend:
 build:
 dockerfile: backend/Dockerfile
 target: api  # 构建API镜像

worker:
 build:
 dockerfile: backend/Dockerfile
 target: worker  # 构建Worker镜像

同一个 Dockerfile，用不同的 target 构建两个镜像。

pprof（性能分析）

pprof 是什么

Go 内置的性能分析工具，帮你找出程序哪里慢、哪里吃内存。

能分析什么

类型	作用
CPU	哪个函数最耗 CPU
内存	哪个函数最耗内存
goroutine	有没有 goroutine 泄漏
阻塞	哪里卡住了

配置

observability:
 pprof:
 enabled: true
 api_addr: localhost:6060  # API进程的pprof端口
 worker_addr: localhost:6061  # Worker进程的pprof端口

启动后，访问 http://localhost:6060/debug/pprof/ 就能看到性能数据。

常用命令

# CPU分析（30秒）
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# 内存分析
go tool pprof http://localhost:6060/debug/pprof/heap

# goroutine分析
go tool pprof http://localhost:6060/debug/pprof/goroutine

场景举例

用户反馈：API响应慢

1. 用pprof抓CPU分析
2. 发现某个函数占了80%的CPU时间
3. 优化这个函数
4. 响应变快了

CI 流程（持续集成）

CI 是什么

代码推送到 GitHub 后，自动运行检查，确保代码质量。

这个项目的 CI

# .github/workflows/ci.yml
jobs:
 test:
 steps:
 - go vet ./...  # 静态检查
 - go test -race ./...  # 运行测试，检测数据竞争

go vet 是什么

静态分析，找出语法错误和可疑代码，不需要运行程序。

举例：
- 变量声明了但没用
- 格式化字符串参数不对
- 死代码（永远不会执行的代码）

go test -race 是什么

运行测试，同时检测数据竞争。

什么是数据竞争

多个 goroutine 同时读写同一个变量，没有加锁。

// 数据竞争的例子
var count int

go func() { count++ }() // goroutine1写
go func() { count++ }() // goroutine2写

// 两个goroutine同时写count，结果不确定

-race 怎么检测

go test -race ./...

如果发现数据竞争：
 WARNING: DATA RACE
 Write by goroutine 1
 Read by goroutine 2
 ...
 FAIL

CI 流程

开发者推送代码到GitHub
 ↓
GitHub Actions自动触发
 ↓
go vet ./... → 静态检查
 ↓
go test -race ./... → 运行测试 + 检测数据竞争
 ↓
全部通过 → 绿色 ✅
有失败 → 红色 ❌，不允许合并

好处

	没有 CI	有 CI
代码质量	靠人工 review	自动检查
数据竞争	上线后才发现	提交时就发现
合并代码	随便合并	检查通过才能合并

启动脚本（start.sh）

一键启动所有服务

./start.sh

相关文件：~/dev/projects/feedsystem_video_go/start.sh

脚本是什么语言写的

Bash（Shell 脚本），文件扩展名 .sh = Shell 脚本。

#!/usr/bin/env bash # 声明用bash解释器
set -euo pipefail # 遇到错误立刻停止

Bash 是 Linux/macOS 终端的脚本语言，用来自动化命令行操作。

脚本做的事

1. 启动Redis（如果没有运行）
2. 启动RabbitMQ（通过Docker Compose）
3. 启动Backend（go run ./cmd）
4. 启动Worker（go run ./cmd/worker）
5. 启动Frontend（npm run dev）
6. Ctrl+C停止所有服务

核心逻辑

# 启动Redis
start_redis() {
 redis-server --bind 127.0.0.1 --port 6379
}

# 启动RabbitMQ（通过Docker Compose）
start_rabbitmq_compose() {
 docker compose up -d rabbitmq
}

# 启动Backend
start_backend_bg() {
 cd backend && go run ./cmd &
}

# 启动Worker
start_worker_bg() {
 cd backend && go run ./cmd/worker &
}

# 启动Frontend
start_frontend_bg() {
 cd frontend && npm run dev &
}

# Ctrl+C停止所有服务
trap cleanup INT TERM EXIT
cleanup() {
 kill $BACKEND_PID
 kill $WORKER_PID
 kill $FRONTEND_PID
 docker compose stop
}

环境变量控制

START_REDIS=1 # 是否启动Redis
START_RABBITMQ=1 # 是否启动RabbitMQ
START_BACKEND=1 # 是否启动Backend
START_WORKER=1 # 是否启动Worker
START_FRONTEND=1 # 是否启动Frontend

可以按需启动：

# 只启动Backend和Worker
START_FRONTEND=0 ./start.sh

面试要点总结

Q: Docker Compose 怎么保证启动顺序？

A: depends_on + healthcheck，服务健康了才启动下一个。

Q: 配置优先级？

A: 环境变量 > .env 文件 > YAML 文件。

Q: API 和 Worker 为什么要分开？

A: 职责不同、独立扩展、故障隔离、资源分配不同。

Q: pprof 能分析什么？

A: CPU、内存、goroutine、阻塞。

Q: CI 做了什么？

A: go vet 静态检查 + go test -race 检测数据竞争。

Q: 什么是数据竞争？

A: 多个 goroutine 同时读写同一个变量，没有加锁。用 go test -race 检测。

Q: 为什么要用 healthcheck？

A: 确保服务真正能接受连接，而不是只启动了容器。

Go 项目反推：Feed 流系统实战——消息队列与异步架构

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——Redis 缓存设计，这一篇继续反推 feedsystem_video_go 的消息队列与异步架构，梳理 RabbitMQ 的消息路由、消费重试、降级策略、Outbox 模式和死信队列。

什么是消息队列（MQ）

想象一个餐厅：

没有 MQ：顾客点餐 → 厨师做完一个才能做下一个 → 顾客等着
有 MQ：顾客点餐 → 写在小票上放窗口 → 厨师按顺序做 → 做好了喊号

消息队列就是那个"窗口"，消息就是"小票"。

为什么需要消息队列

用户点赞后要做的事：

用户点赞 → 更新Like表 → 更新Video点赞数 → 更新热度 → 推送通知 → 返回成功

没有 MQ 的问题：

用户等太久（每个操作都要时间）
任何一个失败，整个流程卡住
高并发时 DB 扛不住

有了 MQ：

用户点赞 → 更新Like表 → 发一条"点赞消息"到MQ → 立刻返回成功
 ↓
 Worker从MQ取消息 → 更新点赞数 → 更新热度 → 推送通知

好处：

用户不用等所有操作完成，体验快
点赞服务和热度计算服务解耦，改一个不影响另一个
高并发时消息排队，DB 不会被打垮

MQ 的三个核心概念

概念	比喻	作用
Exchange	邮局	接收消息，根据规则分发
Queue	邮箱	存储消息，等 Worker 来取
Routing Key	地址	消息的"目的地"，Exchange 根据它决定放哪个 Queue

流程：

生产者（点赞服务） → 发消息到Exchange → Exchange根据Routing Key → 放到Queue → Worker从Queue取消息消费

三种 Exchange 类型

类型	规则	举例
Direct	Routing Key 完全匹配	发到"like.like"，只有绑定了"like.like"的 Queue 才能收到
Topic	支持通配符（* 和 #）	发到"like.*"，能匹配"like.like"、“like.unlike”
Fanout	广播，忽略 Routing Key	发到所有绑定的 Queue，每个 Queue 都能收到

这个项目用的是 Topic Exchange。

项目里的 6 种 MQ

Exchange	Routing Key	用途
like.events	like.like / like.unlike	点赞/取消点赞
comment.events	comment.publish / comment.delete	评论/删除评论
social.events	social.follow / social.unfollow	关注/取关
video.popularity.events	video.popularity.update	热度更新
video.timeline.events	video.timeline.publish	视频发布
dlx.events	#	死信队列（重试/告警）

代码实现

MQ 相关文件

backend/internal/middleware/rabbitmq/
├── rabbitMQ.go # MQ基础封装（连接、Channel、DeclareTopic、PublishJSON）
├── dlx.go # 死信队列声明和重试计数
├── likeMQ.go # 点赞MQ
├── commentMQ.go # 评论MQ
├── socialMQ.go # 关注MQ
├── popularityMQ.go # 热度MQ
└── timelineMQ.go # Feed流MQ（Outbox模式）

Worker 相关文件

backend/internal/worker/
├── likeworker.go # 点赞Worker
├── commentworker.go # 评论Worker
├── socialworker.go # 关注Worker
├── popularityworker.go # 热度Worker
├── outboxworker.go # Outbox定时任务
├── notificationworker.go # 通知Worker
└── ssehub.go # SSE推送Hub

消息生产（发消息）

rabbitMQ.go - PublishJSON

func PublishJSON(ctx context.Context, ch *amqp.Channel, exchange string, routingKey string, payload any) error {
 b, _ := json.Marshal(payload) // 第1步：把数据变成JSON
 return ch.PublishWithContext(ctx, exchange, routingKey, false, false, amqp.Publishing{
 ContentType: "application/json", // 第2步：告诉MQ这是JSON格式
 DeliveryMode: amqp.Persistent, // 第3步：消息持久化
 Body: b, // 第4步：消息内容
 })
}

逐行解释：

json.Marshal(payload)：把 Go 结构体变成 JSON 字节
ch.PublishWithContext(...)：调用 MQ 客户端，发一条消息
exchange：发到哪个 Exchange（邮局）
routingKey：消息地址（like.like）
amqp.Persistent：消息存到磁盘，MQ 重启不丢
Body: b：消息内容

消息长什么样

{
 "video_id": 123,
 "account_id": 456,
 "event_type": "like.like",
 "timestamp": "2026-07-28T14:30:00Z"
}

就是一个 JSON，告诉 Worker"用户 456 给视频 123 点了赞"。

消息消费（Worker 处理）

likeworker.go - Run

func (w *LikeWorker) Run(ctx context.Context) error {
 deliveries, err := w.ch.Consume(w.queue, "", false, false, false, false, nil)

 for {
 select {
 case <-ctx.Done():
 return ctx.Err()
 case d, ok := <-deliveries:
 if !ok {
 return errors.New("deliveries channel closed")
 }
 w.handleDelivery(ctx, d)
 }
 }
}

逐行解释：

w.ch.Consume(w.queue, ...)：从 Queue 订阅消息，返回一个 channel
for { select { ... } }：循环读消息，有消息来就处理
w.handleDelivery(ctx, d)：调用处理函数，执行业务逻辑

handleDelivery - 重试逻辑

func (w *LikeWorker) handleDelivery(ctx context.Context, d amqp.Delivery) {
 const maxRetries = 3
 for i := 0; i <= maxRetries; i++ {
 if err := w.process(ctx, d.Body); err != nil {
 if i >= maxRetries {
 // 超过3次，放弃，Ack删除消息
 log.Printf("like worker: 重试 %d 次后仍失败, 丢弃", maxRetries)
 _ = d.Ack(false)
 return
 }
 // 等一下再重试（指数退避）
 wait := time.Duration(1<<uint(i)) * time.Second // 1s, 2s, 4s
 log.Printf("like worker: 处理失败, %v 后重试 (%d/%d)", wait, i+1, maxRetries)
 time.Sleep(wait)
 continue
 }
 // 成功，Ack删除消息
 _ = d.Ack(false)
 return
 }
}

重试流程：

第1次处理 → 失败 → 等1秒
第2次处理 → 失败 → 等2秒
第3次处理 → 失败 → 等4秒
第4次处理 → 失败 → 放弃，Ack删除消息

指数退避（1s → 2s → 4s）

1<<uint(i) 是位运算：

i=0: 1«0 = 1秒
i=1: 1«1 = 2秒
i=2: 1«2 = 4秒

为什么要等这么久？避免疯狂重试打垮服务器。

为什么失败了还 Ack？

不 Ack 的话，消息会一直留在 Queue 里，Worker 会一直重试，卡住后面的消息。Ack 后消息从 Queue 删除，避免阻塞。

MQ 发布失败的降级策略

场景：用户点赞成功，DB 写入了，但发 MQ 消息失败了。

如果直接忽略：热度不会更新，点赞数据和热度不一致。

fallback 直写

func (s *LikeService) publishLikeEvent(ctx context.Context, videoID, accountID uint, routingKey string) {
 event := LikeEvent{VideoID: videoID, AccountID: accountID}

 err := rabbitmq.PublishJSON(ctx, s.ch, "like.events", routingKey, event)
 if err != nil {
 // MQ发送失败，降级：直接更新热度
 go s.popularityWorker.HandleLikeEvent(event)
 }
}

意思：

MQ 能用 → 走 MQ 异步处理
MQ 挂了 → 直接调 Worker 的处理函数，同步处理

为什么不用重试？如果 MQ 挂了，重试大概率还是失败，用户要等很久。直接降级：虽然绕过了 MQ，但保证功能正常，用户体验不受影响。

Outbox 模式

什么是 Outbox 模式

发视频时用的模式。

场景：用户发视频 → 更新 DB → 发 MQ 消息

问题：如果 DB 更新成功，MQ 发送失败，视频发布了但 Feed 流里没有。

为什么不能放在一个事务里？DB 和 MQ 是两个系统，没法用一个事务包起来。

Outbox 的解法

把 MQ 消息先存到数据库里，用数据库事务保证一致性：

数据库事务（保证原子性）：
 INSERT INTO videos (title, play_url, ...) VALUES (...)
 INSERT INTO outbox_msgs (video_id, status) VALUES (xxx, 'pending')
 COMMIT

两步在同一个 DB 事务里，要么都成功，要么都失败。

然后用定时任务把消息发出去：

OutboxPoller（每秒运行一次）：

 查询：SELECT * FROM outbox_msgs WHERE status = 'pending'

 对于每条消息：
 发MQ消息
 更新：UPDATE outbox_msgs SET status = 'sent' WHERE id = xxx

OutboxMsg 表结构

type OutboxMsg struct {
 ID uint
 VideoID uint
 EventType string
 CreateTime time.Time
 Status string // "pending" 或 "sent"
}

完整流程

00:00 用户发视频
 → 写Video表 + 写OutboxMsg表（同一个事务，保证原子）

00:01 OutboxPoller扫到这条消息
 → 发MQ消息成功
 → 标记为sent

00:02 Worker收到MQ消息
 → 更新Feed流

为什么这样能保证消息不丢？

消息先存在 DB 里，和业务数据在同一个事务
定时任务保证最终会发出去
即使 MQ 暂时挂了，消息还在 DB 里，等 MQ 恢复了再发

回滚只发生在 DB 层面

数据库事务：
 INSERT INTO videos ... → 成功
 INSERT INTO outbox_msgs ... → 失败
 ROLLBACK → 两个都撤销

MQ 发送失败不回滚：

数据库事务：COMMIT（消息已经存到outbox_msgs表了）

OutboxPoller：
 发MQ消息 → 失败（MQ挂了）

 → 不回滚！消息还在outbox_msgs表里
 → 等MQ恢复了，下次扫描再发

为什么发视频用 Outbox，点赞不用？

场景	方案	原因
点赞	直接发 MQ + fallback	点赞失败可以重试，用户能接受
发视频	Outbox 模式	视频必须进 Feed 流，不能丢

视频发布是关键业务，不能丢消息，所以用 Outbox 保证"至少发一次"。

死信队列（DLX）

什么是死信队列

消息"死了"（消费失败），放到一个专门的队列里等处理。

就像快递派送失败：

正常流程：快递 → 送到你家 → 签收

派送失败：快递 → 送到你家 → 没人签收 → 退回快递站（死信队列）
 → 重新派送（重试）
 → 联系收件人（告警）

消息为什么会"死"

原因	举例
业务逻辑报错	热度计算除零了
消费超时	Worker 处理太久，MQ 等不及了
拒绝消息	代码里主动 reject

正常消费流程

Worker从Queue取消息
 ↓
处理成功 → msg.Ack() → MQ删除消息

消费失败了

Worker从Queue取消息
 ↓
处理失败 → msg.Nack() 或 超时
 ↓
MQ把消息放到死信队列（DLX）
 ↓
死信Worker处理：
 - 记录日志
 - 重试（最多N次）
 - 超过重试次数 → 告警/人工处理

dlx.go - DeclareDLX

const DLXExchange = "dlx.events"
const MaxRetryCount = 3

func DeclareDLX(ch *amqp.Channel, queueName string) error {
 // 1. 声明死信Exchange
 ch.ExchangeDeclare(DLXExchange, "topic", true, false, false, false, nil)

 // 2. 声明死信Queue（名字是 原Queue名 + ".dlx"）
 dlxQueue := queueName + ".dlx"
 ch.QueueDeclare(dlxQueue, true, false, false, false, nil)

 // 3. 绑定：# 匹配所有Routing Key
 ch.QueueBind(dlxQueue, "#", DLXExchange, false, nil)
}

like.events 的死信队列叫 like.events.dlx
comment.events 的死信队列叫 comment.events.dlx

GetRetryCount - 获取重试次数

func GetRetryCount(d amqp.Delivery) int {
 deaths, ok := d.Headers["x-death"].([]interface{})
 if !ok || len(deaths) == 0 {
 return 0
 }
 death, ok := deaths[0].(amqp.Table)
 if !ok {
 return 0
 }
 count, ok := death["count"].(int64)
 if !ok {
 return 0
 }
 return int(count)
}

MQ 会自动在消息头里记录"这条消息死了几次"，从 x-death 里取出来。

正常 Queue 声明时绑定 DLX

func DeclareTopic(ch *amqp.Channel, exchange string, queue string, bindingKey string) error {
 // 声明Exchange
 ch.ExchangeDeclare(exchange, "topic", true, false, false, false, nil)

 // 声明Queue，绑定死信Exchange
 q, err := ch.QueueDeclare(queue, true, false, false, false,
 amqp.Table{"x-dead-letter-exchange": DLXExchange})

 // 绑定：Queue订阅Exchange的消息
 ch.QueueBind(q.Name, bindingKey, exchange, false, nil)
}

x-dead-letter-exchange：告诉 MQ，这个 Queue 的消息如果"死了"，发到 DLXExchange。

完整流程举例

正常流程：
 点赞 → like.events Queue → LikeWorker消费 → 成功 → Ack

失败流程：
 点赞 → like.events Queue → LikeWorker消费 → 失败 → Nack
 ↓
 like.events.dlx Queue（死信队列）
 ↓
 死信Worker处理（重试/告警）

API 进程和 Worker 进程为什么要分开

cmd/
├── main.go # API进程（处理HTTP请求）
└── worker/
 └── main.go # Worker进程（消费MQ消息）

分开的原因：

职责不同：API 处理请求，Worker 处理后台任务
独立扩展：API 扛不住加 API 机器，Worker 扛不住加 Worker 机器
故障隔离：Worker 崩了不影响 API，API 崩了不影响 Worker
资源分配：API 需要低延迟，Worker 可以容忍高延迟

ch.Qos(50, 0, false) - 预取数量控制

ch.Qos(50, 0, false)

50：每次最多取 50 条消息
0：不限制消息大小
false：只对当前 Channel 生效

为什么要控制预取数量？

太多：Worker 内存爆了
太少：Worker 闲着没事干
50：平衡点，Worker 处理完一批再取下一批

面试要点总结

Q: 为什么用 MQ？

A: 削峰（高并发时消息排队）、解耦（点赞服务和热度计算独立）、异步（用户不用等所有操作完成）。

Q: MQ 发布失败了怎么办？

A: 降级策略，直接调 Worker 的处理函数同步处理。点赞用 fallback 直写，发视频用 Outbox 模式保证消息不丢。

Q: Outbox 模式是什么？

A: 把 MQ 消息先存到数据库里，用 DB 事务保证一致性。定时任务扫描 outbox_msgs 表，发 MQ 消息，标记已发送。

Q: 死信队列怎么用的？

A: 消息消费失败时，MQ 自动把消息放到死信队列。Worker 里有重试逻辑，最多重试 3 次，指数退避（1s→2s→4s），超过 3 次放弃。

Q: API 进程和 Worker 进程为什么要分开？

A: 职责不同、独立扩展、故障隔离、资源分配不同。

Q: 什么是指数退避？

A: 重试间隔按 2 的幂次增长（1s→2s→4s），避免疯狂重试打垮服务器。

Q: 三种 Exchange 的区别？

A: Direct 精确匹配，Topic 支持通配符，Fanout 广播到所有 Queue。

Q: 为什么点赞用 fallback，发视频用 Outbox？

A: 点赞失败用户能接受重试，视频发布是关键业务不能丢消息。Outbox 保证"至少发一次"。

Go 项目反推：Feed 流系统实战——Redis 缓存设计

Tue, 28 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——数据库与 GORM，这一篇继续反推 feedsystem_video_go 的 Redis 设计，梳理缓存读写、一致性与高并发防护，以及 Lua 限流和 ZSET 热榜的实现。

项目里 Redis 的 7 种用途

#	用途	数据结构	Key模式
1	JWT Token 缓存	String	`account:<id>`
2	Refresh Token 缓存	String	`account:<id>:refresh` / `refresh:<token>`
3	视频详情缓存	String(JSON)	`video:detail:id=<id>`
4	视频实体缓存	String(JSON)	`video:entity:<id>`
5	热榜	ZSET	`hot:video:1m:<时间窗口>`
6	分片上传会话	String(JSON)	`chunk_upload:<upload_id>`
7	接口限流	String(计数器)	`ratelimit:<prefix>:<subject>`

1. 缓存读取流程（video_service.go 的 GetDetail）

func (vs *VideoService) GetDetail(ctx context.Context, id uint) (*Video, error) {
 cacheKey := vs.cache.Key("video:detail:id=%d", id)

 // 第一步：查缓存（50ms 超时）
 getCached := func() (*Video, bool) {
 opCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
 defer cancel()

 b, err := vs.cache.GetBytes(opCtx, cacheKey)
 if err != nil {
 return nil, false // 缓存没命中
 }
 var cached Video
 if err := json.Unmarshal(b, &cached); err != nil {
 return nil, false // 数据损坏
 }
 return &cached, true // 缓存命中
 }

 // 尝试读缓存
 if v, ok := getCached(); ok {
 return v, nil // 命中，直接返回
 }

 // 缓存没命中，查数据库...
}

为什么缓存读取要设 50ms 超时？

50ms 超时不是判断"没命中"，而是防止 Redis 卡住的降级策略：

缓存没命中：Redis 快速返回"key 不存在"，几毫秒就完成
Redis 卡住：网络抖动、Redis 内部阻塞、连接池耗尽，可能卡几秒

没有超时：Redis 卡住 → 请求一直等着 → 用户体验很差有 50ms 超时：Redis 超过 50ms 没响应 → 放弃缓存 → 直接查数据库

为什么不设更短的超时，比如 5ms？

Redis 正常操作本身需要几毫秒，设 5ms 正常情况都可能超时，缓存形同虚设。50ms 是平衡点：覆盖正常操作 + 轻微网络波动，同时不会让用户等太久。

2. 缓存写入

setCached := func(video *Video) {
 b, err := json.Marshal(video)
 if err != nil {
 return
 }
 opCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
 defer cancel()
 _ = vs.cache.SetBytes(opCtx, cacheKey, b, vs.cacheTTL)
}

为什么缓存要设过期时间（TTL）？

TTL = Time To Live，缓存的"保质期"。

主要原因：数据一致性

09:00 缓存存了视频标题"今天天气真好"
09:05 作者把标题改成"今天下雨了"
 → 数据库更新了，但缓存还是旧的
09:06 用户查这个视频 → 从缓存读到"今天天气真好"
 → 看到的是过期数据

没有 TTL：缓存永远是旧数据，用户看到的和数据库不一致有了 TTL（比如 10 分钟）：最多 10 分钟后缓存自动过期，下次请求加载最新数据

这是用时间换一致性：允许短暂不一致，但最终会一致。

次要原因：缓存空间有限

缓存满了需要淘汰旧数据，TTL 帮助自动清理。

3. 缓存删除（主动失效）

为什么不等 TTL 过期，要主动删缓存？

看 video_service.go 删视频时：

func (vs *VideoService) DeleteVideo(ctx context.Context, id uint) error {
 // 先删数据库
 if err := vs.repo.DeleteVideo(ctx, id); err != nil {
 return err
 }
 // 再删缓存
 if vs.cache != nil {
 cacheKey := vs.cache.Key("video:detail:id=%d", id)
 _ = vs.cache.Del(context.Background(), cacheKey)
 }
 return nil
}

DB 更新后立刻删缓存，下次请求来了缓存没命中，从数据库加载最新数据。

4. 缓存和 DB 的一致性策略

两种方案对比

方案	做法	风险
先删缓存，再更新 DB	删缓存 → 写 DB	删完缓存、还没写 DB 时，另一个请求读 DB 旧数据写入缓存
先更新 DB，再删缓存	写 DB → 删缓存	写完 DB、还没删缓存时，另一个请求读到旧缓存

为什么"先更新 DB 再删缓存"更安全？

方案 1：先删缓存，再更新 DB

00:00 请求A：删缓存
00:01 请求B：查视频 → 缓存没命中 → 从DB读到旧数据 → 写入缓存
00:02 请求A：更新DB为新数据

结果：DB是新数据，缓存里是旧数据（脏数据）

发生概率不低，因为"删缓存"到"更新 DB"之间可能有几百毫秒（DB 写入比 Redis 慢）。

方案 2：先更新 DB，再删缓存

00:00 请求A：更新DB为新数据
00:01 请求B：查视频 → 从缓存读到旧数据（概率小）
00:02 请求A：删缓存

结果：即使请求B读到旧缓存，00:02缓存就被删了

出问题窗口极小：必须在"更新 DB"和"删缓存"之间，恰好有另一个请求来读。

共同风险点：删缓存失败了怎么办？

00:00 更新DB成功 → DB是新数据
00:01 删缓存失败（网络抖动、Redis挂了）
 → 缓存还是旧数据

解决方案：靠 TTL 兜底

代码里删缓存都用了 _ = 忽略错误：

_ = vs.cache.Del(context.Background(), cacheKey)

即使删缓存失败，最多等 TTL 过期（比如 10 分钟），缓存自动失效，下次请求从 DB 加载新数据。

这是最终一致性：允许短暂不一致，但最终会一致。

5. 缓存穿透/击穿/雪崩

三个概念的区别

问题	现象	危害
缓存穿透	查询不存在的数据，缓存永远没命中	每次请求都打到 DB
缓存击穿	热点 key 过期，大量请求同时打到 DB	DB 瞬间压力暴增
缓存雪崩	大量 key 同时过期	DB 瞬间压力暴增

缓存击穿的解法（这个项目用的）

场景：一个热门视频的缓存过期了，100 个用户同时请求

// 缓存没命中，尝试获取分布式锁
lockKey := "lock:" + cacheKey
token, locked, lockErr := vs.cache.Lock(lockCtx, lockKey, 2*time.Second)

if lockErr == nil && locked {
 // 拿到锁：去查DB，回填缓存
 defer func() { _ = vs.cache.Unlock(context.Background(), lockKey, token) }()

 video, err := vs.repo.GetByID(ctx, id)
 if err != nil {
 return nil, err
 }
 setCached(video)
 return video, nil
}

// 没拿到锁：等待别人回填缓存（最多100ms）
for i := 0; i < 5; i++ {
 time.Sleep(20 * time.Millisecond)
 if v, ok := getCached(); ok {
 return v, nil // 别人已经回填了，直接用
 }
}

// 降级：直接查DB
video, err := vs.repo.GetByID(ctx, id)

核心逻辑：让一个请求干活，其他请求等着用结果

❌ 没有锁的击穿场景：
100个请求同时来 → 缓存没命中 → 100个都去查DB → DB压力x100

✅ 有锁的保护：
100个请求同时来 → 缓存没命中
 ↓
请求1：拿到锁 → 查DB → 写缓存 → 返回
请求2-100：没拿到锁 → 等20ms → 查缓存 → 命中 → 返回

时序示例（DB 查询 15ms）：

00:00 请求1拿到锁，开始查DB（耗时15ms）
 请求2-100没拿到锁，开始sleep 20ms
00:15 请求1查完DB，写入缓存
00:20 请求2-100醒来，查缓存 → 命中！

降级策略（DB 查询很慢时）：

请求 2-100 最多等 100ms（5次x20ms），如果请求 1 还没完成，降级去查 DB。

但这种情况很少见，DB 查询通常几毫秒到几十毫秒。

缓存穿透的解法（这个项目没做）

缓存穿透：查询不存在的数据，比如 GET /video/999999999，数据库里没有，每次请求都打到 DB。

方案	做法
缓存空值	查 DB 没结果，也写入缓存（value=""），设短 TTL
布隆过滤器	在缓存前加一层，快速判断 key 是否存在

项目为什么没做：视频 ID 通过 Feed 流返回，不存在"查不存在 ID"的正常场景。接口有限流保护，攻击成本高。

缓存雪崩的解法（这个项目没做）

缓存雪崩：大量 key 同时过期，DB 瞬间压力暴增。

方案	做法
随机 TTL	给缓存 TTL 加随机值，避免同时过期
多级缓存	L1 本地缓存 + L2 Redis 缓存
永不过期 + 异步更新	缓存不设 TTL，由后台任务定期更新

项目用的是固定 TTL，没做随机化，业务量可控。

6. 限流中间件（ratelimit.go）

限流是什么？

防止用户发太多请求打垮服务器。像银行取号机：每分钟最多服务 100 个人，第 101 个人来了告诉他"请稍后再来"。

限流中间件是什么？

Gin 中间件，所有请求都要经过它：

用户请求 → 限流中间件检查 → 通过 → handler处理 → 返回
 ↓
 超限 → 直接返回429 "too many requests"

限流实现原理

func Limit(cache *rediscache.Client, keyPrefix string, maxRequests int64, window time.Duration, keyFunc KeyFunc) gin.HandlerFunc {
 return func(c *gin.Context) {
 subject, ok := keyFunc(c)
 key := buildKey(keyPrefix, subject)

 count, err := cache.IncrementWithExpire(c.Request.Context(), key, window)
 if err != nil {
 c.Next()
 return
 }
 if count > maxRequests {
 c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{"error": "too many requests"})
 return
 }
 c.Next()
 }
}

IncrementWithExpire 的 Lua 脚本

local count = redis.call("INCR", KEYS[1])
if count == 1 then
 redis.call("PEXPIRE", KEYS[1], ARGV[1])
end
return count

限流流程（1 分钟内最多 100 次）：

00:00.000 请求1来 → INCR → count=1
 因为count==1，是第一个请求
 → PEXPIRE设60000毫秒（60秒）过期

00:00.001 请求2来 → INCR → count=2
 count!=1，不设过期（沿用之前的）

...

00:00.500 请求100来 → INCR → count=100
 → 通过（100 <= 100）

00:00.600 请求101来 → INCR → count=101
 → 拒绝！（101 > 100）
 → 返回429 "too many requests"

01:00.000 key自动过期，Redis删除这个key
 计数器归零

01:00.001 请求来 → INCR → count=1（重新开始计数）
 → PEXPIRE重新设60秒
 → 通过

为什么用 Lua 脚本？

原子执行 = 两条命令之间不会有其他命令插队

没有 Lua 脚本（可能被插队）：

00:00 你的程序：INCR key → count=1
00:01 另一个程序：INCR key → count=2
00:02 你的程序：EXPIRE key 60秒
00:03 另一个程序：EXPIRE key 60秒

你的 INCR 和 EXPIRE 之间，被别人插队了。

有 Lua 脚本（不会插队）：

00:00 你的程序：开始执行Lua脚本
 INCR key → count=1
 EXPIRE key 60秒
00:01 Lua脚本执行完，其他程序才能执行

注意：原子执行 ≠ 回滚，原子执行 = 不插队

如果 INCR 成功了，EXPIRE 失败了，INCR 的结果不会撤销。

为什么需要原子执行？

如果分开写：

count = redis.INCR(key) // count=1
// 这里程序崩了，EXPIRE没执行
redis.EXPIRE(key, 60秒) // 没执行到

结果：key 永远不过期，计数永远不会归零，限流永久生效。

Lua 脚本保证 INCR 和 EXPIRE 一起执行，不会出现"只执行了一半"的情况。

EXPIRE 和 PEXPIRE

EXPIRE：单位是秒
PEXPIRE：单位是毫秒

限流的 key 设计

func buildKey(keyPrefix, subject string) string {
 return fmt.Sprintf("feedsystem:ratelimit:%s:%s", keyPrefix, strings.TrimSpace(subject))
}

两种维度：

KeyByIP：按 IP 限流，防止单 IP 攻击
KeyByAccount：按用户 ID 限流，防止单用户刷接口

7. ZSET 热榜（popularity_cache.go）

ZSET 是什么？

Redis 的有序集合，每个元素有一个分数，自动按分数排序。

ZSET "热榜"
┌─────────┬─────────┐
│ 元素 │ 分数 │
├─────────┼─────────┤
│ video_5 │ 1000 │ ← 最热
│ video_2 │ 800 │
│ video_8 │ 500 │
│ video_1 │ 100 │ ← 最冷
└─────────┴─────────┘

热榜更新代码

func UpdatePopularityCache(ctx context.Context, cache *rediscache.Client, id uint, change int64) {
 // 删掉旧缓存
 _ = cache.Del(context.Background(), cache.Key("video:detail:id=%d", id))
 _ = cache.Del(context.Background(), cache.Key("video:entity:%d", id))

 // 写入热榜
 now := time.Now().UTC().Truncate(time.Minute) // 当前时间，精确到分钟
 windowKey := cache.Key("hot:video:1m:%s", now.Format("200601021504")) // 热榜key
 member := strconv.FormatUint(uint64(id), 10) // 视频ID

 _ = cache.ZincrBy(opCtx, windowKey, member, float64(change)) // 热度+change
 _ = cache.Expire(opCtx, windowKey, 2*time.Hour) // 2小时后过期
}

滑动窗口设计

热榜 key 是 hot:video:1m:202607281430，意思是"2026 年 7 月 28 日 14:30 这一分钟的热榜"。

00:00 video_5被点赞 → hot:video:1m:202607281430 → video_5分数+1
00:30 video_5又被点赞 → hot:video:1m:202607281430 → video_5分数+1
01:00 新的一分钟 → hot:video:1m:202607281431

每分钟一个 ZSET，2 小时后自动过期。

为什么要按分钟分窗口？

如果用一个大的 ZSET（不分窗口）：

所有点赞都写到同一个key "hot:video"

1月1日：video_5被点赞1000次，分数=1000，排第一
1月2日：video_8被点赞500次，分数=500
1月3日：video_5被点赞0次，但分数还是1000，还是排第一

问题：旧视频的热度永远不衰减，新视频永远追不上。

按分钟分窗口：

每分钟一个ZSET：

hot:video:1m:202607281430 → 14:30这一分钟的热度
hot:video:1m:202607281431 → 14:31这一分钟的热度
hot:video:1m:202607281432 → 14:32这一分钟的热度

查热榜时，把最近几个窗口合并：

14:35查热榜：
→ 合并 14:30、14:31、14:32、14:33、14:34、14:35 这6个窗口
→ 算总分，排序

好处：

14:30 的热度，到 14:35 时已经衰减了（只有 1/6 权重）
14:35 新产生的热度立刻反映
热榜是"最近几分钟"的热度，不是"历史累计"

ZSET 常用操作

// 分数增加
cache.ZincrBy(ctx, key, member, score)

// 按分数倒序取 top N
cache.ZRevRange(ctx, key, 0, 99) // 取前100名

// 合并多个ZSET
cache.ZUnionStore(ctx, dst, keys, "SUM")

// 设置过期时间
cache.Expire(ctx, key, 2*time.Hour)

面试要点总结

Q: 缓存和 DB 的一致性怎么保证？

A: 先更新 DB，再删缓存。删缓存失败靠 TTL 兜底，最终一致性。

Q: 缓存穿透/击穿/雪崩的区别和解法？

A: 穿透是查不存在的数据（缓存空值/布隆过滤器），击穿是热点 key 过期（分布式锁 + 等待重试），雪崩是大量 key 同时过期（随机 TTL）。

Q: 限流怎么实现的？

A: Redis 计数器，Lua 脚本原子执行 INCR + PEXPIRE，超限返回 429。

Q: 为什么用 Lua 脚本？

A: 保证 INCR 和 EXPIRE 原子执行，不会被其他命令插队，避免"只执行了一半"的问题。

Q: 热榜怎么实现的？

A: ZSET 按分钟分窗口，点赞时 ZincrBy 加分数，查热榜时合并最近几个窗口算总分。分窗口实现热度自动衰减。

Go 项目反推：Feed 流系统实战——数据库与 GORM

Mon, 27 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——认证体系，这一篇继续反推 feedsystem_video_go 的数据库代码，理解表结构、索引设计和 GORM 的常见用法。

理解所有表结构、索引设计、GORM 用法。

1. entity.go 的两种结构体

entity.go 里有两种东西：

1. 存数据库的（有 gorm 标签） → Social struct、Like struct...
2. 不存数据库的（没有 gorm 标签）→ FeedVideoItem、Request、Response...

gorm:"xxx" 标签 = 给 GORM 看的指令（怎么存数据库）
json:"xxx" 标签 = 给 JSON 看的指令（怎么显示给客户端）
两者互不影响，各管各的

2. gorm 标签汇总

标签	含义	示例
`gorm:"primaryKey"`	主键（唯一标识，类似身份证号）	`ID uint gorm:"primaryKey"`
`gorm:"unique"`	唯一（不能重复）	`Username string gorm:"unique"`
`gorm:"index"`	普通索引（加快查询，可以重复）	`VideoID uint gorm:"index"`
`gorm:"uniqueIndex:idx_name"`	唯一索引（不能重复）	`VideoID uint gorm:"uniqueIndex:idx_like_video_account"`
`gorm:"uniqueIndex:idx_name;not null"`	联合唯一索引（多个字段组合唯一）	见 Like 表
`gorm:"index:idx_name,priority:1,sort:desc"`	索引排序优先级	见 Video 表
`gorm:"not null"`	不能为空	`Title string gorm:"not null"`
`gorm:"default:false"`	默认值	`IsRead bool gorm:"default:false"`
`gorm:"autoCreateTime"`	自动填创建时间	`CreateTime time.Time gorm:"autoCreateTime"`
`gorm:"type:varchar(255)"`	字符串长度限制	`Title string gorm:"type:varchar(255)"`
`gorm:"type:text"`	长文本（无固定限制）	`Content string gorm:"type:text"`
`gorm:"column:likes_count"`	指定数据库列名	Go 驼峰 → DB 下划线
`gorm:"-"`	不存数据库	临时字段

3. json 标签

标签	含义
`json:"id"`	JSON 里显示为 “id”
`json:"-"`	JSON 里不显示（密码、Token 等敏感信息）
`json:"description,omitempty"`	空值时不显示这个字段

4. 表结构一览

Account 表（用户表）

ID → 主键
Username → 唯一（不能重复注册）
Password → 不显示在 JSON 里
Token → 不显示在 JSON 里
RefreshToken → 不显示在 JSON 里
AvatarURL → 头像地址
Bio → 个人简介

Video 表（视频表）

ID → 主键
AuthorID → 外键（关联 Account 表，存的是用户ID）
Username → 作者名（冗余存储，方便查询）
Title → 标题
Description → 描述
PlayURL → 播放地址
CoverURL → 封面地址
CreateTime → 自动填创建时间
LikesCount → 点赞数（统计字段）
Popularity → 热度值（统计字段）

Video 表的三个索引：

索引名	排序规则	用途
idx_videos_create_time	CreateTime DESC	最新视频
idx_videos_likes_count_id	LikesCount DESC	最热视频（按点赞）
idx_videos_popularity_time_id	Popularity DESC, CreateTime DESC	综合热度

priority = 优先级，数字越小越优先。

Like 表（点赞表）

ID → 主键
VideoID → 外键 + 联合唯一索引
AccountID → 外键 + 联合唯一索引

联合唯一索引：VideoID + AccountID 的组合不能重复

张三给视频 A 点赞 ✓
张三再给视频 A 点赞 ✗（违反唯一索引）
李四给视频 A 点赞 ✓（不同人）
张三给视频 B 点赞 ✓（不同视频）

为什么需要 Like 表 + Video 表的 LikesCount？

Like 表 → 记录"关系"（谁点了谁）
LikesCount → 记录"总数"（点赞数）
两者配合：Like 管关系，LikesCount 管统计

Comment 表（评论表）

ID → 主键
Username → 普通索引
VideoID → 外键 + 普通索引
AuthorID → 外键 + 普通索引
Content → 长文本（type:text）
CreatedAt → 自动填创建时间

index vs uniqueIndex：

index = 普通索引（可以重复，一个视频可以有很多评论）
uniqueIndex = 唯一索引（不能重复）

ID → 主键
FollowerID → 外键 + 联合唯一索引（谁在关注）
VloggerID → 外键 + 联合唯一索引（关注谁）

联合唯一索引：一个人不能关注同一个人两次。

Tag 表 + VideoTag 表（标签表）

Tag 表：
 ID → 主键
 Name → 唯一索引（标签名不能重复）

VideoTag 表（中间表）：
 ID → 主键
 VideoID → 外键 + 普通索引
 TagID → 外键 + 普通索引

多对多关系：一个视频可以有多个标签，一个标签可以属于多个视频，需要中间表 VideoTag 来记录关系。

Message 表（私信表）

ID → 主键
FromID → 外键 + 普通索引（谁发的）
ToID → 外键 + 普通索引（发给谁）
Content → 长文本
IsRead → 是否已读（默认 false）
CreatedAt → 自动填创建时间

ChunkUploadSession（分片上传）

不是 MySQL 表，存 Redis 的。

UploadID → 上传会话ID
AccountID → 谁在上传
UploadedBits → []bool 位图，记录每片上传状态

FeedVideoItem（Feed 流响应格式）

不是数据库表，是 API 响应格式。

Author → FeedAuthor（包含 ID + Username，不是外键）
IsLiked → 动态计算（查 Like 表），不存在数据库里

5. db.go（数据库初始化）

三个函数：

NewDB() → 连接数据库（DSN 格式：用户名:密码@tcp(地址:端口)/数据库名）
AutoMigrate() → 根据 struct 自动建表/更新表
CloseDB() → 关闭数据库连接

AutoMigrate 的好处：

手动建表：写 SQL，容易忘、容易错
AutoMigrate：改 struct，重启程序，自动更新表

6. repo.go（数据库操作）

每个模块都有自己的 repo.go，包含增删改查操作。

基础套路

// 创建
ar.db.WithContext(ctx).Create(&data)

// 查询（根据ID）
ar.db.WithContext(ctx).First(&result, id)

// 查询（根据条件）
ar.db.WithContext(ctx).Where("username = ?", name).First(&result)

// 更新（单字段）
ar.db.WithContext(ctx).Model(&Account{}).Where("id = ?", id).Update("username", newName)

// 更新（多字段）
ar.db.WithContext(ctx).Model(&Account{}).Where("id = ?", id).Updates(map[string]interface{}{"token": "", "refresh_token": ""})

// 删除
ar.db.WithContext(ctx).Delete(&Like{}).Where("video_id = ? AND account_id = ?", vID, aID)

db.WithContext(ctx) 的作用

把 context 传进去，支持超时取消。

事务（db.Transaction）

ar.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 // 操作1
 tx.Model(&Account{}).Where("id = ?", id).Update("username", newName)
 // 操作2
 tx.Model(&Account{}).Where("id = ?", id).Update("token", token)
 return nil
})

事务 = 要么全做，要么全不做。

类比：银行转账，A 扣钱与 B 加钱必须同时成功或同时失败。

原子操作（gorm.Expr）

// 错误做法：先读再写，并发会出错
likes_count = 100
用户A读到100，用户B读到100
用户A写入101，用户B写入101
结果：只加了1 ❌

// 正确做法：让数据库直接加
gorm.Expr("likes_count + ?", 1)
数据库排队执行：100+1=101, 101+1=102
结果：正确加了2 ✓

GREATEST(likes_count + ?, 0)：防止点赞数变成负数。

LikeIgnoreDuplicate（忽略重复点赞）

err = r.db.WithContext(ctx).Create(like).Error
if err == nil {
 return true, nil // 创建成功
}
// 如果是"重复主键"错误（1062），忽略
var mysqlErr *mysql.MySQLError
if errors.As(err, &mysqlErr) && mysqlErr.Number == 1062 {
 return false, nil // 已经点过赞了，不报错
}

为什么需要这个？

联合唯一索引：保证数据正确（一人只能点一次）
LikeIgnoreDuplicate：保证用户体验（重复点赞不报错）
两个配合：数据对 + 体验好

gorm.ErrRecordNotFound（判断记录不存在）

if err == gorm.ErrRecordNotFound {
 return false, nil // 记录不存在
}

关联查询（Joins）

// 查"张三点赞过的所有视频"
r.db.WithContext(ctx).
 Model(&Video{}).
 Joins("JOIN likes ON likes.video_id = videos.id").
 Where("likes.account_id = ?", accountID).
 Find(&videos)

分步查询（GetAllFollowers）

-- 第1步：从 Social 表查出 follower_id 列表
SELECT follower_id FROM socials WHERE vlogger_id = 1;
-- 得到 [2, 5, 8]

-- 第2步：用 ID 列表去 Account 表查用户信息
SELECT * FROM accounts WHERE id IN (2, 5, 8);

为什么分两步？

Social 表只存 ID（避免数据冗余），Account 表存用户信息。用户改名只改 Account 表，Social 表不用动。

7. 数据库规范化

同一份数据只存一个地方，其他地方只存 ID（外键）。

反范例：Social 表存用户名
 用户改名 → 要更新 Account 表 + Social 表 + 其他表...
 牵一发动全身

正范例：Social 表只存 ID
 用户改名 → 只改 Account 表
 需要名字时，拿着 ID 去 Account 表查

8. 面试要点

1. Video 表为什么有三个索引？

因为有三种查询需求：

idx_videos_create_time → 按时间排序（查最新视频）
idx_videos_likes_count_id → 按点赞数排序（查最热视频）
idx_videos_popularity_time_id → 按热度 + 时间排序（综合排名）

每种查询方式都需要自己的“目录”（索引），没有索引就要全表扫描，很慢。

2. 点赞表为什么使用联合唯一索引？

点赞表用 uniqueIndex:idx_like_video_account，保证 VideoID + AccountID 的组合唯一。一个人只能给一个视频点一次赞，如果重复点赞会违反唯一索引报错。配合 LikeIgnoreDuplicate 函数，重复点赞时静默忽略，不向用户报错。

3. gorm.Expr 是怎么解决并发问题的？

错误做法：先读 likes_count=100，再写 100+1=101。两个用户同时读到 100，都写入 101，结果只加了 1。

正确做法：用 gorm.Expr("likes_count + ?", 1)，让数据库直接执行 likes_count = likes_count + 1，数据库保证原子更新，结果正确。GREATEST(likes_count + ?, 0) 可以防止点赞数变成负数。

4. 改名 + 更新 Token 为什么要用事务？

因为改名后 Token 里的 Username 就过期了，必须同时更新。事务保证“要么全做，要么全不做”：改名成功但更新 Token 失败时回滚，改名也不生效。

如果存用户名，用户改名时要更新 Account 表、Social 表和其他表，牵一发动全身。只存 ID 时，用户改名只改 Account 表，Social 表不用动；需要名字时拿着 ID 去 Account 表查询。

6. Tag 和 Video 为什么需要中间表？

一个视频可以有多个标签，一个标签也可以属于多个视频，这是多对多关系。一个外键字段只能存一个值，因此需要中间表 VideoTag 存储 VideoID + TagID，记录“哪个视频有哪些标签”。

Go 项目反推：Feed 流系统实战——认证体系

Sat, 25 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——请求生命周期，这一篇继续反推 feedsystem_video_go 的认证代码，梳理 JWT、Refresh Token、Token 撤销，以及软硬鉴权中间件之间的关系。

一、jwt.go 文件结构

文件位置：internal/auth/jwt.go

jwtSecret() → 获取密钥
Claims → Token 里存什么
GenerateToken() → 生成 accessToken（JWT 格式，15 分钟）
GenerateRefreshToken() → 生成 refreshToken（随机字符串）
ParseToken() → 验证 Token（签名 + 过期）

二、密钥与 Claims

jwtSecret()：获取密钥

优先使用环境变量 JWT_SECRET，没有就随机生成：

JWT_SECRET=*** go run ./cmd

如果没有设置环境变量，每次服务器启动时密钥都会改变，之前签发的 Token 将全部失效，所有用户都要重新登录。因此正式环境必须设置稳定且足够随机的 JWT_SECRET。

Claims：Token 里存什么

type Claims struct {
 AccountID uint // 用户 ID
 Username string // 用户名
 jwt.RegisteredClaims // 标准字段（过期时间、签发时间等）
}

可以把 Claims 类比为一张有有效期的身份证，上面记录用户名、用户 ID、签发时间和过期时间。

需要注意：JWT Payload 只是经过 Base64URL 编码，并不是加密，客户端也能读取其中的内容。因此 Claims 里不能放密码、密钥等敏感数据。

三、生成 Token

GenerateToken()：生成 accessToken

1. 创建 Claims，写入用户 ID、用户名和 15 分钟后的过期时间
2. 使用 HS256 算法创建 Token 对象
3. 使用 JWT Secret 签名，生成 Token 字符串

结果是一串类似 eyJhbG...xxxx 的 JWT。它内部包含经过编码的 Header 和 Payload，以及用于防止内容被篡改的签名。

HS256 只负责签名和验签，不负责加密。其他人虽然可以读取 Payload，但没有 JWT_SECRET 就无法生成有效签名。

GenerateRefreshToken()：生成 refreshToken

Refresh Token 和 Access Token 完全不同：

accessToken → JWT 格式，携带 Claims，并使用密钥签名
refreshToken → 随机字符串，本身不携带用户信息

项目使用 32 个随机字节，再转换为 64 位十六进制字符串。Refresh Token 不需要携带 Claims，它只需要成为一个难以猜中的长期凭证。

双 Token 时间设定

accessToken 15 分钟：泄露后的可利用时间较短
refreshToken 7 天： 用于换取新的 Access Token，减少重复登录

Access Token 有效期短，降低泄露风险；Refresh Token 有效期长，保证使用体验。二者配合，在安全性和便利性之间取得平衡。

四、验证 Token

ParseToken()：验证 Token

输入：客户端发送的 Token 字符串
输出：Claims（用户 ID、用户名）或错误

流程：

1. 解析 Token
2. 确认签名算法是 HS256
3. 使用 JWT Secret 验证签名
4. 检查 Token 是否过期
5. 全部通过 → 返回 Claims
6. 任一失败 → 返回错误

这里不是“解密 Token”，因为 JWT Payload 没有被加密。服务器做的是解析内容并验证签名。

还需要注意：ParseToken() 只检查格式、签名和过期时间，不检查 Token 是否已被撤销。

五、Refresh 流程

Access Token 过期后，可以使用 Refresh Token 换取新的 Access Token：

客户端：Access Token 过期，这是 Refresh Token，请签发新的 Access Token

服务器：
 1. 使用 Refresh Token 查询 Redis 中的 refresh:<token>
 2. 查询成功后得到 accountID
 3. 查询数据库，确认 Refresh Token 与账户记录匹配
 4. 生成新的 Access Token
 5. 将新 Token 写入数据库和 Redis
 6. 返回给客户端

可以类比为：短期门禁卡过期后，使用长期凭证到前台换一张新卡。

关键点是：使用 Refresh Token 换取 Access Token，而不是反过来。

六、Token 撤销

JWT 的签名和过期时间一旦确定，单靠 ParseToken() 无法让一个尚未过期的 Token 提前失效。因此项目额外在 Redis 和 MySQL 中保存当前有效 Token。

登出时删除旧 Token：

删除 Redis 中的三个 Key：
 account:<id> → accessToken
 account:<id>:refresh → refreshToken
 refresh:<token> → accountID

清空 MySQL 中的字段：
 token
 refresh_token

删除后，即使旧 JWT 的签名正确且尚未过期，中间件也无法在 Redis 或 MySQL 中匹配到它，因此会拒绝请求。

修改密码时也可以使用相同思路：

清空旧 Token
→ 签发新 Token
→ 让其他设备上的旧登录状态立即失效

七、JWTAuth 中间件

文件位置：internal/middleware/jwt/jwt.go

处理流程：

1. 从请求头读取 Authorization
2. 检查格式是否为 Bearer <token>
3. 调用 auth.ParseToken() 验证格式、签名和过期时间
4. 调用 check() 检查 Token 是否仍是当前有效 Token
5. 验证通过后将用户信息写入 Gin Context

客户端发送：

Authorization: Bearer ***

check()：为什么同时查询 Redis 和 MySQL

第一步：查询 Redis
 查到 → 对比请求 Token 是否为当前有效 Token
 相同 → 放行
 不同 → 拒绝，Token 已被替换或撤销

 Redis 未命中或不可用 → 查询 MySQL

第二步：查询 MySQL
 查到账户 → 对比数据库保存的 Token
 相同 → 放行，并回填 Redis
 不同 → 拒绝

Redis 是缓存，速度快但可能未命中或不可用；MySQL 是持久化的数据来源，可以作为兜底。MySQL 本身也可能发生故障，因此更准确的说法是“Redis 失败时降级查询 MySQL”，而不是“MySQL 永远可用”。

check() 主要完成两件事：

将请求中的 Token 与服务器保存的当前 Token 对比，判断是否已被撤销
将用户信息写入 gin.Context，方便后续 Handler 使用

八、两种鉴权

JWTAuth（硬鉴权）：
 没有 Token 或 Token 无效 → 拒绝请求

SoftJWTAuth（软鉴权）：
 没有 Token → 继续放行
 有 Token且有效 → 识别用户身份后放行

项目中的使用示例：

JWTAuth（必须登录）：
 /logout
 /rename
 /uploadAvatar

SoftJWTAuth（不强制登录）：
 /feed/listLatest
 /feed/listByPopularity

用户没有 Token 也能浏览 Feed；携带有效 Token 时，系统可以识别用户并提供个性化结果。

可以类比为：

JWTAuth → 会员俱乐部，没有会员卡不能进入
SoftJWTAuth → 商场，没有会员卡也能进入，有会员卡则能获得个性化服务

九、面试要点

JWT 如何生成：Claims + HS256 + JWT Secret 签名
JWT 不等于加密：Payload 可以读取，签名用于防篡改
双 Token：短期 Access Token + 长期 Refresh Token
Refresh 流程：使用 Refresh Token 换取新的 Access Token
Token 撤销：清理 Redis 与 MySQL 中保存的 Token，使旧 JWT 立即失效
中间件 check()：优先查询 Redis，未命中或不可用时查询 MySQL
两种鉴权：JWTAuth 强制登录，SoftJWTAuth 允许匿名访问

这一套设计实际上让 JWT 从“完全无状态”变成了“带服务端状态的认证方案”。它牺牲了一部分无状态带来的简单扩展能力，换取了主动登出、修改密码后强制失效和单会话控制等能力。

Go 项目反推：Feed 流系统实战——请求生命周期

Tue, 21 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——从 Docker 到开源贡献，这一篇继续反推 feedsystem_video_go 的后端代码。这次不再从整体架构看项目，而是以 POST /account/login 为例，追踪一个请求从进来到返回的完整路径。

路由基础

router.go 是什么

router.go = 路由表 = “地址簿”。它告诉服务器：什么方式 + 访问哪个路径 → 转发到哪个函数。

POST /account/login → accountHandler.Login
POST /account/register → accountHandler.CreateAccount
GET /healthz → 返回 {"status":"ok"}

类比：router.go 是前台接待（“办 login 业务找张三”），handler.go 是张三的工位（“我来处理”）。

路由组

accountGroup := r.Group("/account")

创建一个路由组，前缀是 /account。组里的所有路由，路径前面自动加上前缀：

accountGroup.POST("/login", ...) → 实际路径 POST /account/login
accountGroup.POST("/register", ...) → 实际路径 POST /account/register

类比：把用户相关接口都放在 /account 这个“文件夹”下。

路由注册

accountGroup.POST("/login", loginLimiter, accountHandler.Login)

三个参数：

"/login" → 路径（拼上 /account，变成 /account/login）
loginLimiter → 限流中间件（先过这一关）
accountHandler.Login → 最终处理请求的函数（过了限流才到这里）

请求流程：

POST /account/login 进来
 ↓
loginLimiter（限流中间件）
 ↓
accountHandler.Login（handler 处理）

函数引用 vs 函数调用

accountGroup.POST("/login", loginLimiter, accountHandler.Login)

accountHandler.Login 是函数本身，不是调用。Go 里函数可以当变量传来传去，和 CS61A 的高阶函数一个意思：

accountHandler.Login → 函数本身（把函数“交给”路由器，等有人请求时再调用）
accountHandler.Login(c) → 调用函数（立刻执行）

类比：给你一张纸条写上张三的电话号码（函数引用） vs 现在立刻拨打电话（函数调用）。

现在不执行，等有人发 POST /account/login 时，路由器才会调用 Login(c) 并传入请求信息。

三层架构

结构创建

router.go 第 40-42 行：

accountRepository := account.NewAccountRepository(db)
accountService := account.NewAccountService(accountRepository, cache)
accountHandler := account.NewAccountHandler(accountService)

创建三个“工人”：

Repository → 操作数据库的人（查表、写表）
Service → 处理业务逻辑的人（校验密码、生成 Token）
Handler → 接收请求的人（解析参数、返回结果）

依赖关系：db → Repository → Service → Handler → 路由

类比：先招档案员（Repository）给数据库钥匙，再招业务员（Service）管档案员，再招前台（Handler）对接业务员，最后门口挂牌子（路由）：“办 login 业务找前台”。

Handler 结构体

type AccountHandler struct {
 accountService *AccountService
}

func NewAccountHandler(accountService *AccountService) *AccountHandler {
 return &AccountHandler{accountService: accountService}
}

AccountHandler 是一个结构体，里面有一个字段 accountService。NewAccountHandler 创建这个结构体并把 Service 存进去。

分层的意义

handler 只管：解析请求 → 调用 service → 返回结果
service 处理：校验密码 → 生成 Token → 写数据库
repo 处理： 操作数据库

handler 不关心密码怎么校验、Token 怎么生成，它只管“调用 service”。

文件目录结构

internal/http/router.go → 路由目录，负责“找谁”
internal/account/handler.go → 用户模块，负责“怎么干”
internal/account/service.go → 用户模块，负责“核心逻辑”
internal/account/repo.go → 用户模块，负责“操作数据库”

按模块分目录：account 目录下放所有跟用户相关的代码，video 目录下放所有跟视频相关的代码。

Handler 层：Login 函数

handler.go 第 116-133 行：

func (h *AccountHandler) Login(c *gin.Context) {
 var req LoginRequest // 声明容器
 if err := c.ShouldBindJSON(&req); err != nil { ... } // 解析 JSON
 account, err := h.accountService.FindByUsername(...) // 查数据库存不存在
 accessToken, refreshToken, err := h.accountService.Login(...) // 校验密码+生成Token
 c.JSON(200, LoginResponse{Token, RefreshToken, ...}) // 返回给客户端
}

完整流程：

1. 解析客户端发的 JSON（用户名、密码）
2. 去数据库查这个用户存不存在
3. 存在的话，让 service 校验密码、生成 Token
4. 把 Token 返回给客户端

ShouldBindJSON

c.ShouldBindJSON(&req)

把客户端发的 JSON 解析到 req 变量里。客户端发 {"username": "zhangsan", "password": "***"}，解析后 req.Username = "zhangsan"，req.Password = "123456"。

ShouldBindJSON vs json.NewDecoder：两个干的事一样，都是把 JSON 解析到变量里。c.ShouldBindJSON(&req) 是 Gin 封装的一行搞定；json.NewDecoder(r.Body).Decode(&req) 是原生写法，要三行还要检查 err。类比：自动挡 vs 手动挡。

Service 层：Login 函数

handler 调用 service 的 Login：

accessToken, refreshToken, err := h.accountService.Login(c.Request.Context(), req.Username, req.Password)

service.go 的 Login 做了 6 件事：

1. 查数据库拿用户信息（FindByUsername）
2. bcrypt 校验密码
3. 生成 accessToken 和 refreshToken
4. Token 存进 MySQL（调用 repo.Login）
5. Token 存进 Redis（3 个 key）
6. 返回两个 Token

ctx（context）

ctx = 请求的“身份证”，带着两个信息：

超时时间：这个请求最多等多久
取消信号：客户端断开了，别再查了

每一层都要传 ctx，这样整条链路都能感知到“客户端还在不在”。

类比：你去饭店点菜，等了 5 分钟走了。没有 ctx → 厨师还在炒，炒完发现你走了，菜倒掉。有 ctx → 服务员告诉厨师“客人走了”，厨师立刻停手。

bcrypt 校验密码

bcrypt.CompareHashAndPassword([]byte(account.Password), []byte(password))

传入两个参数：数据库里存的加密密码（哈希）和用户这次输入的明文密码。bcrypt 把明文密码加密，和数据库里的对比，一样返回 nil（成功），不一样返回 error（失败）。

为什么不存明文？数据库被黑了，黑客拿到的是加密字符串，反推不出原始密码。

[]byte() = 把字符串转成字节数组，bcrypt 只接收这种格式。

双 Token（JWT）

登录成功返回两个 Token：

accessToken → 短期有效（15分钟），用来证明“我是谁”
refreshToken → 长期有效（7天），用来续期 accessToken

为什么两个？只用一个 token 的问题：设太短 → 用户每 15 分钟重新登录，体验差；设太长 → 被偷了就一直能用，不安全。双 token 解决了这个问题：accessToken 短，被偷了也很快过期；refreshToken 长，用户不用频繁登录；accessToken 过期了，用 refreshToken 换新的。

类比：accessToken = 门禁卡（每天过期，重新刷卡续期），refreshToken = 身份证（长期有效，门禁卡丢了拿身份证补办）。

Token 根据用户信息生成（不是纯随机）：

accessToken → 包含用户ID + 用户名 + 过期时间（15分钟）
refreshToken → 只包含用户ID + 过期时间（7天）
用密钥加密生成一串乱码字符串

为什么有 ID 又有用户名

ID（account.ID） → 数据库主键，不可变，用来精确查找
用户名（username）→ 可以改，用来方便识别

类比：身份证号（ID）不可变，查账户用；姓名（username）可以改，写在凭证上让人看。生成 Token 时两个都存：ID 用来查人，用户名用来识别。

Repo 层：Login 函数

service 调用 repo 把 Token 存进 MySQL：

as.accountRepository.Login(ctx, account.ID, accessToken, refreshToken)

repo.go 里用 GORM 操作数据库：

ar.db.WithContext(ctx).Model(&Account{}).Where("id = ?", id).Updates(
 map[string]interface{}{"token": token, "refresh_token": refreshToken})

翻译：在 account 表里，找到 id 等于 id 的那一行，更新 token 和 refresh_token。

等价 SQL：

UPDATE account SET token = 'xxx', refresh_token = 'yyy' WHERE id = 1;

GORM = 用 Go 代码描述“我要干什么”，GORM 帮你翻译成 SQL。

Redis 缓存

登录成功后，Token 存两份：

MySQL 存一份 → 保险，重启不丢，但慢
Redis 存一份 → 快，验证时直接查这里

Redis 存了 3 个 key：

key: "account:1" → accessToken TTL 24小时
key: "account:1:refresh" → refreshToken TTL 7天
key: "refresh:xxxxx" → accountID TTL 7天

为什么存 3 个？第 1 个验证 Token 时查，第 2 个刷新 Token 时查，第 3 个用 refreshToken 反查用户 ID。

Redis 不可用时降级：跳过缓存，只靠 MySQL，功能不丢，只是慢一点。

中间件

怎么执行的

中间件 = 挡在 handler 前面的一道关卡。两个关键函数：

c.Next() → 放行，让请求继续走到下一个中间件或 handler
c.Abort() → 拦截，不让请求继续走，handler 不会执行

类比：c.Next() = 安检通过，放你进去；c.Abort() = 安检不过，拦住你。

为什么是两层函数

func Limit(cache, name string, ...) gin.HandlerFunc { // 外层：传配置
 return func(c *gin.Context) { // 内层：处理请求
 c.Next()
 }
}

外层传配置，内层处理请求。外层函数执行一次，创建中间件；内层函数每次有人访问都执行一次。

类比：外层 = 装修奶茶店（执行一次，买机器、买原料）；内层 = 每天营业（执行无数次，客人来了做奶茶）。

gin.HandlerFunc = Gin 要求中间件必须是这种格式的函数。

gin.Context 的数据传递

中间件把用户 ID 塞进 c 里：

c.Set("accountID", accountID) // 中间件：往 c 里存

handler 从 c 里取出来：

value, exists := c.Get("accountID") // handler：从 c 里取

c 就是一个“传话筒”，中间件往里塞东西，handler 从里拿东西。c 是临时对象，只活在一次请求里，请求结束就没了，不会存到 Redis。

类比：安检员检查完证件，在你手上盖个章“1号”（中间件 c.Set）；柜员看你手上的章，知道你是“1号”（handler c.Get）。

错误到 HTTP 状态码的映射

ClassifyHTTPStatus 就是一张对照表：

error 类型 → 状态码 → 含义
nil（没错误） → 200 → 成功
ErrUnauthorized（未登录） → 401 → 未授权
ErrValidation（参数错误） → 400 → 请求格式错
gorm.ErrRecordNotFound（查不到）→ 404 → 资源不存在
其他错误 → 500 → 服务器内部错误

handler 里用法：

c.JSON(apierror.ClassifyHTTPStatus(err), gin.H{"error": err.Error()})

翻译：看一眼 error 是什么类型，返回对应的状态码。

1. 用户发 POST /account/login

2. router.go 找到这条路由，先过 loginLimiter（限流中间件）

3. 进入 handler.go 的 Login 函数：
 - 解析 JSON（拿到 username 和 password）
 - 调用 service.FindByUsername（查用户存不存在）
 - 调用 service.Login（校验密码 + 生成 Token）

4. 进入 service.go 的 Login 函数：
 - 再查一次数据库（拿到密码哈希）
 - bcrypt 校验密码
 - 生成 accessToken 和 refreshToken
 - 调用 repo.Login（把 Token 存 MySQL）
 - 把 Token 存进 Redis（3 个 key）

5. 进入 repo.go 的 Login 函数：
 - 用 GORM 把 Token 写进 account 表

6. Token 一层一层返回：repo → service → handler → 客户端

涉及 4 个文件：

router.go → 注册路由，把路径和函数连起来
handler.go → 解析请求，调用 service
service.go → 校验密码，生成 Token，存数据库和缓存
repo.go → 操作 MySQL

涉及 2 个存储：

MySQL → 存用户信息和 Token（持久化，重启不丢）
Redis → 缓存 Token（快，重启会丢）

Go 项目反推：Feed 流系统实战——从 Docker 到开源贡献

Sun, 19 Jul 2026 00:00:00 +0800

承接 Go 语言基础：从变量到指针、Go 语言进阶：方法、接口与错误处理、Go 语言工程化：模块管理与项目结构、Go 语言并发：从 Goroutine 到 Worker Pool 和 Go Web 开发：从 net-http 到 Gin，这一篇跳出语法学习，反推一个真实的开源项目——feedsystem_video_go（279 star，Go + Vue 3 短视频 Feed 流系统），从跑通项目到提交 PR，走一遍完整的工程实战。

项目概览

这个项目是一个短视频 Feed 流系统，技术栈：

后端：Go + Gin + GORM + RabbitMQ + Redis
前端：Vue 3 + TypeScript
基础设施：Docker Compose 编排 MySQL、Redis、RabbitMQ

核心功能包括用户注册登录、视频发布、点赞评论、关注取关、Feed 流推送。架构上采用 API + Worker 的消息队列模式。

Docker Compose：启动基础设施

项目的三个"帮手"——MySQL、Redis、RabbitMQ——通过 Docker Compose 一键启动：

cd ~/dev/projects/feedsystem_video_go
docker compose up -d mysql redis rabbitmq

docker compose up — 根据 docker-compose.yml 启动服务
-d — 后台运行（detach），不占终端窗口
mysql redis rabbitmq — 只启动这三个，不启动 backend/worker/frontend

镜像 vs 容器

Docker 里有两个核心概念：

镜像 = 打包好的集装箱（里面有程序 + 配置），是静态文件
容器 = 集装箱正在运行的实例

类比：.app 文件是镜像，双击打开后正在运行就是容器。

端口映射

MySQL 默认端口 3306，但本机可能已经装了 MySQL 占用了 3306。所以 docker-compose.yml 里写的是：

ports: "3307:3306"

意思是：外部访问 3307 → 转发到容器内部的 3306。就像你家门牌号是 3307，但内部房间编号是 3306。项目配置文件里写的也是 3307，Go 程序连接 MySQL 时用的就是 3307。

通过 docker compose ps 可以查看所有容器的运行状态：

NAME IMAGE STATUS PORTS
feedsystem_video_go-mysql-1 mysql:8.0 Up 5 minutes (healthy) 0.0.0.0:3307->3306/tcp
feedsystem_video_go-redis-1 redis:7-alpine Up 5 minutes (healthy) 0.0.0.0:6379->6379/tcp
feedsystem_video_go-rabbitmq-1 rabbitmq:3 Up 5 minutes (healthy) 0.0.0.0:5672->5672/tcp

0.0.0.0 表示"接受任何来源的连接"，即对外部开放。

启动 Go 后端

基础设施就位后，启动后端：

cd backend
CONFIG_PATH=configs/config.compose-local.yaml go run ./cmd

CONFIG_PATH=... — 告诉程序用哪个配置文件（里面写好了 MySQL 3307、Redis 6379、RabbitMQ 5672 的地址）
go run ./cmd — 编译并运行 cmd/main.go 入口程序

日志解读

启动后会看到几段日志：

第一段：依赖下载

go: downloading github.com/gin-gonic/gin v1.11.0
go: downloading gorm.io/gorm v1.31.1

Go 在下载第三方库，类似 npm install，下载一次以后就不需要了。

第二段：连接建立

Loading config from configs/config.compose-local.yaml
Redis connected (cache enabled)
RabbitMQ connected

注意没有 “MySQL connected”，因为 GORM 连接 MySQL 是在后面 AutoMigrate 时才真正连接。

第三段：Gin 路由注册

[GIN-debug] GET /healthz
[GIN-debug] POST /account/register
[GIN-debug] POST /account/login
[GIN-debug] POST /video/publish
[GIN-debug] POST /like/like
[GIN-debug] POST /feed/listLatest

格式是 HTTP方法路由路径，后面的 (4 handlers) 表示这条路由经过几个中间件（如限流 + JWT 鉴权 + 业务处理）。

第四段：消息队列

DLX ready: exchange=dlx.events queue=like.events.dlx
Timeline consumer 已启动, queue=video.timeline.update.queue

DLX = Dead Letter Exchange（死信队列），专门处理失败的消息。

第五段：启动完成

Server is running on port 8080

为什么不把 Go 也放进 Docker？

Docker 适合最终部署，不适合日常开发调试。本地直接 go run 的好处：

日志直接打印在终端，实时可见
改了代码立刻能跑，不用重新打包镜像
出错了能直接看到报错信息

日志不是中间件

日志是 Go 标准库 log 包写出来的，是程序员手动写的"程序进行到哪一步了"的提示。中间件是处理请求的"关卡"，两者没有关系。

核心概念：缓存与消息队列

Redis 缓存

缓存 = 把经常用的数据放在"取用更快的地方"。

类比：冰箱里有水（MySQL，容量大但取用慢），你拿了一瓶放在桌上（Redis 缓存，取用极快），下次喝水直接从桌上拿，不用再去冰箱。

代码里 cache enabled 表示数据会先从 Redis 取，取不到再去 MySQL。

RabbitMQ 消息队列

消息队列是 API 和 Worker 之间的"传话筒"。API 处理完核心逻辑后，把"后续要做的事"发到队列，Worker 从队列里取任务执行。

前后端分离架构

后端和前端是两个完全不同的程序：

后端：Go 写的，负责业务逻辑、读写数据库，监听 8080 端口
前端：Vue 写的，负责页面展示、用户交互，监听 5173 端口

它们通过 HTTP 请求通信：用户在浏览器点"登录" → 前端发请求到 localhost:8080/account/login → 后端处理 → 返回结果 → 前端展示。

就像餐厅里厨房（后端）和前厅（前端）是两个地方，前厅接到顾客点单传给厨房，厨房做完菜传给前厅。

前端用 npm（Node Package Manager）管理依赖，跟 Go 的 go get、Python 的 pip install 是同一个道理：

cd frontend
npm install # 下载依赖
npm run dev # 启动开发服务器

Worker 进程模式

这是整个项目最核心的架构设计。Worker 是一个独立进程，和 API 分开启动：

cd backend
CONFIG_PATH=configs/config.compose-local.yaml go run ./cmd/worker

为什么要分开？

想象一个外卖平台：

方案 A：一个人又要接单又要送餐 — 接单时有新订单没人接，送餐时又有新订单没人接，效率低。

方案 B：两个人分工 — 前台专门接单（API），骑手专门送餐（Worker），前台接完单把订单放进"待送餐队列"（RabbitMQ），骑手从队列里取订单去送。

对应到项目：

角色	职责
API 进程	接收用户请求（点赞、评论、发布视频），处理核心业务逻辑，把"后续要做的事"发到消息队列
Worker 进程	监听消息队列，处理异步任务：更新点赞数、计算热度、推送通知

这个项目有四个 Worker：

LikeWorker — 处理点赞/取消点赞事件
PopularityWorker — 更新视频热度
SocialWorker — 处理关注/取关事件
CommentWorker — 处理评论事件

分开的好处

性能：用户点赞时，API 只需要返回"点赞成功"，不需要等热度计算完成
独立伸缩：请求量大时启动多个 API 进程，任务多时启动多个 Worker 进程
故障隔离：Worker 挂了 API 还能正常接收请求，API 挂了 Worker 还能把队列里的任务处理完

一句话总结：API 是"接单的"，Worker 是"干活的"，通过消息队列解耦。

开源贡献实战：修复 JWT 密钥缓存 Bug

跑通项目后，在实际使用中发现了一个真实 Bug。

问题复现

不设置 JWT_SECRET 环境变量，启动后端
注册一个账号
登录成功（页面提示"登录成功"）
但左侧栏仍然显示"未登录"
浏览器控制台报错：invalid or expired token (401)

登录本身成功，但所有需要鉴权的接口全部返回 401。

根因定位

文件：backend/internal/auth/jwt.go

func jwtSecret() []byte {
 secret := os.Getenv("JWT_SECRET")
 if secret == "" {
 b := make([]byte, 32)
 rand.Read(b)
 secret = hex.EncodeToString(b)
 }
 return []byte(secret)
}

问题出在这个函数每次调用都生成一个新的随机密钥：

登录时：GenerateToken() 调用 jwtSecret() → 拿到密钥 A → 用 A 签名 token
验证时：ParseToken() 调用 jwtSecret() → 拿到密钥 B → 用 B 验证
A ≠ B → 签名不匹配 → 返回 401

修复方案

用包级别的变量缓存密钥，保证每个进程只生成一次：

var cachedSecret []byte

func jwtSecret() []byte {
 if cachedSecret != nil {
 return cachedSecret
 }
 secret := os.Getenv("JWT_SECRET")
 if secret == "" {
 b := make([]byte, 32)
 if _, err := rand.Read(b); err != nil {
 log.Printf("FATAL: cannot generate JWT secret: %v", err)
 cachedSecret = []byte("fallback-unsafe-key-change-me")
 return cachedSecret
 }
 secret = hex.EncodeToString(b)
 log.Printf("WARNING: JWT_SECRET not set, generated random key.")
 }
 cachedSecret = []byte(secret)
 return cachedSecret
}

修复方案兼顾安全性（缓存保证签名一致）和灵活性（仍然允许随机密钥兜底）。

走通开源贡献流程

步骤	内容
1. 本地复现	按步骤触发 Bug
2. 阅读源码	从前端 → API → JWT 中间件，定位根因
3. 提 Issue	描述问题，附带复现步骤 → #15
4. Fork + 修复分支	`fix/jwt-secret-caching`
5. 提 PR	关联 Issue → #16

面试话术

在一个 279 star 的开源项目中发现了真实 bug
从前端（Vue/TypeScript）追踪到 API（Gin/Go）再到 JWT 鉴权中间件，定位了根因
提出的修复方案兼顾安全性和灵活性
走通了完整的开源贡献流程

这一篇从"跑通项目"出发，反推了 Docker Compose 编排、Gin 路由注册、Redis 缓存、RabbitMQ 消息队列、Worker 进程模式等工程概念，最后通过一次真实的开源贡献把整条链路串了起来。相比纯语法学习，反推真实项目能更快建立工程直觉。

Go Web 开发：从 net-http 到 Gin

Sat, 18 Jul 2026 00:00:00 +0800

承接 Go 语言基础：从变量到指针、Go 语言进阶：方法、接口与错误处理、Go 语言工程化：模块管理与项目结构和 Go 语言并发：从 Goroutine 到 Worker Pool，这一篇进入 Web 开发实战：用 Go 写 HTTP 服务器。

Handler：处理请求的函数

Go 的 HTTP 服务器一切从 Handler 开始。Handler 就是一个处理请求的函数，签名是固定的：

func handler(w http.ResponseWriter, r *http.Request)

w = 响应写入器（往里面写什么，客户端就收到什么）
r = 请求信息（客户端发来的 URL、方法、头部等）

把 w 想象成"回复窗口"，r 想象成"来信内容"。

package main

import (
 "fmt"
 "net/http"
)

func homeHandler(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintf(w, "Hello, Go Web!\n")
}

func aboutHandler(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintf(w, "About Page\n")
}

路由注册与启动服务器

告诉 Go：访问 / 调用 homeHandler，访问 /about 调用 aboutHandler。

func main() {
 // 注册路由
 http.HandleFunc("/", homeHandler)
 http.HandleFunc("/about", aboutHandler)

 // 启动服务器，监听 8080 端口
 fmt.Println("Server starting on http://localhost:8080 ...")
 err := http.ListenAndServe(":8080", nil)
 if err != nil {
 fmt.Println("Server error:", err)
 }
}

`ListenAndServe` 的含义

Listen = 监听（竖起耳朵听有没有人敲门）
And = 并且
Serve = 提供服务（有人来了就接待）

这行代码一旦执行，程序就卡在这不走了，一直等着。下面的 if err 只有服务器出错才会执行。

端口被占了怎么杀：lsof -ti:8080 | xargs kill -9

HTTP 方法与 curl

r.Method → 请求方法，r.URL.Path → 请求路径。

curl 是在终端发 HTTP 请求的工具，相当于用命令代替浏览器：

curl http://localhost:8080/ # GET
curl -X POST http://localhost:8080/ # POST
curl -X PUT http://localhost:8080/ # PUT
curl -X DELETE http://localhost:8080/ # DELETE

HTTP 方法表示"我想干什么"：

方法	含义	类比（快递柜）
GET	获取数据	查看 123 号格子
POST	提交数据	往里放新包裹
PUT	更新数据	换掉 123 号格子的东西
DELETE	删除数据	拿走 123 号格子的东西

返回 JSON 响应

JSON 是程序之间传递数据的标准格式。核心三步：

import "encoding/json"

type User struct {
 Name string `json:"name"`
 Age int `json:"age"`
}

func userHandler(w http.ResponseWriter, r *http.Request) {
 user := User{Name: "Tom", Age: 20}

 // 第1步：把数据变成 JSON
 jsonBytes, err := json.Marshal(user)
 if err != nil {
 http.Error(w, "序列化失败", 500)
 return
 }

 // 第2步：告诉客户端"我返回的是 JSON"
 w.Header().Set("Content-Type", "application/json")

 // 第3步：把 JSON 写出去
 w.Write(jsonBytes)
}

struct 的 json tag

type User struct {
 Name string `json:"name"` // JSON 里字段叫 name（小写）
 Age int `json:"age"`
}

不写 tag 的话字段名就是 Go 里的大写 Name、Age。反引号里整个 json:"xxx" 是一个整体，冒号后面不能有空格。

响应头是什么

HTTP 响应 = 响应头（信封）+ 响应体（信的内容）：

w.Header() = 拿信封
w.Header().Set("Content-Type", "application/json") = 在信封上写"里面是 JSON"
w.Write() = 往信里写内容

读取客户端 JSON

客户端 POST 发来 JSON，服务器解析到结构体：

func createUserHandler(w http.ResponseWriter, r *http.Request) {
 // 检查方法
 if r.Method != "POST" {
 http.Error(w, "只支持 POST 方法", http.StatusMethodNotAllowed)
 return
 }

 // 从请求体解析 JSON 到 user
 var user User
 err := json.NewDecoder(r.Body).Decode(&user)
 if err != nil {
 http.Error(w, "JSON 解析失败", 400)
 return
 }

 // 返回给客户端
 jsonData, _ := json.Marshal(user)
 w.Header().Set("Content-Type", "application/json")
 w.Write(jsonData)
}

测试：

curl -X POST http://localhost:8080/user -d '{"name":"Jerry","age":25}'

序列化 vs 反序列化

操作	函数	用途
结构体 → JSON	`json.Marshal(data)`	返回给客户端
JSON → 结构体	`json.NewDecoder(r.Body).Decode(&data)`	读取客户端数据

关键点：

Decode 的参数必须是 &user（指针），不是 user
Marshal 和 Decode 都返回 err，必须检查
出错要 http.Error + return，不能光打印

REST API 设计风格

REST 的核心思想：用 HTTP 方法 + 路径，表达"对资源做什么操作"。路径放名词（资源），HTTP 方法放动词（操作）。

本质就是 CRUD：

操作	HTTP 方法	路径	含义
Create	POST	`/user`	新建
Read	GET	`/user` 或 `/user/0`	查列表 / 查单个
Update	PUT	`/user/0`	改单个
Delete	DELETE	`/user/0`	删单个

记忆：GET=看，POST=增，PUT=改，DELETE=删

设计规则：

URL 用名词（/user），不用动词（/getUser）
用 HTTP 方法区分操作，而不是路径里写动词
同一个 URL，不同方法 = 不同操作

完整 CRUD 实战

四个 Handler 的套路

不管你写哪个 handler，步骤都是：

检查 HTTP 方法对不对
从 URL 拿 id（列表操作跳过）
检查越界（同上）
业务逻辑（创建/返回/替换/删除）
序列化返回（JSON → 设 Header → 写响应）

区别只在第 4 步：

Create：从请求体解析 → append 到 users
Read：从 users 里取 → 序列化返回
Update：从请求体解析 → 替换 users[id]
Delete：从 users 删掉 → 返回文字消息

结构体与全局变量

type User struct {
 Name string `json:"name"`
 Age int `json:"age"`
}

// 模拟数据库，服务器重启就清空
var users = []User{}

从 URL 提取 id

客户端访问 GET /user/0，服务器用 TrimPrefix 切掉前缀，再转数字：

func getUserHandler(w http.ResponseWriter, r *http.Request) {
 if r.Method != "GET" {
 http.Error(w, "只支持 GET 方法", 405)
 return
 }

 // /user/0 → "0"
 idStr := strings.TrimPrefix(r.URL.Path, "/user/")

 // "0" → 0
 id, err := strconv.Atoi(idStr)
 if err != nil {
 http.Error(w, "无效的 id", 400)
 return
 }

 // 越界检查
 if id < 0 || id >= len(users) {
 http.Error(w, "越界", 404)
 return
 }

 user := users[id]
 jsonData, _ := json.Marshal(user)
 w.Header().Set("Content-Type", "application/json")
 w.Write(jsonData)
}

越界用 >= 不是 >：长度 2 的列表，有效下标是 0、1，id=2 要拦截。

Update Handler（PUT）

套路：检查方法 → 拿 id → 越界检查 → 解析请求体新数据 → 替换 users[id] → 序列化返回。

func updateUserHandler(w http.ResponseWriter, r *http.Request) {
 if r.Method != "PUT" {
 http.Error(w, "只支持 PUT 方法", 405)
 return
 }

 idStr := strings.TrimPrefix(r.URL.Path, "/user/")
 id, err := strconv.Atoi(idStr)
 if err != nil {
 http.Error(w, "无效的 id", 400)
 return
 }
 if id < 0 || id >= len(users) {
 http.Error(w, "越界", 404)
 return
 }

 var user User
 err = json.NewDecoder(r.Body).Decode(&user)
 if err != nil {
 http.Error(w, "解析失败", 400)
 return
 }

 users[id] = user

 jsonData, _ := json.Marshal(user)
 w.Header().Set("Content-Type", "application/json")
 w.Write(jsonData)
}

Delete Handler（DELETE）

套路：检查方法 → 拿 id → 越界检查 → 从 slice 删元素 → 返回消息。

func deleteUserHandler(w http.ResponseWriter, r *http.Request) {
 if r.Method != "DELETE" {
 http.Error(w, "方法错误", 405)
 return
 }

 idStr := strings.TrimPrefix(r.URL.Path, "/user/")
 id, err := strconv.Atoi(idStr)
 if err != nil {
 http.Error(w, "无效的 id", 400)
 return
 }
 if id < 0 || id >= len(users) {
 http.Error(w, "越界", 404)
 return
 }

 // 删 slice 元素
 users = append(users[:id], users[id+1:]...)
 fmt.Fprintf(w, "用户 %d 已删除\n", id)
}

Slice 删除元素的原理

users = append(users[:id], users[id+1:]...)

把 id 前面的人和 id 后面的人拼到一起，跳过 id 本身。假设 users = [张三, 李四, 王五]，删 id=1（李四）：

users[:1] → [张三]
users[2:] → [王五]
append 拼起来 → [张三, 王五]

注意：删除后 users 长度变了，后面的 id 会前移。

路由分发（switch 重构）

当一个 URL 要根据 HTTP 方法分发到不同 handler 时：

func main() {
 http.HandleFunc("/user/", func(w http.ResponseWriter, r *http.Request) {
 path := r.URL.Path

 if path == "/user" || path == "/user/" {
 // 列表和创建
 switch r.Method {
 case "GET":
 listUsersHandler(w, r)
 case "POST":
 createUserHandler(w, r)
 default:
 http.Error(w, "方法不支持", 405)
 }
 } else if strings.HasPrefix(path, "/user/") {
 // 单个用户操作
 switch r.Method {
 case "GET":
 getUserHandler(w, r)
 case "PUT":
 updateUserHandler(w, r)
 case "DELETE":
 deleteUserHandler(w, r)
 default:
 http.Error(w, "方法不支持", 405)
 }
 }
 })

 fmt.Println("Server starting on http://localhost:8080 ...")
 err := http.ListenAndServe(":8080", nil)
 if err != nil {
 fmt.Println("Server error:", err)
 }
}

测试

# 查列表（空的）
$ curl http://localhost:8080/user/
[]

# 创建两个用户
$ curl -X POST http://localhost:8080/user/ -d '{"name":"Jerry","age":25}'
{"name":"Jerry","age":25}

$ curl -X POST http://localhost:8080/user/ -d '{"name":"Tom","age":30}'
{"name":"Tom","age":30}

# 再查列表
$ curl http://localhost:8080/user/
[{"name":"Jerry","age":25},{"name":"Tom","age":30}]

# 查单个
$ curl http://localhost:8080/user/0
{"name":"Jerry","age":25}

ServeMux 的斜杠重定向坑

注册 /user/ 这种子树路由后，Go 默认路由器会把 /user 自动重定向到 /user/（301 Moved Permanently）。一些客户端跟随 301 重定向时会把 POST 改成 GET，导致请求体丢失；另一些客户端不会自动跟随重定向。

解决：访问列表/创建接口时直接使用带斜杠的 /user/，或者同时显式注册 /user 与 /user/ 并自行处理。

Middleware 中间件

一句话理解

在请求到达 handler 之前（或之后）执行的通用逻辑。

比喻：快递站的安检机——每个包裹都要过一遍，但安检机不是最终处理包裹的地方，安检完再交给真正处理的人。

实际用途：

日志记录：每个请求都打印一下
认证检查：检查有没有登录
请求计时：每个请求花了多少时间

核心代码

func loggingMiddleware(next http.HandlerFunc) http.HandlerFunc {
 return func(w http.ResponseWriter, r *http.Request) {
 // 前置：请求进来时
 log.Println("收到请求:", r.URL.Path)

 // 调用真正的 handler
 next(w, r)

 // 后置：响应返回后
 log.Println("处理完成")
 }
}

使用方式

// 原来
http.HandleFunc("/user", createUserHandler)

// 包一层中间件
http.HandleFunc("/user", loggingMiddleware(createUserHandler))

理解方式：

loggingMiddleware(createUserHandler)
 ↑ ↑
 前台（先接客） 厨师（真正干活）

流程：请求进来 → 前台登记 → 转给厨师 → 做完 → 前台记录

多个中间件叠加

http.HandleFunc("/user", authMiddleware(loggingMiddleware(createUserHandler)))
// 请求进来 → auth → logging → createUserHandler

本质：函数当参数传 + 函数当返回值。不用完全理解原理，记住套路就行，写多了自然就懂。

Gin 框架

Gin 是什么

Go 最流行的 Web 框架，帮你省掉 net/http 的重复代码。

go get github.com/gin-gonic/gin

创建服务器

import "github.com/gin-gonic/gin"

r := gin.Default() // 创建路由器，自带 Logger 中间件
r.Run(":8080") // 启动服务器

Gin vs net/http 对比

net/http	Gin
`w http.ResponseWriter, r *http.Request`	`c *gin.Context`
`if r.Method != "GET" ...`	不用写（`r.GET` 自动限定）
`json.NewDecoder(r.Body).Decode()`	`c.ShouldBindJSON(&user)`
`json.Marshal` + `w.Header` + `w.Write`	`c.JSON(200, data)`
`strings.TrimPrefix` + `Atoi`	`c.Param("id")`
`http.HandleFunc` + if/switch	`r.GET/POST/PUT/DELETE` 分开注册
`http.ListenAndServe(":8080", nil)`	`r.Run(":8080")`

路由注册

r.GET("/user", listUsers) // GET /user → listUsers
r.POST("/user", createUser) // POST /user → createUser
r.GET("/user/:id", getUser) // GET /user/0 → getUser
r.PUT("/user/:id", updateUser) // PUT /user/0 → updateUser
r.DELETE("/user/:id", deleteUser) // DELETE /user/0 → deleteUser

:id 是路由参数，/user/0 里的 0 会被捕获。

Handler 签名

func handler(c *gin.Context) {
 // c 把 w 和 r 合到一起了，用 c 就能完成所有事情
}

获取路由参数与查询参数

// 路由参数
id := c.Param("id") // /user/0 → "0"

// 查询参数
name := c.Query("name") // /user?name=张三 → "张三"
page := c.DefaultQuery("page", "1") // 没传就用默认值 "1"

解析请求体 JSON

var user User
if err := c.ShouldBindJSON(&user); err != nil {
 c.JSON(400, gin.H{"error": err.Error()})
 return
}
// 解析成功，user 里有数据了

ShouldBindJSON 一行代替 net/http 的三行（NewDecoder + Decode + 检查 err）。

返回 JSON 响应

c.JSON(200, user) // 返回单个对象
c.JSON(200, users) // 返回列表
c.JSON(400, gin.H{"error": "解析失败"}) // 返回错误信息

gin.H 是 map[string]interface{} 的简写。c.JSON 自动帮你做：序列化 + 设 Content-Type + 写响应。

参数校验

在 struct tag 里加 binding 规则，Gin 自动校验：

type User struct {
 Name string `json:"name" binding:"required,min=2,max=50"`
 Age int `json:"age" binding:"required,gt=0"`
}

常用规则：

required → 必填
min=N / max=N → 最小/最大长度（字符串）或值（数字）
gt=N / gte=N → 大于 / 大于等于
email → 必须是邮箱格式

校验在 c.ShouldBindJSON 时自动执行，不需要额外代码。

Gin 中间件

func Logger() gin.HandlerFunc {
 return func(c *gin.Context) {
 start := time.Now()

 log.Printf(">>> %s %s", c.Request.Method, c.Request.URL.Path)
 c.Next() // 放行
 cost := time.Since(start)
 log.Printf("<<< 耗时: %v", cost)
 }
}

核心两个函数：

c.Next() → 放行，让请求继续走到 handler
c.Abort() → 拦截，不让请求继续走

认证中间件

func AuthRequired() gin.HandlerFunc {
 return func(c *gin.Context) {
 token := c.GetHeader("Authorization")
 if token == "" {
 c.JSON(401, gin.H{"error": "未登录"})
 c.Abort() // 拦截
 return
 }
 c.Next() // 放行
 }
}

路由分组

用法1：单个路由加中间件

r.GET("/user", Logger(), listUsers)
r.GET("/user/:id", Logger(), AuthRequired(), getUser)

用法2：路由分组（推荐）

authorized := r.Group("/user", AuthRequired())
{
 authorized.GET("/:id", Logger(), getUser)
 authorized.PUT("/:id", Logger(), updateUser)
 authorized.DELETE("/:id", Logger(), deleteUser)
}

分组的好处：AuthRequired 写一次，这组路由全部生效。

完整示例（带中间件）

func main() {
 r := gin.Default()

 // 不需要登录的接口
 r.GET("/user", listUsers)
 r.POST("/user", createUser)

 // 需要登录的接口
 auth := r.Group("/user", AuthRequired())
 {
 auth.GET("/:id", getUser)
 auth.PUT("/:id", updateUser)
 auth.DELETE("/:id", deleteUser)
 }

 r.Run(":8080")
}

常用函数速查

函数	作用
`gin.Default()`	创建路由器（自带 Logger）
`r.GET/POST/PUT/DELETE(path, fn)`	注册路由
`r.Group(path, middleware...)`	路由分组
`c.Param("id")`	获取路由参数
`c.Query("key")`	获取查询参数
`c.DefaultQuery("key", "default")`	获取查询参数（带默认值）
`c.GetHeader("key")`	获取请求头
`c.ShouldBindJSON(&data)`	解析请求体 JSON（含校验）
`c.JSON(status, data)`	返回 JSON 响应
`c.Next()`	放行
`c.Abort()`	拦截
`gin.H{...}`	`map[string]interface{}` 简写

踩坑汇总

中文输入法逗号："错误"，405 → 要用英文逗号 "错误", 405
:= vs =：全局变量用 = 赋值，用 := 会创建局部变量
fmt.Fprinf → fmt.Fprintf（p 和 r 反了）
json.Decode 拼写：Docode → Decode
application 拼写：spplication → application
c.Abort 漏括号 → c.Abort() 才是调用
Gin 里用 net/http 的写法：json.NewDecoder(r.Body) 是 net/http 的，Gin 里用 c.ShouldBindJSON
net/http 中 POST /user 不带斜杠：注册的是 /user/ 时会被重定向，测试时直接用 /user/

参考源

raw/GoWeb 后端开发.md

Go 语言并发：从 Goroutine 到 Worker Pool

Tue, 14 Jul 2026 00:00:00 +0800

承接 Go 语言基础：从变量到指针、Go 语言进阶：方法、接口与错误处理和 Go 语言工程化：模块管理与项目结构，这一篇覆盖 Go 最核心的特性：并发编程。

并发 vs 并行

先区分两个概念：

并行（Parallel）：两个人同时吃两碗面
并发（Concurrency）：一个人交替吃两碗面（这口吃这碗，下口吃那碗）

Go 的并发模型就是让你用很少的资源同时做很多事。

Goroutine

一句话：轻量级线程，用 go 关键字启动。

// 普通调用
fmt.Println("hello")

// 用 go 启动一个 goroutine
go fmt.Println("hello") // 加个 go 就行

加了 go，这个函数就会在后台跑，不阻塞当前代码。

先看个例子

package main

import (
 "fmt"
 "time"
)

func sayHello() {
 fmt.Println("hello")
}

func main() {
 go sayHello() // 后台跑
 fmt.Println("main") // 主线程继续
}

你猜输出什么？

答案：只输出 main。

为什么？因为 main 函数结束了，程序就退出了，goroutine 还没来得及跑。

这就像你叫了个外卖（go sayHello），但你立刻出门了（main 结束），外卖员来了发现没人。

怎么等 goroutine 跑完？

最简单的方式：加个 sleep（但这是错误示范）

go sayHello()
time.Sleep(time.Second) // 等1秒，goroutine 有时间跑了
fmt.Println("main")

能工作，但不准、不优雅——你不知道 goroutine 到底要跑多久。

正确方式：用 channel（后面会详细讲）

done := make(chan bool)

go func() {
 fmt.Println("hello")
 done <- true // 说一声：我做完了
}()

<-done // 等着，直到收到信号
fmt.Println("main")

现在输出：

hello
main

用比喻理解

普通函数调用：你叫同事做事，站在旁边等他做完
go 函数调用：你叫同事做事，自己先去忙别的
channel：同事做完了发消息通知你

Channel

为什么需要 Channel？

goroutine 是独立运行的，它们之间怎么传数据？

// 两个 goroutine，一个生产数据，一个消费数据
// 怎么把数据从 A 传到 B？

答案：用 channel，就像一根水管，一头进，一头出。

基本用法

// 创建 channel
ch := make(chan int) // 传 int 类型的 channel

// 发送数据（往管子里塞）
ch <- 42

// 接收数据（从管子里取）
x := <-ch

Channel 的特性：阻塞

这是最关键的：

发送方：ch <- 42 → 没人接收就等着（阻塞）
接收方：x := <-ch → 没人发送就等着（阻塞）

就像一个没有缓冲的传送带：

你放东西上去，必须有人在另一头接着，否则你就一直举着
你去拿东西，必须有人放了东西，否则你就一直等着

用阻塞特性来同步

这就是为什么 channel 能替代 sleep 来等 goroutine：

done := make(chan bool)

go func() {
 fmt.Println("干活中...")
 done <- true // 干完了，发信号
}()

<-done // 等着，直到收到信号
fmt.Println("结束")

goroutine 没发信号 → main 在 <-done 那行等着
goroutine 发了信号 → main 继续往下跑

缓冲 Channel

普通 channel 没有缓冲，一发一收必须配对。可以加缓冲：

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

ch <- 1 // 塞进去，不等（缓冲区没满）
ch <- 2 // 塞进去，不等
ch <- 3 // 塞进去，不等
ch <- 4 // 缓冲区满了，等着（阻塞）

比喻：

没缓冲：打电话，必须对方接了你才能说话
有缓冲：发微信，对方没看之前你也能发几条

关闭 Channel

发送方说"我不再发了"：

close(ch)

接收方可以检测 channel 是否关闭：

x, ok := <-ch
if !ok {
 fmt.Println("channel 已关闭")
}

概念总结

操作	含义
`make(chan T)`	创建 channel
`ch <- data`	发送
`x := <-ch`	接收
`close(ch)`	关闭
`make(chan T, n)`	带缓冲的 channel

Select

Select 是什么？

一句话：同时监听多个 channel，哪个先有数据就处理哪个。

为什么需要 Select？

假设你有两个 channel：

ch1 := make(chan string)
ch2 := make(chan string)

用普通方式只能等一个：

msg := <-ch1 // 只能等 ch1，ch2 来了也不知道

用 select 可以同时等：

select {
case msg := <-ch1:
 fmt.Println(msg)
case msg := <-ch2:
 fmt.Println(msg)
}

哪个先有数据就执行哪个。

完整例子

package main

import (
 "fmt"
 "time"
)

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

 // 1秒后往 ch1 塞数据
 go func() {
 time.Sleep(1 * time.Second)
 ch1 <- "来自 ch1"
 }()

 // 2秒后往 ch2 塞数据
 go func() {
 time.Sleep(2 * time.Second)
 ch2 <- "来自 ch2"
 }()

 // 同时等 ch1 和 ch2
 select {
 case msg := <-ch1:
 fmt.Println(msg)
 case msg := <-ch2:
 fmt.Println(msg)
 }
}

输出：来自 ch1（因为 ch1 先到）

sync.WaitGroup

为什么需要 WaitGroup？

你启动了多个 goroutine，想等它们全部做完再继续：

go task1()
go task2()
go task3()
// 怎么知道三个都做完了？

之前用 channel 可以，但要创建多个 channel 很麻烦。WaitGroup 就是专门解决这个的。

怎么用？三步

var wg sync.WaitGroup

wg.Add(1) // 第1步：告诉 wg 你要等几个任务

go func() {
 // 做事情...
 wg.Done() // 第3步：做完了，报告一下
}()

wg.Wait() // 第2步：等着，全部做完才继续

sync.Mutex 互斥锁

解决的问题：多个 goroutine 同时读写同一个变量。

var mu sync.Mutex

mu.Lock()
counter++
mu.Unlock()

sync.Once

var once sync.Once
once.Do(func() {
 // 这段代码只会执行一次
})

不管你调多少次 once.Do()，里面的函数只执行第一次。

什么时候用？初始化操作，比如数据库连接、配置加载，只做一次。

Context

Context 是什么？

一句话：控制 goroutine 的生命周期，告诉它"别干了，取消"。

为什么需要 context？

假设你发了一个 HTTP 请求，用户等不及关了页面：

用户 → 请求 → 后端启动 goroutine 处理 → 数据库查询中...
用户关了页面
goroutine 还在跑，浪费资源。

用 context 可以通知 goroutine：“别查了，用户走了”。

先忘掉代码，想一个场景

你叫了一个外卖：

你：下单（启动 goroutine）
外卖员：开始送餐（goroutine 在跑）
情况1：你等不及了，打电话说"别送了"（手动取消）
情况2：你下单时就说"30分钟不到就取消"（超时取消）

context 就是那个电话。

代码里的角色

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

ctx → 外卖员手里的对讲机（能听到"取消"的信号）
cancel → 你手里的电话（主动打过去说"取消"）
2*time.Second → 30分钟超时（2秒后自动取消）

goroutine 那边怎么听信号？

select {
case <-ctx.Done(): // 对讲机响了，说"取消"
 fmt.Println("收到取消，退出")
 return
default: // 没响，继续干活
 fmt.Println("干活中...")
}

ctx.Done() 就是对讲机，context 取消时它就响（channel 关闭）。

整个流程

main：创建 context（设定2秒超时）
main：启动 worker，把对讲机给它
worker：干活…干活…
2秒后：超时，context 自动取消
worker：听到对讲机响了，退出

两种取消方式

1. 手动取消：WithCancel

ctx, cancel := context.WithCancel(context.Background())

你自己决定什么时候取消：

go worker(ctx)
// 过了一会儿，你决定取消
cancel() // 打电话说"别干了"

就像：你叫了外卖，等了5分钟不耐烦了，主动打电话取消。

2. 超时取消：WithTimeout

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

设个时间，到了自动取消：

go worker(ctx)
// 不用管了，2秒后自动取消
// cancel() 也可以提前调，但不是必须的

Race Detector

什么是数据竞争？

之前 Mutex 的例子，不加锁会出错：

counter++ // 多个 goroutine 同时改，结果不对

这就是数据竞争，很难复现，偶尔出错，排查很痛苦。

Race Detector

Go 自带一个工具，帮你检测数据竞争：

go run -race demo.go
go build -race -o app
go test -race ./...

加一个 -race 就行。

看个例子

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)
}

go run -race test.go

输出：

WARNING: DATA RACE
...
Found 2 data race(s)

-race 告诉你什么

哪个 goroutine 在读（goroutine 12）
哪个 goroutine 在写（goroutine 8）
在第几行（第16行：counter++）

一句话总结

go run -race → 跑代码 + 检测数据竞争
go test -race → 跑测试 + 检测数据竞争（写项目时常用）

Worker Pool 并发模式

一句话：固定几个 goroutine，从队列里取任务执行。

为什么需要？

假设你有1000个任务：

// 方式1：每个任务一个 goroutine
for i := 0; i < 1000; i++ {
 go doTask(i)
}

启动1000个 goroutine，资源占用大，不好控制。

// 方式2：Worker Pool，只启动3个 worker
for i := 0; i < 3; i++ {
 go worker(tasks)
}
// 3个 worker 从 tasks 里取任务，取完一个再取下一个

就像餐厅只有3个厨师，100个菜排队等他们做，做完一个做下一个。

模型

任务队列（channel）：[任务1, 任务2, 任务3, ...任务N]

Worker 1：从队列取任务 → 执行 → 再取下一个
Worker 2：从队列取任务 → 执行 → 再取下一个
Worker 3：从队列取任务 → 执行 → 再取下一个

完整代码

package main

import (
 "fmt"
 "time"
)

// worker 函数：每个 worker 从 tasks 这个 channel 里不断取任务执行
// id：worker 的编号，用来区分是哪个 worker 在干活
// tasks：任务队列，只读 channel（<-chan 表示只能从里面取，不能塞）
func worker(id int, tasks <-chan int) {
 // range tasks：从 channel 里取任务，取到就执行
 // channel 关闭后，range 自动结束，for 循环退出
 for task := range tasks {
 fmt.Printf("worker %d 开始处理任务 %d\n", id, task)
 time.Sleep(time.Second) // 模拟干活耗时1秒
 fmt.Printf("worker %d 完成任务 %d\n", id, task)
 }
}

func main() {
 // 创建一个带缓冲的 channel，缓冲区大小10
 tasks := make(chan int, 10)

 // 启动3个 worker，用 goroutine 并发跑
 for i := 1; i <= 3; i++ {
 go worker(i, tasks)
 }

 // 往 tasks 里塞5个任务（编号1到5）
 for j := 1; j <= 5; j++ {
 tasks <- j
 }

 // 关闭 channel，告诉 worker："没有新任务了"
 close(tasks)

 // 等6秒，让 worker 有时间把任务做完
 time.Sleep(6 * time.Second)
 fmt.Println("全部完成")
}

执行流程

main：启动 worker 1、worker 2、worker 3
main：塞任务 1、2、3、4、5
worker 1：取到任务1，开始干
worker 2：取到任务2，开始干
worker 3：取到任务3，开始干
worker 1：任务1做完，取任务4
worker 2：任务2做完，取任务5
worker 3：任务3做完，队列空了，等着…
main：close(tasks) → worker 们收到关闭信号，全部退出
main：打印"全部完成"

到底怎么保证"干完了取下一个"还很有序？

关键：channel 的阻塞特性。

for task := range tasks {
 // 干活...
}

range tasks 会自动做这件事：

有任务 → 取出来，执行
没任务 → 阻塞，等着
channel 关闭 → 退出 for 循环

展开来看真实流程：

任务队列（channel）：[1, 2, 3, 4, 5]

worker 1：range tasks → 取到 1 → 开始干
worker 2：range tasks → 取到 2 → 开始干
worker 3：range tasks → 取到 3 → 开始干

// 三个 worker 都在干活，队列里还有 4 和 5

worker 1：干完 → range tasks → 取到 4 → 开始干
worker 2：干完 → range tasks → 取到 5 → 开始干
worker 3：干完 → range tasks → 队列空了 → 阻塞，等着

// 没有新任务了
main：close(tasks)

worker 3：检测到关闭 → 退出
worker 1：干完任务4 → 检测到关闭 → 退出
worker 2：干完任务5 → 检测到关闭 → 退出

为什么不需要锁？

因为 channel 天然安全：

同一个任务不会被两个 worker 取到
channel 保证：取走一个就少一个

一句话总结

range channel → 没任务就阻塞，有任务就取一个，取完再取下一个。channel 关闭 → range 自动结束。

参考源

raw/Go.md

Go 语言工程化：模块管理与项目结构

Mon, 13 Jul 2026 15:42:45 +0800

承接 Go 语言基础：从变量到指针和 Go 语言进阶：方法、接口与错误处理，这一篇覆盖 Go 项目的工程化核心：模块管理、包的组织、目录结构。

Go Modules

之前写的代码都在单个 .go 文件里，使用 package main，直接 go run xxx.go 就能跑。但真实项目通常会有几十个 .go 文件、多个包，还会用到第三方库。这些东西怎么管理？答案就是 Go Modules。

go.mod 是什么？

go.mod 就像项目的“身份证”，它主要记录三类信息：

模块路径是什么：module example.com/demo
项目使用哪个 Go 版本：go 1.26.3
项目依赖哪些第三方模块：由 require 指令记录

为什么要用 Go Modules？

假设你写了一个项目，用了第三方库。朋友拿到代码后，怎么知道需要哪些依赖和版本？

没有 go.mod：

朋友：你用了哪些库？

你：好像有 xxx、yyy，版本忘了……

有 go.mod：

朋友：看 go.mod 就知道了，执行 go mod download 或 go mod tidy 就能准备好依赖。

常用命令

`go mod init 模块路径`

在项目开始时创建 go.mod：

go mod init example.com/demo

生成的文件类似这样：

module example.com/demo

go 1.26.3

练习项目可以使用 demo 这类简单名称；准备发布的模块通常使用代码仓库地址，例如 github.com/用户名/项目名，这样别人才能通过稳定的路径导入它。

`go mod tidy`

go mod tidy 会根据源码中的 import 整理依赖：

添加代码需要、但 go.mod 还没有记录的模块
删除代码已经不再需要的模块
补充或清理 go.sum 中的校验信息

简单说，它会让模块文件与当前代码保持一致。改完依赖后跑一次，通常是个好习惯。

`go get 模块路径`

给当前模块添加或升级依赖：

go get github.com/gin-gonic/gin

它会解析并下载依赖，同时更新 go.mod 和 go.sum。如果你要安装一个命令行工具，而不是给当前项目添加依赖，应使用带版本号的 go install：

go install example.com/tool@latest

go.sum 是什么？

执行 go mod tidy、go get 或构建项目后，通常会出现 go.sum。它记录依赖模块内容的加密校验值：

项目使用某个模块的特定版本
go.sum 保存这个版本及其 go.mod 文件的校验值
再次下载时，Go 会验证拿到的内容是否一致

go.sum 不是用来锁死所有依赖版本的锁文件；真正决定依赖版本的是 go.mod 和 Go 的版本选择规则。go.mod 与 go.sum 都应该提交到 Git，通常不需要手动编辑 go.sum。

package 拆分

为什么要拆 package？

如果所有代码都堆在 main.go 里，用户管理、订单管理和数据库连接会逐渐混在一起。按职责拆包之后，结构会清晰很多：

demo/
 go.mod
 main.go # 程序入口
 user/
 user.go # 用户相关功能
 order/
 order.go # 订单相关功能
 db/
 db.go # 数据库相关功能

怎么拆？

先创建 user/user.go，声明它属于 user 包：

package user

import "fmt"

type User struct {
 Name string
 Age int
}

func Print(u User) {
 fmt.Printf("%s, %d\n", u.Name, u.Age)
}

再在项目根目录的 main.go 中导入它：

package main

import "example.com/demo/user"

func main() {
 u := user.User{Name: "Jasper", Age: 22}
 user.Print(u)
}

这里的导入路径由两部分组成：

example.com/demo/user
└── 模块路径 ──┘ └包目录

也就是：导入路径 = go.mod 中的模块路径 + 包所在的相对目录。

package 与可见性

同一目录下的普通 .go 文件必须属于同一个包。包名通常与目录名最后一段一致，这是一条强烈推荐的惯例，但不是“包名必须等于目录名”的语法规则。

标识符是否能被其他包使用，则由首字母大小写决定：

写法	可见范围
`User`、`Print`	首字母大写，可以被其他包访问
`user`、`print`	首字母小写，只能在当前包内访问

internal 访问控制

internal 是什么？

一句话：internal 是 Go 编译器真正认识的特殊目录，用来限制包的导入范围。

假设项目结构如下：

myapp/
 go.mod # module example.com/myapp
 cmd/api/main.go
 internal/db/db.go

example.com/myapp/internal/db 只能被 example.com/myapp 目录树中的代码导入：

// myapp/cmd/api/main.go：可以导入
import "example.com/myapp/internal/db"

另一个项目则不能导入它：

// otherapp/main.go：编译报错
import "example.com/myapp/internal/db"

更准确地说，规则不是“同一个模块才能用”，而是：只有位于 internal 父目录树中的代码才能导入它。大多数项目把 internal 放在模块根目录，所以看起来就像“只有本模块能用”。

目录	编译器是否特殊处理	用途
`internal/`	是，限制外部导入	不希望暴露给外部项目的实现
`pkg/`	否，只是社区惯例	明确准备对外复用的包，可选

常见项目结构

Go 官方没有规定一套所有项目都必须照搬的“标准目录结构”。下面是一种常见布局，适合已经出现多个入口和多个业务模块的项目：

myproject/
 cmd/ # 程序入口
 api/
 main.go # 启动 HTTP 服务
 worker/
 main.go # 启动后台任务
 internal/ # 不对模块外部开放的代码
 config/
 config.go # 配置读取
 db/
 db.go # 数据库连接
 user/
 user.go # 用户相关逻辑
 handler/
 handler.go # HTTP 处理函数
 pkg/ # 确实需要对外复用时再添加
 utils/
 utils.go
 go.mod
 go.sum

三个常见目录的职责：

cmd/：每个子目录对应一个可执行程序，包名为 main；通常只负责依赖组装、配置和启动
internal/：放不希望被外部项目导入的实现代码，不代表所有业务逻辑都必须塞在这里
pkg/：表达“这些包准备公开复用”的意图，没有编译器层面的特殊含义；小项目完全可以没有

目录不是越多越工程化。只有一个可执行程序的小项目，把 main.go 放在根目录也很正常；随着入口和职责增多，再引入 cmd/、internal/ 即可。

为什么要多一层 cmd/？

一个项目可能提供多个启动方式：

cmd/api/main.go # 启动 HTTP 服务
cmd/worker/main.go # 启动后台任务

它们是两个入口，但可以共享 internal/ 里的业务代码。cmd/ 下的程序应尽量轻量：

// cmd/api/main.go
package main

import "example.com/myproject/internal/server"

func main() {
 server.Start()
}

cmd/api 中不一定只能有一个 main.go，也可以有多个属于 package main 的文件；重要的是入口层保持轻薄，不把大量业务逻辑堆在这里。

引入第三方包

标准库是 Go 自带的，例如 fmt、net/http。标准库之外，由其他项目提供的包就是第三方包，例如：

github.com/gin-gonic/gin：Web 框架
github.com/jackc/pgx/v5：PostgreSQL 驱动与工具包
github.com/spf13/cobra：命令行应用框架

以 UUID 包为例，先添加依赖：

go get github.com/google/uuid

再在代码里导入并使用：

package main

import (
 "fmt"

 "github.com/google/uuid"
)

func main() {
 id := uuid.New()
 fmt.Println(id)
}

此时 go.mod 可能包含：

module example.com/user-api

go 1.26.3

require github.com/google/uuid v1.6.0

改动依赖后执行：

go mod tidy
go test ./...

第一条命令整理模块文件，第二条命令确认整个模块仍能编译并通过测试。到这里，一个 Go 项目从单文件走向模块化工程的基本骨架就搭起来了。

Go 语言基础：从变量到指针

Tue, 07 Jul 2026 00:00:00 +0800

一份 Go 入门语法梳理，从变量到指针，覆盖日常开发最常用的核心概念。

变量声明

两种方法。

1. `var` 标准形式

var name type = value // 标准形式
var pi = 22 // 可以自动推断类型，省略 type
var score int // 可以不给 value

声明不赋值时，系统自动给零值。

2. `:=` 简短声明

name := "草泥马"

比较常见。限制：

只能在函数里用（全局范围必须用 var）
不能只声明不赋值

常量与 iota

常量不可更改，直接用 const 声明：

const Pi = 3.14
const name = "xxx"

常量必须在编译期确定，不能把运行时的值赋给常量：

const now = time.Now() // ✗ 编译报错，time.Now() 是运行时才有的

iota 是 Go 在 const 块里提供的自动计数器：

const (
 Sunday = iota // 0
 Monday // 1
 Tuesday // 2
 Wednesday // 3
)

比较简洁。想跳过某个值，用 _ = iota 占位就好。

注意：Go 没有 enum 关键字，做枚举需要用 const + iota。

数据类型

Go 是强类型语言，类型间不能自动转换（区别于 JS、Python），只能手动强制转换：

var a = 10
var b = 3.14
// 要算 a + b，必须先转类型
float64(a) + b

基本类型一览

var i int = 42 // 平台相关，64 位系统就是 64 位
var i8 int8 = 127 // 范围 -128 ~ 127
var u uint = 42 // 无符号，没有负数
var f32 float32 = 3.14
var f64 float64 = 3.14 // 一般都用 float64
var s string = "hello"
var b bool = true // 只有 true/false，没有 1/0

rune 与 byte 的区别

var b byte = 'A' // byte 就是 uint8，存储一个 ASCII 字符
var r rune = '中' // rune 就是 int32，存储一个 Unicode 字符

为什么要这样？英文字母只占一个字节，而中文、emoji 占 3~4 个字节，一个 byte 装不下，需要 rune。

s := "hello"
len(s) // 5，len 对 string 返回字节数
len([]rune(s)) // 5，返回字符数

想拿字符数就用 len([]rune(s))。原理：[]rune(s) 把 string 转成 []rune 切片。

字符串的两种写法

s1 := "hello\nworld" // 双引号，解释型：\n 会被解释成换行
s2 := `hello\nworld` // 反引号，原始字符串：字面上的 \n 不会换行

切片 Slice

先说数组，但几乎不会用它：

var arr [3]int = [3]int{1, 2, 3} // 长度固定，声明时定死

所以实际开发用可变数组——切片。

slice 声明

nums := []int{1, 2, 3} // 字面量
s := make([]int, 0, 10) // make 指定长度 0，容量 10
var names []string // nil，长度 0，后面 append

len 与 cap

每个 slice 有两个属性：

len 长度：里面实际有多少个元素
cap 容量：底层数组最多能装多少个

s := make([]int, 3, 10)
fmt.Println(len(s)) // 3
fmt.Println(cap(s)) // 10

append 添加元素

nums := []int{1, 2, 3}
nums = append(nums, 4) // 末尾多了个 4
nums = append(nums, 5, 6, 7) // now [1,2,3,4,5,6,7]

注意：append 返回的是新的 slice，必须赋值回去。

扩容：当 append 超过 cap 时，Go 会自动分配一个更大的底层数组，把旧数据拷过去。你不需要手动管，但要知道这个机制存在——它会影响性能。

切片操作

nums := []int{10, 20, 30, 40, 50}
sub := nums[1:3] // 左闭右开 → [20, 30]
all := nums[:] // 全部
first := nums[:2] // [10, 20]
last := nums[2:] // [30, 40, 50]

⚠️ 陷阱：切片出来的 sub 和原 slice 共享底层数组，修改 sub 会影响 nums：

sub[0] = 999
fmt.Println(nums) // [10, 999, 30, 40, 50] —— nums 也被改了！

要独立拷贝用 copy。

遍历

fruits := []string{"apple", "banana", "cherry"}
for i, v := range fruits {
 fmt.Printf("[%d] %s\n", i, v)
}

// 不要索引就用 _
for _, v := range fruits {
 // ...
}

Map

其实就是映射。

// 创建一个 map，key 是 string，value 是 int
scores := map[string]int{
 "math": 90,
 "english": 85,
 "chinese": 92,
}

// 取值
fmt.Println(scores["math"]) // 90

// 添加/修改
scores["science"] = 88 // 新增
scores["math"] = 95 // 修改（key 已存在就覆盖）

// 删除
delete(scores, "english")

长度用 len()。

Comma-ok 模式

取一个不存在的 key 会怎么样？一般直接返回 value 类型的零值。但这会出问题——0 是真实分数，还是因为 key 不存在？所以提供 comma-ok 模式：

score, ok := scores["physics"]
if ok {
 fmt.Println("找到了：", score)
} else {
 fmt.Println("不存在")
}
// ok 是 bool 型变量

Map 的零值

var m map[string]int // nil map
m["a"] = 1 // 🙅 nil map 不能写入

和 slice 一样，声明之后必须初始化才能使用：

m := map[string]int{} // 方式 1：空字面量
m := make(map[string]int) // 方式 2：make

遍历

scores := map[string]int{"math": 90, "english": 85}
for subject, score := range scores { // 同时给 subject、score 赋值
 fmt.Printf("%s: %d\n", subject, score)
}

结构体 Struct

结构体的知识在 C/C++ 中已经讲过很多，这里给个框架：

type Car struct {
 Brand string
 Color string
 Money float64
}

创建实例：

var c Car
c.Brand = "特斯拉"
fmt.Println(c.Brand)

struct 与 map/slice 的区别

struct 是值类型，不同于 map、slice 底层数据共享。struct 可以直接赋值、修改元素，赋值时会拷贝一份完整数据。

struct 与 JSON 互转

这是实际开发中的高频操作。

import "encoding/json"

func main() {
 c := Car{Brand: "特斯拉", Color: "白色", Money: 25.99}

 // 转成 JSON
 jsonData, err := json.Marshal(c)
 if err != nil {
 fmt.Println("转换失败:", err)
 return
 }
 fmt.Println(string(jsonData)) // string() 将字节数组转为可读字符串
}

⚠️ 问题：JSON 里的字段是大写的 Brand，但前端习惯小写。

解决：struct tag，用反引号包裹：

type Car struct {
 Brand string `json:"brand"`
 Color string `json:"color"`
 Money float64 `json:"money"`
}

这样序列化出来的 JSON key 就是小写了。注意反引号 ` 里面整个 json:"xxx" 是一个整体，冒号后面不能有空格。

流程控制

三个核心：if/else、switch、for（Go 没有 while）。

if/else

Go 的 if 可以带初始化语句，用 ; 分隔：

if age := 20; age >= 18 {
 fmt.Println("成年人")
}
// age 仅在 if 块内生效

⚠️ 如果用到了 else，Go 强制要求 } else { 必须在同一行，不然编译报错：

if condition {
 // ...
} else {
 // ...
}

switch

Go 的 switch 不需要写 break，每个 case 自动结束：

day := "Monday"
switch day {
case "Monday":
 fmt.Println("星期一")
case "Tuesday":
 fmt.Println("星期二")
default:
 fmt.Println("其他")
}

for 循环

Go 只有 for，但有四种写法：

1. 经典写法（和 C 一样）

for i := 0; i < 5; i++ {
 // ...
}

2. 当 while 用（只有一个条件）

i := 0
for i < 5 {
 i++
}

3. 无限循环（配合 break）

for {
 fmt.Println("一直跑")
 break
}

4. range 遍历（实际开发中用得最多）

// 遍历 slice
nums := []int{10, 20, 30}
for i, v := range nums {
 fmt.Println(i, v)
}

// 遍历 map
scores := map[string]int{"张三": 90, "李四": 85}
for k, v := range scores {
 fmt.Println(k, v)
}

range 后面可以只用一个变量接收值，用 _ 跳过不需要的：

for _, v := range nums {
 // 只要值，不要索引
}

注意：for 的三部分不用括号，但分号不能省。

函数

Go 用 func 定义函数，函数必须定义在函数外。格式正常，重点看多返回值——这是 Go 的特色。

func divide(a, b float64) (float64, error) {
 if b == 0 {
 return 0, fmt.Errorf("除数不能为零")
 }
 return a / b, nil
}

func main() {
 result, err := divide(10, 3)
 if err != nil {
 fmt.Println("出错了:", err)
 } else {
 fmt.Println("结果:", result)
 }
}

几点注意：

error 是 Go 内置的接口类型，表示错误
没出错时返回 nil
fmt.Errorf 创建一个带错误信息的 error

Go 的错误处理模式就是 返回值 + if 判断，没有 try-catch。这在后面写项目时会反复见到。

指针

核心概念：

概念	符号	作用
取地址	`&a`	获取变量 a 的内存地址
解引用	`*p`	通过地址，读取或修改那个地址里的值

指针类型：

普通类型	对应指针类型	读法
int	`*int`	指向 int 的指针
string	`*string`	指向 string 的指针
User	`*User`	指向 User 的指针

指针的零值是 nil：

var p *int // p 的零值是 nil，没有指向任何东西

两个必须记住的事：

Go 函数传参永远是复制。想改原件，必须传指针。
& 是"取地址"，* 是"去地址找东西"。两个方向相反。

直觉：普通变量是盒子里装着值，指针是纸条上写着"盒子在哪"。

指针与 struct

func birthday(u *User) {
 u.Age++ // Go 自动解引用，不用写 *u（语法糖）
}

func main() {
 user := User{"Jasper", 22}
 birthday(&user) // 传地址
 fmt.Println(user.Age) // 23
}

Go 中局部变量习惯用小驼峰 maxStudent 而不是大驼峰 MaxStudent。import 用小括号 () 而不是花括号 {}。

练习：学生成绩管理

一个综合 struct、slice、指针的小练习：

package main

import "fmt"

type Student struct {
 Name string
 Grade float64
}

// 找出成绩最高的学生
func findMaxGrade(students []Student) Student {
 maxStudent := students[0]
 for _, student := range students {
 if student.Grade > maxStudent.Grade {
 maxStudent = student
 }
 }
 return maxStudent
}

// 给学生加 5 分（通过指针修改原件，不需要返回值）
func plusFive(student *Student) {
 student.Grade += 5
}

func main() {
 students := []Student{
 {Name: "Alice", Grade: 85},
 {Name: "Bob", Grade: 90},
 {Name: "Charlie", Grade: 78},
 }
 maxStudent := findMaxGrade(students)
 plusFive(&maxStudent)
 fmt.Printf("最高分学生: %s, 成绩: %.2f\n", maxStudent.Name, maxStudent.Grade)
}

参考源

raw/go学习之路.md
raw/go.md

Go 语言进阶：方法、接口与错误处理

Tue, 07 Jul 2026 00:00:00 +0800

承接 Go 语言基础：从变量到指针，这一篇覆盖 Go 的进阶核心概念：方法、接口、错误处理，以及泛型入门。

方法

// 普通函数：参数是 Student
func greet(s Student) string {
 return "Hello, " + s.Name
}

// 方法：绑在 Student 上
func (s Student) greet() string {
 return "Hello, " + s.Name
}

区别就在于函数名前面多了一个 (s Student)，这叫接收者（receiver）。

调用方式不同：

student := Student{"Jasper", 90}

// 函数调用
greet(student)

// 方法调用
student.greet()

返回一个字符串可以用 fmt.Sprintf。

值接收者 vs 指针接收者

在接收者的类型前加 * 就变成指针接收者。值接收者只改副本，指针接收者改原件。

// 值接收者：改的是副本
func (s Student) setScore(score float64) {
 s.Grade = score // 不影响原值
}

// 指针接收者：改的是原件
func (s *Student) setScore(score float64) {
 s.Grade = score // 修改原值
}

接口

Go 中最重要的概念之一。

// 定义接口：任何有 speak() 方法的类型，都算 Speaker
type Speaker interface {
 speak() string
}

// Dog 有 speak() 方法，Dog 实现了 Speaker
type Dog struct {
 Name string
}

func (d Dog) speak() string {
 return "Woof"
}

// 同理 Cat 亦如此
type Cat struct {
 Name string
}

func (c Cat) speak() string {
 return "Meow"
}

// 通用函数：接受任何 Speaker
func makeItSpeak(s Speaker) {
 fmt.Println(s.speak())
}

func main() {
 dog := Dog{"Buddy"}
 cat := Cat{"Kitty"}
 makeItSpeak(dog) // Woof!
 makeItSpeak(cat) // Meow!
}

三个要点：

接口定义：type Speaker interface { speak() string } — 定义了一个"能力"，不关心谁实现
隐式实现：Dog 和 Cat 都有 speak() 方法，所以它们自动"算"是 Speaker，不需要显式声明 implements
通用函数：makeItSpeak(s Speaker) 接受任何 Speaker，不关心具体是 Dog 还是 Cat

嵌入接口

小接口可以组合成大接口：

// 两个独立接口
type Speaker interface { speak() string }
type Walker interface { walk() string }

// 嵌入组合
type SpeakerWalker interface {
 Speaker // 把 Speaker 的方法拿过来
 Walker // 把 Walker 的方法拿过来
}

效果：SpeakerWalker 自动拥有 speak() 和 walk() 两个方法。

接口哲学：小接口 > 大接口

Go 的接口是隐式实现的：

// C++ / Java：必须显式声明"我实现了这个接口"
class Person implements Speaker { ... }

// Go：只要你有方法，就自动满足接口
type Person struct { Name string }
func (p Person) speak() string { return "hi" }
// Person 自动满足 Speaker，不需要声明

标准库里最常见的接口：

// io.Reader — 只有一个方法
type Reader interface {
 Read(p []byte) (n int, err error)
}

// io.Writer — 只有一个方法
type Writer interface {
 Write(p []byte) (n int, err error)
}

Go 标准库里很多接口只有 1~2 个方法，而不是把所有功能堆在一个大接口里。

为什么小接口好？

容易实现 — 一个方法的接口，任何类型都能轻松满足
容易组合 — 用嵌入把小接口组合成大接口
灵活 — 你只关心你需要的能力，不关心具体类型

特性	Go	Java/C++
实现方式	隐式（自动满足）	显式（需要声明）
接口大小	通常 1-2 个方法	通常很多方法
设计哲学	小接口，按需组合	大接口，一次定义

io.Reader 与 io.Writer

这是 Go 标准库里最常用的两个接口，用来处理"数据流"。

先想一个问题：从哪里读数据？

从文件读
从网络读
从键盘读
从字符串读

这些地方都能读数据，但它们的实现完全不同。接口解决这个问题：

// io.Reader：任何"能读出数据"的东西
type Reader interface {
 Read(p []byte) (n int, err error)
}

翻译成大白话：

“你只要有 Read 方法，能往 p 里填数据，你就是个 Reader”

参数/返回	含义
`p []byte`	一个空的容器（桶），你把读到的数据放进去
返回 `n int`	实际读了多少字节
返回 `err error`	读取过程中有没有出错

为什么这个接口牛？因为它只有一个方法，所以实现简单、使用广泛——标准库里几百个函数都接受 Reader。

// 这些类型都实现了 io.Reader
// - os.File （文件）
// - strings.Reader （字符串）
// - bytes.Buffer （字节缓冲区）
// - net.Conn （网络连接）

// 通用函数：不关心数据从哪来，只管读
func printAll(r io.Reader) {
 data := make([]byte, 100)
 n, _ := r.Read(data)
 fmt.Println(string(data[:n]))
}

// 从文件读
file, _ := os.Open("test.txt")
printAll(file)

// 从字符串读
str := strings.NewReader("hello")
printAll(str)

同一个函数，能处理不同类型的数据源——这就是接口的价值。

接口	方法数	作用
`io.Reader`	1	能读
`io.Writer`	1	能写
`io.Closer`	1	能关闭
`io.ReadWriter`	2	能读能写（嵌入组合）

Go 的设计哲学：把大能力拆成小接口，按需组合。

空接口 any 与类型断言

有时候需要处理"任意类型"，这时候用空接口：

// any 是 interface{} 的别名
func printAnything(v any) {
 fmt.Println(v)
}

但是有个问题：拿到的是 any，不知道具体的类型怎么办？此时引出类型断言与 type switch。

类型断言

func printAnything(v any) {
 if s, ok := v.(string); ok {
 fmt.Println("是字符串:", s)
 } else if n, ok := v.(int); ok {
 fmt.Println("是整数:", n)
 } else {
 fmt.Println("其他类型:", v)
 }
}

Type Switch

更简洁的写法：

func printAnything(v any) {
 switch val := v.(type) {
 case string:
 fmt.Println("是字符串:", val)
 case Student:
 fmt.Println("是学生:", val)
 }
}

v.(type) 是 Go 的特殊语法，只能在 switch 里用，意思是"告诉我 v 的实际类型是什么"。val 会自动变成对应分支的类型。

Comma-Ok 模式详解

这是 Go 里处理"可能失败的操作"的通用模式，类型断言只是其中一个用法。

s, ok := v.(string)

尝试把 v 转成 string
如果成功：s = 转换后的值，ok = true
如果失败：s = 空字符串零值，ok = false

关键点：如果不写 ok，断言失败会直接 panic（程序崩溃）。所以一般都用 , ok 安全地处理：

// 不安全：失败会 panic
s := v.(string)

// 安全：失败只是 ok = false
s, ok := v.(string)

接口 vs Type Switch

方式	优点	缺点
接口	扩展性好，加新类型不用改函数	需要提前定义接口
Type Switch	直观，能处理任意类型	加新类型要改函数

错误处理

strconv 是 Go 标准库里专门处理字符串和数字之间转换的包。strconv.Atoi = ASCII to Integer。

Go 的错误处理模式：

result, err := someFunction()
if err != nil {
 // 处理错误
 return ..., err // 往上层传
}
// 正常使用 result

核心规则：

错误是普通值，函数返回 error 接口
nil = 没错，非 nil = 有错（带错误信息）
函数只返回错误，调用方决定怎么处理

error 接口

error 是 Go 内置的接口，只有一个方法：

type error interface {
 Error() string
}

任何实现了 Error() string 方法的类型，都算 error。

创建自己的错误

使用 errors.New 或 fmt.Errorf：

import "errors"

func divide(a, b float64) (float64, error) {
 if b == 0 {
 return 0, errors.New("除数不能为零")
 }
 return a / b, nil
}

或者用 fmt.Errorf 带格式化：

return 0, fmt.Errorf("除数不能为零：%f", b)

错误包装

有时候你想在错误上加点上下文，但是不想丢失原始错误：

func readConfig(path string) (string, error) {
 data, err := os.ReadFile(path)
 if err != nil {
 // 包装原始错误，加上上下文
 return "", fmt.Errorf("读取配置文件失败：%w", err)
 }
 return string(data), nil
}

然后用 errors.Is 判断错误类型：

content, err := readFile("不存在的文件.txt")
if err != nil {
 fmt.Println("错误:", err)
 if errors.Is(err, os.ErrNotExist) {
 fmt.Println("原因：文件不存在")
 }
}

设计理念：错误处理就像"层层汇报"

想象一个公司出了问题：

员工：硬盘坏了（原始错误）
主管：服务器出问题了（包装一层）
经理：系统故障（再包装一层）

如果只传一句话：经理只知道"系统故障"，不知道根本原因，没法针对性解决。

如果层层包装但保留原始原因：经理收到 → 系统故障 → 服务器出问题 → 硬盘坏了。经理可以用 errors.Is 查问：“是不是硬盘的问题？"——穿透所有包装，直接找到根本原因。

代码对应：

// 底层：硬盘坏了
os.ReadFile("xxx") // 返回 os.ErrNotExist（文件不存在）

// 中层：服务器出问题了
fmt.Errorf("读取文件失败: %w", err) // 包装，但保留原始错误

// 顶层：经理
if errors.Is(err, os.ErrNotExist) {
 // 穿透包装，发现根本原因是"文件不存在"
 fmt.Println("原因：文件不存在")
}

三种方式对比：

// 方式1：只传原始错误（不好）
return err // main 只知道 "no such file or directory"，不知道是哪个文件

// 方式2：只传新错误（不好）
return errors.New("读取文件失败") // main 不知道为什么失败

// 方式3：包装（正确）
return fmt.Errorf("读取文件失败: %w", err) // main 既知道上下文，又能判断原因

Sentinel Errors（哨兵错误）

就是预先定义好的错误值，让我们可以用 errors.Is 判断。os.ErrNotExist 就是一个 Sentinel Error。自己也可以定义：

var ErrInvalidAge = errors.New("年龄不能为负数")

func setAge(age int) error {
 if age < 0 {
 return ErrInvalidAge
 }
 return nil
}

// 调用方
err := setAge(-1)
if errors.Is(err, ErrInvalidAge) {
 fmt.Println("年龄不合法")
}

panic 与 recover

Go 中大部分用 error 处理错误，但有些情况下程序直接崩溃——panic。

panic：程序崩溃
recover：捕获 panic，让程序继续运行

什么时候用 panic

程序遇到无法继续运行的严重错误：

func divide(a, b int) int {
 if b == 0 {
 panic("除数不能为零") // 程序崩溃
 }
 return a / b
}

什么时候用 recover

在服务器程序里，你不想因为一个请求崩溃就让整个服务器挂掉：

func safeDivide(a, b int) (result int, err error) {
 defer func() {
 if r := recover(); r != nil {
 err = fmt.Errorf("捕获 panic: %v", r)
 }
 // %v 是 Go 里最通用的格式化动词，意思是"用默认格式打印值"
 }()
 return divide(a, b), nil
}

几个要点：

命名返回值：(result int, err error) — Go 允许给返回值起名字，函数内部可以直接用这些名字，return 时可以省略返回值
defer：延迟执行，函数结束的时候才运行
recover：捕获 panic 的唯一方式，只能在 defer 里用

// defer 里的匿名函数：定义后立即调用
defer func() {
 if r := recover(); r != nil {
 // r 是 panic 传出来的信息
 fmt.Println("捕获到 panic:", r)
 }
}() // 定义完立刻调用

泛型（了解即可）

为什么需要泛型？

没有泛型时，同一个逻辑要写多份：

func maxInt(a, b int) int {
 if a > b { return a }
 return b
}

func maxFloat(a, b float64) float64 {
 if a > b { return a }
 return b
}

逻辑完全一样，只是类型不同。泛型用一个函数搞定：

func max[T int | float64 | string](a, b T) T {
 if a > b { return a }
 return b
}

泛型函数语法

func 函数名[类型参数 约束](参数) 返回类型

拆解 func max[T int | float64 | string](a, b T) T：

func max → 函数名
[T int | float64 | string] → T 可以是 int、float64 或 string
(a, b T) → a 和 b 都是 T 类型
T → 返回类型也是 T

调用时 Go 会自动推断 T 的类型：

max(1, 2) // T = int
max(1.5, 2.5) // T = float64
max("hello", "world") // T = string

类型约束

约束就是告诉编译器"T 必须是什么类型”。

常用约束：

[any] → 任意类型
[comparable] → 可以用 == 比较的类型
[constraints.Ordered] → 可以用 < > 比较的类型（int、float64、string）

自定义约束：

type Number interface {
 int | int32 | int64 | float32 | float64
}

func sum[T Number](nums []T) T {
 var total T
 for _, n := range nums {
 total += n
 }
 return total
}

泛型类型

泛型还能用在 struct 上：

type Stack[T any] struct {
 items []T
}

func (s *Stack[T]) push(item T) {
 s.items = append(s.items, item)
}

func (s *Stack[T]) pop() T {
 item := s.items[len(s.items)-1]
 s.items = s.items[:len(s.items)-1]
 return item
}

// 使用
intStack := &Stack[int]{}
intStack.push(1)
intStack.push(2)
fmt.Println(intStack.pop()) // 2

strStack := &Stack[string]{}
strStack.push("hello")
fmt.Println(strStack.pop()) // hello

参考源

raw/Go语言.md