给 AI 返回数据加 TS 类型,别全标 any

接 AI 接口最容易摆烂的地方:返回值全标 any,流式 chunk 也是 any,一路 data.choices[0].delta.content 点下去,点错一个字段运行时才炸。我们项目早期就这德行,后来花了点功夫把类型补上,踩了几个 TS 的坑,分享下。

先给流式 chunk 定结构

后端每条 SSE data 块的结构是固定的,先把它写成 interface:

interface StreamChunk {
  id: string
  choices: {
    delta: { content?: string; role?: string }
    finish_reason: string | null
  }[]
}

注意 content 是可选的------流式里有的 chunk 只有 role 没有 content(开头那条),有的只有 finish_reason(结尾那条)。不标可选,解析时类型对不上。

parse 后别直接信

JSON.parse 的返回是 any,直接 as StreamChunk 是自欺欺人------后端真返回个歪结构,类型系统照样放行,运行时照炸。要么用 zod 这类做运行时校验,要么至少加个手写守卫:

function isChunk(x: unknown): x is StreamChunk {
  return typeof x === 'object' && x !== null && 'choices' in x
}

类型断言只是骗编译器,运行时校验才是真兜底。这俩别混为一谈。

AI 返回结构化数据更要类型

让 AI 返回 JSON(比如抽取出的字段),这种最坑。AI 偶尔会少个字段、或把数字返回成字符串。我给这种返回定了类型,但所有字段都标成可选 + 有兜底默认值,渲染时容错:

interface Extracted {
  name?: string
  amount?: number // AI 可能返回 "100" 字符串,得自己转
}

别假设 AI 一定按你给的 schema 返回,它就是会偶尔抽风。

给 hook 也标好类型

封装的 useChat 之类的 hook,入参、返回的 messages、状态机的 status,全标上字面量联合类型:

type Status = 'idle' | 'streaming' | 'error'

status 标成 'idle' | 'streaming' | 'error' 而不是 string,后面 switch 漏个分支编译器会提醒,省了很多低级 bug。

一个偷懒处

后端接口我没有用工具从 OpenAPI 自动生成类型,是手写的 interface。后端字段一改,前端类型不会自动同步,得手动跟。有 schema 的话最好自动生成,我们这块流程还没搭。

接口背后的模型走讯飞 MaaS,返回格式稳定,前端把类型这层焊牢,联调时少很多扯皮。你们怎么给 AI 返回做类型安全,聊聊。