JSON解析错误：cannot unmarshal string into struct field

Question

在Go语言开发中，常遇到“JSON解析错误：cannot unmarshal string into struct field”问题。典型场景是API接收到的JSON字段为字符串类型（如 `"age": "25"`），但对应结构体字段定义为整型（`Age int`）。JSON反序列化时，Go无法将字符串自动转换为整数，导致解析失败。此问题多见于前端传参未规范类型或后端结构体定义与实际数据不匹配。解决方法包括：修改结构体字段类型为`string`后手动转换，使用`json.Unmarshaler`接口自定义解析逻辑，或确保上下游数据格式一致。建议通过单元测试验证JSON映射正确性，避免运行时错误。

Answer 1

1. 问题背景与典型场景分析

在Go语言开发中，JSON解析是API交互的核心环节。当后端服务接收前端或其他微服务传来的JSON数据时，常因类型不匹配导致反序列化失败，典型错误信息为：cannot unmarshal string into struct field。例如，接收到的JSON数据为 {"age": "25"}，而后端结构体定义为：

type User struct {
    Age int `json:"age"`
}

此时，Go标准库 encoding/json 无法将字符串 "25" 自动转换为整型 int，从而抛出解析异常。该问题常见于以下场景：

• 前端使用JavaScript发送请求，数字被意外序列化为字符串（如表单输入未做类型转换）
• 第三方接口返回数据格式不规范
• 历史遗留系统数据兼容性问题
• 测试数据与生产环境不一致

2. 常见解决方案对比

方案	实现方式	优点	缺点
字段改为string后手动转换	Age string → 转换时调用 strconv.Atoi	简单直接，易于理解	需额外处理，代码冗余
实现 json.Unmarshaler 接口	自定义 UnmarshalJSON 方法	类型安全，复用性强	实现复杂度略高
使用第三方库（如 ffjson、easyjson）	生成高效解析代码	性能高，支持灵活映射	增加依赖，学习成本
统一上下游数据格式	通过文档或Schema约束	根治问题，提升协作效率	跨团队协调难度大

3. 深入技术实现路径

以实现 json.Unmarshaler 接口为例，可构建具备容错能力的整型字段解析。以下为支持字符串转整数的自定义类型：

type FlexibleInt int

func (f *FlexibleInt) UnmarshalJSON(data []byte) error {
    var str string
    if err := json.Unmarshal(data, &str); err == nil {
        val, err := strconv.Atoi(str)
        if err != nil {
            return err
        }
        *f = FlexibleInt(val)
        return nil
    }

    var num int
    if err := json.Unmarshal(data, &num); err != nil {
        return err
    }
    *f = FlexibleInt(num)
    return nil
}

// 使用示例
type User struct {
    Age FlexibleInt `json:"age"`
}

该方法允许字段同时接受 "25" 和 25 两种格式，显著增强API鲁棒性。

4. 架构层面的预防机制

为避免此类问题反复出现，建议从架构设计角度建立防御体系。以下为基于CI/CD流程的数据契约验证流程图：

graph TD
    A[前端提交JSON数据] -- HTTP Request --> B(API Gateway)
    B --> C{Data Type Check}
    C -- Match Schema? --> D[Go Service 反序列化]
    C -- Not Match --> E[Reject with 400 Error]
    D --> F[Business Logic]
    F --> G[Response]
    H[Unit Test] --> C
    I[OpenAPI Spec] --> H

通过集成 OpenAPI/Swagger 规范，可在测试阶段提前发现类型不一致问题。同时，在CI流水线中加入自动化测试脚本，模拟多种输入类型组合，确保反序列化逻辑稳定。

5. 单元测试实践示例

编写覆盖多种输入情况的测试用例，是保障解析逻辑正确性的关键手段。以下为针对 FlexibleInt 的测试代码：

func TestFlexibleInt_UnmarshalJSON(t *testing.T) {
    tests := []struct {
        name string
        json string
        want int
        err  bool
    }{
        {"integer input", `{"age": 25}`, 25, false},
        {"string input", `{"age": "30"}`, 30, false},
        {"invalid string", `{"age": "abc"}`, 0, true},
        {"null value", `{"age": null}`, 0, true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            var u struct{ Age FlexibleInt }
            err := json.Unmarshal([]byte(tt.json), &u)
            if (err != nil) != tt.err {
                t.Errorf("expected error: %v, got: %v", tt.err, err)
            }
            if int(u.Age) != tt.want && !tt.err {
                t.Errorf("expected age: %d, got: %d", tt.want, u.Age)
            }
        })
    }
}

该测试集覆盖了正常整数、字符串数字、非法输入等边界情况，有效防止运行时崩溃。