本文详解 Go 语言中 json.Unmarshal 报错 “cannot unmarshal number into Go value of type string” 的根本原因及解决方案，涵盖结构体标签优化、类型一致性检查、自定义反序列化等实用技巧。
本文详解 go 语言中 `json.unmarshal` 报错 “cannot unmarshal number into go value of type string” 的根本原因及解决方案，涵盖结构体标签优化、类型一致性检查、自定义反序列化等实用技巧。
该错误是 Go 标准库 encoding/json 在反序列化时最典型的类型冲突之一：当 JSON 数据中某字段为数字（如 123 或 3.14），而 Go 结构体中对应字段声明为 string 类型时，json.Unmarshal 会直接报错并终止解析，不会尝试隐式转换——Go 的 JSON 解析器严格遵循类型契约，拒绝“猜测式”类型适配。
? 错误复现与根源分析
以常见场景为例：API 返回如下 JSON：
{
"id": 1001,
"name": "product-a",
"price": 29.99
}若定义结构体如下，则必然触发错误：
type Product struct {
ID string `json:"id"`
Name string `json:"name"`
Price string `json:"price"`
}尽管 id 和 price 在业务中可能被当作标识符或格式化显示值，但 JSON 中它们是数字字面量，Go 不允许自动转为字符串。
立即学习“go语言免费学习笔记（深入）”；
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
✅ 正确解决方案
方案一：修正字段类型（推荐）
根据实际语义选择合适类型：
- id 若为纯数字 ID（如数据库主键），应使用 int64 或 uint；
- price 应使用 float64 或更精确的 decimal.Decimal（需第三方库）；
- 仅当字段始终以字符串形式传输（如 "id": "1001"）时才用 string。
type Product struct {
ID int64 `json:"id"`
Name string `json:"name"`
Price float64 `json:"price"`
}方案二：使用 json.RawMessage 延迟解析
适用于字段类型不确定或需动态处理的场景：
type Product struct {
ID json.RawMessage `json:"id"`
Name string `json:"name"`
Price json.RawMessage `json:"price"`
}
// 后续按需解析
var idStr string
if err := json.Unmarshal(p.ID, &idStr); err != nil {
// 尝试解析为 int64...
}方案三：实现自定义 UnmarshalJSON 方法
当必须将数字转为字符串（如兼容旧版 API），可为字段类型添加反序列化逻辑：
type StringNumber string
func (s *StringNumber) UnmarshalJSON(data []byte) error {
// 先尝试解析为字符串
var str string
if err := json.Unmarshal(data, &str); err == nil {
*s = StringNumber(str)
return nil
}
// 再尝试解析为数字并转字符串
var num json.Number
if err := json.Unmarshal(data, &num); err == nil {
*s = StringNumber(num.String())
return nil
}
return fmt.Errorf("cannot unmarshal %s into StringNumber", string(data))
}
type Product struct {
ID StringNumber `json:"id"`
Name string `json:"name"`
Price StringNumber `json:"price"`
}⚠️ 注意事项
- 避免滥用 interface{}：虽能绕过类型检查，但丧失编译期安全与可读性；
- 检查 JSON Schema：与后端约定字段类型，必要时推动接口标准化；
- 启用 json.Decoder.DisallowUnknownFields()：提前捕获字段名/类型不匹配问题；
- 测试边界数据：包括 null、负数、科学计数法（如 1e5）等，确保鲁棒性。
通过合理设计结构体类型、善用标准库机制或按需扩展反序列化逻辑，即可彻底规避此类错误，构建健壮可靠的 JSON 数据处理流程。
