AI 流式输出如何避免半截 JSON：Go 逐块解析与字段完整性检查

AI 接口改成流式返回后，最容易出现的不是网络断开，而是把每个数据块都当成完整 JSON 去解码。一个对象可能被拆在两个 chunk 中，第一块只有半个字符串，第二块才补上结束引号；此时逐块调用 json.Unmarshal，得到的只是“输入未完整”，不是业务字段真的缺失。

半截 JSON 的问题现场：chunk 并不等于对象

假设上游把一个工具结果分成两个块：第一块是 {"answer":"Go 流式，第二块才是 输出","done":true}。网络层认为这两块都已成功到达，但 JSON 层只能在第二块拼入后才看到完整字符串。

chunks := []string{
    `{"answer":"Go 流式`,
    `输出","done":true}`,
}

for _, chunk := range chunks {
    var item map[string]any
    if err := json.Unmarshal([]byte(chunk), &item); err != nil {
        fmt.Println(err)
    }
}

第一轮报错并不说明响应格式错了。真正的问题是 chunk 还没有形成完整值，直接交给 json.Unmarshal 会把传输边界误当成语法边界。

最小修复：把分片先放进 buffer

修复思路很小：每次收到 chunk 就追加到 buffer，然后尝试从缓冲区读取一个完整 JSON 值。读取失败时保留原内容，继续等待下一个 chunk；读取成功后才删除已经消费的字节。

type StreamItem struct {
    Answer string `json:"answer"`
    Done   bool   `json:"done"`
}

func decodeStream(chunks []string) ([]StreamItem, error) {
    var buffer bytes.Buffer
    var items []StreamItem

    for _, chunk := range chunks {
        buffer.WriteString(chunk)
        decoder := json.NewDecoder(&buffer)

        for buffer.Len() > 0 {
            var item StreamItem
            if err := decoder.Decode(&item); err != nil {
                if errors.Is(err, io.EOF) {
                    break
                }
                return nil, err
            }
            items = append(items, item)
        }
    }
    return items, nil
}

示例的重点是“失败时不丢缓冲区”。生产实现还需要记录消费位置，避免重复创建解码器时把已消费内容再次送入解析器；如果协议是一行一个 JSON，则可以先按换行边界切分，再对完整行调用 json.Unmarshal，边界会更容易审计。

字段完整性检查要等到 done 之后

流式对象解析成功，只能说明 JSON 语法完整，不代表 AI 结果满足业务合同。每个 event 先进入 decode，比如 answer 是必填字段，done 表示上游已经结束；二者的判断顺序应清晰地写在代码里。

func validate(item StreamItem) error {
    if item.Answer == "" {
        return errors.New("required field answer is empty")
    }
    if !item.Done {
        return nil
    }
    return nil
}

不要在每个网络块到达时就把当前对象写入最终答案。只有 decode 成功、required 字段通过，并且收到 done 事件，才把状态置为完成。若流在中间断开，则保存已收到的片段并返回可重试的 incomplete，而不是伪造完整回答。

结束事件、残留字节和重复消费

最后一块数据到达并不自动保证缓冲区为空。可以把 done 当作协议层结束信号，再检查是否存在无法解码的残留字节。残留内容可能是截断的 JSON，也可能是协议分隔符没有清理。

用四组输入复查解析器

1. 把完整 JSON 放进一个 chunk，确认一次 decode 即可得到 done=true。
2. 把字符串、转义符和 Unicode 字符分别切在两个 chunk 之间，确认 buffer 能等待拼接。
3. 在收到半截对象后直接结束流，确认返回 incomplete 而不是空对象。
4. 追加一个缺少 answer 的完整对象，确认 required 检查失败且不会进入完成状态。

测试日志至少打印 chunk 序号、buffer 剩余长度、decode 结果和最终状态。不要打印用户原文或密钥样文本；需要排查时记录长度、哈希或脱敏后的字段即可。

相关问题

为什么不用每个 chunk 都调用 json.Unmarshal？

因为传输分片没有 JSON 语义。一个字符串、数组或对象都可能跨越多个 chunk，逐块解码会把正常的半截输入误判为格式错误。

json.Decoder 遇到半截输入会不会丢数据？

只要底层读取源和缓冲区没有被错误重置，遇到未完成值时应继续保留输入。实现中要明确消费位置，避免重新绑定 reader 后重复读取或丢掉未消费字节。

收到 done 就一定能提交答案吗？

不一定。还要确认最后一个对象已完整 decode、必填字段通过，并且缓冲区没有残留的截断内容。

把“流结束”与“结果可用”分开

流式解析的验收标准不是“收到了几块数据”，而是 buffer 最终被完整消费，decode 得到合法对象，required 字段通过，最后才由 done 推进到完成状态。把这几件事拆开后，半截 JSON、提前断流和缺字段都会有自己的错误路径，重试也不会误把不完整结果当成成功。