Golang枚举JSON序列化技巧

在 Go 中，iota 枚举本质是整数，JSON 默认序列化为数字而非语义化的字符串（如 "pending"），极易导致前后端协作混乱；要实现优雅的字符串序列化，必须为自定义枚举类型同时实现 `json.Marshaler` 和（关键！）带指针接收者的 `json.Unmarshaler`，配合双向映射表处理字符串与值的转换，并严格测试未知值场景——手写虽轻量可控，生成工具可降维护成本，但无论哪种方式，绕过类型安全用 string 模拟枚举或忽略指针接收者、遗漏错误处理，都会在生产环境中埋下状态误判的隐患。

Go 的 iota 枚举默认序列化为数字，不是字符串名

Go 本身没有原生枚举类型，iota 只是常量生成器，定义出来的值本质是整数。所以直接用 json.Marshal 序列化结构体字段时，它只会输出数字，比如 0、1，而不是你期望的 "pending" 或 "done"。

让枚举在 JSON 中显示为字符串：必须实现 json.Marshaler 和 json.Unmarshaler

Go 的 encoding/json 包会自动调用类型实现的 MarshalJSON() 和 UnmarshalJSON() 方法。不实现，就走默认整数逻辑；实现了，才能控制输出格式。

常见错误现象：
– 字段值是 TaskStatus(0)，但 JSON 输出 {"status":0}，前端看不懂
– 实现了 MarshalJSON 却没实现 UnmarshalJSON，反序列化失败报 json: cannot unmarshal string into Go value of type TaskStatus

实操建议：

• 定义枚举类型为自定义命名类型，比如 type TaskStatus int，不能直接用 int
• 为该类型实现 func (s TaskStatus) MarshalJSON() ([]byte, error)，返回字符串字面量的 JSON 字节（注意加双引号）
• 同时实现 func (s *TaskStatus) UnmarshalJSON(data []byte) error，从字符串解析回对应值，失败时要返回具体错误（比如未知字符串）
• 所有枚举值需有对应字符串映射，建议用 map[TaskStatus]string 和 map[string]TaskStatus 两个查找表，避免 switch 冗长且易漏

示例关键片段：

type TaskStatus int

const (
	Pending TaskStatus = iota
	Done
	Cancelled
)

var taskStatusNames = map[TaskStatus]string{
	Pending:   "pending",
	Done:      "done",
	Cancelled: "cancelled",
}

var taskStatusValues = map[string]TaskStatus{
	"pending":   Pending,
	"done":      Done,
	"cancelled": Cancelled,
}

func (s TaskStatus) MarshalJSON() ([]byte, error) {
	if name, ok := taskStatusNames[s]; ok {
		return json.Marshal(name)
	}
	return nil, fmt.Errorf("unknown TaskStatus %d", s)
}

func (s *TaskStatus) UnmarshalJSON(data []byte) error {
	var name string
	if err := json.Unmarshal(data, &name); err != nil {
		return err
	}
	if v, ok := taskStatusValues[name]; ok {
		*s = v
		return nil
	}
	return fmt.Errorf("unknown TaskStatus name %q", name)
}

注意 json.RawMessage 或嵌套结构里别漏掉指针接收者

如果枚举字段是结构体中非导出字段、或嵌套在 json.RawMessage 后再解包，容易因接收者类型不匹配导致 UnmarshalJSON 不被调用——必须用指针接收者（*TaskStatus），否则传值时修改的是副本，原字段不变。

另一个坑：json.Unmarshal 对 nil 指针字段不会自动分配内存，所以结构体字段声明成 TaskStatus（值类型）比 *TaskStatus（指针）更稳妥，除非你明确需要区分零值和未设置。

第三方库如 go-enum 能省事，但会引入额外依赖和生成代码

如果你项目允许代码生成，go-enum 可以基于注释自动生成 MarshalJSON/UnmarshalJSON，减少手写样板。但它要求你把枚举定义在单独文件、加特殊注释，且生成的代码得进 Git（否则 CI 可能失败）。

权衡点：

• 小项目或枚举极少：手写两方法更轻量、可控、无隐藏行为
• 中大型项目、枚举多且频繁变更：生成方案长期看更少出错，但得接受构建流程变重
• 别用 string 类型模拟枚举（比如 type Status string），虽然序列化方便，但失去类型安全和 switch 枚举穷尽检查能力

最常被忽略的一点：测试一定要覆盖未知字符串的反序列化路径，比如传 "unknown" 进去，看是否真返回错误，而不是静默转成零值——这在生产环境会导致状态误判。

好了，本文到此结束，带大家了解了《Golang枚举JSON序列化技巧》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！