Go on 牛哥聊技术

Go 与 Java 泛型：晚到的 vs 老牌的，对比谁更好用

Tue, 09 Dec 2025 15:30:00 +0800

写在前面

泛型是现代编程语言的"老话题"了——Java 1.5（2004 年）就有，C++、C#、TypeScript 都早早具备。但Go 直到 1.18（2022 年）才引入泛型。

很多人好奇——Go 的泛型和 Java 比有什么不同？只是"语法换换"还是真有本质差异？

本文从语法、实现机制、边界、常见用法做全面对比——让你看完能准确判断"什么场景哪个语言的泛型更好用"。

一、语法层面对比

最简单的例子：泛型函数

Java：

1
2
3
4
5
6


public static <T> T identity(T x) {
 return x;
}

String s = identity("hello");
Integer i = identity(42);

Go：

1
2
3
4
5
6


func Identity[T any](x T) T {
 return x
}

s := Identity("hello")
i := Identity(42)

非常相似——只是位置不同。Java 用 <T> 在返回类型前，Go 用 [T any] 在函数名后。

泛型类型 / 结构体

Java：

1
2
3
4
5
6
7


public class Box<T> {
 private T value;
 public Box(T value) { this.value = value; }
 public T get() { return value; }
}

Box<String> box = new Box<>("hello");

Go：

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


type Box[T any] struct {
 value T
}

func NewBox[T any](v T) *Box[T] {
 return &Box[T]{value: v}
}

func (b *Box[T]) Get() T {
 return b.value
}

box := NewBox("hello") // 类型推断

Go 的方法接收者也要写 [T]——稍啰嗦。但类型推断更友好——NewBox("hello") 不用写 NewBox[string]。

二、约束系统的差异

这是两者最大的差异——怎么限制泛型的类型。

Java：基于 `extends` 的边界

1
2
3


public static <T extends Comparable<T>> T max(T a, T b) {
 return a.compareTo(b) > 0 ? a : b;
}

T extends Comparable<T> 限定 T 必须实现 Comparable 接口。

也支持 & 多个接口：

1

public static <T extends Comparable<T> & Serializable> ...

Go：基于"约束接口"

Go 用 interface 表达约束——但比 Java 灵活得多：

1
2
3
4
5
6
7
8


type Ordered interface {
 ~int | ~int64 | ~float64 | ~string
}

func Max[T Ordered](a, b T) T {
 if a > b { return a }
 return b
}

注意 ~int 中的 ~ 符号——表示"底层类型是 int 的所有类型"，包括 type MyInt int 这种自定义类型。

类型集合（type set）

Go 引入了"类型集合"概念——可以用 | 表达多个类型的并集：

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


type Number interface {
 int | int8 | int16 | int32 | int64 | uint | uint8 | ...
 float32 | float64
}

func Sum[T Number](s []T) T {
 var total T
 for _, v := range s {
 total += v
 }
 return total
}

Java 做不到同样的事——Java 没法说"接受 int 或 long 但不接受其他"。Java 要这种行为只能用接口（牺牲基本类型）或重载方法。

三、实现机制：擦除 vs 单态化

这是最深的差异——编译器怎么处理泛型代码。

Java：类型擦除（Type Erasure）

Java 编译时把泛型类型擦除成 Object，运行时所有 List<String> 和 List<Integer> 都是同一个 List 类。

1
2
3


List<String> a = new ArrayList<>();
List<Integer> b = new ArrayList<>();
System.out.println(a.getClass() == b.getClass()); // true！

类型擦除的代价

1
2
3
4
5
6
7


public <T> T create() {
 return new T(); // ❌ 不能 new T，运行时不知道 T 是什么
}

public <T> T[] toArray() {
 return new T[10]; // ❌ 同样不行
}

绕路要传 Class<T>：

1
2
3


public <T> T create(Class<T> clazz) {
 return clazz.getDeclaredConstructor().newInstance();
}

Go：单态化（Monomorphization）

Go 编译时为每个具体类型生成专门的代码——Max[int] 和 Max[float64] 是两段独立代码。

1
2


m1 := Max(1, 2) // 编译生成 Max_int
m2 := Max(1.0, 2.0) // 编译生成 Max_float64

实际上 Go 做的是部分单态化（GCShape）——按"GC 形状"分组，不是每个类型都独立。

对比

	Java（擦除）	Go（单态化）
编译速度	快	慢（要展开多份）
二进制体积	小	大
运行时性能	中（要装箱拆箱）	高（特化代码）
反射支持	弱（运行时类型擦除）	强（保留类型信息）
不能 new T	真	可以（用 reflect）

四、装箱与基本类型

Java 泛型最大的痛——不能用基本类型：

1
2


List<int> l = ...; // ❌ 不行
List<Integer> l = ...; // ✓ 装箱

每个 int 都被装箱成 Integer 对象——内存占用 4-5 倍，还有 GC 压力。

Go 没这个问题：

1
2


list := []int{1, 2, 3} // 直接是 int，无装箱
GenericFunc[int](42) // 直接传 int

Go 在数值密集场景下泛型性能远超 Java 泛型。

五、常见用法对比

1. 集合工具函数

Java（用 Stream）：

1
2
3


List<Integer> doubled = list.stream()
 .map(i -> i * 2)
 .collect(Collectors.toList());

Go（自己实现 Map）：

1
2
3
4
5
6
7
8
9


func Map[T, U any](s []T, f func(T) U) []U {
 r := make([]U, len(s))
 for i, v := range s {
 r[i] = f(v)
 }
 return r
}

doubled := Map(list, func(i int) int { return i * 2 })

Go 1.21 之后标准库有 slices 包：

1
2
3
4
5


import "slices"

slices.Sort(list)
slices.Contains(list, 5)
slices.Max(list)

2. 容器类

Java：

1

Map<String, List<User>> usersByCity = new HashMap<>();

Go：

1

usersByCity := make(map[string][]*User)

Go 的内置容器（map、slice）已经支持泛型——不需要单独的"泛型容器"。这是 Go 的优势。

3. 错误处理 / Result 类型

Rust 风格 Result 类型——Java 没有但能实现：

Java：

1
2
3
4
5


public class Result<T, E> {
 private final T value;
 private final E error;
 // ...
}

Go：

1
2
3
4
5
6
7


type Result[T any] struct {
 Value T
 Err error
}

func Ok[T any](v T) Result[T] { return Result[T]{Value: v} }
func Err[T any](e error) Result[T] { return Result[T]{Err: e} }

不过 Go 社区主流仍是 (value, error) 双返回——Result 类型不流行。

六、Go 泛型的限制

Go 1.18 引入泛型时刻意做了"最小可用"——功能上比 Java 少很多：

1. 无方法泛型

Go 的方法不能引入新的泛型参数——只能复用所属类型的参数：

1
2
3
4
5
6
7


type Box[T any] struct { v T }

// ❌ 不行：方法不能有自己的泛型参数
func (b *Box[T]) Map[U any](f func(T) U) *Box[U] { ... }

// ✓ 必须包装成顶级函数
func MapBox[T, U any](b *Box[T], f func(T) U) *Box[U] { ... }

这是 Go 泛型的最大遗憾——写流式 API 比 Java 啰嗦。

状态更新（截至 Go 1.25, 2025-08）：方法泛型仍未支持，且 Go FAQ 明确写着 “we do not anticipate that Go will ever add generic methods”。社区有持续提案（issue #77273 是当前最新的 spec 提案），但官方态度悲观。技术原因主要是"参数化方法会产生无限多的具体方法签名"——会破坏 reflect 包的向后兼容。所以可见的未来里，写 Go 泛型流式 API 都得用顶级函数包一层。

2. 无变型（Variance）

Java 有 ? extends T / ? super T 表达协变 / 逆变——Go 没有。

1

List<? extends Number> list = new ArrayList<Integer>(); // ✓

1

// Go 没有等价语法

3. 无 Constraint Inference

Java 的类型推断范围广，能推断出复杂约束——Go 仅做"显式 + 简单推断"。

4. 没有"条件实现"

Go 的方法集是"全有或全无"——无法表达"仅当 T 满足某个约束时，Box[T] 才实现某个接口"（C# 的 where T: IFoo + 条件 impl，或 Rust 的 conditional impl<T: Foo> Bar for Box<T> 都做得到，Go 没有等价物）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


type Stringer interface {
 String() string
}

type Box[T any] struct { v T }

// ✓ 可以无条件实现 Stringer，T 是不是 Stringer 都行
func (b Box[T]) String() string { return fmt.Sprintf("%v", b.v) }

// ❌ 没法表达"仅当 T 是 Stringer 时 Box[T] 才实现 Stringer"

5. 顺手吐槽：`[]` 把泛型、map、切片三件事挤在一起

以下纯属个人意见，不喜请轻喷。

Java / C# / Rust / TypeScript 都用 <T> 表达泛型，和数组下标 []、Map 访问 .get(k) 各管一摊，看一眼就知道是哪件事。Go 当年的官方理由是 <> 会和比较运算符 < > 在解析时产生歧义（例如 a, b = w < x, y > (z) 这种）——所以选了已经被 map / slice 占用的方括号。

听起来很学术，但实际上：

Java、C#、Rust、TypeScript 全都用 <>，解析器写得也都没出问题——所谓的歧义在工程上是可以处理的，无非是写编译器麻烦点
Go 团队选 [] 真正避开的是"写解析器麻烦"，但代价是把这个负担转嫁给了所有读代码的人——同一个 [] 现在要在脑子里区分三件事：

1
2
3
4


m[k] // map 访问（运行时）
s[i] // 切片下标（运行时）
List[int] // 泛型类型实参（编译期）
List[int]{1,2} // ↑ 后面跟花括号才知道是泛型实例化，不是数组下标

实际项目里读到 Cache[string, User] 一开始要愣两秒——脑子里要切换到"哦这是泛型"。pool.Get[*User]() 这种调用乍一看像是"取下标然后调用"，得想一下才反应过来。

不算硬伤，但确实是 Go 泛型读起来"差点意思"的最直接原因。省了编译器作者一次工，让全世界的 Go 程序员每天多想一秒——这买卖不太划算。

6. 顺便再吐一句：Go 的时间格式

同样是个人吐槽。

既然提到了 Go 的语法选择——Go 的时间格式化设计也是一脉相承的"为我自己方便"：别的语言都用 %Y-%m-%d %H:%M:%S 这种 strftime / ISO 风格，Go 偏要让你记一个 reference time：

1
2
3


"Mon Jan 2 15:04:05 MST 2006"
// 对应美式记忆：1 月 2 日 下午 3 点 4 分 5 秒 2006 年，时区 MST，星期一
// 1 / 2 / 3 / 4 / 5 / 6 / 7 顺口溜

设计者很得意——“你看，1234567 多好记”。

问题是：

01/02 是美式日期格式（MM/DD），全世界绝大部分国家用 DD/MM
15:04:05 旁边还要配 AM/PM 的 12 小时制
MST（Mountain Standard Time）是美国山地时区——非美国人这辈子用不到几次
整个"顺口溜"只有美国人觉得顺口

所以 Go 程序员每次写 time.Format("2006-01-02 15:04:05") 时，都得在脑子里把美式 1/2/3/4/5/6/7 顺口溜过一遍——其他语言一句 %Y-%m-%d %H:%M:%S 就能表达的事，Go 要绕一圈。

跟泛型用 [] 一样，这两件事有同一种气味——设计者当年的便利感，最后由所有用户来承担。多少有点 American-centric 的味道。

不影响 Go 是好语言，但读 / 写这两处时偶尔会忍不住想"本来可以不这样的"。

七、Java 泛型的限制

1. 类型擦除导致的反射受限

1
2


List<String> list = new ArrayList<>();
list.getClass(); // 只是 ArrayList，不知道 String

要拿到 String 类型信息要 TypeReference（Jackson 等库的常见做法）。

2. 不能 new T

如前所述。

3. 数组与泛型不兼容

1
2


T[] arr = new T[10]; // ❌
List<String>[] lists = new List<String>[10]; // ❌

历史包袱——Java 数组先于泛型存在，两者设计不兼容。

八、性能对比

	Java	Go
泛型函数调用开销	装箱 + 虚调用	无装箱 + 直接调用
内存占用	每个对象多一层 object header	紧凑数组
GC 影响	装箱对象增加 GC 负担	无影响
编译速度	快	慢（单态化）
二进制体积	小	大（每个特化版本）

数值密集场景 Go 泛型快 2-5 倍 —— 因为 Go 不装箱。

九、典型场景该用谁

flowchart TD
 Q1{要写库还是业务?}
 Q1 -->|库| Lib{需要复杂类型约束?}
 Q1 -->|业务| Biz[两个都够用]
 Lib -->|是，需要变型 / 复杂边界| Java[Java 泛型表达力更强]
 Lib -->|否，简单约束| Either[Go 更简洁]

实战建议：

Go 项目：用 1.21+ 标准库的 slices / maps 包——日常需求够了；自己写库时少滥用泛型（Go 社区文化是"够用就好"）
Java 项目：泛型几乎是必须——集合、Stream、CompletableFuture 都依赖

十、Go 社区对泛型的争议

Go 引入泛型的争议持续多年——有人觉得 Go 不需要泛型：

“Go 的简单是它的核心优势——加泛型只会让代码变复杂”

也有人坚定支持：

“没有泛型，每个排序函数都要写一遍”

最终 Go 团队选择了保守的最小可用方案——这是为什么 Go 泛型没有方法泛型、没有变型、没有约束推断。

这个保守是好事还是坏事？——主流意见是好事。Go 泛型保留了 Go 的简洁哲学，业务代码里 90% 场景不需要泛型。

十一、什么时候真的该用泛型

不论 Go 还是 Java——别为了用泛型而用泛型。判断标准：

✅ 真的需要：

写数据结构（链表、树、图）
写算法工具（排序、查找、map/filter/reduce）
写容器（cache、pool）
写跨类型的辅助函数（Identity、Coalesce）

❌ 不该用：

业务实体（User、Order 不需要泛型化）
单一类型的工具函数
“为了通用"的过度设计

简单代码胜过抽象代码——这条原则在两个语言都适用。

小结

把全文压一句：

Go 泛型的设计哲学是『最小可用 + 高性能』，Java 泛型是『表达力强 + 历史包袱重』——前者赢在简洁和速度，后者赢在生态成熟和工具完善。

各自适合的场景：

Go 泛型：性能敏感、数值密集、库开发场景胜出
Java 泛型：复杂业务建模、需要变型、生态丰富时胜出

但两者最重要的共同点：90% 的业务代码根本不需要泛型。把泛型当工具，需要时拿出来用——不要为了显示"会泛型"而强行抽象。

我写的 Go 状态机库 go-fsm——设计与实践

Fri, 04 Jul 2025 16:00:00 +0800

写在前面

订单流转、审批流程、设备状态、协议握手、游戏角色——任何"有限状态 + 状态间转移规则"的业务，本质上都是状态机。

写过这种业务的人都知道：

1
2
3
4
5
6
7
8


// 反例：散落的 if-else
func Approve(order *Order) error {
 if order.Status != "pending" {
 return errors.New("only pending order can be approved")
 }
 order.Status = "approved"
 // ... 还有几十处类似的散落转换逻辑
}

状态多了之后——没人能讲清"系统里有多少种合法转换"。这就是把 FSM 当作一等公民的价值——状态、事件、转换规则集中声明，业务代码只触发事件。

我维护的 go-fsm 是一个轻量的 Go 状态机库——零依赖、类型安全、Builder 风格 API。本文介绍它的设计理念、核心 API、典型用法。

一、设计目标

写 go-fsm 之前调研过几个 Go 状态机库——多数有几个共同问题：

状态/事件用 string——拼写错了运行时才发现
API 啰嗦——每个 transition 要好几行
依赖大——拉一个 100KB 库，依赖几十个第三方包
没有 hook——不能在转换前后做副作用

go-fsm 的设计目标：

类型安全：State 和 Event 是自定义类型，编译期就能查错
Fluent Builder：定义状态机像写句子
零依赖：纯标准库
Hooks：转换前/后/失败都能挂钩
并发安全：开箱即用

二、最小可运行例子

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


package main

import (
 "fmt"
 "github.com/lingcoder/go-fsm"
)

type OrderState string
type OrderEvent string

const (
 StatePending OrderState = "pending"
 StateApproved OrderState = "approved"
 StateRejected OrderState = "rejected"
 StateShipped OrderState = "shipped"

 EventApprove OrderEvent = "approve"
 EventReject OrderEvent = "reject"
 EventShip OrderEvent = "ship"
)

func main() {
 m := fsm.New(StatePending).
 On(EventApprove).From(StatePending).To(StateApproved).
 On(EventReject).From(StatePending).To(StateRejected).
 On(EventShip).From(StateApproved).To(StateShipped).
 Build()

 fmt.Println(m.State()) // pending

 if err := m.Trigger(EventApprove); err != nil {
 fmt.Println(err)
 }
 fmt.Println(m.State()) // approved

 if err := m.Trigger(EventApprove); err != nil {
 fmt.Println(err) // ErrNoTransition: no transition for event...
 }
}

Builder 链式语法让状态机定义读起来像配置文档：

“EventApprove 事件，从 StatePending 到 StateApproved。”

三、Hooks：转换前后做副作用

实际业务中状态切换通常伴随副作用——记日志、发通知、写 DB：

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


m := fsm.New(StatePending).
 On(EventApprove).
 From(StatePending).
 To(StateApproved).
 Before(func(ctx *fsm.Context) error {
 // 转换前校验
 if !canApprove(ctx.Data) {
 return errors.New("not eligible")
 }
 return nil
 }).
 After(func(ctx *fsm.Context) error {
 // 转换后副作用
 sendApprovalNotification(ctx.Data)
 return nil
 }).
 Build()

Before 返回错误 → 转换被中止；After 在状态已经切换后执行——通常用于通知/日志。

全局 Hook

不只针对某个 transition——整个 FSM 也能挂全局 Hook：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


m := fsm.New(StatePending).
 On(EventApprove).From(StatePending).To(StateApproved).
 OnAnyTransition(func(ctx *fsm.Context) error {
 log.Printf("[%s] %s → %s", ctx.Event, ctx.From, ctx.To)
 return nil
 }).
 OnError(func(ctx *fsm.Context, err error) {
 log.Printf("transition failed: %v", err)
 }).
 Build()

全局 Hook 是处理审计日志、metrics、debug 的最佳位置。

四、并发安全

go-fsm 内部用 RWMutex 保护——多 goroutine 调用 Trigger / State 是安全的：

1
2
3
4
5
6
7
8
9


var wg sync.WaitGroup
for i := 0; i < 100; i++ {
 wg.Add(1)
 go func() {
 defer wg.Done()
 m.Trigger(EventApprove) // 并发安全
 }()
}
wg.Wait()

只有一个 goroutine 的 Trigger 能成功（其他被拒绝因为状态已经变了）——这是状态机的天然语义。

五、典型用法：订单状态机

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


type Order struct {
 ID string
 Amount float64
 State OrderState
}

func NewOrderFSM(order *Order) *fsm.FSM {
 return fsm.New(order.State).
 On(EventPay).From(StatePending).To(StatePaid).
 Before(func(ctx *fsm.Context) error {
 if order.Amount > 100000 {
 return errors.New("require manual review")
 }
 return nil
 }).
 After(func(ctx *fsm.Context) error {
 return paymentService.Confirm(order.ID)
 }).

 On(EventShip).From(StatePaid).To(StateShipped).
 After(func(ctx *fsm.Context) error {
 return logisticsService.CreateOrder(order.ID)
 }).

 On(EventRefund).From(StatePaid).To(StateRefunded).
 On(EventRefund).From(StateShipped).To(StateRefunded).

 On(EventComplete).From(StateShipped).To(StateCompleted).

 OnAnyTransition(func(ctx *fsm.Context) error {
 order.State = ctx.To
 return orderRepo.Save(order)
 }).
 Build()
}

业务里：

1
2
3
4


m := NewOrderFSM(order)
if err := m.Trigger(EventPay); err != nil {
 return err
}

业务代码完全不需要写 if-else 判断状态——状态机自己拦截非法转换。

六、可视化导出

go-fsm 支持导出 DOT 格式——直接喂给 Graphviz 生成状态图：

1
2
3


dot := m.ToDOT()
ioutil.WriteFile("order_fsm.dot", []byte(dot), 0644)
// dot -Tpng order_fsm.dot -o order_fsm.png

生成的图：

flowchart LR
 Pending --> Paid: pay
 Paid --> Shipped: ship
 Paid --> Refunded: refund
 Shipped --> Refunded: refund
 Shipped --> Completed: complete

可视化是状态机维护的核心工具——状态多了之后没图没人能 review。

七、常见使用场景

1. 订单 / 审批流转

经典场景——已经在前文展示过。

2. 协议握手

TCP/TLS/WebSocket 握手过程都是有限状态机：

1
2
3
4
5


fsm.New(StateInit).
 On(EventClientHello).From(StateInit).To(StateServerHello).
 On(EventServerHello).From(StateServerHello).To(StateExchange).
 On(EventExchange).From(StateExchange).To(StateEstablished).
 Build()

3. 设备状态

IoT 设备：online → offline → maintenance → online。

4. 游戏角色

角色状态：idle → walking → running → attacking → dying。

5. 工作流引擎

简单的 BPMN 流程可以用状态机表达——节点是状态，迁移条件是事件。

八、什么时候不该用状态机

虽然状态机是好工具，但不是所有"有状态业务"都该上：

❌ 不适合：

状态简单（只有 2-3 种）——if 就够
状态间无清晰转换规则——状态机反而限制业务
状态由外部驱动且不需要校验——状态机是限制非法转换的工具，不需要限制就没意义

✅ 适合：

状态 ≥ 5 种
转换规则明确
要求"非法转换永远不发生"
多人协作开发同一业务

九、go-fsm 的几个未来方向

go-fsm 是 v0.x 阶段——开源后受到一些反馈，正在演进：

持久化状态：把状态机的当前状态自动同步到 DB
超时转换：状态停留超过 X 秒自动跳到下一个状态
嵌套状态机：复杂业务里子状态机
基于 generics 的强类型——Go 1.18+ 后能做出更类型安全的 API
图形化编辑器：基于 DOT 反向编辑状态机

社区贡献欢迎——github.com/lingcoder/go-fsm。

十、设计反思

写 go-fsm 时学到几个关于"如何设计 Go 库"的事：

API 优先于实现——先想"用户怎么用最爽"，再想内部
零依赖是真正的承诺——拉了一个状态机库就拖一堆传递依赖，是对用户不负责
类型安全是 Go 的礼物——别学其他语言用 string 做枚举
Builder 模式让 API 像 DSL——读起来像句子的代码是好代码
Hooks 优于继承——比起让用户继承基类，提供 callback 更灵活

小结

把 go-fsm 的价值压一句：

业务有 5+ 状态时，状态机不是『过度设计』——它是把『非法转换永远不发生』这件事固化进代码的最佳武器。

go-fsm 的核心三句话：

零依赖——纯标准库
类型安全——State / Event 是你的自定义类型
Builder Fluent——读起来像配置

如果你写 Go 业务系统并且为状态散落 if-else 痛苦过——值得试一下 go-fsm。

1

go get github.com/lingcoder/go-fsm

期待你的 issue / star / PR。

Go 程序中 context 的职责与边界

Mon, 26 Feb 2024 15:30:00 +0800

写在前面

每个 Go 函数签名里都见过它：

1

func (s *Service) GetUser(ctx context.Context, id int64) (*User, error)

ctx 是什么？做什么用的？很多新人对这个第一参数的认知止步于"传超时和取消信号"——但 context 在 Go 里的角色远不止于此。

它是 请求级别的数据通道 + 生命周期管理——理解清楚 context，是写出生产级 Go 服务的基础。

本文从设计动机到实战陷阱，把 context 讲透。

一、context 在解决什么问题

设想一个 Web 请求处理链路：

1
2
3
4
5


HTTP Handler → Service → Repository → DB Driver
 ↓
 RPC Client → 上游 Service
 ↓
 Cache

每一层都有自己的 IO，整个链路可能耗时几百 ms。如果在某一层之间发生：

客户端关闭连接：HTTP handler 应该立刻停止处理，下游的 DB 查询也该取消
整体超时：5 秒超时到了，每一层都该立刻返回
传递请求级数据：traceId、userId、rpc deadline 怎么沿调用链传

每一层都自己写一套"超时控制 + 取消信号 + 数据传递"——重复劳动 + 容易漏。

Go 设计了 context 作为统一抽象——沿调用链向下游透明传递取消、截止时间、键值对。

二、context 的接口

1
2
3
4
5
6


type Context interface {
 Deadline() (deadline time.Time, ok bool)
 Done() <-chan struct{}
 Err() error
 Value(key any) any
}

四个方法：

Deadline：何时超时（如果有）
Done：通道，关闭时表示"该停了"
Err：context 的终止原因（取消 / 超时）
Value：取请求级键值对

三、几种创建 context 的方式

1. 起点：Background / TODO

1
2


ctx := context.Background() // 顶层，永不 cancel
ctx := context.TODO() // 占位，意为"未来要补"

Background 是所有派生 context 的根——通常在 main、初始化代码、HTTP handler 入口创建。

2. WithCancel：手动取消

1
2
3
4
5
6
7
8


ctx, cancel := context.WithCancel(parent)
defer cancel() // 必须！

go func() {
 if shouldStop() {
 cancel() // 手动触发取消
 }
}()

派生出的 ctx 在 cancel() 调用后立刻关闭 Done channel。

3. WithTimeout / WithDeadline

1
2
3
4
5


ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()

ctx, cancel := context.WithDeadline(parent, deadline)
defer cancel()

到时间自动取消。

4. WithValue：传请求级数据

1
2
3
4
5
6
7


type ctxKey string
const userIDKey ctxKey = "userID"

ctx := context.WithValue(parent, userIDKey, "u-12345")

// 下游
userID := ctx.Value(userIDKey).(string)

注意：key 必须是自定义类型——不能用 string，否则容易撞键。

四、context 的派生关系

context 是不可变的——每次 With 都返回一个新 context：

flowchart TD
 Bg[Background] --> Req[WithCancel]
 Req --> A[WithTimeout 5s]
 A --> A1[WithValue userID]
 A --> A2[WithValue traceID]
 Req --> B[WithCancel]

派生关系是树形——parent 取消时所有 child 自动取消。这是 context 的核心性质。

五、典型用法

1. HTTP handler 透传

1
2
3
4
5


func handler(w http.ResponseWriter, r *http.Request) {
 ctx := r.Context() // Go 自带：客户端断开时 ctx 自动 cancel
 user, err := userService.GetByID(ctx, id)
 // ...
}

r.Context() 是 Go 标准库给的 ——客户端断连时这个 ctx 自动 cancel。

2. 整体超时

1
2
3
4
5


ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
defer cancel()

// 整个链路 3 秒超时，无论哪一层卡住都会触发
result, err := service.HeavyOp(ctx)

3. 传递 traceId

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


type ctxKey string
const traceIDKey ctxKey = "traceID"

func TraceMiddleware(next http.Handler) http.Handler {
 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 traceID := r.Header.Get("X-Trace-Id")
 if traceID == "" { traceID = uuid.NewString() }
 ctx := context.WithValue(r.Context(), traceIDKey, traceID)
 next.ServeHTTP(w, r.WithContext(ctx))
 })
}

// 下游
traceID, _ := ctx.Value(traceIDKey).(string)
log.Printf("[trace=%s] querying user...", traceID)

4. 数据库查询

database/sql 自带 context 支持：

1

rows, err := db.QueryContext(ctx, "SELECT * FROM user WHERE id = ?", id)

context 取消时 query 立刻返回 context.Canceled 错误。

5. 监听 Done

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func longRunning(ctx context.Context) error {
 for {
 select {
 case <-ctx.Done():
 return ctx.Err()
 case msg := <-ch:
 handle(msg)
 }
 }
}

任何长循环都该监听 ctx.Done——否则 context 取消你的代码不知道，照样跑。

六、几个最常被踩的坑

1. 忘了 defer cancel

1

ctx, _ := context.WithTimeout(parent, 5*time.Second) // ❌ 忽略 cancel

不调 cancel 会导致 context 资源泄漏——它会一直保留对父 context 的引用，直到 deadline 到。go vet 会警告。

正确：

1
2


ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()

2. context.Background() 用错地方

1
2
3
4


func someService() {
 ctx := context.Background() // ❌ 应该接收上游 ctx
 db.QueryContext(ctx, ...)
}

Background 只在程序入口用。函数应该接收 ctx 参数，否则上游取消信号传不进来。

3. 用 string 作 Value 的 key

1

ctx := context.WithValue(parent, "userID", "u-123") // ❌

string key 容易撞——尤其是其他库也用了 “userID”。永远用自定义类型。

4. 把 context 塞 struct 里

1
2
3


type Service struct {
 ctx context.Context // ❌ 反模式
}

context 应该作为参数传递，不应该作为字段保存——否则 context 的"请求级"语义被破坏。

5. 用 context 传业务参数

1
2
3


ctx = context.WithValue(ctx, "orderID", "1234")
// 下游
orderID := ctx.Value("orderID").(string)

反模式——业务参数应该走函数参数，context 只传"基础设施数据"（traceID、userID、deadline）。

6. 不监听 Done

1
2
3
4
5


func work(ctx context.Context) {
 for i := 0; i < 1000000; i++ {
 // ... 不检查 ctx
 }
}

context 取消了你的循环还在跑——白白浪费资源。长循环必须 select 监听 ctx.Done。

七、context 在 RPC 框架里

gRPC、Dubbo、Thrift 这些 RPC 框架都内置 context 支持——ctx 跨进程传递 deadline 和元数据：

1
2
3
4
5
6
7


// 客户端
ctx := metadata.AppendToOutgoingContext(ctx, "x-trace-id", traceID)
resp, err := client.GetUser(ctx, req)

// 服务端
md, _ := metadata.FromIncomingContext(ctx)
traceID := md.Get("x-trace-id")[0]

ctx 让"分布式 trace"变成框架自动处理的事。

八、什么不该用 context 传

context 的定位是基础设施级数据 + 生命周期——不是万能的"请求级 store"。

✅ 适合 context 传：

traceID / requestID
userID（轻量身份标识）
tenantID
locale / language
deadline / cancellation

❌ 不该用 context 传：

业务参数（如 OrderID）→ 函数参数
大对象（如完整 User）→ 函数参数
配置（如数据库连接）→ 通过依赖注入

如果 context 里塞太多东西——说明你把 context 当成『万能容器』用了，需要重新审视设计。

九、context 与 goroutine

启动 goroutine 时永远要传 ctx：

1
2
3
4
5
6
7
8


go func(ctx context.Context) {
 select {
 case <-ctx.Done():
 return
 case msg := <-ch:
 process(msg)
 }
}(ctx)

不传 ctx 的 goroutine 是"野生 goroutine"——主流程结束它还在跑，资源泄漏 + 数据错乱。

errgroup 的 context

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


g, ctx := errgroup.WithContext(parent)

for _, task := range tasks {
 task := task
 g.Go(func() error {
 return process(ctx, task) // 用 group 派生的 ctx
 })
}

if err := g.Wait(); err != nil {
 return err
}

任一 goroutine 失败时 errgroup 自动 cancel ctx——其他 goroutine 立刻退出。这是最优雅的"并发任务 + 全员协同退出"模式。

十、什么时候需要把 ctx 写出来

新人写 Go 经常困惑——“什么时候要在函数签名里加 ctx？"。

经验法则：

函数会做 IO 操作（DB / HTTP / RPC）→ 接收 ctx
函数会启 goroutine → 接收 ctx
函数链路长，可能被中途取消 → 接收 ctx
纯计算、纯转换、辅助函数 → 不需要

1
2
3
4
5
6
7


// ✓ 需要
func GetUser(ctx context.Context, id int64) (*User, error)
func Process(ctx context.Context, items []Item) error

// ✗ 不需要
func formatName(name string) string
func calculateDiscount(amount float64) float64

按"是否会 IO/并发/可能被中途打断"判断——一目了然。

小结

把全文压一句：

context 是 Go 的『请求级数据通道』——不只是 cancel 信号，而是『生命周期 + 元数据』的统一传递。

工程实战清单：

顶层用 Background，函数链路传 ctx
WithTimeout 永远配 defer cancel
value 的 key 用自定义类型
业务参数走函数参数，不要走 ctx
长循环 select 监听 Done
goroutine 永远传 ctx，配 errgroup 更优雅
ctx 不塞 struct，永远当参数传

把 context 用对，你的 Go 服务在"超时控制 + trace 跟踪 + 优雅退出"这三件事上几乎不会再出问题。

Go 中的 Option 模式：构造函数参数膨胀的优雅解法

Tue, 12 Dec 2023 15:30:00 +0800

一个写过 Go 库都遇到的痛

写一个 HTTP client 库——一开始构造函数很简单：

1
2
3


func NewClient(baseURL string) *Client {
 return &Client{baseURL: baseURL}
}

业务用着用着，需要加超时：

1

func NewClient(baseURL string, timeout time.Duration) *Client { ... }

又要加重试：

1

func NewClient(baseURL string, timeout time.Duration, retries int) *Client { ... }

再加 logger、TLS、middleware、connection pool size、custom headers……一年后构造函数变成这样：

1
2
3
4
5


func NewClient(baseURL string, timeout time.Duration, retries int,
 logger *log.Logger, tlsConfig *tls.Config, middleware []Middleware,
 poolSize int, headers map[string]string, dialer *net.Dialer) *Client {
 // ...
}

调用：

1
2


NewClient("https://api.com", 30*time.Second, 3, logger, nil, nil, 100, nil, nil)
// 这一堆 nil 是什么？

这就是『构造函数参数膨胀』反模式——参数多、含义模糊、加新参数破坏向后兼容。

Go 社区的标准解法是 Functional Options Pattern——Rob Pike 推广，K8s / etcd / gRPC / dapr 等几乎所有大型 Go 项目都在用。

一、Option 模式长什么样

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


type Client struct {
 baseURL string
 timeout time.Duration
 retries int
 logger *log.Logger
 headers map[string]string
}

type Option func(*Client)

func WithTimeout(t time.Duration) Option {
 return func(c *Client) { c.timeout = t }
}

func WithRetries(n int) Option {
 return func(c *Client) { c.retries = n }
}

func WithLogger(l *log.Logger) Option {
 return func(c *Client) { c.logger = l }
}

func WithHeader(k, v string) Option {
 return func(c *Client) {
 if c.headers == nil { c.headers = map[string]string{} }
 c.headers[k] = v
 }
}

func NewClient(baseURL string, opts ...Option) *Client {
 c := &Client{
 baseURL: baseURL,
 timeout: 10 * time.Second, // 默认值
 retries: 0,
 }
 for _, opt := range opts {
 opt(c)
 }
 return c
}

调用方：

1
2
3
4
5
6


client := NewClient("https://api.com",
 WithTimeout(30*time.Second),
 WithRetries(3),
 WithLogger(myLogger),
 WithHeader("X-API-Key", apiKey),
)

参数顺序无所谓、可以省略、加新选项不破坏老代码——优雅、灵活、类型安全。

二、为什么 Option 比其他方案好

对比方案 1：构造函数重载（Java 风格）

1
2
3
4


func NewClient(baseURL string) *Client { ... }
func NewClientWithTimeout(baseURL string, t time.Duration) *Client { ... }
func NewClientWithLogger(baseURL string, l *log.Logger) *Client { ... }
// ...

Go 不支持重载——只能换名字。组合爆炸：3 个可选参数有 8 种组合，要写 8 个构造函数。

对比方案 2：Config struct

1
2
3
4
5
6
7
8


type Config struct {
 BaseURL string
 Timeout time.Duration
 Retries int
 Logger *log.Logger
}

func NewClient(cfg Config) *Client { ... }

调用：

1
2
3
4


NewClient(Config{
 BaseURL: "https://api.com",
 Timeout: 30 * time.Second,
})

也不错——但有几个不足：

零值无法区分"没传"和"传了零值"——Retries: 0 是没设置还是显式设置为 0？
不能动态校验/默认值——只能在构造函数里 if-else 兜底
不能"行为型"配置——比如"应用某个 middleware"
不友好对外文档——配置项散在 struct 里

对比方案 3：Builder

1
2
3
4


client := NewClientBuilder("https://api.com").
 Timeout(30 * time.Second).
 Retries(3).
 Build()

Builder 也常见——但要写更多模板代码（Builder 类、Build() 方法、链式 setter），且不如 Option 灵活（无法把多个相关配置打包成一个 helper）。

Option 的独特优势

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Option 可以做"组合配置"
func WithProductionDefaults() Option {
 return func(c *Client) {
 c.timeout = 30 * time.Second
 c.retries = 5
 c.logger = log.Default()
 }
}

// 用户一行搞定一组生产环境配置
client := NewClient(url, WithProductionDefaults(), WithHeader("X-Env", "prod"))

这是 Option 的杀手级特性——把一组配置封装成一个 Option，可复用、可组合、可继承。

三、Option 的进阶用法

1. 必填参数 vs 可选参数

1
2
3
4
5
6


// 必填参数走构造函数位置参数
func NewClient(baseURL string, opts ...Option) *Client { ... }

// 可选参数走 Option
WithTimeout(...)
WithRetries(...)

位置参数表达必填，Option 表达可选——语义清晰。

2. 校验

1
2
3
4
5
6


func WithRetries(n int) Option {
 return func(c *Client) {
 if n < 0 { panic("retries must be >= 0") }
 c.retries = n
 }
}

或者让 Option 返回 error（更优雅但模板代码多）：

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


type Option func(*Client) error

func WithRetries(n int) Option {
 return func(c *Client) error {
 if n < 0 { return errors.New("retries must be >= 0") }
 c.retries = n
 return nil
 }
}

func NewClient(baseURL string, opts ...Option) (*Client, error) {
 c := &Client{baseURL: baseURL, ...}
 for _, opt := range opts {
 if err := opt(c); err != nil {
 return nil, err
 }
 }
 return c, nil
}

3. 互斥/依赖检查

构造完成后整体校验——多个 Option 之间的关系，比单个 Option 内更复杂：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func NewClient(baseURL string, opts ...Option) (*Client, error) {
 c := &Client{...}
 for _, opt := range opts {
 opt(c)
 }
 if c.useTLS && c.tlsConfig == nil {
 return nil, errors.New("TLS enabled but no config")
 }
 return c, nil
}

4. Option 加在已有对象上

1
2
3
4
5
6
7
8
9


func (c *Client) Apply(opts ...Option) {
 for _, opt := range opts {
 opt(c)
 }
}

client := NewClient(url, WithTimeout(10*time.Second))
// 后续动态调整
client.Apply(WithTimeout(30*time.Second))

适合配置可热更新的场景。

5. 接口式 Option（隐藏内部字段）

如果不想暴露内部字段：

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


type Option interface {
 apply(*config)
}

type config struct {
 timeout time.Duration
 retries int
}

type timeoutOption time.Duration

func (t timeoutOption) apply(c *config) { c.timeout = time.Duration(t) }

func WithTimeout(d time.Duration) Option {
 return timeoutOption(d)
}

更复杂——但对外完全不暴露 config 结构。K8s 的 client-go 用了类似模式。

四、Option 模式的"反派"

不是所有场景都该上 Option：

1. 简单 + 字段少

1

func NewQueue(size int) *Queue { ... }

3 个以下参数，直接位置参数最简单——上 Option 是过度设计。

2. 内部数据结构

1
2
3
4
5
6
7


type User struct {
 Name string
 Age int
}

// 反例：给 User 写 Option？
NewUser(WithName("张三"), WithAge(20)) // ❌ 没必要

业务对象用 struct literal 就够：

1

user := &User{Name: "张三", Age: 20}

3. 一次性参数

1

func Send(msg string, channel string) error

每次调用都不同，根本不需要 Option。

五、几个真实案例

gRPC

1
2
3
4
5
6
7


conn, err := grpc.NewClient(
 "localhost:8080",
 grpc.WithTransportCredentials(insecure.NewCredentials()),
 grpc.WithDefaultCallOptions(grpc.MaxCallSendMsgSize(10*1024*1024)),
 grpc.WithKeepaliveParams(...),
 grpc.WithUnaryInterceptor(...),
)

gRPC 是 Option 模式最经典案例——选项几十个，业务用啥配啥。

K8s informers

1
2
3
4
5
6
7
8


factory := informers.NewSharedInformerFactoryWithOptions(
 clientset,
 time.Minute,
 informers.WithNamespace("default"),
 informers.WithTweakListOptions(func(opts *metav1.ListOptions) {
 opts.LabelSelector = "app=myapp"
 }),
)

Kubernetes 生态的 informer / controller-runtime / cobra 等库大量使用 Option——典型的"参数多 + 大多数有合理默认 + 经常加新选项"场景。

etcd client

1
2
3
4


cli, err := clientv3.New(clientv3.Config{
 Endpoints: []string{"localhost:2379"},
 DialTimeout: 5 * time.Second,
})

etcd 用了 Config struct——也是 Go 社区认可的姿势。可以混用。

六、踩坑提醒

1. Option 名要规范

约定：WithXxx 格式。

1
2
3


WithTimeout(...)
WithLogger(...)
WithRetries(...)

不要写成 SetTimeout、Timeout 等——With 是 Go 社区共识。

2. Option 不要保存状态

1
2
3
4
5
6
7
8


// 反例
var sharedHeader = make(map[string]string)
func WithHeaders(h map[string]string) Option {
 return func(c *Client) {
 sharedHeader = h // ❌ Option 不该改外部状态
 c.headers = sharedHeader
 }
}

Option 应当是纯函数——只改传入的对象。

3. 不要在 Option 里做重活

1
2
3
4
5


func WithDB(dsn string) Option {
 return func(c *Client) {
 c.db = openDB(dsn) // ❌ 在 Option 里建连接
 }
}

Option 应当只设值——副作用、IO、初始化都放到 NewClient 主流程。

4. Option 数量过多

如果你的 Option 已经 30 个了——这不是 Option 模式的问题，是 API 设计太复杂。考虑把 Client 拆成多个职责更聚焦的子 Client。

七、Option 是 Go 的"文化"

Java 用 Builder，Python 用 kwargs，TypeScript 用 Options object——每个语言生态都有自己的"配置传递文化"。

Go 的 Option 模式不仅是技术选择——它是 Go 文化的体现：

简单：不需要继承、不需要装饰器
显式：每个选项都有自己的函数 + 文档
可读：WithTimeout(30*time.Second) 比 cfg.Timeout = 30*time.Second 更像句子

学 Go 不只是学语法——学这种"小语言、强约定"的文化。

小结

把全文压一句：

Option 模式是 Go 解决『构造函数参数膨胀』的标准答案——必填走位置参数，可选走 WithXxx Option，灵活、可组合、对外友好。

工程实践：

2-3 个参数用位置参数；4+ 用 Option
WithXxx 命名规范
Option 是纯函数，不做副作用
校验在 NewXxx 主流程一次性做
可以把多个 Option 组合成预设

下次写 Go 库时——别再让构造函数变成"参数大字报"。Option 是 Go 给你的礼物。

如何把 Go 模块文档发布到 pkg.go.dev

Thu, 05 Oct 2023 15:30:00 +0800

写在前面

Go 生态里没有 npm registry / Maven Central 这种"集中仓库"——Go 模块直接通过 git 仓库地址拉取：

1

go get github.com/lingcoder/go-fsm

但有一个东西扮演了"官方文档站"的角色——pkg.go.dev。它不存代码，只存文档——从你的 Go 源码自动生成。

如果你写了一个 Go 库想让人用，go get 能拉到不代表你"发布了"——pkg.go.dev 上有完整文档、版本列表、示例代码、依赖图，才是 Go 生态意义上的"发布"。

本文用我自己的 go-fsm 作为例子，把发布流程、文档规范、版本管理讲清楚。

一、pkg.go.dev 是什么

它是 Google 维护的 Go 模块文档中心：

自动从 GitHub / GitLab 拉取公开 Go 模块
解析源码生成 HTML 文档
显示版本列表、license、依赖图、被引用数
支持搜索、跳转、链接到源码

flowchart LR
 GitHub[GitHub Tag] --> Proxy[proxy.golang.org]
 Proxy --> PkgGoDev[pkg.go.dev]
 PkgGoDev --> Doc[文档站]

你不需要"提交"什么——只要模块能被 go get，pkg.go.dev 就会自动收录。

二、最小可发布的 Go 模块

1. 仓库结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


go-fsm/
├── go.mod
├── go.sum
├── LICENSE
├── README.md
├── doc.go # 包级文档
├── fsm.go # 主代码
├── fsm_test.go
└── examples/
 └── basic/
 └── main.go

2. go.mod

1
2
3


module github.com/lingcoder/go-fsm

go 1.21

module 名必须是仓库的 import path——pkg.go.dev 通过这个找到对应的 git 仓库。

3. doc.go：包级文档

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


// Package fsm provides a lightweight, type-safe finite state machine
// implementation for Go applications.
//
// # Quick Start
//
// Define states and events:
//
// const (
// StatePending = fsm.State("pending")
// StateApproved = fsm.State("approved")
// StateRejected = fsm.State("rejected")
// )
//
// m := fsm.New(StatePending).
// On(EventApprove).From(StatePending).To(StateApproved).
// On(EventReject).From(StatePending).To(StateRejected).
// Build()
//
// # Features
//
// - Type-safe state and event definitions
// - Hooks before / after transitions
// - Concurrent-safe by default
// - Zero dependencies
package fsm

doc.go 里的 package 注释会成为 pkg.go.dev 主页的描述——它是用户对你库的第一印象。

4. README.md

pkg.go.dev 会同时展示 README 与包级 doc——README 显示在首页 Overview 区，包级 doc 显示在 Documentation 区。两者各司其职：README 面向 GitHub / pkg.go.dev 访客做项目介绍，doc.go 面向 godoc / IDE 跳转做 API 文档。建议把 GitHub 风格的徽章、功能 GIF、安装命令放 README，把 API 用法和 example 放 doc.go。

三、文档规范：让 godoc 漂亮

pkg.go.dev 的文档完全从 Go 源码注释生成——注释规范决定文档质量。

1. 每个导出符号都要有注释

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


// State represents a state in the finite state machine.
type State string

// Event represents a transition trigger event.
type Event string

// FSM is a finite state machine instance.
type FSM struct {
 current State
 // ...
}

// New creates a new FSM with the given initial state.
func New(initial State) *FSM {
 return &FSM{current: initial}
}

注释必须以符号名开头——这是 godoc 的强约定。

2. 多行注释

1
2
3
4
5
6
7
8
9


// Trigger fires an event and transitions the FSM.
//
// If no transition is defined for the current state and event,
// it returns an ErrNoTransition error.
//
// Trigger is safe for concurrent use.
func (m *FSM) Trigger(e Event) error {
 // ...
}

空行分段，每段一个意思。

3. 列表

1
2
3
4
5


// Available hooks:
//
// - BeforeTransition: called before state changes
// - AfterTransition: called after state changes
// - OnError: called when transition fails

注意——列表项前要有 4 空格缩进，pkg.go.dev 才会渲染成 bullet。

4. 可执行示例

example_*.go 文件里的 Example* 函数会自动出现在 pkg.go.dev：

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


// example_test.go
package fsm_test

import (
 "fmt"
 "github.com/lingcoder/go-fsm"
)

func ExampleFSM_Trigger() {
 m := fsm.New("pending").
 On("approve").From("pending").To("approved").
 Build()

 m.Trigger("approve")
 fmt.Println(m.State())
 // Output: approved
}

// Output: ... 是 Go 测试框架的语法——它既验证示例正确性，也是文档。

5. 标题（Go 1.19+）

1
2
3
4
5
6
7


// # Configuration
//
// The FSM can be configured via options...

// # Performance
//
// The FSM is optimized for...

# 在注释里被识别为标题——pkg.go.dev 会渲染成大标题、生成目录。

四、版本管理：发布正式版本

1. 用 git tag 发布

1
2


git tag v1.0.0
git push origin v1.0.0

tag 必须是 vX.Y.Z 格式——Go modules 强制语义化版本。

2. 让 pkg.go.dev 收录新版本

打 tag 后，第一次访问 https://pkg.go.dev/github.com/lingcoder/go-fsm@v1.0.0 会触发proxy.golang.org 抓取——几秒后页面就有了。

或者用：

1

go get github.com/lingcoder/go-fsm@v1.0.0

也会触发同样的抓取。

3. v2+ 的特殊规则

重要：v2 及以上版本要在 module path 里加版本号：

1
2
3


v0.x.x / v1.x.x → module path: github.com/lingcoder/go-fsm
v2.x.x → module path: github.com/lingcoder/go-fsm/v2
v3.x.x → module path: github.com/lingcoder/go-fsm/v3

发布 v2 时：

1
2
3
4


# go.mod
module github.com/lingcoder/go-fsm/v2

go 1.21

并打 tag v2.0.0。这是 Go 1.13 之后的强制规则——强迫"breaking change 必显式"。

五、license 文件：影响排名

pkg.go.dev 会显示模块的 license——有 license 的模块在搜索结果里更靠前。最常用：

MIT —— 最宽松，工业首选
Apache 2.0 —— 带专利授权条款，大公司喜欢
BSD-3-Clause —— 简单、宽松

把对应的 LICENSE 文件放仓库根目录就行——pkg.go.dev 自动识别。

没 license 的代码 法律上等于"All rights reserved" ——别人不能用。开源前一定要加。

六、CI 集成：自动化发布

GitHub Actions 自动测试 + 发版：

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


# .github/workflows/release.yml
name: release

on:
 push:
 tags: ['v*']

jobs:
 release:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - uses: actions/setup-go@v4
 with:
 go-version: '1.21'

 - name: Test
 run: go test ./...

 - name: Vet
 run: go vet ./...

 - name: Trigger pkg.go.dev fetch
 run: |
 curl -sSf "https://proxy.golang.org/github.com/${{ github.repository }}/@v/${{ github.ref_name }}.info"

最后一步主动告诉 proxy.golang.org 拉取——比等用户访问快。

七、提高搜索排名

pkg.go.dev 的搜索排名考虑：

被 import 数量——其他 Go 模块依赖你的越多，排名越高
license 是否存在
文档完整度——所有导出符号都有注释
版本稳定——是否打过 v1+ tag
README / doc.go 内容——关键词是否覆盖搜索词

策略：

取好搜的名字（关键词命中度高）
早发 v1.0.0——pkg.go.dev 把 0.x 版本视为不稳定
写好 doc.go——是搜索引擎的主要食粮
写 example——示例丰富的库更受欢迎

八、常见问题

1. 推了 tag 但 pkg.go.dev 没显示

主动触发抓取：

1

curl "https://proxy.golang.org/github.com/your/repo/@v/v1.0.0.info"

或访问一次 https://pkg.go.dev/github.com/your/repo@v1.0.0。

2. README 里的图片不显示

pkg.go.dev 会渲染 README，但不加载相对路径的本地图片——![logo](docs/logo.png) 这种引用在 pkg.go.dev 上看不到。要让图片正常显示：

用 GitHub raw 的绝对 URL：![logo](https://raw.githubusercontent.com/owner/repo/main/docs/logo.png)
或者把图片放在 GitHub Pages / 图床上引用

API 文档建议同时维护 README（项目介绍）和 doc.go（API 用法）——两者会分别在 Overview 区和 Documentation 区展示，互不替代。

3. 私有仓库怎么办

私有 module 不会在 pkg.go.dev 出现。要内部 doc：

自托管 godoc -http=:6060
公司内部用 pkgsite 自建

4. 删除已发布版本

不能删除。一旦 tag 发布到 proxy.golang.org，会被永久缓存——这是 Go modules 的"checksum 不可变"承诺。

发现版本有 bug：

标记 retract（go.mod 里加 retract v1.0.5）
立刻发新版本 v1.0.6 修复

1
2
3
4
5
6


// go.mod
module github.com/lingcoder/go-fsm

go 1.21

retract v1.0.5 // bug, use v1.0.6+

retracted 版本仍能解析，但用户用 go get 时会得到警告。

5. examples 怎么组织

简单示例 → example_test.go（pkg.go.dev 显示）
完整 demo → examples/ 目录（GitHub 显示但 pkg.go.dev 不显示——所以 doc.go 里指向）

九、一份发布前 Checklist

发版前对照检查：

go.mod 的 module path 正确
doc.go 写好包级文档
所有导出符号有注释（用 golint / revive 检查）
LICENSE 文件存在
README.md 包含安装、quickstart、license
至少 3 个 Example 函数
单元测试覆盖关键路径
CI 通过
打 v1.0.0+ tag（或符合 v2+ 规则）
推 tag 后访问 pkg.go.dev 验证

小结

把全文压一句：

Go 模块发布的『正式仪式』是 git tag + pkg.go.dev——但真正决定库能否被人用的是 doc.go 和 Example 函数的质量。

工程要点：

注释以符号名开头，每个导出符号都有
doc.go 是包的脸面——花时间写
Example 函数比一万字文档有效
v1.0.0 是分水岭——别永远停在 0.x
v2+ 必改 module path

把这套做对，你的 Go 库就不只是"能 go get"——它有文档、有版本、有声誉，是 Go 生态的"正式公民"。

Go 业务代码里的错误处理最佳实践

Wed, 29 Mar 2023 16:00:00 +0800

写在前面

Java / Python / JS 抛异常，Go 用返回值——这是 Go 最被争论的设计。一段典型的 Go 业务代码：

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


user, err := userRepo.GetByID(id)
if err != nil {
 return nil, err
}
order, err := orderRepo.Create(user, dto)
if err != nil {
 return nil, err
}
err = mqProducer.Send(orderCreatedEvent(order))
if err != nil {
 return nil, err
}
return order, nil

每隔三行就 if err != nil——很多新手吐槽"丑"。但写过几年 Go 你会发现：这种"显式错误传递"反而让错误处理路径极其清晰——不像异常那样在调用栈里随机冒出。

但工程上要做对，几个细节：

怎么区分错误类型？err 都是 string 不利于业务判断
怎么追溯错误源头？层层 return err 后只剩最后一层信息
panic 什么时候用？
业务错误 vs 系统错误怎么处理？

本文把 Go 业务代码里错误处理的最佳实践讲清楚。

一、Go 错误处理的核心原则

四个关键原则：

错误是值（errors are values）——不是控制流
错误要有类型——光凭字符串无法做精确判断
错误要带上下文——知道错在哪里
错误要可断言——上层能判断"是不是某种特定错误"

老的 Go 代码多用 fmt.Errorf("%v: %v", ...) 拼字符串——丢失类型。新的 Go（1.13+）有 errors.Is、errors.As、fmt.Errorf("%w", ...)——错误处理终于有了正经工具。

二、定义业务错误：sentinel + 类型

Sentinel 错误（哨兵错误）

1
2
3
4
5
6
7
8
9


package usercase

import "errors"

var (
 ErrUserNotFound = errors.New("user not found")
 ErrUserInactive = errors.New("user inactive")
 ErrInvalidStatus = errors.New("invalid status")
)

调用方判断：

1
2
3
4


user, err := getUser(id)
if errors.Is(err, ErrUserNotFound) {
 return c.Status(404).JSON(...)
}

errors.Is 会沿着 error 链查找——即便错误被 wrap 包过几层，仍然能识别。

类型化错误

光 sentinel 不够——业务错误经常带细节信息：

1
2
3
4
5
6
7
8


type ValidationError struct {
 Field string
 Message string
}

func (e *ValidationError) Error() string {
 return fmt.Sprintf("validation: %s: %s", e.Field, e.Message)
}

调用方判断：

1
2
3
4
5
6
7


var ve *ValidationError
if errors.As(err, &ve) {
 return c.Status(400).JSON(map[string]string{
 "field": ve.Field,
 "message": ve.Message,
 })
}

errors.As 把 error 链中类型匹配的错误赋值给目标变量——能拿到具体字段。

三、Wrap 错误：保留上下文

朴素的 return err 让错误传递时丢失链路：

1
2


// 反例：看不出错在哪里
return userRepo.GetByID(id)

正确做法是 wrap 上下文：

1
2


// 1.13+ 用 fmt.Errorf %w
return fmt.Errorf("getUserByID(%d): %w", id, err)

%w 让错误保留可被 errors.Is/As 追溯的链——而不是普通 %v 拼字符串后丢失类型。

错误打印长这样：

1

service.GetOrder: repo.GetOrder(123): db query: connection refused

每一层都加上下文——出问题时直接看错误信息就能定位。

有些第三方库用 `pkg/errors`

1
2
3


import "github.com/pkg/errors"

err = errors.Wrap(err, "getOrder failed")

老 Go 项目还能见到这种写法——和标准库的 %w 同一思想，新项目直接用标准库即可。

四、什么时候 wrap，什么时候不 wrap

不是每个 err 都要 wrap——盲目 wrap 会让信息冗余：

1
2


// 反例：每层都 wrap，错误信息变成俄罗斯套娃
service: handle: process: validate: check: getValue: db query: connection refused

实战原则：

跨层时 wrap（repo → service → handler）
加业务上下文时 wrap（“creating order for user 123”）
同层多次调用同一函数时 wrap（区分是哪次失败）
直接 return 即可的简单透传，不 wrap

五、Sentinel 还是类型化？

	sentinel error	typed error
表达力	弱（只是个标识）	强（带字段）
比较方式	`errors.Is`	`errors.As`
模板代码	少	多（要写 type）
适合	简单标志（NotFound/Forbidden）	携带详细信息

实战折中：简单错误用 sentinel，需要带字段用 typed。

1
2
3


var ErrNotFound = errors.New("not found") // sentinel

type RateLimitError struct { RetryAfter time.Duration } // typed

六、错误分层：业务错误 vs 系统错误

业务错误（用户输入错了、状态不允许）和系统错误（DB 挂了、网络超时）应该完全不同处理：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


type DomainError struct {
 Code string // "USER_NOT_FOUND" / "INSUFFICIENT_BALANCE"
 Message string // 给用户看的消息
 HTTPStatus int // 4xx
}

func (e *DomainError) Error() string {
 return fmt.Sprintf("%s: %s", e.Code, e.Message)
}

// system error 是普通 error

handler 里统一处理：

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


func errorHandler(c *fiber.Ctx, err error) error {
 var de *DomainError
 if errors.As(err, &de) {
 // 业务错误：返回给用户
 return c.Status(de.HTTPStatus).JSON(map[string]string{
 "code": de.Code,
 "message": de.Message,
 })
 }

 // 系统错误：500，且消息脱敏
 log.Errorf("internal error: %+v", err)
 return c.Status(500).JSON(map[string]string{
 "code": "INTERNAL_ERROR",
 "message": "服务暂时不可用",
 })
}

业务错误暴露给前端没问题；系统错误的细节（如 SQL 报错）绝不能传给用户——日志记录、外部模糊处理。

七、不要用 panic 做控制流

panic 是 Go 的"异常逃生通道"——但不是给业务用的：

1
2
3
4
5
6
7
8


// ❌ 反例：用 panic 做错误处理
func GetOrder(id int) *Order {
 order, err := repo.GetByID(id)
 if err != nil {
 panic(err)
 }
 return order
}

业务代码里 panic 的合法用途几乎只有两类：

真正不应该发生的情况（如 nil pointer 解引用、数组越界）——表示编程 bug
初始化时的致命错误（如配置文件加载失败）——直接退出

正常业务流程永远 return error，让调用方决定怎么处理。

recover 的合法用途

1
2
3
4
5
6
7
8
9


func handler(w http.ResponseWriter, r *http.Request) {
 defer func() {
 if r := recover(); r != nil {
 log.Errorf("panic recovered: %v", r)
 http.Error(w, "internal error", 500)
 }
 }()
 // 业务逻辑
}

每个 HTTP handler 入口、goroutine 入口加 recover——避免一个 panic 把整个服务搞挂。这是兜底，不是常规手段。

八、goroutine 里的错误

启动 goroutine 后，错误不会自动传回 main——必须显式：

1
2
3
4
5
6
7


// ❌ 错误丢失
go func() {
 err := doWork()
 if err != nil {
 // ??? 没人收
 }
}()

正确姿势：

1
2
3
4
5
6
7


errCh := make(chan error, 1)
go func() {
 errCh <- doWork()
}()
if err := <-errCh; err != nil {
 return err
}

或者用 errgroup——更优雅：

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


import "golang.org/x/sync/errgroup"

g, ctx := errgroup.WithContext(ctx)
for _, task := range tasks {
 task := task
 g.Go(func() error {
 return process(ctx, task)
 })
}
if err := g.Wait(); err != nil {
 return err
}

errgroup 还会任一任务失败时自动 cancel ctx——其他任务能立刻退出。

九、错误日志的姿势

1
2
3


// 反例：错误又抛出又日志，导致重复日志
log.Errorf("query user: %v", err)
return err

原则：要么 log，要么 return。同一错误只 log 一次——通常在最上层（HTTP handler / cron entry）。

1
2
3
4
5
6
7
8


// 在 service / repo 层只 wrap：
return fmt.Errorf("getUser: %w", err)

// 在 handler 层一次性记录：
if err := service.GetUser(id); err != nil {
 log.Errorf("getUser failed: %+v", err)
 return ...
}

%+v 配合带 stack trace 的 error 库（如 pkg/errors 或 cockroachdb/errors）能打印完整调用栈。

十、几个常见反模式

1. 错误吞掉

1

result, _ := json.Marshal(obj) // ❌

_ 把错误丢了——出问题永远查不到。显式忽略只在你 100% 确定不会出错时才用，并加注释说明。

2. 错误转字符串再判断

1

if err.Error() == "not found" { ... } // ❌

字符串匹配脆得不行——别人改一个字你的判断就废了。用 errors.Is / errors.As。

3. 把所有错误压成一个 Internal Error

1

return errors.New("internal error")

调用方完全不知道发生什么——永远要 wrap 原 error，保留链。

4. 错误信息含敏感数据

1

return fmt.Errorf("query failed: %v", sqlPassword) // ❌

错误信息可能上日志、上前端——敏感数据要脱敏。

5. error 字段在结构体里

1
2
3
4


type Result struct {
 Data interface{}
 Err error // ❌ 反 Go 风格
}

Go 的约定是"return (T, error)"——别学其他语言把 error 塞结构体里。

十一、Go 1.20+ 的 errors.Join

Go 1.20 引入 errors.Join——支持组合多个错误：

1
2
3


err1 := process(1)
err2 := process(2)
return errors.Join(err1, err2) // 把多个错误打包返回

errors.Is 仍能识别每个原错误：

1
2
3


joined := errors.Join(ErrA, ErrB)
errors.Is(joined, ErrA) // true
errors.Is(joined, ErrB) // true

适合并发任务、批量操作场景——以前要自己写一个 multi-error，现在标准库有了。

小结

把全文压一句：

Go 错误处理的核心是『错误是值，要有类型、有上下文、可断言』——if err != nil 看着烦，但带上 errors.Is/As/Wrap 后是 Go 最干净的设计。

工程实战清单：

业务错误用 sentinel 或 typed，不要 errors.New(...) 拼字符串
跨层 wrap，加业务上下文，用 %w
errors.Is 比较 sentinel，errors.As 提取 typed
业务错误和系统错误分层处理——前端区分对待
panic 不做业务控制流——只在不可恢复 + 初始化失败时
goroutine 用 errgroup
错误只 log 一次，在最上层

把这些做对，“if err != nil 写到吐"会变成你 Go 代码里最可靠的一部分——而不是负担。

Go on 牛哥聊技术

Go 与 Java 泛型：晚到的 vs 老牌的，对比谁更好用

写在前面

一、语法层面对比

最简单的例子：泛型函数

泛型类型 / 结构体

二、约束系统的差异

Java：基于 extends 的边界

Go：基于"约束接口"

类型集合（type set）

三、实现机制：擦除 vs 单态化

Java：类型擦除（Type Erasure）

类型擦除的代价

Go：单态化（Monomorphization）

对比

四、装箱与基本类型

五、常见用法对比

1. 集合工具函数

2. 容器类

3. 错误处理 / Result 类型

六、Go 泛型的限制

1. 无方法泛型

2. 无变型（Variance）

3. 无 Constraint Inference

4. 没有"条件实现"

5. 顺手吐槽：[] 把泛型、map、切片三件事挤在一起

6. 顺便再吐一句：Go 的时间格式

七、Java 泛型的限制

1. 类型擦除导致的反射受限

2. 不能 new T

3. 数组与泛型不兼容

八、性能对比

九、典型场景该用谁

十、Go 社区对泛型的争议

十一、什么时候真的该用泛型

小结

我写的 Go 状态机库 go-fsm——设计与实践

写在前面

一、设计目标

二、最小可运行例子

三、Hooks：转换前后做副作用

全局 Hook

四、并发安全

五、典型用法：订单状态机

六、可视化导出

七、常见使用场景

1. 订单 / 审批流转

2. 协议握手

3. 设备状态

4. 游戏角色

5. 工作流引擎

八、什么时候不该用状态机

九、go-fsm 的几个未来方向

十、设计反思

小结

Go 程序中 context 的职责与边界

写在前面

一、context 在解决什么问题

二、context 的接口

三、几种创建 context 的方式

1. 起点：Background / TODO

2. WithCancel：手动取消

3. WithTimeout / WithDeadline

4. WithValue：传请求级数据

四、context 的派生关系

五、典型用法

1. HTTP handler 透传

2. 整体超时

3. 传递 traceId

4. 数据库查询

5. 监听 Done

六、几个最常被踩的坑

1. 忘了 defer cancel

2. context.Background() 用错地方

3. 用 string 作 Value 的 key

4. 把 context 塞 struct 里

5. 用 context 传业务参数

6. 不监听 Done

七、context 在 RPC 框架里

八、什么不该用 context 传

Java：基于 `extends` 的边界

5. 顺手吐槽：`[]` 把泛型、map、切片三件事挤在一起

有些第三方库用 `pkg/errors`