架構(gòu)對(duì)象遵循與 AsyncAPI 版本 2.x 和 OpenAPI 基本相同的語(yǔ)義。在我們的示例中，這些在組件對(duì)象中實(shí)現(xiàn)，以便跨消息對(duì)象重用。我們總共創(chuàng)建了四個(gè)，具有兩個(gè)操作的請(qǐng)求和響應(yīng)有效負(fù)載，然后實(shí)現(xiàn)了引用每個(gè)操作的消息對(duì)象，并且可以攜帶消息的語(yǔ)義，包括公共標(biāo)頭等消息特征。我們實(shí)現(xiàn)了一個(gè) header?health-system-id?，它提供了發(fā)送消息的系統(tǒng)的高級(jí)指示器。

components:

  messages:

    patientMedicationStatementRequest:

      summary: Request message for patient and current medication data

      title: Patient and Medication Request

      payload:

        $ref: "#/components/schemas/patientMedicationStatementRequestPayload"

      traits:

        - $ref: "#/components/messageTraits/healthSystemHeaders"

    patientMedicationStatementResponse:

      summary: Response message for patient and current medication data

      title: Patient and Medication Response

      payload:

        $ref: "#/components/schemas/patientMedicationStatementRequestPayload"

      traits:

        - $ref: "#/components/messageTraits/healthSystemHeaders"

    patientMedicationRequest:

      summary: Request message for patient and current medication data

      title: Patient and Medication Request

      payload:

        $ref: "#/components/schemas/patientMedicationStatementRequestPayload"

      traits:

        - $ref: "#/components/messageTraits/healthSystemHeaders"

    patientMedicationResponse:

      summary: Request message for patient and current medication data

      title: Patient and Medication Request

      payload:

        $ref: "#/components/schemas/patientMedicationStatementRequestPayload"

      traits:

        - $ref: "#/components/messageTraits/healthSystemHeaders"

  schemas:

    patientMedicationStatementRequestPayload:

      type: "object"



      # Remainder of Schema Object definitions



  messageTraits:

    healthSystemHeaders:

      headers:

        type: object

        properties:

          health-system-id:

            description: Health system provider ID as UUID

            type: string

            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

因此，AsyncAPI 的現(xiàn)有用戶(hù)應(yīng)該非常熟悉此處描述的結(jié)構(gòu)。請(qǐng)注意，為了這篇文章的目的，我們已經(jīng)大大減少了示例中的消息結(jié)構(gòu)。源FHIR JSON Schema 文檔要全面得多。

添加溝通渠道

消息就位后，我們創(chuàng)建了Channel 對(duì)象。通道描述了發(fā)送和接收消息的傳輸機(jī)制，并將給定的消息隊(duì)列或主題與其支持的消息結(jié)構(gòu)對(duì)齊。 3.0 版中對(duì) Channel 對(duì)象的更改值得注意，因?yàn)?code>publish和subscribe屬性已被刪除，并且它們引用的操作對(duì)象已移至其自己的根級(jí)屬性。

操作對(duì)象的刪除導(dǎo)致通道對(duì)象更加精簡(jiǎn)并專(zhuān)注于技術(shù)實(shí)現(xiàn)。在我們的示例中，您可以看到 Channel 定義了一個(gè)address ，它是我們消息系統(tǒng)中假設(shè)的消息隊(duì)列，并通過(guò)messages屬性提供支持的消息和通道之間的綁定：

channels:

  patientMedicationStatements:

    description: Channel for requesting patient record and medication statement

    address: health.patient.medication.statement

    messages:

      patientMedicationStatementRequest:

        $ref: "#/components/messages/patientMedicationStatementRequest"

      patientMedicationStatementResponse:

        $ref: "#/components/messages/patientMedicationStatementResponse"

  patientMedicationRequest:

    description: Channel for ordering medication for a patient

    address: health.patient.medication.request

    messages:

      patientMedicationRequest:

        $ref: "#/components/messages/patientMedicationRequest"

      patientMedicationResponse:

        $ref: "#/components/messages/patientMedicationResponse"

在 3.0 版本中，通道對(duì)象更加關(guān)注技術(shù)實(shí)現(xiàn)。通道的重點(diǎn)允許 API 設(shè)計(jì)者將重點(diǎn)放在操作對(duì)象上，這種抽象提高了可重用性。

描述操作

我們?cè)O(shè)計(jì)的最后一步是創(chuàng)建操作對(duì)象，它使我們能夠告訴 AsyncAPI 描述的使用者“做什么”以將他們的應(yīng)用程序與我們的 API 集成。由于操作對(duì)象的名稱(chēng)是給定對(duì)象的標(biāo)識(shí)符，因此我們決定使用標(biāo)準(zhǔn)前綴order-medication/來(lái)命名它們，以提供對(duì)操作進(jìn)行分組的方法。我們可以使用標(biāo)簽對(duì)象作為此方法的替代方案。

我們創(chuàng)建了兩個(gè)操作對(duì)象， order-medication/get-patient-and-medication-statement 和 order-medication/make-medication-request 映射到我們的藥物訂購(gòu)用例中的兩個(gè)操作：

operations:

  order-medication/get-patient-and-medication-statement:

    summary: Retrieve the patient record and current medication for the patient

    action: send

    channel:

      $ref: "#/channels/patientMedicationStatements"

    messages:

      - $ref: "#/channels/patientMedicationStatements/messages/patientMedicationStatementRequest"

    reply:

      address:

        "location": "$message.header#/replyTo"

      channel:

        $ref: "#/channels/patientMedicationRequest"

      messages:

        - $ref: "#/channels/patientMedicationRequest/messages/patientMedicationResponse"

  order-medication/make-medication-request:

    summary: Send a medication request on-behalf of the patient

    action: send

    channel:

      $ref: "#/channels/patientMedicationRequest"

    messages:

      - $ref: "#/channels/patientMedicationRequest/messages/patientMedicationRequest"

    reply:

      address:

        "location": "$message.header#/replyTo"

      channel:

        $ref: "#/channels/patientMedicationRequest"

      messages:

        - $ref: "#/channels/patientMedicationRequest/messages/patientMedicationResponse"

操作引用我們已經(jīng)創(chuàng)建的通道對(duì)象及其支持的消息。我們還在操作中利用了 3.0 版本的另一個(gè)新功能，操作回復(fù)對(duì)象。操作回復(fù)對(duì)象支持請(qǐng)求/回復(fù)模式的實(shí)現(xiàn)，這是一種非常常見(jiàn)的消息傳遞范例。在我們的示例中，我們指定了一個(gè)動(dòng)態(tài)設(shè)置的回復(fù)隊(duì)列，它是使用運(yùn)行時(shí)表達(dá)式指定的。回復(fù)的系統(tǒng)在發(fā)送響應(yīng)時(shí)必須使用消息頭replyTo的值。

有效的 AsyncAPI 描述

將 3.0 版 AsyncAPI 描述集中在一起，重點(diǎn)關(guān)注特定用例，顯示了 AsyncAPI 規(guī)范修訂后的結(jié)構(gòu)的一些重要內(nèi)容，即： 添加操作對(duì)象提供了消息、傳輸和操作描述之間的關(guān)注點(diǎn)分離。

除了能夠描述用例之外，修訂后的結(jié)構(gòu)還有其他幾個(gè)顯著的好處：

• 一致性：操作對(duì)象可以在整個(gè) API 生命周期中在 AsyncAPI 文檔中保持靜態(tài)，從而提供一致的簽名。因此，操作對(duì)象更容易管理，因?yàn)樗鼈儾粫?huì)“陷入”傳輸語(yǔ)義中。
• 可移植性：將操作對(duì)象與通道對(duì)象分離意味著通道對(duì)象可以描述一次然后重復(fù)使用，包括跨 AsyncAPI 描述。這使得通道對(duì)象更加可移植。
• 所有權(quán)：不同團(tuán)隊(duì)擁有其負(fù)責(zé)的 AsyncAPI 描述部分的所有權(quán)的方式補(bǔ)充了一致性和可移植性。例如，技術(shù)運(yùn)營(yíng)團(tuán)隊(duì)可以向 API 設(shè)計(jì)團(tuán)隊(duì)單獨(dú)定義通道對(duì)象，并在信息可用時(shí)注入通道定義，例如服務(wù)器對(duì)象。這使得組織能夠采用管道方法來(lái)創(chuàng)建準(zhǔn)確的 AsyncAPI 描述，并利用自動(dòng)化來(lái)確保描述盡可能準(zhǔn)確。

我們將設(shè)計(jì)重點(diǎn)放在“自下而上”的方法上，使用源自開(kāi)放標(biāo)準(zhǔn)的現(xiàn)有消息有效負(fù)載結(jié)構(gòu)，并創(chuàng)建我們的操作對(duì)象作為最后一步。當(dāng)然，您可以按照自己的方法來(lái)構(gòu)建 AsyncAPI 描述（這完全取決于您），但是用例設(shè)計(jì)方法為您希望界面實(shí)際執(zhí)行的操作提供了一些切實(shí)的結(jié)果。如果您愿意，您可以首先從操作對(duì)象開(kāi)始，勾勒出支持的操作的要求并與設(shè)計(jì)利益相關(guān)者達(dá)成一致，然后再開(kāi)始詳細(xì)的消息傳遞設(shè)計(jì)。

在 AsyncAPI 中描述用例的主要缺點(diǎn)是傳達(dá)順序和依賴(lài)關(guān)系。除了通過(guò)描述和命名約定之外，AsyncAPI 不通過(guò)操作對(duì)象傳達(dá)此信息。然而，提供全功能用例描述的下一步將通過(guò) OpenAPI Initiative?Arazzo規(guī)范來(lái)提供。支持 AsyncAPI 最初是在 1.0.0 版本中發(fā)布的，現(xiàn)在又出現(xiàn)在下一版本的路線圖中。

Arazzo 將提供更豐富的方法來(lái)描述端到端用例，包括依賴(lài)關(guān)系、操作之間傳遞的動(dòng)態(tài)值以及基于消息數(shù)據(jù)的故障條件。這與解耦的操作對(duì)象一起，使得通過(guò)異步 API的豐富用例描述來(lái)改善開(kāi)發(fā)人員體驗(yàn)變得非常可行。

原文鏈接：https://nordicapis.com/how-to-write-a-v3-asyncapi-description/

#你可能也喜歡這些API文章!

掌握API建模：基本概念和實(shí)踐

程序員常用的API接口管理工具有哪些？

簡(jiǎn)化API縮寫(xiě)：應(yīng)用程序編程接口終極指南

如何為你的項(xiàng)目挑選最佳API？完整選擇流程解讀

應(yīng)用程序開(kāi)發(fā)蓬勃發(fā)展的必備開(kāi)放API

.NET Core Web APi類(lèi)庫(kù)如何內(nèi)嵌運(yùn)行和.NET Core Web API 中的異常處理

.NET Core Web API + Vue By Linux and Windows 部署方案知識(shí)點(diǎn)總結(jié)

優(yōu)化利潤(rùn)：計(jì)算并報(bào)告OpenAI支持的API的COGS

用于集成大型語(yǔ)言模型的LLM API