异步API设计Skill asyncapi-design

---

名称: asyncapi-design 描述: 使用AsyncAPI 3.0为基于消息的架构设计事件驱动API规范 允许工具: Read, Glob, Grep, Write, Edit, mcp__perplexity__search, mcp__context7__resolve-library-id, mcp__context7__query-docs

AsyncAPI设计技能

何时使用此技能

使用此技能当：

• 设计事件驱动API - 使用AsyncAPI 3.0为基于消息的架构
• 配置消息代理 - Kafka、RabbitMQ、MQTT、WebSocket绑定
• 在C#中实现 - 事件契约、MassTransit、Confluent Kafka
• 事件版本控制 - 架构演进和向后兼容性

强制：文档优先方法

在创建AsyncAPI规范之前：

1. 调用docs-management技能 用于事件驱动模式
2. 通过MCP服务器验证AsyncAPI 3.0语法（使用context7获取最新规范）
3. 所有指导基于AsyncAPI 3.0规范

AsyncAPI vs OpenAPI

方面	OpenAPI	AsyncAPI
通信	请求/响应	事件驱动
协议	HTTP/HTTPS	Kafka、RabbitMQ、MQTT、WebSocket
发起者	客户端请求	发布者发出
模式	同步	异步
用例	REST API	消息队列、流处理、物联网

AsyncAPI 3.0结构概述

asyncapi: 3.0.0
info:
  title: API标题
  version: 1.0.0

servers:
  production:
    host: kafka.example.com:9092
    protocol: kafka

channels:
  orderCreated:
    address: orders.created
    messages:
      orderCreatedMessage:
        $ref: '#/components/messages/OrderCreated'

operations:
  publishOrderCreated:
    action: send
    channel:
      $ref: '#/channels/orderCreated'

components:
  messages: { }
  schemas: { }
  securitySchemes: { }

完整模板：参见basic-template.md

快速参考

支持协议

协议	用例	绑定版本
Kafka	高吞吐量流处理	0.5.0
AMQP（RabbitMQ）	消息队列	0.3.0
MQTT	物联网、轻量级消息	0.2.0
WebSocket	实时浏览器通信	-

协议特定模式：参见protocol-patterns.md

通道命名约定

{域}.{实体}.{动作}.{版本}
示例: orders.order.created.v1

工作流程

1. 识别事件 - 需要通信哪些重要发生？
2. 定义通道 - 哪些主题/队列将携带这些事件？
3. 设计消息 - 每个事件包含什么数据？
4. 选择协议 - Kafka、RabbitMQ、MQTT等？
5. 添加绑定 - 协议特定配置
6. 文档化安全 - 认证和授权
7. 版本策略 - 事件将如何演进？
8. 生成代码 - 使用AsyncAPI生成器用于客户端/处理程序

参考

根据需要加载：

参考	加载时机
basic-template.md	从零创建新AsyncAPI规范
protocol-patterns.md	配置Kafka、RabbitMQ、MQTT、WebSocket
csharp-implementation.md	在.NET/C#中实现，使用MassTransit或Confluent
event-design-patterns.md	事件信封、版本控制、最佳实践

相关技能（跨插件）

阶段	技能	插件	目的
设计	asyncapi-design（此技能）	formal-specification	架构研究、模式选择
创作	asyncapi-authoring	spec-driven-development	具体YAML文件创建

工作流程：设计（研究事件模式）→ 创作（创建YAML）→ 实现（生成代码）

MCP研究

对于当前AsyncAPI模式和工具：

perplexity: "AsyncAPI 3.0规范" "事件驱动API设计模式"
context7: "asyncapi"（用于官方文档）
ref: "AsyncAPI规范示例" "Kafka绑定模式"

版本历史

• v2.0.0 (2026-01-17): 重构为渐进披露模式
  • 提取4个参考文件（约650行）
  • 中心从789行减少到约130行
• v1.0.0 (2025-12-26): 初始发布

---

最后更新: 2026-01-17