Съдържание на курса
Урок 13 — Пристига пратката
От Dorian Chávez · съосновател и 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. Предвиди
Отговори на лист хартия, преди да пускаш каквото и да е:
- В урок 12 се научи да пускаш три реплики на една услуга. Ако три реплики проверяваха една и съща папка, какво би могло да се случи с един файл?
- Складът записва файла малко по малко. Какво става, ако polling услугата го вземе, когато е по средата?
- Пристига повреден файл, който не е валиден 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/ всеки може да види какво е обработено и какво трябва
да се прегледа, без да отваря лог.
Упражнение: второто събитие от жизнения цикъл без нови маршрути
С твоята завършена версия:
- Колко маршрута на канали има в рутера за изпращането и колко за създаването? Какво се променя между едното
извикване и другото? (Подсказка: потърси
${variable.paso}.) - Смени
delayна 10000 и пусни./verifica. Колко време отнема сега да се появи EMBARCADO? Какво печелиш и какво губиш с по-бавен polling? Върни на 2000. - Отвори
compose.yamlна урока. Коя услуга носиreplicas: 1? Какво би станало с пратката на 4001, ако ѝ сложиш 3? Помисли за API-то, ERP и партньора поотделно: кой би го забелязал и кой — не? (Подсказка: ключът на API-то.)
Защо е направено така
Какво решихме в този урок, заедно с това, което отхвърлихме, и какво би ни накарало да си променим мнението:
- Една папка, един-единствен polling
Преговор
- Какво е polling и защо е нужен при склада, а не при магазина?
- За какво служи всяка от четирите мерки:
include,readLock,moveиmoveFailed, иdelay? - Защо файлът
.tmpна 4002 не беше взет? Какво би станало, ако складът пишеше направо с окончателното име? - Какво прави един повреден файл без
moveFailedи защо това е проблем, макар той да не се губи? - Заключителният въпрос: защо polling-ът работи в една-единствена реплика, докато рутерът и каналите могат да работят в няколко? Какво би станало, ако го правеха всички реплики?
Следва: в урок 14 складът вече не праща по един файл за поръчка: праща един с всичко, което е излязло сутринта. Един файл, няколко поръчки. Колко 856-ци очакваш?
Предпочитате имейл? Пишете ни на hola@habil.mx