AsyncAPI v3.0 有什么新功能？

所有接口都是 API，无论是 RESTful、RPC、基于消息还是其他，这一理念多年来一直是 API 经济中公认的一部分。在消息传递领域，这一点再正确不过了。在此背景下，自 2016 年创建以来，AsyncAPI 已成为该领域的一个重要特征。

对于初学者来说，AsyncAPI是一种面向消息通信的 API 规范语言。它的结构和语法与OpenAPI非常相似，但它实现了自己的与描述基于消息的 API 相关的对象定义。

在本文中，我们将评估AsyncAPI v3.0，这是该规范的一个新主要版本。此版本有望在 API 提供商描述其基于消息的 API 的方式上提供有价值的增强功能。它有几处变化，因此我们将重点关注两个“大问题”：重构通道和操作以及对请求-回复模式的支持。

重构通道和操作

AsyncAPI 中最显著的变化是重构了 Channels 和 Operations，从Channel Object（以前称为 Channel Item）中删除了publish和属性。这些属性被定义为Operation Object。在 2.x 版本中，它们提供了区分 API 提供者“订阅”的消息（即从队列读取）和“发布”的消息（即写入队列）的方法。这些术语被用作一个统称，并未反映出是否真正使用了发布-订阅消息传递方法。它们是内联声明的，不能重复使用。

publish和属性subscribe从某些消息传递拓扑的反映来看是有意义的，但从 API 提供商如何描述事件以及为谁描述事件的实际情况来看则不是。该术语描述的是 API 提供商在消息传递基础架构中的操作，而不是 API 消费者可以做什么。这可以说使规范的可用性降低，因为它似乎没有描述 API 消费者可以使用哪些操作。缺乏对 Channel Item 对象和 Operation 对象的重用也使用OpenAPI 编写的 API 描述文档比必要的更冗长。

AsyncAPI 要取得成功，必须准确反映向 API 使用者提供的内容，因此删除了这些属性。取而代之的是一种与拓扑无关的机制，该机制提供了描述和重用独立于通道的操作的方法。它基于通道和操作对象的解耦。

描述和重用操作

修改后的指定渠道和操作的方法有五个主要变化：

通道 (Channel) 与操作 (Operation) 是分开定义的。
通道定义了在该通道发送或接收的所有消息。
一个通道 (Channel) 由一个操作 (Operation) 引用。
操作指定了通道定义的消息的子集。
一个操作包括一个action属性，该属性可以是send或receive。

通过这些变化，渠道已成为捕获有关消息传递层功能的信息的实体，而操作捕获特定 API 使用者“可以使用 API 执行的操作”。从 API 使用者的角度来看，这是一个重要的转变，因为它有助于强调用例而不是技术基础设施的功能。

使用规范中的示例，以下是一个 Channel 对象，它指定了面向技术实现的属性。例如，它包括参数、服务器和特定于协议的绑定以及通道支持的所有消息定义：

address: 'users.{userId}'

title: Users channel

description: This channel is used to exchange messages about user events.

messages:

  userSignedUp:

    $ref: '#/components/messages/userSignedUp'

  userCompletedOrder:

    $ref: '#/components/messages/userCompletedOrder'

parameters:

  userId:

    $ref: '#/components/parameters/userId'

servers:

  - $ref: '#/servers/rabbitmqInProd'

  - $ref: '#/servers/rabbitmqInStaging'

bindings:

  amqp:

    is: queue

    queue:

      exclusive: true

tags:

  - name: user

    description: User-related messages

externalDocs:

  description: 'Find more info here'

  url:‘https://example.com'

相比之下，使用合适的对象名称定义的操作对象标识了可在此通道上调用的某些内容，并且仅使用引用对象来标识所使用的特定通道消息：

title: User sign up

summary: Action to sign a user up.

description: A longer description

channel:

  $ref: '#/channels/userSignup'

action: send

security:

  - petstore_auth:

    - write:pets

    - read:pets

tags:

  - name: user

  - name: signup

  - name: register

bindings:

  amqp:

    ack: false

traits:

  - $ref: "#/components/operationTraits/kafka"

messages:

  - $ref: '#/components/messages/userSignedUp'

reply:

  address:

    location: '$message.header#/replyTo'

  channel:

    $ref: '#/channels/userSignupReply'

  messages:

    - $ref: '#/components/messages/userSignedUpReply'

您会注意到，上面的 Operation 对象示例中有一些属性反映了技术实现。但是，它主要侧重于让 API 提供者更容易定义操作，让 API 使用者更简单。对象的这种重用还将使用 AsyncAPI 编写的 API 描述文档更加简洁。

支持请求-回复模式

AsyncAPI v3.0 的另一个显著增强是正式支持请求-回复模式，这是一种非常常见的消息传递模式。许多人都熟悉Hophe 和 Wolf 所著《企业集成模式》中的请求-回复模式。作为一种架构模式，它显然提供了客户端如何提交请求并期望对该请求做出响应的通用视图，使用同步或异步行为等待完整的响应或确认工作正在进行。

此模式的请求部分显然由操作对象引用的消息对象表示。AsyncAPI v3.0 将操作回复对象引入到操作对象中，允许 API 提供者指定 API 使用者如何解析回复队列。

再次以 v3.0 规范中的一个例子为例：

description: Consumer Inbox

location: $message.header#/replyTo

API 提供者向 API 使用者指示，可以从消息头中检索回复队列值replyTo。该对象实现了运行时表达式，这意味着可以在环境中设置该值，而不是在 API 描述文档中静态提供。这显然使文档（因此使界面）变得更加可靠，并允许部署到不同的环境而不会影响 API 的形状。

在OpenAPI和 AsyncAPI中，运行时表达式的使用非常普遍，值得一提的是，这种方法通常可以提高 API 描述文档的灵活性。提供可以在运行时解析的指标（由适当的工具支持）意味着 API 提供者可以指定所需的行为而不是静态值。这降低了脆弱性，并增加了 API 的给定版本获得更长时间支持的机会。另请阅读：

最后的想法：使用 AsyncAPI v3.0 的权衡

对于绝大多数用户来说，AsyncAPI v3.0 中的开发将受到欢迎。简化了指定操作的过程，省去了使用publish和subscribe属性的负担，使规范更容易理解。将通道和操作分离使得通道可以在操作之间重复使用，并简化了操作的声明。建立请求-回复语义也极大地有利于这种普遍异步模式的实施者。

这些变化也有可能使 AsyncAPI 成为企业集成的一项广泛使用的功能。对象既可以从内部类型定义获取，也可以从外部远程定义获取，这增强了更容易重用对象的能力。允许 API 生产商重用来自（例如）企业范围 API 存储库的定义，为 API 治理提供了关键信息。此外，当 API 提供商修改用 AsyncAPI 编写的 API 描述文档时，他们可以轻松了解更改的影响。

因此，AsyncAPI 有可能在消息传递领域带来巨大好处。在工具制造商和供应商的支持下，它可能会成为企业消息传递生态系统中 API 治理的支柱。

文章来源：What’s New in AsyncAPI v3.0?