[!info] 关联笔记

• 所属 MOC：语言基础 · 类型与抽象 · 学习路线
• 前置概念：基本类型、变量常量与零值
• 后续概念：类型别名与定义、struct 与方法
• 相关：[[go-stringer|stringer]]（若有）、go:generate

Go iota 与枚举

这个概念为什么会出现

状态机、错误码、权限位、星期……需要一组相关命名常量。许多语言有 enum 关键字；Go 选择更小的机制：

• const 组
• 预声明标识符 iota
• 自定义类型区分“颜色”和“随便一个 int”

这避免了复杂枚举运行时，却把“类型安全 + 可读字符串 + 稳定数值”交给约定与工具。

[!abstract] 一句话理解 iota 在每个 const 声明块里从 0 递增，用于生成相关常量序列；枚举是“命名类型 + iota 常量 + 行为方法”的惯用模式，不是内置枚举类型。

最小可运行示例

先把示例放进业务场景，再看代码：

场景：工单系统的优先级枚举

客服工单有三级优先级：Low / Medium / High。
用自定义类型 TicketPriority + iota 生成稳定序号；
实现 String() 让日志和 API 响应打印 medium 而不是裸 1。

package main

import "fmt"

// TicketPriority 是工单优先级（定义类型，不是裸 int）。
// 业务意图：函数参数写成 TicketPriority，避免和别的 int 状态码混用。
// 教学点：枚举 = 命名类型 + const/iota + 行为方法，不是语言内置 enum。
type TicketPriority int

const (
	// iota 在本 const 块从 0 起，每行 +1。
	PriorityLow TicketPriority = iota // 0
	PriorityMedium                      // 1
	PriorityHigh                        // 2
)

// String 让 fmt 与日志输出可读名称。
// 业务意图：工单列表/告警里直接显示 medium，而不是数字。
// 教学点：实现 fmt.Stringer；未知值要有 default，防止静默空白。
func (p TicketPriority) String() string {
	switch p {
	case PriorityLow:
		return "low"
	case PriorityMedium:
		return "medium"
	case PriorityHigh:
		return "high"
	default:
		return fmt.Sprintf("TicketPriority(%d)", int(p))
	}
}

// routeTicket 模拟按优先级分流。
func routeTicket(p TicketPriority) {
	fmt.Println("route:", p, "code:", int(p))
}

func main() {
	// 业务：新建一条中优先级工单。
	var p TicketPriority = PriorityMedium
	routeTicket(p) // medium 1
}

建议运行：

go run .

期望输出：

route: medium code: 1

结合场景再看三个关注点

1. iota 只在 const 块里自增
   本块 Low=0, Medium=1, High=2；新开一个 const 块会重新从 0 计。

2. 定义类型提供弱枚举边界
   TicketPriority 与 int 不同名，减少和错误码、HTTP status 混用。

3. String() 是工程必备
   日志、测试失败信息、简易 API 都更可读；未知值要有 default 兜底。

核心概念与准确模型

iota 规则

依据 Spec — Iota：

1. 仅在 const 声明中有意义
2. 每个 const 块重置为 0
3. 块内每遇到一个 const spec（一行声明）自增 1
4. 可出现在表达式：1 << iota、iota + 1
5. 隐式重复上一表达式（省略 RHS 时）

const (
	a = iota      // 0
	b             // 1
	c = 1 << iota // 4  （此时 iota 已是 2）
	d             // 8
)

一行多标识符

const (
	x, y = iota, iota // 0, 0 —— 同一 spec 共享同一 iota
)

跳过与偏移

const (
	_ = iota // 跳过 0
	One
	Two
)

const (
	StatusOK Color = iota + 1 // 从 1 起
	StatusFail
)

自定义类型 vs 别名

type Status int     // 定义：新类型
type Status = int   // 别名：不是枚举隔离

枚举要用类型定义才能在 API 上区分 UserID/Status。见 go-type-aliases-and-definitions。

位标志

type Flag uint

const (
	FlagRead Flag = 1 << iota
	FlagWrite
	FlagExec
)

func (f Flag) Has(h Flag) bool { return f&h != 0 }

组合：FlagRead | FlagWrite。注意与“互斥枚举”语义不同。

Stringer 与 generate

手写 String 易漏；官方工具：

//go:generate stringer -type=Color

见 stringer 与 go generate。

零值

var s Status 为 0。设计枚举时要么让 0 有意义（Unknown/Unspecified），要么文档强制显式初始化，避免静默零值当合法业务态。

边界情况

1. 数值当协议：对外 API 改 iota 顺序即破坏兼容；应用稳定字符串或显式赋值。
2. 非连续 iota 插入：中间加常量会改变后续值。
3. JSON：默认编成数字；常需自定义 MarshalText/UnmarshalText。
4. 穷尽性：switch 无编译期穷尽检查，default 要处理非法值。
5. 跨包重复 iota 块：每块独立从 0 计，不全局递增。

常见误区

[!warning] 常见误区：Go 有 enum 关键字 错误：找 enum Color { ... }。
正确：类型 + const + 方法的惯用法。

[!warning] 常见误区：iota 在函数里用 错误：for { x := iota }。
正确：只在 const 声明。

[!warning] 常见误区：用别名当枚举 错误：type Status = int 期望类型安全。
正确：type Status int。

[!warning] 常见误区：重排常量不改协议文档 错误：插入新状态导致线上旧数字语义漂移。
正确：持久化用稳定值或字符串枚举。

工程实践

1. 导出枚举类型与合法常量，校验函数 func (s Status) Valid() bool。
2. 0 值显式命名 Unknown = iota。
3. 外部格式用字符串，内部可用 int。
4. stringer 或手工 String 统一日志。
5. 不要用 iota 生成“需要密码学稳定”的 ID。
6. 测试非法值路径。
7. 位标志与枚举分类型，避免同一类型混用两种语义。

可验证实验

实验 1：块重置

两个 const 块各用 iota，确认都从 0 起。

实验 2：位移

打印 1 << iota 序列。

实验 3：类型不兼容

func f(c Color) 传入 int(1) 应编译失败。

实验 4：JSON

默认 json.Marshal(Green) 输出数字；实现 MarshalText 后输出字符串。

实验 5：stringer

go generate 后确认 String() 生成文件。

本节总结

• 本质：iota 是 const 块计数器；枚举是约定模式。
• 关键规则：块内递增、表达式可用、类型定义隔离、零值与稳定性。
• 最易错：当真正 enum、重排破坏协议、别名伪安全。
• 下一步：go-type-aliases-and-definitions；方法与 String 见 go-structs-and-methods。

自测题

概念题

1. iota 在何处重置为 0？
2. 为什么枚举常用自定义类型？
3. 位标志为何用 1 << iota？

代码推理题

const (
	a = iota
	b = 3
	c
)

c 是多少？

工程思考题

gRPC/JSON 公共 API 应暴露数字枚举还是字符串？如何兼容？

参考答案

展开

1. 每个 const 声明块开始。
2. 与底层 int 区分，防止混用；可挂方法。
3. 生成互不重叠的 2 幂，便于 OR/AND。
   代码题：c 为 3——省略 RHS 时重复上一表达式 3（iota 仍递增但不出现在该表达式）。若上一行是含 iota 的表达式则不同；此处 b=3 无 iota，c 亦为 3。
   工程题：字符串更稳；或 protobuf enum 显式编号；版本化与 Unknown 处理。

延伸阅读与资料来源

资料	类型	支撑
Spec — Iota	规范	精确语义
Spec — Constant declarations	规范	隐式重复
Effective Go — Constants	文档	iota 示例
stringer	工具	String 生成
Generate	博客	go:generate

---

笔记元信息

• 建议文件名：go-iota-and-enums.md
• 所属阶段：语言基础 / 类型
• 建议下一篇：类型别名与定义
• 本篇状态：已深化