AsyncAPI 是什么
AsyncAPI 是描述事件驱动接口的规范，定位相当于异步世界的 OpenAPI：用 channels 描述消息通道（Kafka 主题、消息队列等），用 operations 描述发布与订阅动作，用 messages 与载荷结构描述消息内容与格式。它把「谁在哪个通道发布什么、谁订阅什么」写成机器可读的契约，从而支撑文档生成、代码生成、结构校验与变更评审。
契约里都写了什么
服务段声明可连接的中间件地址与协议，通道段声明主题或队列名，操作段指明该通道上是发布还是订阅，消息段描述载荷结构并引用组件中的结构定义，绑定段承载中间件特有参数，例如分区键、消费组与服务质量等级。评审时把这几段与线上实际配置逐项对照，能在接入前发现命名不符、权限缺失与协议不匹配的问题，而不是等消息收不到时再去查。
基本信息
| 顶层结构 | 版本、描述信息、服务、通道、操作、组件六段 |
|---|---|
| 核心概念 | 发布与订阅操作绑定到通道，消息引用组件中的结构定义 |
| 常见载体 | Kafka、MQTT、AMQP、WebSocket、NATS，由协议字段声明 |
| 配套生态 | 文档渲染工具、代码生成模板，以及与结构注册中心的衔接 |
与 OpenAPI 的分工
| 维度 | OpenAPI | AsyncAPI |
|---|---|---|
| 交互模型 | 请求与响应 | 发布与订阅 |
| 一等概念 | 路径与操作 | 通道与消息 |
| 契约消费方 | 调用方为主 | 生产者与消费者双向 |
| 典型载体 | 同步接口 | 消息主题与队列 |
| 变更影响面 | 按接口评估 | 按主题与订阅方评估 |
典型使用场景
- 事件契约进入设计评审与流水线校验，避免字段被随意改动
- 由契约生成生产者与消费者骨架代码、接口文档与联调桩
- 梳理某个主题的订阅方清单，评估一次字段变更的影响面
- 与结构注册中心配合，把兼容性检查落到流水线卡点上
事件契约最难的部分是消费者识别：生产者往往不清楚谁订阅了，上线前要维护订阅方清单，废弃事件需逐个通知到团队并约定过渡期。
消息载荷要带版本标识或采用兼容演进策略（只增字段、不改既有语义），否则消费者无法判断该按哪套规则解析，一次字段调整就可能静默打挂下游。