Към съдържанието
Съдържание на курса

Урок 13 — Пристига пратката

От · съосновател и Chief Executive Officer на Hábil ·

Какво ще постигнеш: да получиш файла, който складът оставя, когато една поръчка излезе, без да го вземеш наполовина, без да го вземеш два пъти и без да загубиш този, който пристига повреден. Този файл се превръща в 856 за партньора и в статус EMBARCADO в API-то и в ERP.

Преди да започнеш, ти трябват: завършен урок 12 и включена средата от урок 00. Този урок използва две нови таблици в ERP, embarque и entrega. Ако твоят ERP е отпреди, пресъздай го веднъж:

docker compose -f infra/compose.yaml up -d --wait --build --force-recreate -V

Новото днес, в едно изречение

Дотук поръчката пристигаше при твоята интеграция: магазинът викаше рутера. С пратката е обратното: складът не вика никого, оставя файл в една папка и си тръгва. Някой трябва да ходи да гледа дали има нещо ново. Това се нарича polling — периодична проверка (Polling Consumer), и днес го конфигурираш.

Картината: пощенската кутия на една сграда. Пощальонът оставя писмата и не звъни. Портиерът слиза от време на време да провери, взема само затворените пликове (не писмото, което някой още пише на масата), отделя това, което вече е предал, и оставя настрана това, което е пристигнало скъсано. И има само един портиер: ако бяха трима, двама можеха да качат едно и също писмо.

Това е част 2: поръчката вече е създадена; сега излиза от склада (днес), разделя се на няколко (14), записва се нейното състояние (15) и стига до клиента (16 и 17).


1. Подготви папката си

cd lecciones/13-llega-el-embarque
cp -R inicio mio

Днес има нова услуга, sondeo-bodega. Разгледай папката buzon/ на урока, която в compose.yaml се монтира вътре в контейнера на polling услугата. Цялата ти работа е в един-единствен файл: mio/sondeo-bodega/sondeo-bodega.camel.yaml, а в него — само в параметрите на from.

Отвори и една примерна пратка, datos/embarques/embarque-4001.json: носи поръчката, куриерската фирма, товарителницата (номера, с който куриерската фирма следи пратката) и кои редове са излезли.

2. Предвиди

Отговори на лист хартия, преди да пускаш каквото и да е:

  1. В урок 12 се научи да пускаш три реплики на една услуга. Ако три реплики проверяваха една и съща папка, какво би могло да се случи с един файл?
  2. Складът записва файла малко по малко. Какво става, ако polling услугата го вземе, когато е по средата?
  3. Пристига повреден файл, който не е валиден JSON. Какво трябва да стане с него: да се изтрие, да остане където е или да се отдели настрана?

Виж какво е положението днес:

./verifica inicio

Няколко отметки излизат в червено. Прочети ги: всяка ти казва коя предпазна мярка липсва на polling услугата. Тази от inicio/ чете всичко, което има в buzon/, и не отделя нищо (noop: true оставя всеки файл където си е бил).

3. Това, което вече е направено: каналите се използват повторно

Преди да пишеш, виж какво не е нужно да пишеш. Отвори mio/orden-router/orden-router.camel.yaml и намери platform-http:/embarques. Това е вратата, през която polling услугата предава всяка пратка на рутера. По-долу е същият multicast от урок 10, със същите три канала: direct:canal-api, direct:canal-erp и direct:canal-socio. Единственото различно е стъпката (paso): преди всеки канал викаше /integrar; сега вика /embarque.

Канал Услуга Какво прави с пратката
API int-rest Съобщава на API-то, че поръчката е изпратена, като събитие със своя ключ (orden-4001-embarcada)
ERP int-bd Записва реда в embarque с товарителницата и прехвърля поръчката в EMBARCADO
Партньор int-edi Сглобява 856, известието за изпращане в X12, и го оставя на SFTP с предпазните мерки от урок 07

И правилото от урок 11 продължава да важи: само франчайзите получават EDI. Затова днес поръчките са от магазини T-501 и T-502.

4. Четирите предпазни мерки на polling-а

Компонентът file на Camel вече умее да прави polling. Твоята работа е да му кажеш какви предпазни мерки да взема, с четири параметъра. Всяко TODO във файла ти казва кой:

TODO Параметър Мярката В пощенската кутия на сградата
1 include Да взема само завършените файлове: embarque-<algo>.json. Файлът .tmp не съвпада Само затворените пликове
2 readLock с changed Да изчака файлът да спре да расте, преди да го вземе Да изчака пощальонът да пусне писмото
3 move и moveFailed (и махане на noop) Да отделя това, което рутерът е получил, в .camel/, а провалилото се — в .error/ Предаденото на една страна, скъсаното — на друга
4 delay През колко време да проверява папката: на всеки 2 секунди, тоест 2000 милисекунди През колко време слиза портиерът

Две подсказки:

  • include е регулярен израз върху името на файла. Точката в .json трябва да е екранирана, а в YAML в двойни кавички наклонената черта се пише два пъти: \\.
  • За името на отделения файл използвай ${file:name}: така embarque-4001.json става .camel/embarque-4001.json.

Обърни внимание какво не правиш: не пишеш цикъл, не четеш папката сам, не триеш нищо. Четирите мерки са конфигурация, а компонентът върши останалото.

5. Счупи едно нарочно

С твоя завършен polling махни реда с moveFailed и пусни ./verifica. Преди това предвиди: къде отива повреденият файл, ако не му кажеш къде да го пратиш?

Излиза в червено Buzón: el embarque roto no está en .error/. Файлът остава в buzon/, а в лога на polling услугата ще го видиш как се проваля отново и отново: без moveFailed Camel го оставя където си е бил и опитва пак на следващата обиколка. Повреден файл, който се опитва вечно, не се губи, но и не предупреждава: пълни лога и скрива грешките на останалите. Върни реда.

6. Провери

./verifica

verifica създава поръчки 4001 и 4002 в трите дестинации и после оставя три неща в пощенската кутия: пратката на 4001, завършена; тази на 4002, все още като .tmp; и една повредена. Урокът е завършен, когато видиш десетте зелени отметки:

✅ Arrancaron el router, los tres canales y el sondeo de la bodega
✅ Antes del embarque: la 4001 está CREADO en la API y REGISTRADO en el ERP
✅ API: la 4001 está EMBARCADO con la guía PAQX770004001
✅ API: recibió el embarque de la 4001 una sola vez
✅ ERP: la 4001 está EMBARCADO y su fila de embarque tiene la guía
✅ Socio: el 856 de la 4001 está en su SFTP y el lector X12 no le encontró fallas
✅ Socio: el 856 lleva la guía (REF*CN) y la orden (PRF)
✅ Buzón: el embarque de la 4001 se apartó a .camel/
✅ Buzón: el embarque roto se apartó a .error/ (no se perdió ni se reintenta sin fin)
✅ Buzón: el .tmp que la bodega aún escribía no se tocó (la 4002 sigue CREADO)

Виж доказателството в самата папка: ls -A buzon buzon/.camel buzon/.error. И отвори 856-цата, която стигна до партньора, mio/salida/856-4001.edi: намери товарителницата в сегмента REF*CN, а поръчката — в PRF.

Не тръгва? ./verifica solucion тества нашето решение, а diff mio/sondeo-bodega solucion/sondeo-bodega ти казва по какво се различават.

Какво виждаш Какво правиш
el sondeo tomó el .tmp Шаблонът в include не завършва на \\.json: само с embarque-.* влиза и embarque-4002.json.tmp. Или липсва include
el embarque de la 4001 no está en .camel/ Останало е noop: true или move не носи ${file:name}
el embarque roto no está en .error/ Липсва moveFailed
le faltan las tablas embarque y entrega Твоят ERP е отпреди този урок: пресъздай го, както казва „Преди да започнеш“
El puerto 8080 está ocupado Оставил си да работят услугите от друг урок: docker compose … down в неговата папка

Какво учи това извън курса

Много системи не викат: оставят файлове. Складове, банки и стари системи предават работата си като файлове в папка или на SFTP, в часа, в който могат. Интеграцията се нагажда към това, което другият умее да прави, а не обратното.

Който прави polling, е сам. Polling-ът е малко работа, а тежкото (мапинга, викането на дестинациите) го вършат рутерът и каналите, които могат да растат с реплики. Затова compose.yaml слага replicas: 1 на polling услугата и оставя останалото да расте от другата страна на едно HTTP извикване.

По-добре да отделиш, отколкото да изтриеш. С .camel/ и .error/ всеки може да види какво е обработено и какво трябва да се прегледа, без да отваря лог.

Упражнение: второто събитие от жизнения цикъл без нови маршрути

С твоята завършена версия:

  1. Колко маршрута на канали има в рутера за изпращането и колко за създаването? Какво се променя между едното извикване и другото? (Подсказка: потърси ${variable.paso}.)
  2. Смени delay на 10000 и пусни ./verifica. Колко време отнема сега да се появи EMBARCADO? Какво печелиш и какво губиш с по-бавен polling? Върни на 2000.
  3. Отвори compose.yaml на урока. Коя услуга носи replicas: 1? Какво би станало с пратката на 4001, ако ѝ сложиш 3? Помисли за API-то, ERP и партньора поотделно: кой би го забелязал и кой — не? (Подсказка: ключът на API-то.)

Защо е направено така

Какво решихме в този урок, заедно с това, което отхвърлихме, и какво би ни накарало да си променим мнението:

  • Една папка, един-единствен polling

Преговор

  1. Какво е polling и защо е нужен при склада, а не при магазина?
  2. За какво служи всяка от четирите мерки: include, readLock, move и moveFailed, и delay?
  3. Защо файлът .tmp на 4002 не беше взет? Какво би станало, ако складът пишеше направо с окончателното име?
  4. Какво прави един повреден файл без moveFailed и защо това е проблем, макар той да не се губи?
  5. Заключителният въпрос: защо polling-ът работи в една-единствена реплика, докато рутерът и каналите могат да работят в няколко? Какво би станало, ако го правеха всички реплики?

Следва: в урок 14 складът вече не праща по един файл за поръчка: праща един с всичко, което е излязло сутринта. Един файл, няколко поръчки. Колко 856-ци очакваш?

Да обсъдим вашия проект

Предпочитате имейл? Пишете ни на hola@habil.mx