Съдържание на курса
Урок 09 — Нишката между услугите
От Dorian Chávez · съосновател и Chief Executive Officer на Hábil ·
Какво ще постигнеш: всяка поръчка да носи идентификатор за корелация, който я придружава от магазина до рутера, от рутера до int-rest и от int-rest до API-то, така че да можеш да я намериш във всяка точка от маршрута ѝ, като търсиш една-единствена стойност.
Преди да започнеш, ти трябват: завършен урок 08 и включена средата от урок 00:
docker compose -f infra/compose.yaml up -d --wait # desde la carpeta raíz de la práctica
Новото днес, в едно изречение
В урок 08 поръчката мина през три услуги и всяка писа в собствения си лог. Ако утре един магазин се оплаче: „поръчката ми не пристигна“, как събираш редовете от трите лога, които говорят за тази поръчка? Днес ѝ слагаш нишка: идентификатор, който всяка услуга получава и подава на следващата.
Картината: номерът на товарителницата на една пратка. Минава през офиса, разпределителния център и куриера и на всяко място го записват. С този номер знаеш къде е била. Ако един офис не го запише, оттам нататък пратката става невидима.
Пликът, целият
В урок 08 видя хедърите ce-*, без да ги използваш. Днес ги четеш:
| Хедър | Какво казва | За поръчка 1003 |
|---|---|---|
ce-specversion |
Коя версия на CloudEvents използва пликът | 1.0 |
ce-id |
Кое събитие е това, едно-единствено | orden-1003-creada |
ce-type |
От какъв тип е събитието | mx.tienda.orden.creada |
ce-source |
Къде се е случило | /tiendas/T-022 |
ce-subject |
За какво говори: за поръчката | 1003 |
ce-correlationid |
Нишката: свързва всичко, което се случва заради една и съща заявка | решава го магазинът или рутерът |
ce-id и ce-correlationid изглеждат еднакви, но не са. ce-id назовава едно събитие. Нишката следва една
заявка на магазина през всички услуги, до които тя се докосва. Когато една поръчка породи няколко събития (създадена, изпратена,
доставена), всяко ще има собствен ce-id, а всички ще могат да споделят една и съща нишка.
ce-correlationid не е едно от основните полета на CloudEvents: то е разширение — поле, което се добавя към
плика. Стандартът позволява да се добавят разширения.
1. Подготви папката си
cd lecciones/09-el-hilo-entre-servicios
cp -R inicio mio
2. Прочети откъде идва нишката
Отвори mio/orden-router/orden-router.camel.yaml. Отгоре има стъпка choice:
| Ако магазинът… | Рутерът… |
|---|---|
прати хедъра X-Correlation-Id |
използва същия идентификатор като нишка |
| не го прати | измисля нов — UUID (случайно число, толкова дълго, че на практика не се повтаря) |
А накрая рутерът го връща на магазина в отговора. Така магазинът има с какво да пита за своята поръчка.
Обърни внимание на коментара: идентификаторът се записва в променлива, преди да се изчистят хедърите. Това е сърцето на урока.
3. Предвиди
Маршрутът от inicio/ има три TODO и засега никоя услуга не подава нишката на следващата. Отговори на лист хартия:
- Ако магазинът прати поръчка 1003 с идентификатор
mi-hilo-1, в коя точка от пътя се губи той: в рутера, в int-rest или в API-то? - Получава ли магазинът обратно своя идентификатор, макар той да се губи по пътя?
Провери го:
./verifica inicio
Излизат три червени отметки и едната казва La API no recibió el hilo de la 1003 (anotó: correlacion=-). Тирето е начинът, по който
API-то пише „не ми пристигна никакъв“. Рутерът записа нишката и магазинът я получи обратно: нишката се
губи в първата услуга, която не я препраща, точно след рутера.
4. Напиши трите стъпки
Това са три TODO и трите са една и съща идея: получи нишката и я подай нататък.
1. В рутера: сложи я в плика. В mio/orden-router/orden-router.camel.yaml, там където пише TODO, добави
setHeader с име ce-correlationid и стойността на променливата correlacion. Използвай като образец setHeader-а
за ce-subject, който е няколко реда по-горе.
2. В int-rest: запази я, преди да бъде изтрита. В mio/int-rest/int-rest.camel.yaml, първият TODO. Добави
setVariable с име correlacion и стойност ${header.ce-correlationid}. Трябва да е там, отгоре: няколко
стъпки по-долу е removeHeaders, който изтрива всички пристигнали хедъри.
3. В int-rest: подай я на API-то. Вторият TODO. Добави setHeader с име X-Correlation-Id и стойността
на променливата correlacion. Мястото му е след removeHeaders, до останалите хедъри на извикването към API-то.
5. Проследи я с очите си
От папката на урока вдигни услугите и гледай логовете им:
DONDE=mio docker compose -f compose.yaml up -d
DONDE=mio docker compose -f compose.yaml logs -f
В друг терминал, от основната папка на курса, влез в ролята на магазина със собствена нишка:
curl -i -XPOST localhost:8080/ordenes -H 'Content-Type: application/json' \
-H 'X-Correlation-Id: mi-hilo-1' -d @datos/ordenes/orden-1003.json
Потърси mi-hilo-1 на три места:
| Къде | Какво да търсиш |
|---|---|
Отговорът на curl |
Хедъра X-Correlation-Id: mi-hilo-1 |
| Логовете на рутера и на int-rest | correlacion=mi-hilo-1 в редовете им |
| Логът на API-то | docker compose -f infra/compose.yaml logs api-pedidos | grep mi-hilo-1 |
Ако и на трите места се появява една и съща стойност, нишката е цяла. Сега прати поръчката без хедъра
X-Correlation-Id. Какъв идентификатор ти върна магазинът? Потърси го в логовете: трябва да е един и същ навсякъде.
Когато приключиш, изключи услугите:
DONDE=mio docker compose -f compose.yaml down
6. Най-честата грешка: да я прочетеш късно
Направи опита: в int-rest премести своя setVariable за корелацията така, че да остане под removeHeaders.
Изключи, вдигни отново и прати поръчката с mi-hilo-1.
Магазинът получава идентификатора си обратно, рутерът го записва, но int-rest пише correlacion= (празно), а API-то —
correlacion=-. Когато int-rest отиде да прочете хедъра, removeHeaders вече го беше изтрил. Няма нито грешка, нито
аларма: нишката се къса безшумно.
Затова правилото е: каквото ти трябва от входящото извикване, запази го в променлива, преди да чистиш. Променливите не се изтриват заедно с хедърите. Върни стъпката си на мястото ѝ.
7. Провери
./verifica
verifica рестартира API-то, вдига двете услуги и праща две поръчки: 1003 със собствена нишка и 1001 без
никаква. Урокът е завършен, когато видиш осемте зелени отметки:
✅ Arrancaron el router e int-rest
✅ La tienda mandó la 1003 y la respuesta final fue 201
✅ El router anotó el hilo tienda-…
✅ int-rest recibió el hilo en el sobre
✅ La API registró la 1003 con el mismo hilo: se puede seguir de punta a punta
✅ La tienda recibió de vuelta su mismo id
✅ Los encabezados del sobre (ce-*) no salieron hacia la tienda
✅ Sin id de la tienda, el router inventó … y llegó igual a la API
Там, където виждаш …, се появява идентификаторът на това пускане: verifica използва нов всеки път.
Седмата проверява нещо, което не си писал ти: пликът ce-* е за вътрешните услуги и рутерът го
изтрива, преди да отговори на магазина. На магазина се връща само X-Correlation-Id.
Не тръгва? ./verifica solucion тества нашето решение, а тези две команди ти казват по какво се различават:
diff mio/orden-router/orden-router.camel.yaml solucion/orden-router/orden-router.camel.yaml
diff mio/int-rest/int-rest.camel.yaml solucion/int-rest/int-rest.camel.yaml
| Какво виждаш | Какво правиш |
|---|---|
int-rest no anotó el hilo |
Липсва стъпка 1 в рутера или стъпка 2 е останала под removeHeaders (стъпка 6) |
La API no recibió el hilo, а всичко останало е в зелено |
Липсва стъпка 3: int-rest я има, но не я подава на API-то |
El puerto 8080 está ocupado |
Услугите са останали вдигнати: DONDE=mio docker compose -f compose.yaml down |
Упражнение: намери една поръчка
Вдигни своята версия, прати три поръчки (1001, 1003 и пак 1001), всяка без X-Correlation-Id, и
запиши идентификатора, който ти върна всяка. После, само с идентификатора на втората, отговори: коя поръчка беше, какво ѝ
отговори API-то и колко време мина от пристигането ѝ в рутера до отговора на API-то? Подсказка: всеки ред от лога
започва с часа.
Защо е направено така
Какво решихме в този урок, заедно с това, което отхвърлихме, и какво би ни накарало да си променим мнението:
- CloudEvents в двоичен режим като плик
- Нишката за корелация пътува с поръчката, но не излиза от къщи
Преговор
- Каква е разликата между
ce-idиce-correlationid? - Ако магазинът не прати идентификатор, кой го слага и по какъв начин?
- Защо int-rest запазва нишката в променлива преди
removeHeaders? - Какво написа API-то, когато нишката не стигна до него, и защо това е по-лошо от грешка?
- Каква е ползата за магазина да получи идентификатора си обратно?
Следва: в урок 10 рутерът вече не праща поръчката само на int-rest: праща я едновременно на трите дестинации и същата нишка трябва да стигне до API-то, до ERP и до партньора.
Предпочитате имейл? Пишете ни на hola@habil.mx