AsyncAPI：事件驱动架构的 API 描述

yaml asyncapi: '2.6.0' info: title: 用户事件服务 version: '1.0.0' description: 处理用户注册相关的事件通知

servers: production: url: 'kafka.mycompany.com:9092' protocol: kafka description: 生产环境Kafka集群

channels: user/signedup: description: 当用户成功注册时，向此通道发送事件 publish: operationId: onUserSignUp summary: 通知其他服务有用户注册 message: name: UserSignedUp contentType: application/json payload: type: object properties: userId: type: string description: 用户唯一标识 email: type: string format: email registeredAt: type: string format: date-time required: - userId - email

在这个例子中：

- 我们定义了一个服务器（Kafka 集群）和一个通道 `user/signedup`。
- 通道上定义了 `publish` 操作，表示事件的生产方会向这里发送消息。
- 消息负载（payload）是一个 JSON 对象，包含 `userId`、`email` 和 `registeredAt` 字段，其中前两者为必填。

这份文件就可以被各种 AsyncAPI 工具解析，生成文档门户、代码或模拟服务。

## 如何开始使用 AsyncAPI？

### 第一步：安装工具

- 使用 **AsyncAPI CLI** 来校验、生成 HTML 文档或代码。
```bash
npm install -g @asyncapi/cli

• 验证你的 AsyncAPI 文件：

asyncapi validate myfile.yaml

第二步：在线编辑与预览

访问 AsyncAPI Studio，可以直接在浏览器中编写 YAML/JSON 文件，并能实时看到格式化文档和消息示例。

第三步：从现有系统生成文档

如果你已经有 Kafka 集群或消息代理，可以使用 EventCatalog 或通过代码注解配合生成器来创建 AsyncAPI 文件，减少手动编写工作量。

第四步：生成代码和微服务骨架

AsyncAPI 社区提供了大量的代码生成模板，支持 Node.js、Java、Python、Go 等多种语言。例如，为上述文件生成一个 Node.js 的 Kafka 消费者：

asyncapi generate fromTemplate myfile.yaml @asyncapi/nodejs-kafka-template -o ./output