技能介绍

要解决的问题

在 Kafka 技术栈里，Avro / Protobuf 的 schema 通常集中在 Confluent Schema Registry 中，但消费端和生产端的代码里往往各自手写了一份对应的类型定义。时间一长，两份定义就开始漂移：字段改了名，代码里的 TypeScript interface 仍然是旧结构；某个字段从可选变成必填，两端的编解码结果出现偏差，往往要到联调甚至线上才暴露出来。

文档的处境同样尴尬。subject 才是权威来源，但能准确说出某个 subject 当前包含哪些字段的人通常很少。手工维护的契约文档要么过期，要么只覆盖了部分 topic。

技能如何工作

这个技能不引入额外的元数据仓库，直接把 Schema Registry 的 REST API 当作输入，从已注册的 subject 出发产出三份产物：

TypeScript 接口：把 schema 中的 record、enum、union 结构转成可以直接放进项目的 interface，嵌套字段保留原有层级关系
JSON Schema：输出与 schema 结构对应的 JSON Schema 描述，便于做校验或与其他工具链对接
数据契约文档：把字段含义、类型和变更情况整理成可读的契约说明，而不是散落在代码注释里

整个处理过程只依赖 REST 接口本身，不需要额外的代理或本地缓存层。

适用边界与注意点

依赖 Schema Registry 的 REST 能力：schema 必须已经正确注册并存在对应 subject，技能不会替用户创建或推断 schema
上游客户端要求：上游依赖现代的 Node.js Kafka 客户端，兼容 Kafka 0.10+，并对 0.11 的特性提供原生支持
union 与默认值：Avro 的 union 和默认值在不同客户端实现里语义并不完全一致，生成的类型建议结合项目实际使用的编码器复核一遍
只负责生成：技能产出的是类型和文档，schema 的演进策略与兼容性检查仍然需要团队自己的流程来保证

截图预览

使用场景

新建 Kafka 消费服务时，从 Schema Registry 拉取已注册的 Avro schema，快速生成对应的 TypeScript 接口用于消息解析。
前后端或多端联调时，从注册表提取 subject 的字段结构，生成 JSON Schema 作为各端消息解析的统一契约基准。
梳理 topic 的数据契约文档时，直接通过 REST API 提取指定 subject 的 schema 信息，输出可读的字段说明文档。