TypeScript 开发 AI Webhook 时 Node.js 怎么设计类型
我在用 Node.js 开发 AI Webhook 时，入参字段经常会随着模型能力变化而调整。TypeScript 里应该怎样设计请求体类型，既能限制必要字段，又能方便后续扩展？
用基础类型加可扩展结构来建模
可以把请求体拆成“固定字段”和“扩展字段”两部分来定义。固定字段用于描述 webhook 必须具备的核心信息，例如 event、timestamp、requestId、payload 等；扩展字段可以用索引签名、泛型或联合类型来承载不同 AI 场景的数据。这样做的好处是类型检查仍然清晰，同时不会把结构锁死。对于不同 webhook 事件，建议用 discriminated union 来区分，例如通过 event 字段映射不同 payload 类型，既能提升代码可读性，也能让编辑器获得更好的推断能力。
我的 webhook 可能返回任务已接收、模型处理中、执行成功、执行失败等多种结果。TypeScript 里该如何定义响应类型，避免业务代码里到处写 if 判断却还容易出错？
用结果枚举配合联合类型表达状态
可以把 webhook 响应建成一个状态驱动的联合类型。比如用 status 字段表示当前状态，success、processing、failed、accepted 分别对应不同的数据结构。每个状态下只暴露必要字段，这样调用方能够根据状态安全读取对应内容。对于失败场景，建议明确 errorCode、message、retryable 等字段，便于上层系统判断是否重试。若你的接口会被多个服务消费，也可以抽出通用响应基类，统一 traceId、requestId、timestamp 等信息，减少跨服务协作时的歧义。
接入不同 AI 平台后，它们的回调字段格式不一样，有的有签名，有的有事件类型，有的还有嵌套数据。Node.js 和 TypeScript 该怎么组织这些类型，才不会后期维护很痛苦？
按平台分层建模，再抽象公共部分
建议把第三方平台参数分成公共层和平台专属层。公共层包含所有 webhook 都会用到的信息，例如 headers、signature、eventId、receivedAt 等；平台专属层则分别定义不同供应商的 payload 类型。实现上可以用接口继承、交叉类型或泛型参数来表达差异。若项目需要支持多家平台，建议再加一层适配器，把外部原始结构转换成内部统一类型，这样业务代码只依赖内部模型，不必直接面对各个平台的字段差异。
Webhook 接收到的内容来自外部系统，字段可能缺失或格式不合法。除了运行时校验，TypeScript 在设计类型时还能提供哪些保护，降低线上问题？
把静态类型与运行时校验结合起来
TypeScript 只能在编译期约束结构，无法保证外部请求真实合法，所以需要把静态类型和运行时校验一起使用。做法是先定义清晰的接口或类型，再配合 zod、joi、class-validator 这类校验库把未知输入收敛成可信数据。校验通过后，再把结果赋值为已收窄的类型，这样后续逻辑就能在类型安全的前提下开发。对于 webhook 这类边界输入，建议把原始请求和解析后的业务对象分开管理，避免未经校验的数据直接进入核心处理逻辑。