跳转到内容

AIGoCode JSON 转 TypeScript 后怎么验收:从响应样本到类型交付清单

AIGoCode发布于 更新于

响应样本与类型结构逐项核对

生成了一份类型,先确认它对应哪份响应

你已经把 AIGoCode 的一次响应保存为 JSON,希望给前端或日志处理代码补上 TypeScript 类型。最容易漏掉的工作,是把“这份样本能生成类型”直接当作“所有返回都已覆盖”。

AIGoCode Tools 中的“JSON 转 TypeScript”按目录说明,可以根据 JSON 示例生成嵌套的 TypeScript 类型定义。下面关注生成之后如何人工核对和交付;这是建议的工程检查流程,不代表工具会自动找齐全部响应形态。

第一步:给样本写一张来源卡

把样本、生成结果和来源说明一起保存。来源卡建议记录协议、是否流式、取得样本的时间、用途和脱敏范围。只写模型名称不够:同一模型的两种接口或两种返回方式,可能需要分别整理。

用于分享的 JSON 应移除真实密钥、个人信息和业务正文。替换敏感值时,尽量保留原来的对象、数组层级与值的类型;如果某个字段被整体删除,在来源卡中注明,免得接手的人以为接口从来不返回它。工具目录也列出了敏感信息脱敏入口,处理后仍建议人工查看结果。

例如,来源卡可以写“Chat Completions,非流式,普通文本样本,业务文字已替换”。不要写“覆盖全部 Chat 返回”,除非你确实另有足够的协议依据和验收材料。

第二步:先列业务读取路径,再看生成结果

官方 Chat Completions 文档 说明,普通文本读取 choices[0].message.content,结束原因位于 finish_reason;工具调用按 tool_calls 处理,用量位于 usage。

建议先列出应用真正读取的路径,而不是直接接受整份生成结果:

应用要做的事应检查的材料验收问题
展示普通回复普通文本响应与读取代码类型中的对象、数组层级能否对应到实际读取路径?
记录结束原因响应中的结束字段代码读取的是哪一层字段,是否保留原值?
处理工具调用另有工具调用资料时单独核对是否误把普通文本样本当成完整的工具调用结构?
记录用量实际出现的 usage 样本样本未出现的字段,是尚未观察到,还是有文档明确说明?

只负责展示文字的组件,不必因为样本里出现许多字段就承诺处理全部内容。反过来,业务需要记录用量时,样本没有 usage 就应标记资料缺口,不能自己补一个看似合理的完整结构。

第三步:用人工对照表处理样本差异

先保存第一份生成结果,再收集已有的、合规可用的其他样本逐项对照。下面是一张建议的检查表,不是对该工具合并算法的说明,也不要求为了凑样本额外发起付费调用。

  • 字段只在一份样本出现:记录出现条件,回查文档或调用场景,再决定类型与读取代码如何处理缺失。
  • 字段出现空值:把空值和字段根本不存在分开记,不替接口推断两者永远等价。
  • 数组在样本里为空:记录“尚无元素样本”,不要凭空补出业务上期待的元素字段。
  • 多份样本的同名字段形态不同:先检查是不是混入另一协议、流式事件或错误响应,再考虑业务类型设计。

这里的目标是把未知项显露出来。如果暂时只有一份普通文本样本,就把交付范围限定为它,留下“工具调用结构待核对”等明确待办,优于给文件起一个暗示全量覆盖的名称。

第四步:把流式和非流式分开验收

官方文档给出的 Chat 流式处理方式,是从事件的 choices[].delta 读取新增内容,data: [DONE] 表示流结束。它还提醒,Responses 使用另一套事件结构。

因此,整理非流式 JSON 时,不要顺手把生成结果当成流式事件类型。建议为两者分别保留样本说明、类型文件和读取路径;如果当前只实现了非流式,就在交付记录中明示这一范围。响应取文字的基础问题可先参考本站三种响应结构解析指南,再回到本稿核对类型材料是否完整。

最后交付四样材料

建议交付脱敏样本、生成后经人工检查的类型、应用读取路径清单、尚未核实的差异表。让接手者能够沿着“样本—类型—读取代码”追溯,而不是只收到一份无法解释来源的文件。

项目若已有类型检查和响应处理测试,把这些材料放入现有验证流程;另行核对实际输入处理与错误分支,不能仅凭生成了一份类型就宣布接口验收完成。本文未进行新的 API 调用,也不把文档示例当成本次实测记录。