AsyncAPI & Event-Driven API Vocabulary для розробників
Специфікація AsyncAPI, канали, повідомлення, прив’ язки і словник проектування API на основі подій.
Архітектура, керована подією, трансформувала спосіб спілкування сучасних систем, але вона також ввела багатий словник, який може спіткати навіть досвідчених розробників, коли вони працюють англійською. Незалежно від того, переглядаєте ви запит на звантаження, обговорюєте інтеграцію Kafka у спільній роботі або пишете документацію для служби, заснованої на AsyncAPI, знати точні терміни і як їх використовувати у розмові є обов’ язковим.
Цей посібник охоплює основний словник Специфікація AsyncAPI і дизайн API, керований подією. Кожен термін містить визначення простою англійською та реальні приклади розмов, взяті з дискусій, які розробники мають щодня.
Основні терміни
** Специфікація AsyncAPI ** — стандартний документ, який можна читати машиною (написано у YAML або JSON), який описує API, керований подією: його канали, формати повідомлень, протоколи і відомості про сервер. Це еквівалент документа OpenAPI (Swagger) для REST API, який керується подією.
“Чи ви мали можливість подивитися на специфікацію AsyncAPI, яку я вчора випустив? Я задокументував всі теми Кафки, які публікує служба замовлень»
«Перед тим, як ми додамо нового споживача, давайте оновимо специфікацію AsyncAPI, щоб контракт був ясним для решти команди»
** Канал ** — названий акведук, через який протікають повідомлення. У Kafka це відображення теми; у AMQP це відображення обміну або черги; у WebSocket це може бути певний шлях. Визначення каналу у AsyncAPI описує адресу каналу і тип повідомлень, які буде передано за допомогою цього каналу.
«Ми потребуємо окремого каналу для невдалих платіжних подій — змішування їх в головний платіжний канал робить логіку споживача незграбною»
«Назва каналу повинна відповідати нашій конвенції іменування:
{domain}.{entity}.{event}, тожbilling.invoice.created.»
** Повідомлення ** — одиниця даних, що надсилається каналом. Повідомлення складається з двох частин: ** заголовка ** (метадані, такі як інформація про маршрутизацію або штамп часу) і ** вмісту ** (справжні бізнес- дані).
«Схема повідомлень визначена в специфікації, але споживач відкидає повідомлення — я думаю, що є невідповідність у структурі корисного навантаження»
“Чи можете ви підтвердити, чи знаходиться ідентифікатор кореляції в заголовку повідомлення або в корисному вантажі? Служба споживання очікує його в заголовку.”
** Опублікувати/ підписатися на дію ** — шаблон, за якого ** опублікувати ** надсилає повідомлення на канал, не знаючи, хто слухає, і один або декілька ** підписників ** споживає ці повідомлення незалежно. Документи AsyncAPI описують операції як або publish (застосунок відсилає) або subscribe (застосунок отримує).
«Ця служба тільки публікує — вона викликає подію
user.registeredі забуває. Нижні служби підписуються і займаються рештою»
У AsyncAPI 3.x термінологія змінилася з
publish/subscribeнаsend/receive, що трохи більш інтуїтивно зрозуміло
Прив’язки, схеми і брокери
** Прив’ язка ** — блок розширення, що стосується протоколу, у документі AsyncAPI, який містить параметри, унікальні для певного транспорту, наприклад, ключі розділів Kafka, типи обміну AMQP, заголовки обміну WebSocket або визначення методів HTTP. Прив’ язки є тим, що робить специфікацію AsyncAPI конкретною, а не загальною.
«Я додав прив’язку Kafka до визначення каналу — вона вказує ключ розділу теми і політику очищення»
«Прив’язка AMQP показує, що цей обмін є типу
fanout, що пояснює, чому кожна черга, прив’язана до нього, отримує копію повідомлення»
** Схема повідомлення ** — формальне визначення структури повідомлення, зазвичай написане у форматі JSON Schema або Avro і посилання на нього міститься у документі AsyncAPI. Хороша схема діє як контракт між виробником і споживачем.
«Схема повідомлення каже, що поле
amountє числом, але ми серіалізуємо його як рядок — це джерело помилки перевірки»
«Перед тим, як ви розгорнете, переконайтеся, що нові поля, які ви додали, позначені як необмежені в схемі, інакше існуючі споживачі будуть пошкоджені.»
** Корисна вантажність ** — тіло повідомлення; бізнес- дані, які передаються. Корисна нагрузка визначається схемою повідомлення і містить інформацію, на яку споживачі фактично діють.
«Повний об’єкт замовлення включає в себе повний об’єкт замовлення — чи нам дійсно потрібні всі ці поля, чи нам слід скоротити його до того, що споживачі дійсно потребують?»
«Ми бачимо розміри вантажу понад 1 МБ на деяких подіях. Ми повинні розглянути зберігання великих бляшок в об’єкті зберігання і встановити тільки посилання в корисному навантаженні. ”
** Заголовок ** — метадані ключ- значення, долучені до повідомлення, яке відокремлено від корисного вмісту бізнес- повідомлення. Заголовки зазвичай містять підказки щодо маршрутизації, тип вмісту, версію повідомлення, ідентифікатори трасування і ідентифікатори кореляції.
Додати заголовок
x-message-version, щоб споживачі могли легко обробляти декілька версій схеми під час міграції
«Проміжне програмне забезпечення для відстеження читає заголовок
traceparentавтоматично — вам не потрібно передавати його вручну у виклику публікації»
** ІД кореляції ** — унікальний ідентифікатор, вміщений у повідомленні (зазвичай, у заголовку), який надає змогу зв’ язати відповідь або подію, що відбулася згодом, з початковим запитом або подією, що спричинила його. Необхідний для відстеження потоків у асинхронних службах.
“Якщо служба електронної пошти не працює, як ми знаємо, який запит її запустив? Нам потрібен ідентифікатор кореляції, щоб ми могли відстежити подію назад до початкового запиту»
«Я додав
correlationIdяк обов’язкове поле заголовка в специфікації AsyncAPI — кожне опубліковане повідомлення повинно включати його»
** Сервер (брокер) ** — у термінології AsyncAPI, запис server описує брокера повідомлень або платформу потокового передачі подій, до якої з’ єднується програма. У ній вказано протокол, вузол, порт і всі вимоги безпеки. Поширені приклади: Apache Kafka, RabbitMQ (AMQP) і AWS EventBridge.
“Специфікація AsyncAPI має два записи сервера: один для кластера Kafka для розробників і один для виробництва. Упевніться, що ваш споживач вказує на правильний»
«Ми переходимо з RabbitMQ на Kafka. Визначення сервера зміниться, і деякі з прив’язок будуть потребувати переписування»
Організація та управління
** AsyncAPI Studio ** — офіційний редактор на основі переглядача для створення і перегляду документів AsyncAPI. Цей інструмент надає перевірку у реальному часі, візуальне відтворення каналів і повідомлень, а також живий перегляд створеної документації.
«Вставте YAML в AsyncAPI Studio — він вловить будь-які помилки схеми, перш ніж ви витратите час на зневадження споживача»
«Команда продукту може використовувати AsyncAPI Studio для читання специфікації без необхідності розуміти YAML. Візуальний вигляд досить чіткий»
** Створення коду з AsyncAPI** — процес використання інструментів (таких як AsyncAPI Generator або Microcks) для створення стандартного коду — моделей, клієнтських шаблонів, скелетів сервера — безпосередньо з документа AsyncAPI. Це забезпечує, що код і специфікація залишаються синхронними.
«Ми використовуємо AsyncAPI Generator для автоматичного виробництва типів TypeScript зі специфікації — більше немає вручну оновлювати інтерфейси, коли схема змінюється.»
“Створення коду зберегло нам тиждень. Ми генеруємо скелет споживача Кафки, а потім просто заповнюємо бізнес-логіку»
** Каталог подій ** — реєстр з можливістю пошуку всіх типів подій, які створює і використовує організація, їх схем, власників і історії версій. Інструменти, такі як EventCatalog.dev, можуть приймати документи AsyncAPI для автоматичного заповнення каталогу.
Перед тим, як створити новий тип події, перевірте каталог подій — вже є подія
payment.completed, яка може покрити ваш випадок використання
«Каталог подій є єдиним джерелом правди про те, які події існують у наших мікросервісах. Якщо його немає в каталогу, то він не повинен бути в виробництві»
** Реєстр схем з AsyncAPI ** — реєстр схем (наприклад, Confluent Schema Registry або AWS Glue) зберігає і версії схем повідомлень централізованим чином. Документи AsyncAPI можуть посилатися на схеми, збережені в реєстрі, замість того, щоб вставляти їх, що дозволяє перевіряти управління і сумісність.
«Ми інтегрували специфікацію AsyncAPI з нашим Confluent Schema Registry. Кожного разу, коли нова версія схеми об’єднується, реєстр перевіряє зворотну сумісність
«Реєстр схеми відхилив розгортання, тому що нова версія видаляє необхідне поле — це поразкова зміна.»
** Версії договорів подій ** — практика керування змінами у схемах повідомлень у спосіб, який не порушує існуючих споживачів. Поширені стратегії включають семантичні версії схем, тільки зворотньо сумісні додавання і тестування договорів, керованих споживачами.
“Ми працюємо на версії 2.1 схеми. Нове поле
discountCodeє необмеженим, тому воно є зворотньо сумісним — існуючі споживачі не помітять»
“Зміни в контрактах на події потребують періоду відновлення. Ми зберігаємо стару версію, що працює, принаймні, два спринти, поки споживачі мігрують. “
Як використовувати їх у розмові
У перегляді коду і обговоренні дизайну важлива точність. Ось деякі з природних шаблонів для звичайних ситуацій:
** Пропозиція нової події: ** “Я думаю, що ми опублікуємо подію cart.abandoned на каналі ecommerce.cart. Я підготую запис специфікації AsyncAPI зі схемою повідомлення і запропонованими заголовками — чи можете ви переглянути його, перш ніж я підніму PR?»
** Позначення проблеми зі схемою: ** « У специфікації показано userId як рядок, але виробник серіалізує його як ціле число. Який з них канонічний — чи повинен я виправити код або оновити специфікацію?»
** Обговорення версій: ** “Якщо ми додамо поле region, як це потрібно, це буде зміна, що порушує договір події. Нам потрібно буде перенести основну версію і продовжувати працювати канал v1, поки всі споживачі не мігрують»
** Посилання на брокера: ** « Запис сервера у специфікації вказує на кластер Kafka для перевірки. Нам буде потрібно окреме середовище конфігурації для виробництва, перш ніж ми перейдемо на життя»
** Питання щодо кореляції: ** « Як ми зв’ язуємо сповіщення webhook з початковим замовленням? Чи ми переносимо кореляційний ідентифікатор через всі події вниз по течії?»
Краткий справочник
| Term | Plain-English Meaning |
|---|---|
| AsyncAPI specification | YAML/JSON document describing an event-driven API’s channels, messages, and protocols |
| Channel | Named conduit (topic, queue, path) through which messages travel |
| Message | The unit of data: header (metadata) + payload (business data) |
| Binding | Protocol-specific settings (Kafka, AMQP, WebSocket, HTTP) attached to a channel or message |
| Payload | The business data body of a message |
| Correlation ID | A unique ID linking a reply or downstream event back to its origin |
| Server (broker) | The message broker entry (Kafka, RabbitMQ, etc.) described in the AsyncAPI spec |
| AsyncAPI Studio | Browser-based editor and visual preview tool for AsyncAPI documents |
| Schema registry | Central store for message schemas with versioning and compatibility checks |
| Versioning event contracts | Managing schema changes without breaking existing consumers |