Zowely

在线体验：ak.lansganbs.cn

起因#

明日方舟不缺「指定材料 → 刷哪关」的计算器，但几乎没有工具回答一个更前置的问题：我现在整体最缺什么？

大多数计算器的思路是「目标驱动」——先选一个想合成的材料，再反推最优刷图路线。但对于已经有一定库存的老玩家，真正的痛点往往不是「某一种材料去哪刷」，而是「仓库整体失衡了，不知道该先补哪一块」。

这个工具换了一个切入点：把仓库里所有素材统一折算到一个可比较的口径，然后直接告诉你缺口最大的蓝材是什么。

核心思路#

整个计算流程可以概括为三步：

折算：将所有品质的素材按权重折算为蓝色素材等价物
排序：按缺口量从大到小排列，找出仓库最失衡的方向
决策：玩家根据排序结果决定接下来优先刷什么

这种「先看全局再定目标」的思路，更适合已经有一定库存积累、不想每次都先指定目标材料的玩家。

功能#

库存导入#

支持两种主流库存 JSON 格式，导入时自动识别来源：

企鹅物流规划器格式
MAA 仓库识别导出的 details.data 格式

如果上传的是 MAA 导出数据，会先过滤掉经验书、芯片、模组材料等无关项，再转换为内部统一的企鹅物流格式处理。

权重系统#

内置一份默认权重数据，无需额外配置即可使用。权重决定了不同品质素材之间的折算比例——比如一个紫材等价于多少蓝材。

如果需要更新权重，可以从一图流下载最新数据，再通过页面重新导入覆盖。

在线编辑#

导入库存后，可以直接在页面中修改任意素材的数量，无需重新上传文件。方便手动调整或做假设分析。

缺口计算#

点击计算后，会输出当前最缺的蓝色素材排名，并支持展开查看完整排序。一目了然地看到仓库哪里失衡最严重。

库存导出#

支持将当前库存导出为企鹅物流格式的 JSON 文件（export_penguin.json），方便在其他工具中继续使用。

本地运行#

确保本地已安装 Node.js 18+ 和 npm，然后执行：

Terminal window

1
# macOS / Linux
2
./start.sh
3

4
# Windows CMD
5
start.bat
6

7
# Windows PowerShell
8
.\start.ps1

首次启动会自动安装前端依赖并打开本地页面。

手动启动：

Terminal window

1
cd frontend
2
npm ci
3
npm run start

部署#

仓库已包含 GitHub Actions 工作流，推送到 main 分支后自动部署到 GitHub Pages：

将仓库推到 GitHub
进入 Settings → Pages
Source 选择 GitHub Actions
推送后自动构建部署

技术细节#

纯静态页面，无后端依赖，所有计算在浏览器端完成
Liquid Glass 视觉风格
只关注素材，不处理芯片、经验书、龙门币等其他物品
所有品质素材统一折算到蓝材口径进行比较

小红书基础架构部面经

Mon, 09 Mar 2026 00:00:00 GMT

一面（03-02）#

Docker 和 Kubernetes 有什么区别？
请介绍 Binlog、Redo Log 和 Undo Log 的作用及写入时机。
Redo Log 和数据页最终都要写入磁盘，为什么还需要额外写 Redo Log？
给定一个正整数 aaa，将其分解为若干大于 1 的正整数之积，且满足 a1≤a2≤⋯≤ana_1 \leq a_2 \leq \cdots \leq a_na1≤a2≤⋯≤an，其中 a=aa=aa=a 也算一种分解，求共有多少种不同的分解方式。
请介绍 Multi-Raft 项目中的 Replica Group。
为什么采用 Multi-Raft，而不是让所有数据共用一个 Raft Group？
Multi-Raft 共识引擎做过哪些性能调优？
Raft 日志复制发生冲突时，如何快速回溯并定位匹配位置？
Multi-Raft 系统是否支持日志回收，具体如何实现？
请介绍 Raft 协议中的 Leader、Follower 和 Candidate 三种角色。
如果同一个 Term 中出现两个 Leader，系统应如何处理？
Raft 集群发生网络分区后，网络恢复时会经历什么流程？
Multi-Raft 系统如何实现负载均衡？

二面（03-03）#

给定平面上的四个点，如何判断它们能否组成一个正方形？
给定 nnn 个数，如何实现一个既不会溢出、又不会产生精度误差的 avg 函数？
为什么使用增量平均公式仍然不能满足“无精度误差”的要求？
Raft 日志复制发生冲突时，如何快速回溯？
如果 Follower 缺少对应日志，Leader 应如何定位双方日志的冲突位置？
日志回溯过程中能否触发新的 Leader 选举？
对 Raft 原论文所做的协议改进，应如何论证其正确性？
Multi-Raft 或 Raft 协议中最核心的性质有哪些？
Raft 制作 Snapshot 的根本诉求是解决 CPU 使用率过高吗？
为什么 Raft 节点重启时需要从第一条日志开始恢复，是因为系统没有快照吗？
阅读或了解过哪些开源 Raft 实现？

三面（03-06）#

请介绍 Redis 的持久化机制。
生成 RDB 快照后，Redis 是否可以继续一直写入 AOF？
持续写入 AOF 是否会直接导致文件过大？
C/C++ 中指针和数组有什么区别？
TCP 端口承担什么作用？
TCP/UDP 端口号只有 65535 个，当进程数或连接数超过这个数量时，端口是否会不够用？
服务器建立大量连接后，内核如何根据收到的数据包找到对应连接，例如多个连接的目标端口都是 80 时如何区分？
请介绍项目的完整业务流程。
项目中的订单号是如何生成的？
项目引入 Redis 是为了解决什么问题？
项目引入消息队列是为了解决什么问题？
项目是否可以不使用 Redis，去掉后会产生什么影响？
项目是否可以不使用消息队列，去掉后会产生什么影响？
为什么消息处理需要保持局部顺序性？
如果张三的订单消息阻塞，同一队列中后续的李四、王五订单应如何处理？
用户尚未成功创建订单时为什么能够点击支付，订单创建与支付流程是否应该串行化？
如果购买接口中的下单操作执行失败，后续流程应如何处理？

腾讯S3线面经

Thu, 05 Mar 2026 00:00:00 GMT

一面（03-05）#

Go 的垃圾回收机制是怎样的？
Go 垃圾回收为什么采用三色标记法？
Go 的 map 底层是如何实现的？
Go 的 map 内部是否自带锁？
Go 的 map 是否支持并发访问，应如何控制并发？
Go 中 defer 关键字有什么作用？
注册多个 defer 时，它们按照什么顺序执行？
使用过哪些 Go 框架？
ProtoBuf 和 JSON 有哪些异同？
Raft 为什么需要使用 Snapshot？
RAG 适用于哪些场景？
哪些产品使用了 RAG？
如何确认一个产品确实使用了 RAG？
实现 Top-K 算法，并保证时间复杂度低于 O(nlog⁡n)O(n \log n)O(nlogn)。

字节抖音直播后端面经

Mon, 09 Feb 2026 00:00:00 GMT

一面（01-30）#

如果自行设计一个限流器，会如何设计？
给定一个有序、可并行执行的任务列表，如何使用 Golang 并行执行任务，并在前序任务执行完毕后按照原顺序输出结果？
Raft 中日志不匹配时需要逐条回溯，时间复杂度为 O(N)O(N)O(N)，应该如何优化？
Raft 日志的批量同步应该如何实现？
批量同步 Raft 日志时，如何确定每一批应该发送多少条日志？
Raft 性能测试数据是如何测得的，又应该如何量化？
Raft 日志未经优化时可能遇到磁盘 I/O 瓶颈，应该如何优化？
Multi-Raft 节点重启后应该如何恢复？
Multi-Raft 系统的流量监控是如何实现的？
如何使用 Prometheus 进行指标埋点，需要重点监控哪些指标？

二面（02-03）#

进程和线程有什么区别？
哪些场景适合使用多线程，哪些场景适合使用多进程？
进程之间有哪些通信方式？
Linux 中常见的信号有哪些？
TCP 拥塞控制的过程是怎样的，其中涉及哪些超时器或重传机制？
发起一次网络请求时，会涉及哪些网络缓存？
给定一个数字集合 digits 和上限 nnn，如何使用 digits 中的数字组成一个严格小于 nnn 的最大数？
Multi-Raft 和单 Raft 有什么区别？
Multi-Raft 的数据同步是如何执行的？
Multi-Raft 系统如何管理不同节点上的 Leader，Leader 是否存在备份？
Multi-Raft Group 的 Leader 宕机后，系统应该如何处理？
Raft 的完整选举流程是怎样的？

终面（02-09）#

Kubernetes HPA 执行水平扩展时，各节点之间是否需要相互通信？
新增节点正在加载数据时，是否应该对外提供服务？
如何确认服务已经 Ready，是由服务主动上报，还是由 Kubernetes 主动探测？
如何实现 LeetCode 56「合并区间」？
高并发场景下，可以在数据库上游提供哪些支持来降低数据库压力？
消息队列应该放在系统链路的什么位置，为什么要放在那里？
消费服务宕机后，消息队列中的消息应该如何处理？
请介绍项目中的本地信息表。
GORM 的预加载机制是什么，如何利用它提升性能，又会付出什么代价？
如果系统需要支持 10,000 QPS，应该如何估算所需内存？
如果系统 QPS 持续增长，应该如何扩展和保护系统？

CloudWeGo-Kitex

Thu, 05 Feb 2026 00:00:00 GMT

1. 为什么选择 Kitex#

如果你已经熟悉 gRPC，可能会问：为什么还需要 Kitex？

1.1 gRPC 的局限性#

gRPC 是 Google 开源的 RPC 框架，基于 HTTP/2 协议，但它有一些限制：

协议绑定：强制使用 HTTP/2，无法切换到其他传输协议
网络库：基于 Go 标准库的 net/http，在高并发场景下性能受限
扩展性：中间件机制相对简单，难以实现复杂的治理功能
序列化：仅支持 ProtoBuf，无法使用 Thrift

1.2 Kitex 的核心优势#

Kitex 是字节跳动开源的 RPC 框架，属于 CloudWeGo 微服务生态的一部分。

底层逻辑：Kitex 不依赖 HTTP/2，而是基于自研的网络库 Netpoll，实现了：

多协议支持：支持 Thrift、ProtoBuf、gRPC 协议
高性能网络层：基于 epoll/kqueue，零拷贝优化
丰富的治理功能：服务发现、负载均衡、熔断、限流、超时控制
代码生成优化：通过 kitex 工具生成高性能的序列化代码

与 gRPC 的核心差异：

gRPC 是”协议优先”（HTTP/2），Kitex 是”性能优先”（可插拔协议）
gRPC 的中间件是拦截器（Interceptor），Kitex 的中间件是洋葱模型（Middleware）
Kitex 内置了完整的微服务治理功能，gRPC 需要额外集成

2. 核心架构#

2.1 分层设计#

Kitex 采用四层架构：

1
治理层 (服务发现/负载均衡/熔断)
2
    ↓
3
中间件层 (Middleware)
4
    ↓
5
协议层 (Thrift/Protobuf/gRPC)
6
    ↓
7
网络层 (Netpoll)

底层逻辑：这种分层使得 Kitex 可以灵活扩展。例如：

协议层可以切换 Thrift/ProtoBuf
网络层可以切换 Netpoll/Go Net
治理层可以插拔不同的服务发现组件（Consul/Etcd/Nacos）

2.2 核心数据结构#

RPCInfo#

Kitex 的核心是 rpcinfo.RPCInfo，它贯穿整个请求生命周期。

1
type RPCInfo interface {
2
    From() EndpointInfo    // 调用方信息
3
    To() EndpointInfo      // 被调用方信息
4
    Invocation() Invocation // 方法调用信息
5
    Config() RPCConfig     // RPC 配置
6
    Stats() RPCStats       // 统计信息
7
}

关键字段解析：

From/To：记录调用链路信息（服务名、方法名、地址）
Invocation：当前调用的方法名和参数类型
Stats：记录耗时、错误等统计信息

底层逻辑：RPCInfo 通过 context.Context 传递，中间件可以读取和修改它，实现链路追踪、监控等功能。

3. 快速上手#

3.1 代码生成#

Kitex 使用代码生成工具，基于 Thrift/ProtoBuf IDL 生成客户端和服务端代码。

Terminal window

1
# 安装 kitex 工具
2
go install github.com/cloudwego/kitex/tool/cmd/kitex@latest
3

4
# 基于 Thrift IDL 生成代码
5
kitex -module example.com/project -service user-service user.thrift

生成的目录结构：

1
.
2
├── handler.go           # 服务端 Handler（需要你实现业务逻辑）
3
├── main.go             # 服务端启动入口
4
├── kitex_gen/          # 生成的代码
5
│   └── user/
6
│       ├── user.go     # Thrift 结构体
7
│       ├── userservice.go  # 服务接口
8
│       └── ...

3.2 实现服务端#

1
package main
2

3
import (
4
    "context"
5
    "github.com/cloudwego/kitex/server"
6
    user "example.com/project/kitex_gen/user/userservice"
7
)
8

9
type UserServiceImpl struct{}
10

11
func (s *UserServiceImpl) GetUser(ctx context.Context, req *user.GetUserRequest) (*user.User, error) {
12
    return &user.User{
13
        ID:       req.UserID,
14
        Username: "TestUser",
15
    }, nil
16
}
17

18
func main() {
19
    svr := user.NewServer(new(UserServiceImpl))
20
    err := svr.Run()
21
    if err != nil {
22
        panic(err)
23
    }
24
}

展开收起

底层逻辑：

NewServer 会自动配置 Netpoll 网络层、Thrift 协议层
默认监听 :8888 端口
支持通过 server.WithServiceAddr() 自定义地址

3.3 调用客户端#

1
package main
2

3
import (
4
    "context"
5
    "github.com/cloudwego/kitex/client"
6
    user "example.com/project/kitex_gen/user/userservice"
7
)
8

9
func main() {
10
    c, err := user.NewClient("user-service", client.WithHostPorts("127.0.0.1:8888"))
11
    if err != nil {
12
        panic(err)
13
    }
14

15
    resp, err := c.GetUser(context.Background(), &user.GetUserRequest{UserID: 123})
16
    if err != nil {
17
        panic(err)
18
    }
19

20
    println(resp.Username)
21
}

展开收起

底层逻辑：

NewClient 第一个参数是服务名（用于服务发现）
WithHostPorts 直连模式，不使用服务发现
客户端会自动管理连接池

4. 中间件机制#

4.1 中间件执行流程#

Kitex 的中间件采用洋葱模型，与 Hertz 类似。

1
func LogMiddleware(next endpoint.Endpoint) endpoint.Endpoint {
2
    return func(ctx context.Context, req, resp interface{}) error {
3
        start := time.Now()
4

5
        err := next(ctx, req, resp) // 执行下一个中间件或 Handler
6

7
        ri := rpcinfo.GetRPCInfo(ctx)
8
        fmt.Printf("[%s] %v\n", ri.To().Method(), time.Since(start))
9
        return err
10
    }
11
}
12

13
svr := user.NewServer(
14
    new(UserServiceImpl),
15
    server.WithMiddleware(LogMiddleware),
16
)

展开收起

底层逻辑：中间件通过函数闭包实现洋葱模型：

1
Middleware1 → Middleware2 → Handler → Middleware2 → Middleware1

4.2 客户端与服务端中间件#

1
// 服务端中间件
2
svr := user.NewServer(
3
    new(UserServiceImpl),
4
    server.WithMiddleware(serverMiddleware),
5
)
6

7
// 客户端中间件
8
cli, _ := user.NewClient(
9
    "user-service",
10
    client.WithMiddleware(clientMiddleware),
11
)

底层逻辑：

服务端中间件在接收请求后执行
客户端中间件在发送请求前执行
两者可以共享相同的中间件逻辑（如链路追踪）

5. 服务发现与负载均衡#

5.1 服务发现#

Kitex 支持多种服务发现组件，通过 Resolver 接口实现。

1
import (
2
    "github.com/cloudwego/kitex/client"
3
    "github.com/kitex-contrib/registry-etcd"
4
)
5

6
// 使用 Etcd 作为服务发现
7
r, _ := etcd.NewEtcdResolver([]string{"127.0.0.1:2379"})
8

9
cli, _ := user.NewClient(
10
    "user-service",
11
    client.WithResolver(r),
12
)

底层逻辑：

客户端启动时，从 Etcd 获取服务实例列表
监听 Etcd 变更，动态更新实例列表
每次 RPC 调用时，从实例列表中选择一个（通过负载均衡策略）

5.2 负载均衡#

Kitex 内置多种负载均衡策略：

1
import "github.com/cloudwego/kitex/pkg/loadbalance"
2

3
cli, _ := user.NewClient(
4
    "user-service",
5
    client.WithLoadBalancer(loadbalance.NewWeightedRoundRobinBalancer()),
6
)

支持的策略：

RoundRobin：轮询
WeightedRoundRobin：加权轮询（根据实例权重分配流量）
Random：随机选择
ConsistentHash：一致性哈希（相同请求路由到相同实例）

底层逻辑：负载均衡器在每次 RPC 调用时执行：

1
1. 获取可用实例列表
2
2. 根据策略选择一个实例
3
3. 建立连接并发送请求

5.3 超时控制#

Kitex 支持多层超时控制：

1
// 客户端全局超时
2
cli, _ := user.NewClient(
3
    "user-service",
4
    client.WithRPCTimeout(3 * time.Second),
5
)
6

7
// 单次调用超时
8
ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
9
defer cancel()
10
resp, err := cli.GetUser(ctx, req)

底层逻辑：

WithRPCTimeout：设置默认超时时间
context.WithTimeout：覆盖默认超时
超时后会自动取消请求，释放连接

6. 与 Hertz 集成#

在微服务架构中，常见的模式是：Hertz 作为网关层接收 HTTP 请求，Kitex 作为服务层处理 RPC 调用。

6.1 集成示例#

1
package main
2

3
import (
4
    "context"
5
    "github.com/cloudwego/hertz/pkg/app"
6
    "github.com/cloudwego/hertz/pkg/app/server"
7
    "github.com/cloudwego/kitex/client"
8
    user "example.com/project/kitex_gen/user/userservice"
9
)
10

11
var userClient user.Client
12

13
func main() {
14
    // 初始化 Kitex 客户端
15
    userClient, _ = user.NewClient("user-service", client.WithHostPorts("127.0.0.1:8888"))
16

17
    // 初始化 Hertz 服务器
18
    h := server.Default()
19

20
    h.GET("/user/:id", func(ctx context.Context, c *app.RequestContext) {
21
        userID := c.Param("id")
22

23
        // 调用 Kitex 客户端
24
        resp, err := userClient.GetUser(ctx, &user.GetUserRequest{
25
            UserID: parseInt64(userID),
26
        })
27

28
        if err != nil {
29
            c.JSON(500, map[string]string{"error": err.Error()})
30
            return
31
        }
32

33
        c.JSON(200, resp)
34
    })
35

36
    h.Spin()
37
}

展开收起

底层逻辑：

Hertz 的 context.Context 可以直接传递给 Kitex，保持链路追踪信息
Kitex 客户端可以复用，不需要每次请求都创建

7. 性能优化要点#

7.1 连接池配置#

1
cli, _ := user.NewClient(
2
    "user-service",
3
    client.WithLongConnection(
4
        connpool.IdleConfig{
5
            MaxIdlePerAddress: 10,
6
            MaxIdleGlobal:     100,
7
            MaxIdleTimeout:    60 * time.Second,
8
        },
9
    ),
10
)

底层逻辑：

MaxIdlePerAddress：每个服务实例保持的最大空闲连接数
MaxIdleGlobal：全局最大空闲连接数
MaxIdleTimeout：空闲连接超时时间

7.2 协议选择#

1
// 使用 Thrift Binary 协议（默认，最快）
2
svr := user.NewServer(new(UserServiceImpl))
3

4
// 使用 ProtoBuf 协议
5
svr := user.NewServer(
6
    new(UserServiceImpl),
7
    server.WithPayloadCodec(thrift.NewThriftCodecDisableFramed()),
8
)

性能对比：

Thrift Binary：最快，体积中等
Thrift Compact：体积最小，速度稍慢
ProtoBuf：兼容 gRPC 生态，性能介于两者之间

8. 总结#

Kitex 是为高性能 RPC 场景设计的框架，核心优势在于：

网络层优化：基于 Netpoll，支持 epoll/kqueue，减少协程切换开销
多协议支持：支持 Thrift、ProtoBuf、gRPC，灵活选择
完整的治理功能：服务发现、负载均衡、熔断、超时控制一应俱全
生态集成：与 Hertz 无缝配合，适合构建微服务架构

适用场景：

高并发 RPC 服务（QPS > 10k）
需要完整微服务治理功能的场景
使用 CloudWeGo 生态（与 Hertz 配合）

学习路径建议：

先掌握 Thrift IDL 语法，理解代码生成机制
实现一个简单的 RPC 服务，熟悉客户端和服务端 API
学习中间件机制，实现日志、监控等功能
集成服务发现和负载均衡，构建完整的微服务调用链
与 Hertz 集成，构建网关层

通过本文，你应该已经掌握了 Kitex 的核心原理和使用方法。结合 Hertz 和 Thrift，你可以构建高性能的微服务架构。

CloudWeGo-Thrift

Tue, 03 Feb 2026 00:00:00 GMT

1. 为什么需要 Thrift#

如果你已经熟悉 ProtoBuf，可能会问：为什么还需要 Thrift？

1.1 ProtoBuf 的局限性#

ProtoBuf 是优秀的序列化协议，但它有一些限制：

仅定义数据结构：ProtoBuf 主要关注 Message 定义，服务定义（Service）是后来才加入的
RPC 框架绑定：使用 gRPC 时，你被绑定到 Google 的生态（HTTP/2、gRPC 协议）
类型系统有限：不支持某些复杂类型（如 Set）

1.2 Thrift 的核心优势#

Thrift 是 Facebook 开源的跨语言 RPC 框架，它的设计目标是：

底层逻辑：Thrift 不仅是序列化协议，更是完整的 RPC 解决方案。它包含：

IDL 层：定义数据结构和服务接口
协议层：多种序列化协议（Binary/Compact/JSON）可选
传输层：多种传输方式（Socket/HTTP/FramedTransport）可选
服务端模型：多种并发模型（Simple/ThreadPool/NonBlocking）可选

与 ProtoBuf 的核心差异：

Thrift 是”全家桶”，ProtoBuf 是”单一工具”
Thrift 的协议层和传输层可以自由组合
Thrift 原生支持更丰富的类型系统（Set、Exception）

2. Thrift IDL 语法#

2.1 基础类型#

Thrift 支持的基础类型比 ProtoBuf 更丰富：

1
// 布尔型
2
bool is_active
3

4
// 整数型（有符号）
5
i8  tiny_num    // 8位，对应 Go 的 int8
6
i16 small_num   // 16位，对应 Go 的 int16
7
i32 normal_num  // 32位，对应 Go 的 int32
8
i64 big_num     // 64位，对应 Go 的 int64
9

10
// 浮点型
11
double price    // 64位浮点数，对应 Go 的 float64
12

13
// 字符串和二进制
14
string username // UTF-8 字符串
15
binary avatar   // 二进制数据（对应 Go 的 []byte）

展开收起

底层逻辑：Thrift 的类型系统直接映射到各语言的原生类型，不像 ProtoBuf 需要通过 varint 编码优化。

2.2 容器类型#

Thrift 支持三种容器类型：

1
// List：有序列表，允许重复
2
list<string> hobbies
3

4
// Set：无序集合，不允许重复
5
set<i64> follower_ids
6

7
// Map：键值对映射
8
map<string, string> metadata

与 ProtoBuf 的差异：

ProtoBuf 只有 repeated（对应 List）和 map
Thrift 原生支持 set，ProtoBuf 需要用 repeated + 去重逻辑模拟

2.3 结构体定义#

1
struct User {
2
    1: required i64 id           // 必填字段
3
    2: required string username  // 必填字段
4
    3: optional string email     // 可选字段
5
    4: optional bool is_active = true  // 可选字段，带默认值
6
}

关键概念：

字段编号：1:, 2: 是字段的唯一标识，类似 ProtoBuf 的 Tag
required/optional：显式声明字段是否必填
- required：序列化时必须有值，反序列化时必须存在
- optional：可以不设置，反序列化时缺失不会报错

底层逻辑：Thrift 的 required 会在运行时检查，如果缺失会抛出异常。ProtoBuf 在 proto3 中移除了 required，所有字段都是可选的。

2.4 枚举和异常#

1
// 枚举定义
2
enum UserStatus {
3
    NORMAL = 1,
4
    BANNED = 2,
5
    DELETED = 3
6
}
7

8
// 异常定义（类似结构体，但用于错误处理）
9
exception UserNotFoundException {
10
    1: string message
11
    2: i64 user_id
12
}

底层逻辑：Thrift 的 exception 会被映射到各语言的异常机制：

Go：生成实现 error 接口的结构体
Java：生成继承 Exception 的类
Python：生成继承 Exception 的类

2.5 服务定义#

1
service UserService {
2
    // 定义 RPC 方法
3
    User getUser(1: i64 user_id) throws (1: UserNotFoundException e)
4

5
    // void 返回类型
6
    void deleteUser(1: i64 user_id)
7

8
    // oneway：不等待响应（异步调用）
9
    oneway void logEvent(1: string event)
10
}

关键概念：

throws：声明可能抛出的异常
oneway：客户端发送请求后立即返回，不等待服务端响应（类似消息队列）

底层逻辑：oneway 方法在网络层不会等待响应包，适合日志、监控等场景。

3. 序列化协议#

Thrift 的核心优势是协议层可插拔，支持多种序列化格式。

3.1 Binary Protocol#

最常用的协议，紧凑且高效。

1
transport := thrift.NewTSocket("localhost:9090")
2
protocol := thrift.NewTBinaryProtocol(transport, true, true)
3
client := userservice.NewUserServiceClient(thrift.NewTStandardClient(protocol, protocol))

底层逻辑：

使用固定长度编码（i32 占 4 字节，i64 占 8 字节）
字段按顺序编码：[字段类型][字段ID][字段值]
不压缩，但解析速度快

3.2 Compact Protocol#

压缩版本，牺牲少量性能换取更小的体积。

1
protocol := thrift.NewTCompactProtocol(transport)

底层逻辑：

使用 varint 编码整数（类似 ProtoBuf）
字段 ID 使用 zigzag 编码
体积比 Binary 小 20-30%，但编解码稍慢

3.3 JSON Protocol#

人类可读的格式，用于调试或与前端交互。

1
protocol := thrift.NewTJSONProtocol(transport)

底层逻辑：

直接序列化为 JSON 字符串
体积最大，性能最差
适合调试或跨语言兼容性要求高的场景

3.4 协议对比#

协议	体积	速度	可读性	适用场景
Binary	中等	最快	不可读	生产环境（默认）
Compact	最小	较快	不可读	带宽敏感场景
JSON	最大	最慢	可读	调试、前端交互

4. 传输层#

Thrift 的传输层负责数据的读写，也是可插拔的。

4.1 TSocket#

最基础的 TCP Socket 传输。

1
transport := thrift.NewTSocket("localhost:9090")

底层逻辑：直接使用 TCP 连接，每次 RPC 调用对应一次完整的请求-响应。

4.2 TFramedTransport#

带帧头的传输，用于非阻塞服务器。

1
transport := thrift.NewTFramedTransport(thrift.NewTSocket("localhost:9090"))

底层逻辑：

每个消息前加 4 字节的长度头：[长度][消息体]
服务端可以先读取长度，再读取完整消息体
适合 NonBlocking Server（基于 epoll/kqueue）

4.3 TBufferedTransport#

带缓冲的传输，减少系统调用次数。

1
transport := thrift.NewTBufferedTransport(thrift.NewTSocket("localhost:9090"), 8192)

底层逻辑：在内存中维护读写缓冲区，积累到一定大小再调用 write()，减少系统调用开销。

5. 代码生成与使用#

5.1 生成 Go 代码#

假设你有一个 user.thrift 文件：

1
namespace go user
2

3
struct User {
4
    1: required i64 id
5
    2: required string username
6
}
7

8
service UserService {
9
    User getUser(1: i64 user_id)
10
}

生成代码：

Terminal window

1
thrift --gen go user.thrift

gen-go/user/user.go：所有 Thrift 生成的接口、客户端、服务端代码都在这一个 user.go 文件中。

5.2 实现服务端#

1
package main
2

3
import (
4
    "context"
5
    "fmt"
6
    "github.com/apache/thrift/lib/go/thrift"
7
    "your-module/gen-go/user"
8
)
9

10
// 实现服务接口
11
type UserServiceHandler struct
12

13
func (h *UserServiceHandler) GetUser(ctx context.Context, userID int64) (*user.User, error) {
14
    return &user.User{
15
        ID:       userID,
16
        Username: "TestUser",
17
    }, nil
18
}
19

20
func main() {
21
    handler := &UserServiceHandler{}
22
    processor := user.NewUserServiceProcessor(handler)
23

24
    transport, _ := thrift.NewTServerSocket(":9090")
25
    server := thrift.NewTSimpleServer4(
26
        processor,
27
        transport,
28
        thrift.NewTBufferedTransportFactory(8192),
29
        thrift.NewTBinaryProtocolFactoryDefault(),
30
    )
31

32
    fmt.Println("Starting server on :9090")
33
    server.Serve()
34
}

展开收起

底层逻辑：

Processor：负责解析请求、调用 Handler、序列化响应
Transport：负责网络 I/O
ProtocolFactory：负责创建序列化协议实例

6. Thrift vs ProtoBuf#

6.1 核心差异#

特性	Thrift	ProtoBuf
定位	完整 RPC 框架	序列化协议
类型系统	支持 Set、Exception	仅支持基础类型
协议层	可选（Binary/Compact/JSON）	固定（Protobuf Wire Format）
传输层	可选（Socket/Framed/HTTP）	依赖 gRPC
服务端模型	多种（Simple/ThreadPool/NonBlocking）	依赖 gRPC
字段修饰符	required/optional	proto3 全部可选

6.2 选择建议#

选择 Thrift 的场景：

需要灵活的协议层和传输层组合
需要使用 Set 类型
需要显式的 required 字段校验
已有 Thrift 生态（如使用 Kitex）

选择 ProtoBuf 的场景：

需要与 gRPC 生态集成
需要更好的向后兼容性（proto3 的设计更宽松）
需要更广泛的语言支持（ProtoBuf 社区更活跃）

7. 实战技巧#

7.1 字段演化#

Thrift 支持字段的增删改，但需要遵循规则：

1
struct User {
2
    1: required i64 id
3
    2: required string username
4
    // 3: string old_field  // 已废弃，不要删除编号
5
    4: optional string email  // 新增字段，使用新编号
6
}

底层逻辑：

不要修改已有字段的编号
不要将 optional 改为 required（会导致旧客户端反序列化失败）
废弃字段保留编号，避免未来冲突

7.2 性能优化#

1
// 使用对象池复用 Transport
2
var transportPool = sync.Pool{
3
    New: func() interface{} {
4
        transport, _ := thrift.NewTSocket("localhost:9090")
5
        return thrift.NewTBufferedTransport(transport, 8192)
6
    },
7
}
8

9
func callRPC() {
10
    transport := transportPool.Get().(thrift.TTransport)
11
    defer transportPool.Put(transport)
12

13
    transport.Open()
14
    defer transport.Close()
15

16
    protocol := thrift.NewTBinaryProtocol(transport, true, true)
17
    client := user.NewUserServiceClient(thrift.NewTStandardClient(protocol, protocol))
18

19
    result, _ := client.GetUser(context.Background(), 123)
20
    fmt.Println(result)
21
}

展开收起

底层逻辑：复用 Transport 对象可以减少连接建立开销和内存分配。

8. 总结#

Thrift 是一个功能完整的 RPC 框架，核心优势在于：

灵活的分层设计：协议层、传输层、服务端模型可自由组合
丰富的类型系统：原生支持 Set、Exception 等类型
跨语言支持：支持 20+ 种编程语言

适用场景：

需要灵活选择序列化协议的场景（如带宽敏感时用 Compact）
需要使用 Set 类型或显式 required 校验
使用 CloudWeGo 生态（Kitex 基于 Thrift）

学习路径建议：

先掌握 IDL 语法，理解 required/optional 的区别
了解三种序列化协议的适用场景
理解传输层的选择（Framed 用于 NonBlocking Server）
在实际项目中尝试使用 Kitex（对 Thrift 的高性能封装）

通过本文，你应该已经掌握了 Thrift 的核心原理和使用方法。接下来可以学习 Kitex，它是对 Thrift 的高性能封装，提供了更好的开发体验。

CloudWeGo-Hertz

Sun, 01 Feb 2026 00:00:00 GMT

1. 为什么选择 Hertz#

如果你已经熟悉 Gin，可能会问：为什么还需要 Hertz？

1.1 Gin 的局限性#

Gin 基于 Go 标准库的 net/http，这意味着：

网络模型：使用 Go 原生的 goroutine-per-connection 模型，在高并发场景下会产生大量协程切换开销
内存分配：每次请求都会分配新的 http.Request 和 http.ResponseWriter，GC 压力较大
扩展性：标准库的抽象层次较高，难以深度优化网络层

1.2 Hertz 的核心优势#

Hertz 是字节跳动开源的 HTTP 框架，属于 CloudWeGo 微服务生态的一部分。它的设计目标是：

底层逻辑：Hertz 不依赖 net/http，而是基于自研的网络库 Netpoll（epoll/kqueue 封装），实现了：

零拷贝：通过 nocopy API 减少内存拷贝
对象池化：RequestContext 等核心对象复用，降低 GC 压力
协议层优化：HTTP/1.1 解析器手写优化，性能超过标准库

与 Gin 的 API 兼容性：Hertz 刻意保持了与 Gin 相似的 API 设计，迁移成本低。

2. 核心架构#

2.1 分层设计#

Hertz 采用三层架构：

1
应用层 (Handler/Middleware)
2
    ↓
3
协议层 (HTTP Parser)
4
    ↓
5
网络层 (Netpoll/Go Net)

底层逻辑：这种分层使得 Hertz 可以灵活切换网络库。默认使用 Netpoll，但也支持降级到标准库（通过 WithTransport 选项）。

2.2 核心数据结构#

RequestContext#

Hertz 的核心是 app.RequestContext，它对应 Gin 的 gin.Context。

1
type RequestContext struct {
2
    conn     network.Conn
3
    Request  protocol.Request
4
    Response protocol.Response
5
    // ...
6
}

关键差异：

Gin 的 Context 包装了标准库的 *http.Request
Hertz 的 RequestContext 直接持有底层连接和自定义的 Request/Response 对象

底层逻辑：这种设计让 Hertz 可以：

复用 RequestContext 对象（通过 sync.Pool）
直接操作底层 buffer，避免多次拷贝
支持流式读写（标准库的 http.Request.Body 只能读一次）

3. 快速上手#

3.1 基础示例#

1
package main
2

3
import (
4
    "context"
5
    "github.com/cloudwego/hertz/pkg/app"
6
    "github.com/cloudwego/hertz/pkg/app/server"
7
)
8

9
func main() {
10
    h := server.Default()
11

12
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
13
        c.JSON(200, map[string]string{"msg": "pong"})
14
    })
15

16
    h.Spin() // 启动服务
17
}

展开收起

与 Gin 的对比：

1
// Gin
2
r.GET("/ping", func(c *gin.Context) {
3
    c.JSON(200, gin.H{"msg": "pong"})
4
})
5

6
// Hertz
7
h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
8
    c.JSON(200, map[string]string{"msg": "pong"})
9
})

核心差异：Hertz 的 Handler 多了一个 context.Context 参数，这是为了：

支持超时控制（通过 ctx.Done()）
传递链路追踪信息（OpenTelemetry）
与 Kitex（gRPC 框架）保持一致的接口风格

3.2 参数绑定#

Hertz 支持多种参数绑定方式，与 Gin 类似但更强大。

1
type LoginReq struct {
2
    Username string `json:"username" query:"username"`
3
    Password string `json:"password" query:"password"`
4
}
5

6
h.POST("/login", func(ctx context.Context, c *app.RequestContext) {
7
    var req LoginReq
8
    // 自动根据 Content-Type 选择绑定方式
9
    if err := c.Bind(&req); err != nil {
10
        c.JSON(400, map[string]string{"error": err.Error()})
11
        return
12
    }
13
    c.JSON(200, req)
14
})

底层逻辑：Bind 方法会检查 Content-Type 头：

application/json → JSON 解析
application/x-www-form-urlencoded → Form 解析
multipart/form-data → Multipart 解析

零拷贝优化：Hertz 提供 c.Query() 和 c.PostForm() 等方法，返回的字符串直接引用底层 buffer，避免拷贝。但要注意：这些字符串在请求结束后会失效，如需持久化需要手动拷贝。

4. 源码走读#

4.1 Engine 结构#

1
type Engine struct {
2
    trees            MethodTrees  // 路由树
3
    maxParams        uint16
4
    allNoRoute       HandlersChain
5
    allNoMethod      HandlersChain
6
    noRoute          HandlersChain
7
    noMethod         HandlersChain
8
    pool             sync.Pool    // RequestContext 对象池
9
    // ...
10
}

核心字段解析：

trees：每个 HTTP 方法（GET/POST/…）对应一棵前缀树（Radix Tree）
pool：RequestContext 对象池，每次请求从池中取出，处理完归还

底层逻辑：对象池化是 Hertz 性能优化的关键。每次请求的处理流程：

1
1. 从 pool 获取 RequestContext
2
2. 重置字段（清空上次请求的数据）
3
3. 解析 HTTP 请求
4
4. 路由匹配 + 执行 Handler
5
5. 写回响应
6
6. 归还 RequestContext 到 pool

4.2 路由树结构#

Hertz 使用 Radix Tree（基数树）存储路由，与 Gin 相同。

1
type node struct {
2
    path      string
3
    indices   string
4
    children  []*node
5
    handlers  HandlersChain
6
    priority  uint32
7
    nType     nodeType
8
    // ...
9
}

示例：注册以下路由

1
h.GET("/user/:id", handler1)
2
h.GET("/user/:id/profile", handler2)
3
h.GET("/user/admin", handler3)

会构建如下树结构：

1
root
2
 └─ /user/
3
     ├─ :id (handler1)
4
     │   └─ /profile (handler2)
5
     └─ admin (handler3)

底层逻辑：

:id 是参数节点，可以匹配任意值
admin 是静态节点，优先级更高（通过 priority 字段控制）
匹配时先尝试静态节点，再尝试参数节点

5. 中间件机制#

5.1 中间件执行流程#

Hertz 的中间件模型与 Gin 完全一致，使用 Next() 方法控制执行流程。

1
func Logger() app.HandlerFunc {
2
    return func(ctx context.Context, c *app.RequestContext) {
3
        start := time.Now()
4

5
        c.Next(ctx) // 执行后续中间件和 Handler
6

7
        latency := time.Since(start)
8
        fmt.Printf("[%s] %s %v\n", c.Method(), c.Path(), latency)
9
    }
10
}
11

12
h.Use(Logger())

底层逻辑：中间件和 Handler 被存储在 HandlersChain（[]HandlerFunc）中。执行时通过索引遍历：

1
type RequestContext struct {
2
    handlers HandlersChain
3
    index    int8  // 当前执行到第几个 Handler
4
    // ...
5
}
6

7
func (c *RequestContext) Next(ctx context.Context) {
8
    c.index++
9
    for c.index < int8(len(c.handlers)) {
10
        c.handlers[c.index](ctx, c)
11
        c.index++
12
    }
13
}

调用 c.Next(ctx) 会递增索引并执行下一个 Handler，形成洋葱模型。

5.2 中间件注册方式#

1
// 全局中间件
2
h.Use(middleware1, middleware2)
3

4
// 路由组中间件
5
v1 := h.Group("/v1", authMiddleware)
6
{
7
    v1.GET("/users", getUsers)
8
}
9

10
// 单个路由中间件
11
h.GET("/admin", adminMiddleware, adminHandler)

底层逻辑：注册时，中间件会被合并到 HandlersChain 中：

1
[全局中间件...] + [路由组中间件...] + [路由中间件...] + [Handler]

6. 与 Kitex 集成#

Hertz 和 Kitex 是 CloudWeGo 生态的两大支柱，分别处理 HTTP 和 RPC。

6.1 为什么需要集成#

在微服务架构中，常见场景：

网关层：使用 Hertz 接收 HTTP 请求
服务层：使用 Kitex 进行 RPC 调用

6.2 集成示例#

假设你有一个 Kitex 定义的用户服务：

1
// 在 Hertz Handler 中调用 Kitex 客户端
2
func GetUserHandler(ctx context.Context, c *app.RequestContext) {
3
    userID := c.Param("id")
4

5
    // 调用 Kitex 客户端
6
    client, _ := userservice.NewClient("user-service")
7
    resp, err := client.GetUser(ctx, &user.GetUserRequest{
8
        UserId: userID,
9
    })
10

11
    if err != nil {
12
        c.JSON(500, map[string]string{"error": err.Error()})
13
        return
14
    }
15

16
    c.JSON(200, resp)
17
}

展开收起

底层逻辑：

Hertz 的 context.Context 可以直接传递给 Kitex，保持链路追踪信息
Kitex 客户端会自动进行服务发现、负载均衡、超时控制

6.3 统一的 IDL 管理#

推荐使用 Thrift 或 Protobuf 定义接口，同时生成 Hertz 和 Kitex 代码：

Terminal window

1
# 生成 Kitex 服务端代码
2
kitex -module example.com/project -service user-service user.thrift
3

4
# 生成 Hertz HTTP 接口代码（基于同一份 IDL）
5
hz new -module example.com/project -idl user.thrift

这样可以保证 HTTP 接口和 RPC 接口的数据结构完全一致。

7. 性能优化要点#

7.1 零拷贝 API#

Hertz 提供了 nocopy 系列 API，避免不必要的内存拷贝。

1
// 不推荐：会拷贝字符串
2
username := c.Query("username")
3
go func() {
4
    fmt.Println(username) // 危险！请求结束后 username 可能失效
5
}()
6

7
// 推荐：手动拷贝
8
username := string(c.Query("username"))
9
go func() {
10
    fmt.Println(username) // 安全
11
}()

底层逻辑：Hertz 的 Query()、PostForm() 等方法返回的字符串直接引用底层 buffer。这个 buffer 在请求结束后会被复用，因此：

在当前请求的生命周期内使用是安全的
如果需要在 goroutine 中使用或持久化存储，必须手动拷贝

7.2 流式处理#

对于大文件上传/下载，使用流式 API 避免一次性加载到内存。

1
h.POST("/upload", func(ctx context.Context, c *app.RequestContext) {
2
    file, err := c.FormFile("file")
3
    if err != nil {
4
        c.String(400, "upload failed")
5
        return
6
    }
7

8
    // 流式保存文件
9
    src, _ := file.Open()
10
    defer src.Close()
11

12
    dst, _ := os.Create("./uploads/" + file.Filename)
13
    defer dst.Close()
14

15
    io.Copy(dst, src) // 流式拷贝，不会占用大量内存
16
    c.String(200, "success")
17
})

展开收起

7.3 连接池配置#

Hertz 默认使用 Netpoll，可以通过选项优化连接池：

1
h := server.New(
2
    server.WithMaxRequestBodySize(4 * 1024 * 1024), // 限制请求体大小
3
    server.WithIdleTimeout(60 * time.Second),       // 空闲连接超时
4
    server.WithReadTimeout(3 * time.Second),        // 读超时
5
    server.WithWriteTimeout(3 * time.Second),       // 写超时
6
)

底层逻辑：

MaxRequestBodySize：防止恶意大请求耗尽内存
IdleTimeout：及时回收空闲连接，减少资源占用
ReadTimeout/WriteTimeout：防止慢客户端攻击

7.4 对象池化#

除了 RequestContext，你也可以为自己的对象使用 sync.Pool：

1
var bufferPool = sync.Pool{
2
    New: func() interface{} {
3
        return new(bytes.Buffer)
4
    },
5
}
6

7
func handler(ctx context.Context, c *app.RequestContext) {
8
    buf := bufferPool.Get().(*bytes.Buffer)
9
    defer func() {
10
        buf.Reset()
11
        bufferPool.Put(buf)
12
    }()
13

14
    // 使用 buf 进行操作
15
}

展开收起

8. Hertz vs Gin：迁移指南#

如果你要从 Gin 迁移到 Hertz，主要改动点：

特性	Gin	Hertz
Handler 签名	`func(*gin.Context)`	`func(context.Context, *app.RequestContext)`
启动方法	`r.Run(":8080")`	`h.Spin()`
参数绑定	`c.ShouldBind(&req)`	`c.Bind(&req)`
获取参数	`c.Query("key")`	`c.Query("key")` (相同)
JSON 响应	`c.JSON(200, data)`	`c.JSON(200, data)` (相同)

核心差异：

Handler 多了 context.Context 参数
字符串可能引用底层 buffer（需注意生命周期）
默认使用 Netpoll（可切换到标准库）

9. 总结#

Hertz 是为高性能场景设计的 HTTP 框架，核心优势在于：

网络层优化：基于 Netpoll，支持 epoll/kqueue，减少协程切换开销
内存优化：对象池化 + 零拷贝 API，降低 GC 压力
生态集成：与 Kitex 无缝配合，适合构建微服务网关

适用场景：

高并发 HTTP 服务（QPS > 10k）
需要与 Kitex 集成的微服务网关
对延迟敏感的业务（P99 < 10ms）

通过本文，你应该已经掌握了 Hertz 的核心原理和使用方法。接下来可以在实际项目中尝试使用，体会它在高并发场景下的性能优势。

Redis 分布式锁实现原理

Sun, 25 Jan 2026 00:00:00 GMT

0. 前言#

Golang 分布式锁实现原理

1. redis 分布式锁实现原理#

1.1 redis 实现分布式锁#

1.2 过期时间不精准问题#

使用 setnx 命令设置锁时，通常会设置一个过期时间以防止死锁。然而，由于网络延迟或其他因素，准确说是“客户端视角与服务端视角的时钟脱节” 以及 “进程停顿（STW）”，实际的过期时间可能会有所偏差，导致锁提前释放或延迟释放，从而引发并发问题。

一旦发生一锁多持现象，锁的基本性质 —— 独占性遭到破坏。这个可以通过看门狗策略来缓解，但是不能完全解决。

1.3 数据弱一致性问题#

当 Redis 挂了，可能会导致锁的状态不一致。例如，如果一个客户端持有锁并且正在执行关键操作，而 Redis 突然崩溃，其他客户端可能会认为锁已经释放，从而同时进入临界区，导致数据不一致。

Redis 挂了导致的状态不一致，本质是主从异步复制导致的锁丢失。Etcd/红锁从存储侧解决了‘锁状态的强一致性’，但依然无法从逻辑侧解决因客户端 STW 导致的一锁多持，后者需配合 Fencing Token 实现终极一致。

2. redis 分布式锁实现源码#

xiaoxuxiansheng

redis_lock

2.1 基本框架#

在 Redis sdk 之上，基于 Redis 连接池模式，封装了一个简易的 Redis 客户端。

redis-lock基本框架.png

接下来，以分布式锁使用方的进程 id + 协程 id 拼接生成一个字符串，作为使用方的身份标识；在执行加锁操作时，通过 redis 的 setNEX 操作，把生成的字符串设置为 val，并且设定好锁数据的过期时间；

在执行解锁操作时，通过 lua 脚本原子化执行两个步骤：

get 操作获取 val，查看是否和当前使用方身份一致；
倘若身份校验通过，执行 del 操作删除锁数据；

在加锁/解锁操作之外，额外支持一个延长锁过期时间的操作. 该操作同样通过 lua 脚本实现，包括两个步骤：

get 操作获取 val，查看是否和当前使用方身份一致；
倘若身份校验通过，执行 expire 完成锁数据的续期

redis-lock流程.png

3. watch dog 实现原理#

3.1 续约机制#

在加锁成功后，启动一个后台协程，定时检查锁的剩余过期时间。如果发现剩余时间低于某个阈值（例如过期时间的一半），则调用续约函数，延长锁的过期时间。

基本上可以看为就是在 Redis 中实现了一个 etcd 的租约机制。

也就是说 Etcd 租约是 watch 回调型使用的，Redis 锁是主动轮询型用的

3.2 redisson#

Redisson 是一个基于 Redis 的 Java 分布式锁实现，上文提到的续约机制就是仿照 Redisson 实现的。

redisson

3.3 看门狗 watch dog#

watch dog.png

下面聊聊看门狗模式的执行流程（其实和 etcd 的租约续约机制非常类似）：

在执行 redis 分布式锁的上锁操作时，通过 setNEX 指令完成锁数据的设置，携带了一个默认的锁数据过期时间
确认上锁成功后，异步启动一个 watchDog 守护协程，按照锁默认过期时间 1/4 ~ 1/3 的节奏（可自由设置），持续地对锁数据进行 expire 续期操作
在解锁成功后，会负责关闭 watchDog，回收协程资源. （由于看门狗续期操作会先检查锁的所有权再延期数据，因此实际上使用方只要删除了锁数据，续期操作就不会生效了. 回收看门狗协程是为了规避协程泄漏问题）

4. RedLock实现原理#

本文 1.3 小节提出了因 redis 走的是注重于高可用性的 AP 流派，因此存在数据弱一致的问题，进而导致 redis 分布式锁可能出现同时被多方持有的情况. 本章开始，基于 red lock 红锁机制尝试提出这个问题的解决方案。

4.1 多数派原则#

所谓多数派原则，就是做出一项决议之前，让所有的参与者进行投票表决，只有投赞同票的人数达到参与者总人数的一半以上成为多数派时，这项决议才被通过。

在红锁 RedLock 实现中，会基于多数派准则进行 CAP 中一致性 C 和可用性 A 之间矛盾的缓和，保证在 RedLock 下所有 redis 节点中达到半数以上节点可用时，整个红锁就能够正常提供服务。

4.2 红锁 redLock#

红锁 Redlock 全称 redis distribution lock，是 redis 作者 antirez 提出的一种分布式锁实现方案。加锁成功的判断条件和Raft中向Candidate节点发起投票选举Leader的过程类似，都是基于多数派原则。

在红锁的实现中：

我们假定集群中有 2N+1个 redis 节点（通常将节点总数设置为奇数，有利于多数派原则的执行效率）
这些 redis 节点彼此间是相互独立的，不存在从属关系
每次客户端尝试进行加锁操作时，会同时对2N+1个节点发起加锁请求
每次客户端向一个节点发起加锁请求时，会设定一个很小的请求处理超时阈值
客户端依次对2N+1个节点发起加锁请求，只有在小于请求处理超时阈值的时间内完成了加锁操作，才视为一笔加锁成功的请求
过完2N+1个节点后，统计加锁成功的请求数量
倘若加锁请求成功数量大于等于N+1（多数派），则视为红锁加锁成功
倘若加锁请求成功数量小于N+1，视为红锁加锁失败，此时会遍历2N+1个节点进行解锁操作，有利于资源回收，提供后续使用方的取锁效率

Golang 分布式锁实现原理

Thu, 22 Jan 2026 00:00:00 GMT

1. 分布式锁#

1.1 使用场景#

在分布式场景中，有时我们需要跨域多个物理节点执行加锁操作，因此我们就需要依赖到类似于 redis、mysql 这样的状态存储组件，在此基础之上实现所谓的“分布式锁”技术。

1.2 核心性质#

分布式锁需要满足以下几个核心性质：

独占性：同一时刻只能有一个取锁方占用。
健壮性：锁持有者在崩溃后，锁能够被其他节点重新获取。
对称性：获取锁和释放锁的操作必须为同一身份，不允许非法释放他人持有的锁。
可用性：当提供分布式的基础组件存在少量节点发生故障时，不应该影响到分布式锁的正常使用。

1.3 实现类型#

实现类型.png

分布式锁的实现类型主要有以下几种：

主动轮询型：客户端通过不断地向分布式存储组件发送请求，尝试获取锁。类似于单机锁的 CAS + 自旋。
watch回调型：客户端在获取锁失败后，会创建 watcher 监听锁的释放事件，随后不再主动获取锁；当锁被释放时，watcher 会收到通知，从而尝试重新获取锁。

2. 主动轮询型#

2.1 实现思路#

主动轮询型.png

主动轮询型分布式锁的实现思路为：

针对于同一把分布式锁，使用同一条数据进行标识（以 redis 为例，则为同一个 key 对应的 kv 数据记录）
假如在存储介质成功插入了该条数据（要求之前该 key 对应的数据不存在），则被认定为加锁成功
把从存储介质中删除该条数据这一行为理解为释放锁操作
倘若在插入该条数据时，发现数据已经存在（锁已被他人持有），则持续轮询，直到数据被他人删除（他人释放锁），并由自身完成数据插入动作为止（取锁成功）
由于是并发场景，需要保证
- 检查数据是否已被插入
- 数据不存在则插入数据
- 这两个步骤之间是原子化不可拆分的（在 redis 中是 set only if not exist —— SETNX 操作）

2.2 技术选型#

常见的分布式存储组件有 redis、mysql、zookeeper 等。

setnx 使用文档：https://redis.io/commands/setnx/ （事实上，在 redis 2.6.12 版本之后，setnx 操作已经被弃置，官方推荐大家使用 set 指令并附加 nx 参数来实现与 setnx 指令相同的效果）

此外，redis 还支持使用 lua 脚本自定义组装同一个 redis 节点下的多笔操作形成一个具备原子性的事务。

2.3 死锁问题#

这项能力在 mysql 中显得捉襟见肘，不过在使用 redis 时，我们可以通过过期时间 expire time 机制得以保证。我们通常会在插入分布式锁对应的 kv 数据时设置一个过期时间 expire time，这样即便使用方因为异常原因导致无法正常解锁，锁对应的数据项也会在达到过期时间阈值后被自动删除，实现释放分布式锁的效果。

这种过期机制的引入也带来了新的问题：因为锁的持有者并不能精确预判到自己持锁后处理业务逻辑的实际耗时，因此此处设置的过期时间只能是一个偏向于保守的经验值，假如因为一些异常情况导致占有锁的使用方在业务处理流程中的耗时超过了设置的过期时间阈值，就会导致锁被提前释放，其他取锁方可能取锁成功，最终引起数据不一致的并发问题。

针对于这个问题，在分布式锁工具 redisson 中给出了解决方案——看门狗策略（watch dog strategy）：在锁的持有方未完成业务逻辑的处理时，会持续对分布式锁的过期阈值进行延期操作。

2.4 弱一致性问题#

Redis 走的是 AP 架构，为了保证服务的可用性和吞吐量，Redis 在进行数据的主从同步时采用的是异步执行机制。

到这里问题就来了，试想一种场景：倘若使用方 A 在 Redis master 节点加锁成功，但是对应的 kv 记录在同步到 slave 之前，master 节点就宕机了。此时未同步到这项数据的 slave 节点升为 master，这样分布式锁被 A 持有的“凭证” 就这样凭空消失了。于是不知情的使用方 B C D 都可能加锁成功，于是就出现了一把锁被多方同时持有的问题，导致分布式锁最基本的独占性遭到破坏。也就是发生了一锁多持的问题。

关于这个问题，一个比较经典的解决方案是：RedLock 红锁。它采用了公式算法，同时也是 Redis 官方推荐的分布式锁实现方案，但是这种方法在发布之初就受到了不少质疑，比如时钟漂移问题、网络分区问题等。

3. redis 分布式锁#

3.1 sdk 介绍#

gomodule

redigo

4. watch 回调型#

4.1 实现思路#

watch 回调型.png

对于实现 watch 回调型分布式锁，一些基本要点和 2.1 小节中聊到的主动轮询型分布式锁类似：

针对于同一把分布式锁，使用一条相同的数据进行标识（唯一、明确的 key）
倘若在存储介质内成功插入该条数据（要求 key 对应的数据不存在），则这一行为被认定为加锁成功
把从存储介质中删除该条数据这行为理解为解锁操作

与主动轮询型分布式锁不同的是，在取锁失败时，watch 回调型分布式锁不会持续轮询，而是会 watch 监听锁的删除事件：

倘若在插入数据时，发现该条记录已经存在，说明锁已被他人持有，此时选择监听这条数据记录的删除事件，当对应事件发生时说明锁被释放了，此时才继续尝试取锁

4.2 技术选型#

在实现上，我们需要依赖于提供了 watch 机制的状态存储组件，不仅能支持数据的存储和去重，还需要利用到其中的 watch 监听回调功能进行锁释放事件的订阅感知。

为满足上述诉求，我们常用的技术组件包括 etcd 和 zookeeper。

etcd 文档：https://etcd.io/

etcd 是一款适合用于共享配置和服务发现的分布式 kv 存储组件，底层基于分布式共识算法 raft 协议保证了存储服务的强一致和高可用。

在 etcd 中提供了 watch 监听器的功能，即针对于指定范围的数据，通过与 etcd 服务端节点创建 grpc 长连接的方式持续监听变更事件。

此外，etcd 中写入数据时，还支持通过版本 revision 机制进行取锁秩序的统筹协调，是一款很适合用于实现分布式锁的组件。

4.3 死锁问题#

为避免死锁问题的产生，etcd 中提供了租约 lease 机制。租约，顾名思义，是一份具有时效性的协议，一旦达到租约上规定的截止时间，租约就会失去效力。同时，etcd 中还提供了续约机制（keepAlive），用户可以通过续约操作来延迟租约的过期时间。

那么，我们如何来利用租约 lease 机制解决分布式锁中可能存在的死锁问题呢？实现思路如下：

用户可以先申请一份租约，设定好租约的截止时间
异步启动一个续约协程，负责在业务逻辑处理完成前，按照一定的时间节奏持续进行续约操作
在执行取锁动作，将对应于锁的 kv 数据和租约进行关联绑定，使得锁数据和租约拥有相同的过期时间属性

上面这个思路就类似于 Redis 的看门狗机制。在这样的设定之下，倘若分布式锁的持有者出现异常状况导致无法正常解锁，则可以通过租约的过期机制完成对分布式锁的释放，死锁问题因此得以规避。此外，锁的使用方可以将租约的初始过期时间设定为一个偏小的值，并通过续约机制来对租约的生效周期进行动态延长。可以看到，此处 etcd 中的租约及续约机制，实现了与 redisson 中 watch dog 机制类似的效果。

4.4 惊群效应#

在 watch 回调型分布式锁中，惊群效应主要体现在当锁被释放时，所有监听该锁释放事件的客户端都会收到通知，从而引发一场“抢锁大战”，这可能会导致系统资源的过度消耗和性能下降。

为了解决惊群效应问题，etcd 中提供了前缀 prefix 机制以及版本 revision 机制。这和 zookeeper 中的临时顺序节点（ephemeral sequential node）有异曲同工之妙。

对于同一把分布式锁，锁记录数据的 key 拥有共同的前缀 prefix，作为锁的标识
每个取锁方取锁时，会以锁前缀 prefix 拼接上自身的身份标识（租约 id），生成完整的 lock key。因此各取锁方完整的 lock key 都是互不相同的（只是有着相同的前缀），理论上所有取锁方都能成功把锁记录数据插入到 etcd 中
每个取锁方插入锁记录数据时，会获得自身 lock key 处在锁前缀 prefix 范围下唯一且递增的版本号 revision
取锁方插入加锁记录数据不意味着加锁成功，而是需要在插入数据后查询一次锁前缀 prefix 下的记录列表，判定自身 lock key 对应的 revision 是不是其中最小的，如果是的话，才表示加锁成功
如果锁被他人占用，取锁方会 watch 监听 revision 小于自己但最接近自己的那个 lock key 的删除事件。

这样所有的取锁方就会在 revision 机制的协调下，根据取锁序号（revision）的先后顺序排成一条队列，每当锁被释放，只会惊动到下一顺位的取锁方，惊群问题得以避免。

惊群效应.png

5. etcd 分布式锁#

5.1 sdk 介绍#

etcd 开源地址

etcd-io

etcd

单机锁实现原理

Sun, 18 Jan 2026 00:00:00 GMT

1. Sync.Mutex#

1.1 单机锁实现框架#

1.1.1 上锁/解锁#

通过Mutex内的一个状态值state来表示锁的状态：上锁把0变成1，解锁把1变成0。

上锁时假设state为0，使用原子操作将state从0变成1，如果成功则表示上锁成功。如果失败，说明state不为0，表示锁已经被其他协程持有，此时需要进入等待队列等待。

这是一个原子操作，保证了多个协程同时尝试上锁时不会出现竞态条件。

1.1.2 抢占锁的两种策略#

阻塞/唤醒：当协程尝试上锁失败时，会将自己加入等待队列，并进入阻塞状态，直到被唤醒。这是悲观锁。
自旋+CAS：协程在尝试上锁失败后，不立即阻塞，而是进行一段时间的忙等待（自旋），尝试再次获取锁。如果在自旋期间锁被释放，则可以直接获取锁，避免了阻塞和唤醒的开销。这是乐观锁。

正常模式下，Goroutine会先进行自旋4次尝试获取锁，如果自旋失败则进入阻塞状态。饥饿模式下，Goroutine会直接进入阻塞状态，到阻塞队列末尾，不进行自旋。

需要注意的是，不管在哪种模式下，阻塞队列队头的Goroutine在被唤醒后都会得到不同程度的优待：在正常模式下，队头Goroutine会进行正常抢占锁，但是抢占失败依然会被放在队头；在饥饿模式下，队头Goroutine会直接获取锁。

1.1.3 饥饿模式#

饥饿模式：阻塞队列中的锁超过 1ms 而不得的Goroutine会被标记为饥饿，整个锁进入饥饿模式，将抢锁流程由非公平机制转为公平机制。饥饿模式下，保证FIFO，阻塞队列中的头部Goroutine获取锁，避免饥饿现象。

饥饿模式和正常模式的切换条件就是看阻塞队列中是否有Goroutine超过1ms而不得。

1.2 数据结构#

1
type Mutex struct {
2
    state int32
3
    sema  uint32
4
}

state：表示锁的状态，包括是否被锁定、是否有等待的Goroutine、是否处于饥饿模式等信息。
sema：用于实现阻塞和唤醒机制的信号量。

1.2.1 几个全集变量#

1
const (
2
    mutexLocked = 1 << iota // mutex is locked
3
    mutexWoken
4
    mutexStarving
5
    mutexWaiterShift = iota
6

7
    starvationThresholdNs = 1e6
8
)

mutexLocked：表示锁被持有。
mutexWoken：表示有Goroutine被唤醒。
mutexStarving：表示锁处于饥饿模式。
mutexWaiterShift：表示等待Goroutine的数量在state中的偏移量。
starvationThresholdNs：表示饥饿模式的阈值，超过这个时间的Goroutine会被标记为饥饿。

1.2.2 state 字段详述#

state字段是一个32位整数，其中每一位或一组位表示不同的状态信息：

第0位（mutexLocked）：表示锁是否被持有。如果为1，表示锁被持有；如果为0，表示锁未被持有。
第1位（mutexWoken）：表示是否有Goroutine被唤醒。如果为1，表示有Goroutine被唤醒；如果为0，表示没有Goroutine被唤醒。
第2位（mutexStarving）：表示锁是否处于饥饿模式。如果为1，表示锁处于饥饿模式；如果为0，表示锁未处于饥饿模式。
第3位及之后的位（mutexWaiterShift及之后的位）：表示等待Goroutine的数量。通过将等待Goroutine的数量左移mutexWaiterShift位，可以将其存储在state字段的高位部分。最多可以表示 229−12^{29}-1229−1 个等待Goroutine。

1.3 Mutex.Lock()#

1.3.1 Lock 方法主干#

1
func (m *Mutex) Lock() {
2
    if atomic.CompareAndSwapInt32(&m.state, 0, mutexLocked) {
3
        return
4
    }
5
    // Slow path (outlined so that the fast path can be inlined)
6
    m.lockSlow()
7
}

首先尝试CAS获取锁，如果失败，说明锁已经被其他协程持有，进入慢路径lockSlow。这是在正常模式下的上锁流程，因为atomic.CompareAndSwapInt32(&m.state, 0, mutexLocked)保证了state为0，一定不是饥饿模式。

1.3.2 Mutex.lockSlow()#

1.3.2.1 几个局部变量#

1
func (m *Mutex) lockSlow() {
2
    var waitStartTime int64
3
    starving := false
4
    awoke := false
5
    iter := 0
6
    old := m.state
7
    for {
8
        // ...
9
    }
10
}

waitStartTime：记录Goroutine开始等待的时间，用于判断是否进入饥饿模式。
starving：表示当前Goroutine是否处于饥饿状态。
awoke：表示当前Goroutine是否被唤醒。
iter：表示当前Goroutine尝试获取锁的次数，用于控制自旋次数。
old：记录当前的state值，用于后续的CAS操作。

1.3.2.2 自旋空转#

1
func (m *Mutex) lockSlow() {
2
    // ...
3
    for {
4
        // 进入该 if 分支，说明抢锁失败，处于正常模式，且仍满足自旋条件
5
        if old&(mutexLocked|mutexStarving) == mutexLocked && runtime_canSpin(iter) {
6
            // 进入自旋后处理环节
7
            // ...
8
            continue
9
        }
10
        // ...
11
    }
12
}

假如满足三个条件：1. 当前锁处于正常模式 2. 锁被持有 3. 自旋次数未达上限，则进行自旋。则进入自旋后处理环节。
进入自旋后处理环节中，假如当前锁有尚未唤醒的阻塞协程，则通过 CAS 操作将 state 的 mutexWoken 标识置为 1，将局部变量 awoke 置为 true。
调用 runtime_doSpin 告知调度器 P 当前处于自旋模式。
更新自旋次数 iter 和锁状态值 old。
通过 continue 语句进入下一轮尝试。

1.3.2.3 state 新值构造#

1
func (m *Mutex) lockSlow() {
2
    // ...
3
    for {
4
        // 自旋抢锁失败后处理 ...
5
        new := old
6
        if old&mutexStarving == 0 {
7
            new |= mutexLocked
8
        }
9
        if old&(mutexLocked|mutexStarving) != 0 {
10
            new += 1 << mutexWaiterShift
11
        }
12
        if starving && old&mutexLocked != 0 {
13
            new |= mutexStarving
14
        }
15
        if awoke {
16
            new &^= mutexWoken
17
        }
18
        // ...
19
    }
20
}

展开收起

从自旋中走出来后，会存在两种分支，要么加锁成功，要么陷入自锁，不论是何种情形，都会先对 sync.Mutex 的状态新值 new 进行更新；
倘若当前是非饥饿模式，则在新值 new 中置为已加锁，即尝试抢锁；
倘若旧值为已加锁或者处于饥饿模式，则当前 goroutine 在这一轮注定无法抢锁成功，可以直接令新值的阻塞协程数加1；
倘若当前进入饥饿模式且旧值已加锁，则将新值置为饥饿模式；
倘若局部变量标识是已有唤醒协程抢锁，说明 Mutex.state 中的 mutexWoken 是被当前 goroutine 置为 1 的，但由于当前 goroutine 接下来要么抢锁成功，要么被阻塞挂起，因此需要在新值中将该 mutexWoken 标识更新置 0.

1.3.2.4 state 新旧值替换#

1
func (m *Mutex) lockSlow() {
2
    // ...
3
    for {
4
        // 自旋抢锁失败后处理 ...
5

6
        // new/old 状态值更新 ...
7

8
        if atomic.CompareAndSwapInt32(&m.state, old, new) {
9
            // case1 加锁成功
10
            // case2 将当前 goroutine 挂起
11

12
            // ...
13
        } else {
14
            old = m.state
15
        }
16
        // ...
17
    }
18
}

展开收起

通过 CAS 操作，用构造的新值替换旧值；
倘若失败（即旧值被其他 goroutine 介入提前修改导致不符合预期），则将旧值更新为此刻的 Mutex.state，并开启一轮新的循环；
倘若 CAS 替换成功，则进入最后一轮的二择一局面：
- I）倘若当前 goroutine 加锁成功，则返回；
- II）倘若失败，则将 goroutine 挂起并添加到阻塞队列。

1.3.2.5 上锁成功分支#

加锁成功的分支

1
func (m *Mutex) lockSlow() {
2
    // ...
3
    for {
4
        // 自旋抢锁失败后处理 ...
5
        // new/old 状态值更新 ...
6
        if atomic.CompareAndSwapInt32(&m.state, old, new) {
7
            if old&(mutexLocked|mutexStarving) == 0 {
8
                break
9
            }
10

11
            // ...
12
        }
13
        // ...
14
    }
15
}

展开收起

延续 1.3.2.4 的思路，此时已经成功将 Mutex.state 由旧值替换为新值；
接下来进行判断：倘若旧值是未加锁状态且为正常模式，则意味着加锁标识位正是由当前 goroutine 完成的更新，说明加锁成功，返回即可；
倘若旧值中锁未释放或者处于饥饿模式，则当前 goroutine 需要进入阻塞队列挂起。

1.3.2.6 阻塞挂起#

阻塞挂起 goroutine

1
func (m *Mutex) lockSlow() {
2
    // ...
3
    for {
4
        // 自旋抢锁失败后处理 ...
5

6
        // new/old 状态值更新 ...
7

8
        if atomic.CompareAndSwapInt32(&m.state, old, new) {
9
            // 加锁成功后返回的逻辑分支 ...
10

11
            queueLifo := waitStartTime != 0
12
            if waitStartTime == 0 {
13
                waitStartTime = runtime_nanotime()
14
            }
15
            runtime_SemacquireMutex(&m.sema, queueLifo, 1)
16
            // ...
17
        }
18
        // ...
19
    }
20
}

展开收起

承接上节，走到此处的情形有两种：要么是抢锁失败，要么是锁已处于饥饿模式，而当前 goroutine 不是从阻塞队列被唤起的协程。不论处于哪种情形，当前 goroutine 都面临被阻塞挂起的命运。

基于 queueLifo 标识当前 goroutine 是从阻塞队列被唤起的“老客”还是新进流程的“新客”；
倘若等待的起始时间为 0，则为新客；倘若非 0，则为老客；
倘若是新客，则对等待的起始时间进行更新，置为当前时刻的 ns 时间戳；
将当前 goroutine 添加到阻塞队列中：倘若是老客则挂入队头；倘若是新客则挂入队尾；
挂起当前 goroutine。

1.3.2.7 从阻塞态被唤醒#

goroutine 被唤醒后

1
func (m *Mutex) lockSlow() {
2
    // ...
3
    for {
4
        // 自旋抢锁失败后处理...
5

6
        // new/old 状态值更新 ...
7

8
        if atomic.CompareAndSwapInt32(&m.state, old, new) {
9
            // 加锁成功后返回的逻辑分支 ...
10

11
            // 挂起前处理 ...
12
            runtime_SemacquireMutex(&m.sema, queueLifo, 1)
13

14
            // 从阻塞队列被唤醒了
15
            starving = starving || runtime_nanotime()-waitStartTime > starvationThresholdNs
16
            old = m.state
17
            if old&mutexStarving != 0 {
18
                delta := int32(mutexLocked - 1<<mutexWaiterShift)
19
                if !starving || old>>mutexWaiterShift == 1 {
20
                    delta -= mutexStarving
21
                }
22
                atomic.AddInt32(&m.state, delta)
23
                break
24
            }
25
            awoke = true
26
            iter = 0
27
        }
28
        // ...
29
    }
30
}

展开收起

走入此处，说明当前 goroutine 是从 Mutex 的阻塞队列中被唤起的；
判断是否需要进入饥饿模式：倘若当前 goroutine 在阻塞队列中等待时间长达 1ms，则更新 starving 变量，并在下一轮循环中完成对 Mutex.state 中 mutexStarving 标识位的更新；
获取此时锁的状态，通过 old 存储；
倘若此时锁是饥饿模式，则当前 goroutine 无需竞争可以直接获得锁；
饥饿模式下，goroutine 获取锁前需要更新锁的状态，包含 mutexLocked、阻塞队列等待 goroutine 数以及 mutexStarving 三个信息；均通过 delta 变量记录差值，最终通过原子操作添加到 Mutex.state 中；
mutexStarving 的更新要作前置判断：倘若当前 starving 为 false，或者当前 goroutine 就是阻塞队列的最后一个 goroutine，则将 Mutex.state 置为正常模式。

1.4 Unlock#

1.4.1 Unlock 方法主干#

Unlock方法主流程

1
func (m *Mutex) Unlock() {
2
    new := atomic.AddInt32(&m.state, -mutexLocked)
3
    if new != 0 {
4
        m.unlockSlow(new)
5
    }
6
}

通过原子操作解锁；
倘若解锁时发现，目前参与竞争的仅有自身一个 goroutine，则直接返回即可；
倘若发现锁中还有阻塞协程，则走入 unlockSlow 分支。

1.4.2 unlockSlow#

解锁时唤醒等锁的阻塞 goroutine

1.4.2.1 未加锁的异常情形#

1
func (m *Mutex) unlockSlow(new int32) {
2
    if (new+mutexLocked)&mutexLocked == 0 {
3
        fatal("sync: unlock of unlocked mutex")
4
    }
5
    // ...
6
}

解锁时倘若发现 Mutex 此前未加锁，直接抛出 fatal。

1.4.2.2 正常模式#

1
func (m *Mutex) unlockSlow(new int32) {
2
    // ...
3
    if new&mutexStarving == 0 {
4
        old := new
5
        for {
6
            if old>>mutexWaiterShift == 0 || old&(mutexLocked|mutexWoken|mutexStarving) != 0 {
7
                return
8
            }
9

10
            new = (old - 1<<mutexWaiterShift) | mutexWoken
11
            if atomic.CompareAndSwapInt32(&m.state, old, new) {
12
                runtime_Semrelease(&m.sema, false, 1)
13
                return
14
            }
15
            old = m.state
16
        }
17
    }
18
    // ...
19
}

展开收起

倘若阻塞队列内无 goroutine 或者 mutexLocked、mutexStarving、mutexWoken 标识位任一不为零，三者均说明此时有其他活跃协程已介入，自身无需关心后续流程；
基于 CAS 操作将 Mutex.state 中的阻塞协程数减 1，倘若成功，则唤起阻塞队列头部的 goroutine，并退出；
倘若减少阻塞协程数的 CAS 操作失败，则更新此时的 Mutex.state 为新的 old 值，开启下一轮循环。

1.4.2.3 饥饿模式#

1
func (m *Mutex) unlockSlow(new int32) {
2
    // ...
3
    if new&mutexStarving == 0 {
4
        // ...
5
    } else {
6
        runtime_Semrelease(&m.sema, true, 1)
7
    }
8
}

饥饿模式下，直接唤醒阻塞队列头部的 goroutine 即可。

2. Sync.RWMutex#

2.1 核心机制#

从逻辑上，可以把 RWMutex 理解为一把读锁加一把写锁；
写锁具有严格的排他性，当其被占用，其他试图取写锁或者读锁的 goroutine 均阻塞；
读锁具有有限的共享性，当其被占用，试图取写锁的 goroutine 会阻塞，试图取读锁的 goroutine 可与当前 goroutine 共享读锁；
综上可见，RWMutex 适用于读多写少的场景，最理想化的情况，当所有操作均使用读锁，则可实现去无化；最悲观的情况，倘若所有操作均使用写锁，则 RWMutex 退化为普通的 Mutex。

2.2 数据结构#

RWLock数据结构

1
const rwmutexMaxReaders = 1 << 30
2

3
type RWMutex struct {
4
    w           Mutex  // held if there are pending writers
5
    writerSem   uint32 // semaphore for writers to wait for completing readers
6
    readerSem   uint32 // semaphore for readers to wait for completing writers
7
    readerCount int32  // number of pending readers
8
    readerWait  int32  // number of departing readers
9
}

rwmutexMaxReaders：共享读锁的 goroutine 数量上限，值为 2292^{29}229；
w：RWMutex 内置的一把普通互斥锁 sync.Mutex；
writerSem：关联写锁阻塞队列的信号量；
readerSem：关联读锁阻塞队列的信号量；
readerCount：正常情况下等于介入读锁流程的 goroutine 数量；当 goroutine 接入写锁流程时，该值为实际介入读锁流程的 goroutine 数量减 rwmutexMaxReaders；
readerWait：记录在当前 goroutine 获取写锁前，还需要等待多少个 goroutine 释放读锁。

2.3 读锁流程#

2.3.1 RLock#

1
func (rw *RWMutex) RLock() {
2
    if atomic.AddInt32(&rw.readerCount, 1) < 0 {
3
        runtime_SemacquireMutex(&rw.readerSem, false, 0)
4
    }
5
}

基于原子操作，将 RWMutex 的 readCount 变量加一，表示占用或等待读锁的 goroutine 数加一；
倘若 RWMutex.readCount 的新值仍小于 0，说明有 goroutine 未释放写锁，因此将当前 goroutine 添加到读锁的阻塞队列中并阻塞挂起。

2.3.2 RUnlock#

2.3.2.1 RUnlock 方法主干#

1
func (rw *RWMutex) RUnlock() {
2
    if r := atomic.AddInt32(&rw.readerCount, -1); r < 0 {
3
        rw.rUnlockSlow(r)
4
    }
5
}

基于原子操作，将 RWMutex 的 readCount 变量加一，表示占用或等待读锁的 goroutine 数减一；
倘若 RWMutex.readCount 的新值小于 0，说明有 goroutine 在等待获取写锁，则走入 RWMutex.rUnlockSlow 的流程中。

2.3.2.2 rUnlockSlow#

1
func (rw *RWMutex) rUnlockSlow(r int32) {
2
    if r+1 == 0 || r+1 == -rwmutexMaxReaders {
3
        fatal("sync: RUnlock of unlocked RWMutex")
4
    }
5
    if atomic.AddInt32(&rw.readerWait, -1) == 0 {
6
        runtime_Semrelease(&rw.writerSem, false, 1)
7
    }
8
}

对 RWMutex.readerCount 进行校验，倘若发现当前协程此前未抢占过读锁，或者介入读锁流程的 goroutine 数量达到上限，则抛出 fatal；
(倘若 r+1 == -rwmutexMaxReaders，说明此时有 goroutine 介入写锁流程，但当前此前未加过读锁，具体原因见 2.3 小节；倘若 r+1==0，则要么此前未加过读锁，要么介入读锁流程的 goroutine 数量达到上限，具体原因见 2.3 小节。)
基于原子操作，对 RWMutex.readerWait 进行减一操作，倘若其新值为 0，说明当前 goroutine 是最后一个介入读锁流程的协程，因此需要唤醒一个等待写锁的阻塞队列的 goroutine。（综合 RWMutex.readerCount 为负值，可以确定存在等待写锁的 goroutine，具体原因见 2.3 小节。）

2.4 写锁流程#

2.4.1 Lock#

1
func (rw *RWMutex) Lock() {
2
    rw.w.Lock()
3
    r := atomic.AddInt32(&rw.readerCount, -rwmutexMaxReaders) + rwmutexMaxReaders
4
    if r != 0 && atomic.AddInt32(&rw.readerWait, r) != 0 {
5
        runtime_SemacquireMutex(&rw.writerSem, false, 0)
6
    }
7
}

对 RWMutex 内置的互斥锁进行加锁操作；
基于原子操作，对 RWMutex.readerCount 进行减少 -rwmutexMaxReaders 的操作；
倘若此时存在未释放读锁的 gouroutine，则基于原子操作在 RWMutex.readerWait 的基础上加上介入读锁流程的 goroutine 数量，并将当前 goroutine 添加到写锁的阻塞队列中挂起。

2.4.2 Unlock#

1
func (rw *RWMutex) Unlock() {
2
    r := atomic.AddInt32(&rw.readerCount, rwmutexMaxReaders)
3
    if r >= rwmutexMaxReaders {
4
        fatal("sync: Unlock of unlocked RWMutex")
5
    }
6
    for i := 0; i < int(r); i++ {
7
        runtime_Semrelease(&rw.readerSem, false, 0)
8
    }
9
    rw.w.Unlock()
10
}

基于原子操作，将 RWMutex.readerCount 的值加上 rwmutexMaxReaders；
倘若发现 RWMutex.readerCount 的新值大于 rwmutexMaxReaders，则说明要么当前 RWMutex 未上过写锁，要么介入读锁流程的 goroutine 数量已经超限，因此直接抛出 fatal；
因此唤醒读锁阻塞队列中的所有 goroutine；(可见，竞争读锁的 goroutine 更具备优势)
解开 RWMutex 内置的互斥锁。

遇到的一些八股

Fri, 16 Jan 2026 00:00:00 GMT

Go#

Goroutine 出现 panic 会发生什么
Golang 的 GC 什么时候会出现卡顿
清理过程会出现 STW 吗？
Golang 中的 GMP 调度模型是如何工作的？P的作用是什么？
Golang 的逃逸分析机制是什么？如何进行内存分配优化？
Sync.Map 是如何实现并发安全的？
Golang 的反射原理是什么？
Golang 的栈增长机制？为什么 Goroutine 初始栈 2KB 而线程栈是 MB 级？
Sync.Mutex 的实现原理（1.18前后差异）？为什么要引入饥饿模式？
for range 遍历 slice/map 时变量地址是否变化？“赋值不对”的原因？
interface{} 空接口底层实现？为什么可接收任意类型？断言区别？
Golang 的 GMP 模型，以及各组件之间的协作流程？
Golang 的 GC 机制是什么？
map的底层实现？并发读写是否 panic？如何解决？
slice 和 array 的区别？底层与扩容机制
关闭后的 Channel 读写行为？如何安全关闭？
Go 中的 Channel 及其并发控制流程？
使用 Channel 控制图片下载并发数（限流）？
介绍 Go 的 Context 功能？
Context 取消后子协程如何感知？
Go 结构体方法与指针方法的区别？
Go 的继承（组合）与接口？
介绍 GMP 模型？
协程（G）创建的时机？
M 的创建与销毁时机？
P 的创建时机、数量确定及初始化参数？

MySQL#

MySQL 的索引类型？如何优化慢查询？
MySQL 的事务隔离级别；如何解决幻读；Mysql 如何给单行数据加锁；对数据库的复制、备份有了解吗；半同步复制两种模式

计网#

TCP 的拥塞控制算法有哪些？BBR 算法的工作原理？
Websocket 如何实现全双工通信？与长轮询区别？

操作系统#

I/O 多路复用说一下
为什么 select 的文件描述符集合是有序的？
异步 I/O 和非阻塞 I/O？
Linux 进程的虚拟地址空间是如何布局的？
什么是 CPU 的 NUMA 架构？对程序性能的影响？

数据结构#

为什么 epoll 底层用红黑树管理？
如何判断一个数是否为 2 的幂次方？给出最优解
统计海量数据中出现次数最多的前 K 个元素
实现一个循环队列，支持并发安全的入队/出队
介绍堆（大顶堆）的插入、删除和调整过程？
数据流的中位数思路？

MQ#

为什么要使用消息队列？
保证消息有序，一个 topic 只能有一个 partition 吗？
业务突然增长，导致消息消费不过来怎么办？
生产者收到写入成功响应后消息一定不会丢失吗？
高并发场景下怎么保证消息不会重复消费？
如何保证消息的可靠性？
各大消息队列中间件对比及使用场景

分布式#

分布式一致性哈希算法是如何工作的？
什么是 Paxos 算法？Basic 与 Multi 的区别？
分布式系统如何实现服务发现和健康检查？
什么是分布式系统的脑裂问题？如何避免？
分布式 ID 生成方案？
高并发场景下，如何保证接口的幂等性？
如何解决缓存雪崩、穿透、击穿问题？
Redis 分布式锁实现、原子性及 Lua 脚本？
Redis 底层数据结构、Zset 跳表及复杂度？
Redis 布隆过滤器？

Linux/Git#

文件描述符是什么
什么是零拷贝技术？在 Golang 中如何实现？
容器与虚拟机的区别？如何实现资源隔离？
如何使用 Linux 命令查看一个服务是否在运行？
K8s 有用过吗？

Channel 实现原理

Thu, 15 Jan 2026 00:00:00 GMT

1. 核心数据结构#

数据存储在一个环形数组中，并且维护了两个等待队列，分别用于存放因读写操作而阻塞的协程。

Channel.png

1.1 hchan#

1
type hchan struct {
2
    qcount   uint           // total data in the queue
3
    dataqsiz uint           // size of the circular queue
4
    buf      unsafe.Pointer // points to an array of dataqsiz elements
5
    elemsize uint16
6
    closed   uint32
7
    elemtype *_type // element type
8
    sendx    uint   // send index
9
    recvx    uint   // receive index
10
    recvq    waitq  // list of recv waiters
11
    sendq    waitq  // list of send waiters
12

13
    lock mutex
14
}

hchan：channel 数据结构。

qcount：当前 channel 中存在多少个元素；
dataqsize: 当前 channel 能存放的元素容量；
buf：channel 中用于存放元素的环形缓冲区；
elemsize：channel 元素类型的大小；
closed：标识 channel 是否关闭；
elemtype：channel 元素类型；
sendx：发送元素进入环形缓冲区的 index；
recvx：接收元素所处的环形缓冲区的 index；
recvq：因接收而陷入阻塞的协程队列；
sendq：因发送而陷入阻塞的协程队列。

1.2 waitq#

1
type waitq struct {
2
    first *sudog
3
    last  *sudog
4
}

waitq：阻塞的协程队列。

first：队列头部
last：队列尾部

1.3 sudog#

1
type sudog struct {
2
    g *g
3

4
    next *sudog
5
    prev *sudog
6
    elem unsafe.Pointer // data element (may point to stack)
7

8
    isSelect bool
9

10
    c        *hchan
11
}

sudog：用于包装协程的节点。

g：goroutine，协程；
next：队列中的下一个节点；
prev：队列中的前一个节点；
elem: 读取/写入 channel 的数据的容器;
isSelect：标识当前协程是否处在 select 多路复用的流程中；
c：标识与当前 sudog 交互的 chan.

2. 构造器函数#

几种类型的 channel

1
func makechan(t *chantype, size int) *hchan {
2
    elem := t.elem
3

4
    // ...
5
    mem, overflow := math.MulUintptr(elem.size, uintptr(size))
6
    if overflow || mem > maxAlloc-hchanSize || size < 0 {
7
        panic(plainError("makechan: size out of range"))
8
    }
9

10
    var c *hchan
11
    switch {
12
    case mem == 0:
13
        // Queue or element size is zero.
14
        c = (*hchan)(mallocgc(hchanSize, nil, true))
15
        // Race detector uses this location for synchronization.
16
        c.buf = c.raceaddr()
17
    case elem.ptrdata == 0:
18
        // Elements do not contain pointers.
19
        // Allocate hchan and buf in one call.
20
        c = (*hchan)(mallocgc(hchanSize+mem, nil, true))
21
        c.buf = add(unsafe.Pointer(c), hchanSize)
22
    default:
23
        // Elements contain pointers.
24
        c = new(hchan)
25
        c.buf = mallocgc(mem, elem, true)
26
    }
27

28
    c.elemsize = uint16(elem.size)
29
    c.elemtype = elem
30
    c.dataqsiz = uint(size)
31

32
    lockInit(&c.lock, lockRankHchan)
33

34
    return
35
}

展开收起

判断申请内存空间大小是否越界，mem 大小为 element 类型大小与 element 个数相乘后得到，仅当无缓冲型 channel 时，因个数为 0 导致大小为 0；
根据类型，初始 channel，分为无缓冲型、有缓冲元素为 struct 型、有缓冲元素为 pointer 型 channel;
倘若为无缓冲型，则仅申请一个大小为默认值 96 的空间；
如若有缓冲的 struct 型，则一次性分配好 96 + mem 大小的空间，并且调整 chan 的 buf 指向 mem 的起始位置；
倘若为有缓冲的 pointer 型，则分别申请 chan 和 buf 的空间，两者无需连续；
对 channel 的其余字段进行初始化，包括元素类型大小、元素类型、容量以及锁的初始化。

3. 写流程#

3.1 两类异常情况处理#

1
func chansend1(c *hchan, elem unsafe.Pointer) {
2
    chansend(c, elem, true, getcallerpc())
3
}
4

5
func chansend(c *hchan, ep unsafe.Pointer, block bool, callerpc uintptr) bool {
6
    if c == nil {
7
        gopark(nil, nil, waitReasonChanSendNilChan, traceEvGoStop, 2)
8
        throw("unreachable")
9
    }
10

11
    lock(&c.lock)
12

13
    if c.closed != 0 {
14
        unlock(&c.lock)
15
        panic(plainError("send on closed channel"))
16
    }
17

18
    // ...
19
    // ...
20
}

展开收起

对于未初始化的 chan，写入操作会引发死锁；
对于已关闭的 chan，写入操作会引发 panic。

3.2 case1：写时存在阻塞读协程#

直接写入阻塞读协程

1
func chansend(c *hchan, ep unsafe.Pointer, block bool, callerpc uintptr) bool {
2
    // ...
3
    lock(&c.lock)
4
    // ...
5
    if sg := c.recvq.dequeue(); sg != nil {
6
        // Found a waiting receiver. We pass the value we want to send
7
        // directly to the receiver, bypassing the channel buffer (if any).
8
        send(c, sg, ep, func() { unlock(&c.lock) }, 3)
9
        return true
10
    }
11
    // ...
12
}

加锁；
从阻塞度协程队列中取出一个 goroutine 的封装对象 sudog；
在 send 方法中，会基于 memmove 方法，直接将元素拷贝交给 sudog 对应的 goroutine；
在 send 方法中会完成解锁动作。

WriteCase1.png

3.3 case2：写时无阻塞读协程但环形缓冲区仍有空间#

写入环形缓冲区

1
func chansend(c *hchan, ep unsafe.Pointer, block bool, callerpc uintptr) bool {
2
    // ...
3
    lock(&c.lock)
4
    // ...
5
    if c.qcount < c.dataqsiz {
6
        // Space is available in the channel buffer. Enqueue the element to send.
7
        qp := chanbuf(c, c.sendx)
8
        typedmemmove(c.elemtype, qp, ep)
9
        c.sendx++
10
        if c.sendx == c.dataqsiz {
11
            c.sendx = 0
12
        }
13
        c.qcount++
14
        unlock(&c.lock)
15
        return true
16
    }
17

18
    // ...
19
}

展开收起

加锁；
将当前元素添加到环形缓冲区 sendx 对应的位置；
sendx++;
qcount++;
解锁，返回。

WriteCase2.png

3.4 case3：写时无阻塞读协程且环形缓冲区无空间#

阻塞写协程

1
func chansend(c *hchan, ep unsafe.Pointer, block bool, callerpc uintptr) bool {
2
    // ...
3
    lock(&c.lock)
4

5
    // ...
6
    gp := getg()
7
    mysg := acquireSudog()
8
    mysg.elem = ep
9
    mysg.g = gp
10
    mysg.c = c
11
    gp.waiting = mysg
12
    c.sendq.enqueue(mysg)
13

14
    atomic.Store8(&gp.parkingOnChan, 1)
15
    gopark(chanparkcommit, unsafe.Pointer(&c.lock), waitReasonChanSend, traceEvGoBlockSend, 2)
16

17
    gp.waiting = nil
18
    closed := !mysg.success
19
    gp.param = nil
20
    mysg.c = nil
21
    releaseSudog(mysg)
22
    return true
23
}

展开收起

加锁；
构造封装当前 goroutine 的 sudog 对象；
完成指针指向，建立 sudog、goroutine、channel 之间的指向关系；
把 sudog 添加到当前 channel 的阻塞写协程队列中；
park 当前协程；
倘若协程从 park 中被唤醒，则回收 sudog（sudog 能被唤醒，其对应的元素必然已经被读协程取走）；
解锁，返回。

WriteCase3.png

3.5 写流程整体串联#

写流程串联

Write.png

4. 读流程#

4.1 异常 case1：读空 channel#

1
func chanrecv(c *hchan, ep unsafe.Pointer, block bool) (selected, received bool) {
2
    if c == nil {
3
        gopark(nil, nil, waitReasonChanReceiveNilChan, traceEvGoStop, 2)
4
        throw("unreachable")
5
    }
6
    // ...
7
}

park 挂起，引起死锁。

4.2 异常 case2：channel 已关闭且内部无元素#

1
func chanrecv(c *hchan, ep unsafe.Pointer, block bool) (selected, received bool) {
2

3
    lock(&c.lock)
4

5
    if c.closed != 0 {
6
        if c.qcount == 0 {
7
            unlock(&c.lock)
8
            if ep != nil {
9
                typedmemclr(c.elemtype, ep)
10
            }
11
            return true, false
12
        }
13
        // The channel has been closed, but the channel's buffer have data.
14
    }
15

16
    // ...
17
}

展开收起

直接解锁返回即可。

4.3 case3：读时有阻塞的写协程#

从阻塞写协程中读取

1
func chanrecv(c *hchan, ep unsafe.Pointer, block bool) (selected, received bool) {
2

3
    lock(&c.lock)
4

5
    if sg := c.sendq.dequeue(); sg != nil {
6
        recv(c, sg, ep, func() { unlock(&c.lock) }, 3)
7
        return true, true
8
     }
9
     // ...
10
}

加锁；
从阻塞写协程队列中获取到一个写协程；
倘若 channel 无缓冲区，则直接读取写协程元素，并唤醒写协程；
倘若 channel 有缓冲区，则读取缓冲区头部元素，并将写协程元素写入缓冲区尾部后唤醒写写成；
解锁，返回。

4.4 case4：读时无阻塞写协程且缓冲区有元素#

从环形缓冲区读取

1
func chanrecv(c *hchan, ep unsafe.Pointer, block bool) (selected, received bool) {
2
    // ...
3
    lock(&c.lock)
4
    // ...
5
    if c.qcount > 0 {
6
        // Receive directly from queue
7
        qp := chanbuf(c, c.recvx)
8
        if ep != nil {
9
            typedmemmove(c.elemtype, ep, qp)
10
        }
11
        typedmemclr(c.elemtype, qp)
12
        c.recvx++
13
        if c.recvx == c.dataqsiz {
14
            c.recvx = 0
15
        }
16
        c.qcount--
17
        unlock(&c.lock)
18
        return true, true
19
    }
20
    // ...
21
}

展开收起

加锁；
获取到 recvx 对应位置的元素；
recvx++
qcount--
解锁，返回。

4.5 case5：读时无阻塞写协程且缓冲区无元素#

阻塞读协程

1
func chanrecv(c *hchan, ep unsafe.Pointer, block bool) (selected, received bool) {
2
    // ...
3
    lock(&c.lock)
4
    // ...
5
    gp := getg()
6
    mysg := acquireSudog()
7
    mysg.elem = ep
8
    gp.waiting = mysg
9
    mysg.g = gp
10
    mysg.c = c
11
    gp.param = nil
12
    c.recvq.enqueue(mysg)
13
    atomic.Store8(&gp.parkingOnChan, 1)
14
    gopark(chanparkcommit, unsafe.Pointer(&c.lock), waitReasonChanReceive, traceEvGoBlockRecv, 2)
15

16
    gp.waiting = nil
17
    success := mysg.success
18
    gp.param = nil
19
    mysg.c = nil
20
    releaseSudog(mysg)
21
    return true, success
22
}

展开收起

加锁；
构造封装当前 goroutine 的 sudog 对象；
完成指针指向，建立 sudog、goroutine、channel 之间的指向关系；
把 sudog 添加到当前 channel 的阻塞读协程队列中；
park 当前协程；
倘若协程从 park 中被唤醒，则回收 sudog（sudog 能被唤醒，其对应的元素必然已经被写入）；
解锁，返回。

4.6 读流程整体串联#

读流程串联

Read.png

5. 阻塞与非阻塞模式#

在上述源码分析流程中，均是以阻塞模式为主线进行讲述，忽略非阻塞模式的有关处理逻辑. 此处阐明两个问题：

非阻塞模式下，流程逻辑有何区别？
何时会进入非阻塞模式？

5.1 非阻塞模式逻辑区别#

非阻塞模式下，读/写 channel 方法通过一个 bool 型的响应参数，用以标识是否读取/写入成功.

所有需要使得当前 goroutine 被挂起的操作，在非阻塞模式下都会返回 false；
所有是的当前 goroutine 会进入死锁的操作，在非阻塞模式下都会返回 false；
所有能立即完成读取/写入操作的条件下，非阻塞模式下会返回 true。

5.2 何时进入非阻塞模式#

默认情况下，读/写 channel 都是阻塞模式，只有在 select 语句组成的多路复用分支中，与 channel 的交互会变成非阻塞模式：

1
ch := make(chan int)
2
select{
3
case <- ch:
4
default:
5
}

5.3 代码一览#

1
func selectnbsend(c *hchan, elem unsafe.Pointer) (selected bool) {
2
    return chansend(c, elem, false, getcallerpc())
3
}
4

5
func selectnbrecv(elem unsafe.Pointer, c *hchan) (selected, received bool) {
6
    return chanrecv(c, elem, false)
7
}

在 select 语句包裹的多路复用分支中，读和写 channel 操作会被汇编为 selectnbrecv 和 selectnbsend 方法，底层同样复用 chanrecv 和 chansend 方法，但此时由于第三个入参 block 被设置为 false，导致后续会走进非阻塞的处理分支。

6. 两种读 channel 的协议#

读取 channel 时，可以根据第二个 bool 型的返回值用以判断当前 channel 是否已处于关闭状态：

1
ch := make(chan int, 2)
2
got1 := <- ch
3
got2,ok := <- ch

实现上述功能的原因是，两种格式下，读 channel 操作会被汇编成不同的方法：

1
func chanrecv1(c *hchan, elem unsafe.Pointer) {
2
    chanrecv(c, elem, true)
3
}
4

5
//go:nosplit
6
func chanrecv2(c *hchan, elem unsafe.Pointer) (received bool) {
7
    _, received = chanrecv(c, elem, true)
8
    return
9
}

7. 关闭#

关闭 channel 流程

1
func closechan(c *hchan) {
2
    if c == nil {
3
        panic(plainError("close of nil channel"))
4
    }
5

6
    lock(&c.lock)
7
    if c.closed != 0 {
8
        unlock(&c.lock)
9
        panic(plainError("close of closed channel"))
10
    }
11

12
    c.closed = 1
13

14
    var glist gList
15
    // release all readers
16
    for {
17
        sg := c.recvq.dequeue()
18
        if sg == nil {
19
            break
20
        }
21
        if sg.elem != nil {
22
            typedmemclr(c.elemtype, sg.elem)
23
            sg.elem = nil
24
        }
25
        gp := sg.g
26
        gp.param = unsafe.Pointer(sg)
27
        sg.success = false
28
        glist.push(gp)
29
    }
30

31
    // release all writers (they will panic)
32
    for {
33
        sg := c.sendq.dequeue()
34
        if sg == nil {
35
            break
36
        }
37
        sg.elem = nil
38
        gp := sg.g
39
        gp.param = unsafe.Pointer(sg)
40
        sg.success = false
41
        glist.push(gp)
42
    }
43
    unlock(&c.lock)
44

45
    // Ready all Gs now that we've dropped the channel lock.
46
    for !glist.empty() {
47
        gp := glist.pop()
48
        gp.schedlink = 0
49
        goready(gp, 3)
50
    }
51
}

展开收起

关闭未初始化过的 channel 会 panic；
加锁；
重复关闭 channel 会 panic；
将阻塞读协程队列中的协程节点统一添加到 glist；
将阻塞写协程队列中的协程节点统一添加到 glist；
唤醒 glist 当中的所有协程。

Golang map 实现原理

Mon, 12 Jan 2026 00:00:00 GMT

1. 基本用法#

1.1 概述#

map 又称字典，是一种常用的数据结构，核心特征包含下述三点：

（1）存储基于 key-value 对映射的模式；

（2）基于 key 维度实现存储数据的去重；

（3）读、写、删操作控制，时间复杂度 O(1)O(1)O(1).

1.2 初始化#

1.2.1 几种初始化方法#

golang 中，对 map 的初始化分为以下几种方式：

1
myMap1 := make(map[int]int,2)

通过 make 关键字进行初始化，同时指定 map 预分配的容量.

1
myMap2 := make(map[int]int)

通过 make 关键字进行初始化，不显式声明容量，因此默认容量为 0.

1
myMap3 :=map[int]int{
2
    1:2,
3
    3:4,
4
}

初始化操作连带赋值，一气呵成.

1.2.2 key 的类型要求#

map 中，key 的数据类型必须为可比较的类型，chan、map、func不可比较

1.3 读#

读 map 分为下面两种方式：

1
v1 := myMap[10]

第一种方式是直接读，倘若 key 存在，则获取到对应的 val，倘若 key 不存在或者 map 未初始化，会返回 val 类型的零值作为兜底.

1
v2,ok := myMap[10]

第二种方式是读的同时添加一个 bool 类型的 flag 标识是否读取成功. 倘若 ok == false，说明读取失败， key 不存在，或者 map 未初始化.

此处同一种语法能够实现不同返回值类型的适配，是由于代码在汇编时，会根据返回参数类型的区别，映射到不同的实现方法.

1.4 写#

1
myMap[5] = 6

写操作的语法如上. 须注意的一点是，倘若 map 未初始化，直接执行写操作会导致 panic：

1
const plainError string
2
panic(plainError("assignment to entry in nil map"))

1.5 删#

1
delete(myMap,5)

执行 delete 方法时，倘若 key 存在，则会从 map 中将对应的 key-value 对删除；倘若 key 不存在或 map 未初始化，则方法直接结束，不会产生显式提示.

1.6 遍历#

遍历分为下面两种方式：

1
for k,v := range myMap{
2
    // ...
3
}

基于 k,v 依次承接 map 中的 key-value 对；

1
for k := range myMap{
2
    // ...
3
}

基于 k 依次承接 map 中的 key，不关注 val 的取值.

需要注意的是，在执行 map 遍历操作时，获取的 key-value 对并没有一个固定的顺序，因此前后两次遍历顺序可能存在差异.

1.7 并发冲突#

map 不是并发安全的数据结构，倘若存在并发读写行为，会抛出 fatal error.

具体规则是：

（1）并发读没有问题；

（2）并发读写中的”写”是广义上的，包含写入、更新、删除等操作；

（3）读的时候发现其他 goroutine 在并发写，抛出 fatal error；

（4）写的时候发现其他 goroutine 在并发写，抛出 fatal error.

1
fatal("concurrent map read and map write")
2
fatal("concurrent map writes")

需要关注，此处并发读写会引发 fatal error，是一种比 panic 更严重的错误，无法使用 recover 操作捕获.

2. 核心原理#

map 又称为 hash map，在算法上基于 hash 实现 key 的映射和寻址；在数据结构上基于桶数组实现 key-value 对的存储.

以一组 key-value 对写入 map 的流程为例进行简述：

（1）通过哈希方法取得 key 的 hash 值；

（2）hash 值对桶数组长度取模，确定其所属的桶；

（3）在桶中插入 key-value 对.

hash 的性质，保证了相同的 key 必然产生相同的 hash 值，因此能映射到相同的桶中，通过桶内遍历的方式锁定对应的 key-value 对.

因此，只要在宏观流程上，控制每个桶中 key-value 对的数量，就能保证 map 的几项操作都限制为常数级别的时间复杂度.

2.1 hash#

hash 译作散列，是一种将任意长度的输入压缩到某一固定长度的输出摘要的过程，由于这种转换属于压缩映射，输入空间远大于输出空间，因此不同输入可能会映射成相同的输出结果. 此外，hash在压缩过程中会存在部分信息的遗失，因此这种映射关系具有不可逆的特质.

（1）hash 的可重入性：相同的 key，必然产生相同的 hash 值；

（2）hash 的离散性：只要两个 key 不相同，不论其相似度的高低，产生的 hash 值会在整个输出域内均匀地离散化；

（3）hash 的单向性：企图通过 hash 值反向映射回 key 是无迹可寻的.

（4）hash 冲突：由于输入域（key）无穷大，输出域（hash 值）有限，因此必然存在不同 key 映射到相同 hash 值的情况，称之为 hash 冲突.

2.2 桶数组#

桶数组.png

map 中，会通过长度为 2 的整数次幂的桶数组进行 key-value 对的存储：

（1）每个桶固定可以存放 8 个 key-value 对；

（2）倘若超过 8 个 key-value 对打到桶数组的同一个索引当中，此时会通过创建桶链表的方式来化解这一问题.

2.3 拉链法解决 hash 冲突#

首先，由于 hash 冲突的存在，不同 key 可能存在相同的 hash 值；

再者，hash 值会对桶数组长度取模，因此不同 hash 值可能被打到同一个桶中.

综上，不同的 key-value 可能被映射到 map 的同一个桶当中.

此时最经典的解决手段分为两种：拉链法和开放寻址法.

（1）拉链法

拉链法中，将命中同一个桶的元素通过链表的形式进行链接，因此很便于动态扩展.

（2）开放寻址法

开放寻址法中，在插入新条目时，会基于一定的探测策略持续寻找，直到找到一个可用于存放数据的空位为止.

对标拉链还有开放寻址法，两者的优劣对比：

方法	优点
拉链法	简单常用；无需预先为元素分配内存.
开放寻址法	无需额外的指针用于链接元素；内存地址完全连续，可以基于局部性原理，充分利用 CPU 高速缓存.

在 map 解决 hash /分桶冲突问题时，实际上结合了拉链法和开放寻址法两种思路. 以 map 的插入写流程为例，进行思路阐述：

（1）桶数组中的每个桶，严格意义上是一个单向桶链表，以桶为节点进行串联；

（2）每个桶固定可以存放 8 个 key-value 对；

（3）当 key 命中一个桶时，首先根据开放寻址法，在桶的 8 个位置中寻找空位进行插入；

（4）倘若桶的 8 个位置都已被占满，则基于桶的溢出桶指针，找到下一个桶，重复第（3）步；

（5）倘若遍历到链表尾部，仍未找到空位，则基于拉链法，在桶链表尾部续接新桶，并插入 key-value 对.

拉链法.png

2.4 扩容优化性能#

倘若 map 的桶数组长度固定不变，那么随着 key-value 对数量的增长，当一个桶下挂载的 key-value 达到一定的量级，此时操作的时间复杂度会趋于线性，无法满足诉求.

因此在实现上，map 桶数组的长度会随着 key-value 对数量的变化而实时调整，以保证每个桶内的 key-value 对数量始终控制在常量级别，满足各项操作为 O(1) 时间复杂度的要求.

map 扩容机制的核心点包括：

（1）扩容分为增量扩容和等量扩容；

（2）当桶内 key-value 总数/桶数组长度 > 6.5 时发生增量扩容，桶数组长度增长为原值的两倍；

（3）当桶内溢出桶数量大于等于 2^B 时( B 为桶数组长度的指数，B 最大取 15)，发生等量扩容，桶的长度保持为原值；

（4）采用渐进扩容的方式，当桶被实际操作到时，由使用者负责完成数据迁移，避免因为一次性的全量数据迁移引发性能抖动.

3. 数据结构#

3.1 hmap#

1
type hmap struct {
2
    count     int
3
    flags     uint8
4
    B         uint8
5
    noverflow uint16
6
    hash0     uint32
7
    buckets    unsafe.Pointer
8
    oldbuckets unsafe.Pointer
9
    nevacuate  uintptr
10
    extra *mapextra
11
}

（1）count：map 中的 key-value 总数；

（2）flags：map 状态标识，可以标识出 map 是否被 goroutine 并发读写；

（3）B：桶数组长度的指数，桶数组长度为 2^B；

（4）noverflow：map 中溢出桶的数量；

（5）hash0：hash 随机因子，生成 key 的 hash 值时会使用到；

（6）buckets：桶数组；

（7）oldbuckets：扩容过程中老的桶数组；

（8）nevacuate：扩容时的进度标识，index 小于 nevacuate 的桶都已经由老桶转移到新桶中；

（9）extra：预申请的溢出桶.

3.2 mapextra#

1
type mapextra struct {
2
    overflow    *[]*bmap
3
    oldoverflow *[]*bmap
4
    nextOverflow *bmap
5
}

在 map 初始化时，倘若容量过大，会提前申请好一批溢出桶，以供后续使用，这部分溢出桶存放在 hmap.mapextra 当中：

（1）mapextra.overflow：供桶数组 buckets 使用的溢出桶；

（2）mapextra.oldoverFlow: 扩容流程中，供老桶数组 oldBuckets 使用的溢出桶；

（3）mapextra.nextOverflow：下一个可用的溢出桶.

3.3 bmap#

1
const bucketCnt = 8
2
type bmap struct {
3
    tophash [bucketCnt]uint8
4
}

（1）bmap 就是 map 中的桶，可以存储 8 组 key-value 对的数据，以及一个指向下一个溢出桶的指针；

（2）每组 key-value 对数据包含 key 高 8 位 hash 值 tophash，key 和 val 三部分；

（3）在代码层面只展示了 tophash 部分，但由于 tophash、key 和 val 的数据长度固定，因此可以通过内存地址偏移的方式寻找到后续的 key 数组、val 数组以及溢出桶指针；

（4）为方便理解，把完整的 bmap 类声明代码补充如下：

1
type bmap struct {
2
    tophash [bucketCnt]uint8
3
    keys [bucketCnt]T
4
    values [bucketCnt]T
5
    overflow uint8
6
}

4. 构造方法#

创建 map 时，实际上会调用 runtime/map.go 文件中的 makemap 方法，下面对源码展开分析：

4.1 makemap#

方法主干源码一览：

1
func makemap(t *maptype, hint int, h *hmap) *hmap {
2
    mem, overflow := math.MulUintptr(uintptr(hint), t.bucket.size)
3
    if overflow || mem > maxAlloc {
4
        hint = 0
5
    }
6

7
    if h == nil {
8
        h = new(hmap)
9
    }
10
    h.hash0 = fastrand()
11

12
    B := uint8(0)
13
    for overLoadFactor(hint, B) {
14
        B++
15
    }
16
    h.B = B
17

18
    if h.B != 0 {
19
        var nextOverflow *bmap
20
        h.buckets, nextOverflow = makeBucketArray(t, h.B, nil)
21
        if nextOverflow != nil {
22
            h.extra = new(mapextra)
23
            h.extra.nextOverflow = nextOverflow
24
        }
25
    }
26

27
    return h
28
}

展开收起

（1）hint 为 map 拟分配的容量；在分配前，会提前对拟分配的内存大小进行判断，倘若超限，会将 hint 置为零；

1
mem, overflow := math.MulUintptr(uintptr(hint), t.bucket.size)
2
if overflow || mem > maxAlloc {
3
    hint = 0
4
}

（2）通过 new 方法初始化 hmap；

1
if h == nil {
2
    h = new(hmap)
3
}

（3）调用 fastrand，构造 hash 因子：hmap.hash0；

1
h.hash0 = fastrand()`
2
``
3

4

5
（4）大致上基于 log2(B) >= hint 的思路（具体见 4.2 小节 overLoadFactor 方法的介绍），计算桶数组的容量 B；
6

7
```go
8
B := uint8(0)
9
for overLoadFactor(hint, B) {
10
    B++
11
}
12
h.B = B

（5）调用 makeBucketArray 方法，初始化桶数组 hmap.buckets；

1
var nextOverflow *bmap
2
h.buckets, nextOverflow = makeBucketArray(t, h.B, nil)

（6）倘若 map 容量较大，会提前申请一批溢出桶 hmap.extra.

1
if nextOverflow != nil {
2
    h.extra = new(mapextra)
3
    h.extra.nextOverflow = nextOverflow
4
}

4.2 overLoadFactor#

通过 overLoadFactor 方法，对 map 预分配容量和桶数组长度指数进行判断，决定是否仍需要增长 B 的数值：

1
const loadFactorNum = 13
2
const loadFactorDen = 2
3
const goarch.PtrSize = 8
4
const bucketCnt = 8
5

6
func overLoadFactor(count int, B uint8) bool {
7
    return count > bucketCnt && uintptr(count) > loadFactorNum*(bucketShift(B)/loadFactorDen)
8
}
9

10
func bucketShift(b uint8) uintptr {
11
    return uintptr(1) << (b & (goarch.PtrSize*8 - 1))
12
}

（1）倘若 map 预分配容量小于等于 8，B 取 0，桶的个数为 1；

（2）保证 map 预分配容量小于等于桶数组长度 * 6.5.

4.3 makeBucketArray#

makeBucketArray 方法会进行桶数组的初始化，并根据桶的数量决定是否需要提前作溢出桶的初始化. 方法主干代码如下：

1
func makeBucketArray(t *maptype, b uint8, dirtyalloc unsafe.Pointer) (buckets unsafe.Pointer, nextOverflow *bmap) {
2
    base := bucketShift(b)
3
    nbuckets := base
4
    if b >= 4 {
5
        nbuckets += bucketShift(b - 4)
6
    }
7

8
    buckets = newarray(t.bucket, int(nbuckets))
9

10
    if base != nbuckets {
11
        nextOverflow = (*bmap)(add(buckets, base*uintptr(t.bucketsize)))
12
        last := (*bmap)(add(buckets, (nbuckets-1)*uintptr(t.bucketsize)))
13
        last.setoverflow(t, (*bmap)(buckets))
14
    }
15
    return buckets, nextOverflow
16
}

展开收起

makeBucketArray 会为 map 的桶数组申请内存，在桶数组的指数 b >= 4时（桶数组的容量 >= 52 ），会需要提前创建溢出桶。

通过 base 记录桶数组的长度，不包含溢出桶；通过 nbuckets 记录累加上溢出桶后，桶数组的总长度.

5. 读流程#

5.1 读流程梳理#

map 读流程主要分为以下几步：

（1）根据 key 取 hash 值；

（2）根据 hash 值对桶数组取模，确定所在的桶；

（3）沿着桶链表依次遍历各个桶内的 key-value 对；

（4）命中相同的 key，则返回 value；若 key 不存在，则返回零值.

map 读操作最终会走进 runtime/map.go 的 mapaccess 方法中，下面是关键实现和说明：

5.2 mapaccess 方法（关键代码）#

1
func mapaccess1(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer {
2
    if h == nil || h.count == 0 {
3
        return unsafe.Pointer(&zeroVal[0])
4
    }
5
    if h.flags&hashWriting != 0 {
6
        fatal("concurrent map read and map write")
7
    }
8
    hash := t.hasher(key, uintptr(h.hash0))
9
    m := bucketMask(h.B)
10
    b := (*bmap)(add(h.buckets, (hash&m)*uintptr(t.bucketsize)))
11
    if c := h.oldbuckets; c != nil {
12
        if !h.sameSizeGrow() {
13
            m >>= 1
14
        }
15
        oldb := (*bmap)(add(c, (hash&m)*uintptr(t.bucketsize)))
16
        if !evacuated(oldb) {
17
            b = oldb
18
        }
19
    }
20
    top := tophash(hash)
21
bucketloop:
22
    for ; b != nil; b = b.overflow(t) {
23
        for i := uintptr(0); i < bucketCnt; i++ {
24
            if b.tophash[i] != top {
25
                if b.tophash[i] == emptyRest {
26
                    break bucketloop
27
                }
28
                continue
29
            }
30
            k := add(unsafe.Pointer(b), dataOffset+i*uintptr(t.keysize))
31
            if t.indirectkey() {
32
                k = *((*unsafe.Pointer)(k))
33
            }
34
            if t.key.equal(key, k) {
35
                e := add(unsafe.Pointer(b), dataOffset+bucketCnt*uintptr(t.keysize)+i*uintptr(t.elemsize))
36
                if t.indirectelem() {
37
                    e = *((*unsafe.Pointer)(e))
38
                }
39
                return e
40
            }
41
        }
42
    }
43
    return unsafe.Pointer(&zeroVal[0])
44
}

展开收起

关键说明（简要）：

未初始化或空 map：直接返回零值指针；
并发写检测：若发现写标记（hashWriting），抛出 fatal；
扩容兼容：若处于扩容（oldbuckets != nil），可能需要先在 oldbuckets 中取桶并判断是否已迁移；
使用 tophash（hash 的高 8 位，且避开 0-4 的保留值）进行快速筛选，匹配后再比较完整 key。

6. 写流程#

6.1 写流程梳理#

map 写流程主要分为：

根据 key 取 hash 值；
根据 hash 值计算桶索引；
若处于扩容，帮助迁移命中的桶（渐进扩容）；
遍历桶链表查找匹配或空槽；
若已存在 key，则更新 value；否则插入；
若触发扩容条件，则开启扩容并重试定位。

6.2 mapassign（关键代码）#

1
func mapassign(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer {
2
    if h == nil {
3
        panic(plainError("assignment to entry in nil map"))
4
    }
5
    if h.flags&hashWriting != 0 {
6
        fatal("concurrent map writes")
7
    }
8
    hash := t.hasher(key, uintptr(h.hash0))
9

10
    h.flags ^= hashWriting
11

12
    if h.buckets == nil {
13
        h.buckets = newobject(t.bucket)
14
    }
15

16
again:
17
    bucket := hash & bucketMask(h.B)
18
    if h.growing() {
19
        growWork(t, h, bucket)
20
    }
21
    b := (*bmap)(add(h.buckets, bucket*uintptr(t.bucketsize)))
22
    top := tophash(hash)
23

24
    var inserti *uint8
25
    var insertk unsafe.Pointer
26
    var elem unsafe.Pointer
27
bucketloop:
28
    for {
29
        for i := uintptr(0); i < bucketCnt; i++ {
30
            if b.tophash[i] != top {
31
                if isEmpty(b.tophash[i]) && inserti == nil {
32
                    inserti = &b.tophash[i]
33
                    insertk = add(unsafe.Pointer(b), dataOffset+i*uintptr(t.keysize))
34
                    elem = add(unsafe.Pointer(b), dataOffset+bucketCnt*uintptr(t.keysize)+i*uintptr(t.elemsize))
35
                }
36
                if b.tophash[i] == emptyRest {
37
                    break bucketloop
38
                }
39
                continue
40
            }
41
            k := add(unsafe.Pointer(b), dataOffset+i*uintptr(t.keysize))
42
            if t.indirectkey() {
43
                k = *((*unsafe.Pointer)(k))
44
            }
45
            if !t.key.equal(key, k) {
46
                continue
47
            }
48
            if t.needkeyupdate() {
49
                typedmemmove(t.key, k, key)
50
            }
51
            elem = add(unsafe.Pointer(b), dataOffset+bucketCnt*uintptr(t.keysize)+i*uintptr(t.elemsize))
52
            goto done
53
        }
54
        ovf := b.overflow(t)
55
        if ovf == nil {
56
            break
57
        }
58
        b = ovf
59
    }
60

61
    if !h.growing() && (overLoadFactor(h.count+1, h.B) || tooManyOverflowBuckets(h.noverflow, h.B)) {
62
        hashGrow(t, h)
63
        goto again
64
    }
65

66
    if inserti == nil {
67
        newb := h.newoverflow(t, b)
68
        inserti = &newb.tophash[0]
69
        insertk = add(unsafe.Pointer(newb), dataOffset)
70
        elem = add(insertk, bucketCnt*uintptr(t.keysize))
71
    }
72

73
    if t.indirectkey() {
74
        kmem := newobject(t.key)
75
        *(*unsafe.Pointer)(insertk) = kmem
76
        insertk = kmem
77
    }
78
    if t.indirectelem() {
79
        vmem := newobject(t.elem)
80
        *(*unsafe.Pointer)(elem) = vmem
81
    }
82
    typedmemmove(t.key, insertk, key)
83
    *inserti = top
84
    h.count++
85

86
done:
87
    if h.flags&hashWriting == 0 {
88
        fatal("concurrent map writes")
89
    }
90
    h.flags &^= hashWriting
91
    if t.indirectelem() {
92
        elem = *((*unsafe.Pointer)(elem))
93
    }
94
    return elem
95
}

展开收起

要点：

对未初始化的 map 进行写会 panic；
写前设置写标记（hashWriting），写后清除；
在插入前会检查是否需要触发扩容；
插入时优先复用第一个空槽（inserti），否则新建溢出桶。

7. 删除流程#

7.1 删除流程梳理#

删除流程与读、写类似：先定位桶，再遍历链表；命中后清除 key、value，并更新 tophash 与相邻空位标记，必要时帮助扩容迁移。

7.2 mapdelete（关键代码）#

1
func mapdelete(t *maptype, h *hmap, key unsafe.Pointer) {
2
    if h == nil || h.count == 0 {
3
        return
4
    }
5
    if h.flags&hashWriting != 0 {
6
        fatal("concurrent map writes")
7
    }
8

9
    hash := t.hasher(key, uintptr(h.hash0))
10

11
    h.flags ^= hashWriting
12

13
    bucket := hash & bucketMask(h.B)
14
    if h.growing() {
15
        growWork(t, h, bucket)
16
    }
17
    b := (*bmap)(add(h.buckets, bucket*uintptr(t.bucketsize)))
18
    bOrig := b
19
    top := tophash(hash)
20
search:
21
    for ; b != nil; b = b.overflow(t) {
22
        for i := uintptr(0); i < bucketCnt; i++ {
23
            if b.tophash[i] != top {
24
                if b.tophash[i] == emptyRest {
25
                    break search
26
                }
27
                continue
28
            }
29
            k := add(unsafe.Pointer(b), dataOffset+i*uintptr(t.keysize))
30
            k2 := k
31
            if t.indirectkey() {
32
                k2 = *((*unsafe.Pointer)(k2))
33
            }
34
            if !t.key.equal(key, k2) {
35
                continue
36
            }
37
            // Only clear key if there are pointers in it.
38
            if t.indirectkey() {
39
                *(*unsafe.Pointer)(k) = nil
40
            } else if t.key.ptrdata != 0 {
41
                memclrHasPointers(k, t.key.size)
42
            }
43
            e := add(unsafe.Pointer(b), dataOffset+bucketCnt*uintptr(t.keysize)+i*uintptr(t.elemsize))
44
            if t.indirectelem() {
45
                *(*unsafe.Pointer)(e) = nil
46
            } else if t.elem.ptrdata != 0 {
47
                memclrHasPointers(e, t.elem.size)
48
            } else {
49
                memclrNoHeapPointers(e, t.elem.size)
50
            }
51
            b.tophash[i] = emptyOne
52
            // 如果是末位或后续为空，则向前合并为 emptyRest
53
            if i == bucketCnt-1 {
54
                if b.overflow(t) != nil && b.overflow(t).tophash[0] != emptyRest {
55
                    goto notLast
56
                }
57
            } else {
58
                if b.tophash[i+1] != emptyRest {
59
                    goto notLast
60
                }
61
            }
62
            for {
63
                b.tophash[i] = emptyRest
64
                if i == 0 {
65
                    if b == bOrig {
66
                        break
67
                    }
68
                    c := b
69
                    for b = bOrig; b.overflow(t) != c; b = b.overflow(t) {
70
                    }
71
                    i = bucketCnt - 1
72
                } else {
73
                    i--
74
                }
75
                if b.tophash[i] != emptyOne {
76
                    break
77
                }
78
            }
79
        notLast:
80
            h.count--
81
            if h.count == 0 {
82
                h.hash0 = fastrand()
83
            }
84
            break search
85
        }
86
    }
87

88
    if h.flags&hashWriting == 0 {
89
        fatal("concurrent map writes")
90
    }
91
    h.flags &^= hashWriting
92
}

展开收起

8. 遍历流程#

map 的遍历首先创建迭代器（hiter），随机选择起始桶与起始偏移，然后通过 mapiternext 实现按顺序遍历（兼容扩容场景）。

8.1 迭代器结构（hiter）#

1
type hiter struct {
2
    key         unsafe.Pointer
3
    elem        unsafe.Pointer
4
    t           *maptype
5
    h           *hmap
6
    buckets     unsafe.Pointer
7
    bptr        *bmap
8
    overflow    *[]*bmap
9
    oldoverflow *[]*bmap
10
    startBucket uintptr
11
    offset      uint8
12
    wrapped     bool
13
    B           uint8
14
    i           uint8
15
    bucket      uintptr
16
    checkBucket uintptr
17
}

展开收起

8.2 mapiterinit / mapiternext（要点）#

mapiterinit 初始化迭代器并随机选取 startBucket 与 offset；若 t.bucket.ptrdata == 0，会预取 overflow 信息供迭代器使用；
mapiternext 在遍历时检测并发写（hashWriting），并在遇到扩容时通过 checkBucket 兼容旧桶未迁移的数据顺序；
遍历遇到被标记为 evacuated 的条目时，会通过 mapaccessK 等方法完成安全读取。

9. 扩容流程#

9.1 扩容类型#

增量扩容（grow bigger）：桶数组长度翻倍；
等量扩容（same size grow）：保持桶数量不变，但降低溢出桶数量，提高填充率。

9.2 何时扩容#

只有写操作可能触发扩容；
overLoadFactor 判断（count > bucketCnt 且 count > loadFactorNum*(bucketShift(B)/loadFactorDen)）会触发增量扩容；
tooManyOverflowBuckets 判断溢出桶过多会触发等量扩容。

9.3 开启扩容（hashGrow 要点）#

根据 overLoadFactor 决定 bigger（0 或 1）；
将旧 buckets 赋给 oldbuckets，创建新 buckets，并初始化 nevacuate 等字段；
如果存在预分配的 overflow，会把它们提升为 oldoverflow。

9.4 扩容迁移规则与渐进式迁移#

在增量扩容中，旧桶中的条目要么迁到 x 区（同索引），要么迁到 y 区（索引 + oldBucketsLen），取决于 hash 的低位；
map 采用渐进式扩容：每次写/删会迁移两组桶 —— 当前命中的桶与最小未迁移桶（h.nevacuate）；
evacuate 会遍历旧桶，把条目按规则搬到目标桶（并标记已搬迁），在适当时机释放旧桶引用。

总结一些八股答案

Sun, 04 Jan 2026 00:00:00 GMT

怎么保证 MQ 消息顺序性#

严格来说，无法保证。首先，这个 MQ 消息顺序性是得区分全局顺序还是局部顺序的。

如果是全局顺序，那这个需求肯定是不合理的。我们一般做的就是局部顺序。

那局部顺序因为一个 topic 下面有多个 queue，正常发送是肯定无法保证局部顺序的。所以，我们就需要给需要保证顺序的消息分组路由在同一个 queue 里面，这样就能保证消息的顺序性。

但是，如果说消费者是通过线程池并行访问的，这时又会出现问题。那消费者就可以维护内存中的阻塞队列，同样的把同一个订单的消息放在同一个阻塞队列，一个队列对应一个线程并行的处理。

那么问题又来了，顺序消费的 topic 里面的分区数和队列数需要是固定的，不能轻易扩容和缩容。顺序消费的 topic 分区数必须固定，一旦扩容和缩容，消息就可能被路由到其他的队列中或者其他的分区。扩容或者某个分区挂了，会触发 rebalance，那某个分区可能从 A 变 B，就会导致拉错消息，这也会导致乱序问题。

最后，消息消费失败了，会放到队列里重试。那这时候就涉及到两种情况：放到阻塞队列里，这直接就无法保证顺序性了；我们只能放在本地队列。但是放在本地队列，本地重试遇到 rebalance 的时候，就可能会被其他消费者处理，一样会出问题。

所以，MQ 本身就是一个高性能不太可靠的中间件，不应该完全依赖 MQ 去保障。极端情况下很有可能会出问题的，只能做好兜底措施，比如通过定时任务做好数据对账、数据补偿等等。

如何保证消息可靠性？消息重试应该本地重试还是重试队列#

首先，消息丢失的原因主要有几种：1. 从生产者发送到 MQ 的过程中丢失；2. MQ 自己也会弄丢，比如说宕机重启等等的；3. MQ 把消息发送给消费者也可能会丢；4. 消费者处理完消息没有成功确认或者说线程重启了、崩溃了等等。

这些都会导致消息丢失。

首先，从生产者发送到 MQ 的过程中丢失，我们可以用 ACK 机制，MQ 收到直接给生产者一个 ACK 就可以了。

其次，MQ 自己丢失消息，这个我们可以通过开启消息持久化来解决。这样就算宕机重启也不会丢失消息，MQ 集群保证高可用，避免宕机。

最后，消费者还没消费就丢了，那就用消费者 ACK 机制。

如果说消费者消费失败了，这个时候就需要重试机制了。应该放在重试队列肯定是最好的，因为本地队列遇到 rebalance 会丢失消息。消费者数量变化了或者说 Topic 分区数变化了，都会导致 rebalance。本地重试就是在内存里，当队列被回收的时候，发生 rebalance，这些没有被确认和待处理的消息就和队列一起被丢弃了。所以说，本地重试是不靠谱的。

而且，重试队列还有其他的好处，因为它是独立的队列或者 topic，可以去做好监控、观测，重试的次数、延迟、堆积都能监控到，这样就能及时发现问题，进行补偿。

其次，在做好消息的幂等，加上消息的唯一 ID，再加上 Redis 的 setNX 去保证幂等，或者其他方式都是可以的。总之，就是避免消息丢失带来的重复消费问题。

但是，无论再怎么做，MQ 都可能出问题，就是可能因为 rebalance 加上本地重试造成消息丢失，就是可能因为幂等性没做好出问题，也可能因为服务抖动、业务异常等等出现一些现象。

所以，对于重要场景就是要做好兜底的措施。首先，就是死信队列，去保存拒绝、处理失败、超时的这些信息，便于后面复核、修复、重放，配合链路追踪去定位这些问题。

做好定时的消息对账，保证最终消息一致性，保证各种数据最终态没问题，这样才能真正的保证消息的可靠、消息的幂等。

缓存击穿、穿透、雪崩怎么解决#

缓存击穿#

就是一个高并发的 key 过期失效了，这时候大量请求直接打到数据库上，造成数据库压力过大，甚至宕机。

那缓存击穿有很多方案，甚至有很多公司搞了一个中间件或者框架去解决这个问题。主要就是有几种方法。

首先，就是互斥锁，也就是加锁，只有第一个请求去加载数据，其他请求等待。这样就能避免大量请求打到数据库上，但是这种方式会导致大量请求阻塞等待，影响响应时间。

然后，就可以用逻辑过期，设计缓存是永不过期的，数据内部去维护一个过期时间。请求来了之后拿到数据，判断这个过期时间是否过期，如果过期了，那就异步去更新缓存，其他的请求先返回旧数据。这样就能避免大量请求打到数据库上，但是这种方法数据一致性会差一些。

最后，就是一些中间件或者框架，比如快手的 RPC 服务，叫做 cache setter，通过一致性哈希让查同一个 key 的请求都路由到同一个 cache setter。出现了 miss 的情况，那就尝试从 map 里拿出一个 countDownLatch，拿不到就说明是第一个请求，那就给 map 中 put 一个 countDownLatch，然后去更新缓存。后续的请求过来就从 map 里拿到这个 countDownLatch，然后被 await 阻塞住，等待第一个请求更新完缓存之后，调用 countDown() 方法，其他线程就解除阻塞了。

还有京东的方案 jd hot key，通过检测 hot key，直接放在本地缓存里，这样就能避免击穿。

缓存穿透#

就是请求一个根本不存在的数据，这个请求会直接打到数据库上，造成数据库压力过大。

这时候，主要就是对这些请求做好校验、拦截、限流、设置黑名单等等，尽量就在网关这一步拦住非法请求。

然后，就是缓存空值，对于不存在的数据，也缓存一个空值。这样下次请求来的时候，就不会打到数据库上了。

但是，每一次查询的值都不一样，这时候也会造成压力。所以，就上布隆过滤器，写数据库的时候同时写布隆过滤器，这样查询的时候先查布隆过滤器，如果不存在，直接拦截掉，不用查数据库。

但缺点还是有，一个是误判率，另外一个是布隆过滤器本身不支持删除。如果数据库做了删除操作，布隆过滤器还是存在的，这时候就需要定期重建布隆过滤器。

缓存雪崩#

就是缓存集中过期失效了，或者干脆 Redis 宕机了，这时候大量请求打到数据库上，造成数据库压力过大。

第一种方案，就是在固定的过期时间上，加上一个随机值，这样就能避免大量 key 在同一时间过期。

其次，就是针对几乎不太变化的数据，设置永不过期。这样就能避免这些数据过期之后，大量请求打到数据库上。如果说需要修改，那异步的去删除和更新缓存就可以了。

第三种，就是针对能够预知到的热点数据，进行预热。比如说双十一活动之前，把一些热点数据提前加载到缓存里，这样就能避免活动开始之后，大量请求打到数据库上。

最后，就是比如说 Redis 宕机了，内存不够了，或者说缓存里大量冷数据进来导致缓存被淘汰了，或者就是完全不可抗力因素，机房被水淹了导致的缓存雪崩。那就是做好 Redis 的高可用，该上主从上主从，该上集群上集群，多机房的容灾，同城双活，异地多活，该上上。对于不可控的意外情况做好兜底措施，做好服务降级、限流、熔断，避免服务被打垮了。

Redis 的数据持久化#

Redis 提供了两种持久化方式：RDB（Redis DataBase）和 AOF（Append Only File）。

RDB 持久化：RDB 是 Redis 默认的持久化方式。它会在指定的时间间隔内生成数据快照，并将其保存到磁盘上的 RDB 文件中。RDB 持久化的优点是恢复速度快，占用空间小，但缺点是可能会丢失最近一段时间的数据，因为它是基于时间间隔进行持久化的。
AOF 持久化：AOF 是另一种持久化方式，它会将每个写操作追加到一个日志文件中。AOF 持久化的优点是数据恢复更完整，可以配置为每次写操作都进行持久化，但缺点是文件体积较大，恢复速度较慢。

Redis 还支持混合持久化模式，即同时使用 RDB 和 AOF。在 AOF 重写的时候，把当前内存里的数据以 RDB 的方式写进去，把后面的新命令以 AOF 的形式写下来。这样前半段是 RDB 的二进制，后面是 AOF 的命令，可以在保证数据完整性的同时，提高恢复速度。

YAML 在 Go 语言中的使用

Fri, 07 Nov 2025 00:00:00 GMT

YAML 与 OpenAPI 在 Go 项目中的系统讲解#

一、YAML 的语法与模型#

1. 基本数据结构#

YAML 的数据结构与 JSON 对应：

对象（映射、map）：key: value
数组（序列、list）：
```
1
fruits:
2
  - apple
3
  - banana
```
标量（scalar）：字符串、数字、布尔、null、时间等。

YAML 强依赖缩进表达层级：只用空格，不要用 Tab。团队应统一 2 或 4 个空格缩进。

2. 字符串与数字#

普通字符串可不加引号；包含冒号、前导零、布尔词、特殊字符时建议加引号，避免被误解析：

1
code: "01"        # 避免被当作数字
2
enabled: "off"    # 避免被当作 false（YAML 有多种布尔字面量）
3
path: "/v1/users" # 含斜杠更安全

多行字符串有两种常用块标量：
```
1
desc: |
2
  第一行
3
  第二行
4
note: >
5
  这一段
6
  渲染为单行
```
| 保留换行；> 折叠换行为空格。可用 |-、|+ 控制末尾换行修剪。

3. 数组与对象的行内写法#

行内（flow）风格与 JSON 类似：
```
1
obj: {a: 1, b: 2}
2
arr: [1, 2, 3]
```
多数配置建议使用缩进（block）风格，可读性更高。

4. 引用、锚点与合并（进阶）#

复用片段：
```
1
base: &base
2
  retries: 3
3
  timeout: 5s
4
server:
5
  <<: *base
6
  timeout: 10s
```
合并键 << 会把 base 的键值并入 server。注意：不同工具对锚点/合并支持不完全一致，写 OpenAPI 时尽量谨慎使用。

5. 注释与文件后缀#

注释用 #。
.yaml 与 .yml 完全等价，二者只是扩展名不同。实践中各生态有约定俗成：如 docker-compose.yml、Kubernetes 常见 .yaml。

二、在 Go 中读取 YAML#

1. 使用 `gopkg.in/yaml.v3`#

适合直接把 YAML 映射到结构体。

1
type Server struct {
2
    Host string `yaml:"host"`
3
    Port int    `yaml:"port"`
4
}
5
type Config struct {
6
    Server Server `yaml:"server"`
7
}
8

9
data, err := os.ReadFile("config.yaml")
10
if err != nil { /* handle */ }
11
var cfg Config
12
if err := yaml.Unmarshal(data, &cfg); err != nil { /* handle */ }

要点与常见问题：

结构体标签用 yaml:"fieldName"；未匹配的字段会被忽略。
建议在解析前设置默认值（或使用 viper 的默认值能力）。
对可能缺省的字段，使用指针类型可区分“没填”和“零值”。
时间、持续时间等：time.Duration 在 YAML 中以字符串表示（如 "5s"），解析时可用自定义类型或中间字符串再转换。
严格模式：社区常见做法是加载后对未识别键进行二次校验（如先反序列化到 map[string]any 做白名单检查），或在 CI 用 schema 校验配置。

2. 使用 `github.com/spf13/viper`#

适合复杂项目的“配置中心”方案：多格式、环境变量覆盖、默认值、可选热加载。

1
viper.SetConfigName("config")
2
viper.SetConfigType("yaml")
3
viper.AddConfigPath(".")
4
if err := viper.ReadInConfig(); err != nil { /* handle */ }
5

6
viper.SetDefault("server.port", 8080)
7
viper.AutomaticEnv()
8
viper.SetEnvPrefix("APP") // APP_SERVER_PORT=9090
9
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
10

11
var cfg Config
12
if err := viper.Unmarshal(&cfg); err != nil { /* handle */ }

实践建议：

配置层叠：基础配置 + 环境覆盖。例如 config.yaml、config.dev.yaml，再用环境变量兜底。
明确配置优先级：默认值 < 文件 < 环境变量 < 命令行参数。
若启用热加载，记得设计并发安全的配置读取方式（例如原子替换）。

三、OpenAPI 用 YAML 描述接口的心智模型#

OpenAPI 是一种“接口契约”规范，可以用 JSON 或 YAML 描述。核心结构（3.0 与 3.1 大体一致）：

1
openapi: 3.1.0
2
info:            # 文档元信息
3
servers:         # 服务基地址（可带变量）
4
paths:           # 路由与操作（get/post/put/delete/...）
5
components:      # 复用部件（schemas、parameters、responses、securitySchemes 等）

关键点：

paths 定义每个资源路径及其操作（参数、请求体、响应体、状态码、示例等）。
components 存放可复用对象，通过 $ref 引用，减少重复。
OpenAPI 3.1 与 JSON Schema 2020-12 更接近；3.0 的 schema 子集略有差异。选择版本要与工具链匹配。

四、OpenAPI 常用关键字与结构说明（与 YAML 语法解耦）#

1. 文档与服务层面#

openapi: 规范版本。
info: 文档元信息，含 title、description、version 等。

servers: 一组基础 URL，可用 variables 定义模板变量及默认值。

1
servers:
2
  - url: "https://{host}/api"
3
    variables:
4
      host:
5
        default: "example.com"

2. 路由与操作（`paths` 与 HTTP 动作）#

paths 的键是路径模板，形如 /users/{id}。
每个路径下可定义 get、post、put、delete、patch 等操作。
操作级字段常见：
- summary、description：人类可读说明。
- tags：分组标签。
- operationId：全局唯一的操作标识，代码生成器常用它生成方法名。
- parameters：参数列表（path/query/header/cookie）。
- requestBody：请求体描述及媒体类型。
- responses：响应状态码映射。
- security：操作级安全策略（可覆盖全局）。
- servers：操作级覆盖的服务器地址（可选）。

3. 参数（`parameters`）#

位置：in 为 path、query、header、cookie。
路径参数必须 required: true，且名称与路径模板占位符一致。
序列化控制：
- style、explode、allowReserved 等影响数组/对象在查询串或头部的编码方式（如 form、simple、pipeDelimited、spaceDelimited 等）。
类型通过 schema 指定，支持 type、format、enum 等。

示例（查询参数数组的不同风格）：

1
parameters:
2
  - in: query
3
    name: ids
4
    schema:
5
      type: array
6
      items: { type: string }
7
    style: form
8
    explode: true    # ?ids=a&ids=b

4. 请求体（`requestBody`）#

required: 是否必须。
content: 媒体类型到 schema 的映射，例如 application/json、multipart/form-data、application/x-www-form-urlencoded、text/plain。
对上传文件，在 3.0 中常用 type: string, format: binary，配合 multipart/form-data。

5. 响应（`responses`）#

键为状态码字符串（建议加引号避免 YAML 把 200 解析成数字）。
default 为兜底响应。
headers 可定义响应头。
content 定义不同媒体类型的 schema。

示例：

1
responses:
2
  "200":
3
    description: ok
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User"
8
  default:
9
    description: error

6. 复用部件（`components`）#

常见子节：

schemas：数据模型（强烈建议集中管理）。
parameters：可复用的参数定义。
responses：可复用的响应。
requestBodies、headers、examples、securitySchemes、links、callbacks 等。

$ref 用法：

1
schema:
2
  $ref: "#/components/schemas/User"

OpenAPI 3.0 中 $ref 节点不能与并列的其他键共存；3.1 放宽，但生成器支持度不一，务必验证。

五、Schema（数据模型）关键字详解（与 Go 类型映射）#

1. 基本类型与格式#

1
type: string
2
type: integer
3
  format: int32     # 也可 int64
4
type: number
5
  format: float     # 或 double
6
type: boolean
7
type: array
8
  items: { $ref: "#/components/schemas/User" }
9
type: object
10
  properties: { ... }

Go 常见映射（生成器可能略有差异）：

string → string
integer(int32) → int32 或 int
integer(int64) → int64
number(float/double) → float32/float64
boolean → bool
array[T] → []T
object → struct 或 map[string]any（有时 additionalProperties 决定是否为 map）

2. 约束与校验#

字符串：minLength、maxLength、pattern、enum、format（如 date-time、uuid、email）。
数值：minimum、maximum、exclusiveMinimum、exclusiveMaximum、multipleOf。
数组：minItems、maxItems、uniqueItems。
对象：required、minProperties、maxProperties、additionalProperties（控制是否允许未声明字段，及其类型）。

示例：

1
type: object
2
required: [id, name]
3
properties:
4
  id:
5
    type: string
6
    format: uuid
7
  name:
8
    type: string
9
    minLength: 1
10
  labels:
11
    type: object
12
    additionalProperties:
13
      type: string

3. 组合与多态#

oneOf: 多选一
anyOf: 任一匹配
allOf: 全部匹配（常用于“继承/扩展”）
not: 排除

Go 中对 oneOf/anyOf 的表达策略：

手写自定义类型与 json.Unmarshaler 判别；
借助生成器的辅助类型；
通过 discriminator 明确区分字段，提高可生成性与可读性。

4. 可空、读写属性、弃用#

OpenAPI 3.0：nullable: true；3.1 更推荐 type: ["string", "null"] 等联合类型写法。
readOnly：仅响应体现，客户端提交可省略。
writeOnly：仅请求体现，响应应省略。
deprecated: true：标记弃用，但不影响校验。

5. 示例与默认值#

example：单个示例。
examples：命名示例集合。
default：字段未提供时的默认值（规范层面的语义，具体是否生效依赖服务端实现与生成器支持）。

六、将 OpenAPI 应用到 Go 的工作流#

1. 验证与质量控制#

在 CI 中加入校验步骤：语法有效性、引用完整性、风格约束。

可以使用 Go 库（如 kin-openapi）在单测或启动时验证文档：

1
loader := openapi3.NewLoader()
2
doc, err := loader.LoadFromFile("openapi.yaml")
3
if err != nil { /* handle */ }
4
if err := doc.Validate(context.Background()); err != nil { /* handle */ }

2. 代码生成（服务端与客户端）#

两条常见线路：

轻量生成器（如 deepmap/oapi-codegen）适合与 chi、gin 集成，能生成类型、服务接口、客户端、请求校验中间件。典型做法：
1. 用 OpenAPI 定义契约；
2. 生成 Go 类型与服务接口；
3. 你只需实现接口方法并挂载到路由；
4. 可用生成的校验器在入站请求处做 schema 校验。
OpenAPI Generator（多语言生态广，需 Java 运行时）适合同时生成多语言客户端或服务器桩代码。

选择原则：以团队现有栈、生成代码质量、可维护性与工具链稳定性为首要考虑。

3. 路由绑定与校验#

生成器通常提供“把接口实现绑定到路由”的适配函数。
强烈建议在路由层启用“请求校验中间件”，确保落到业务逻辑之前已经满足 OpenAPI 的参数与 schema 约束。

4. 与 YAML 配置的关系#

OpenAPI 文档本身是 YAML 文件；服务运行配置（端口、数据库）也是 YAML。二者解耦：
- 配置 YAML → 用 yaml.v3/viper 加载到结构体；
- OpenAPI YAML → 仅用于契约、校验与代码生成，不直接参与运行时配置。

七、一个示例#

下面是一个在 Go 语言中的 YAML 示例：

1
openapi: 3.1.0
2
info:
3
  title: order service
4
  description: order service
5
  version: 1.0.0
6
servers:
7
  - url: 'https://{hostname}/api'
8
    variables:
9
      hostname:
10
        default: '127.0.0.1'
11

12
paths:
13
  /customer/{customerID}/orders/{orderID}:
14
    get:
15
      description: "get order"
16
      parameters:
17
        - in: path
18
          name: customerID
19
          schema:
20
            type: string
21
          required: true
22

23
        - in: path
24
          name: orderID
25
          schema:
26
            type: string
27
          required: true
28

29
      responses:
30
        '200':
31
          description: todo
32
          content:
33
            application/json:
34
              schema:
35
                $ref: '#/components/schemas/Order'
36
        default:
37
          description: todo
38
          content:
39
            application/json:
40
              schema:
41
                $ref: '#/components/schemas/Error'
42

43
  /customer/{customerID}/orders:
44
    post:
45
      description: "creat order"
46
      parameters:
47
        - in: path
48
          name: customerID
49
          schema:
50
            type: string
51
          required: true
52
      requestBody:
53
        required: true
54
        content:
55
          application/json:
56
            schema:
57
              $ref: '#/components/schemas/CreateOrderRequest'
58

59
      responses:
60
        '200':
61
          description: todo
62
          content:
63
            application/json:
64
              schema:
65
                $ref: '#/components/schemas/Order'
66
        default:
67
          description: todo
68
          content:
69
            application/json:
70
              schema:
71
                $ref: '#/components/schemas/Error'
72

73
components:
74
  schemas:
75
    Order:
76
        type: object
77
        properties:
78
            id:
79
              type: string
80
            customerID:
81
              type: string
82
            status:
83
              type: string
84
            items:
85
              type: array
86
              items:
87
                $ref: '#/components/schemas/Item'
88
            paymentLink:
89
                type: string
90

91
    Item:
92
      type: object
93
      properties:
94
        id:
95
          type: string
96
        name:
97
          type: string
98
        quantity:
99
          type: integer
100
          format: int32
101
        priceID:
102
          type: string
103

104
    Error:
105
      type: object
106
      properties:
107
        message:
108
          type: string
109

110
    CreateOrderRequest:
111
      type: object
112
      required:
113
        - customerID
114
        - items
115
      properties:
116
        customerID:
117
          type: string
118
        items:
119
          type: array
120
          items:
121
            $ref: '#/components/schemas/ItemWithQuantity'
122

123
    ItemWithQuantity:
124
      type: object
125
      properties:
126
        id:
127
          type: string
128
        quantity:
129
          type: integer
130
          format: int32

展开收起

基于多邻国的单元单词背诵软件

Mon, 03 Nov 2025 00:00:00 GMT

基于多邻国单元的日语单词背诵软件#

LANSGANBS

nihon-vocab-trainer