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

Урок 18 — Кога две съобщения са едно и също?

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

Какво ще постигнеш: рутерът да разпознава известие, което вече е получил, дори да пристига написано по друг начин, и да не го разпределя отново. И да различава това повторение от известие, което носи същия ключ с друго съдържание: това не е повторение, а конфликт, и за него се съобщава.

Преди да започнеш, ти трябват: завършени уроци 15 и 16 и включена средата от урок 00. Този урок използва нова таблица в базата на състоянието, conflicto. Ако базата ти е отпреди, пресъздай я веднъж:

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

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

В урок 16 научи, че който праща webhook, опитва отново, ако не получи своето 2xx навреме. Това има последица: рано или късно едно и също известие пристига два пъти. Днес рутерът се учи да го разпознава. Това се нарича Idempotent Consumer: да получиш два пъти едно и също оставя същия резултат, както да го получиш веднъж.

Картината: будката на входа на една сграда с нейната тетрадка за посетители. Госпожата от 302 идва в 10:00 и я записват. В 10:05 се връща, защото е забравила пропуска си: не я записват отново, вече е в тетрадката. Но ако дойде някой, който твърди, че е госпожата от 302, а не прилича на тази от снимката, пазачът нито я пуска, нито я записва отгоре: обажда се на този, който живее там. Първият случай е повторение; вторият — конфликт.


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

cd lecciones/18-cuando-dos-mensajes-son-el-mismo
cp -R inicio mio

Рутерът има нов файл, orden-router/reconocer.camel.yaml. Отвори го и прочети коментара отгоре. Казва по какво се разпознава едно съобщение:

Понятие Какво е В курса
Ключ Това, което казва за какво е съобщението orden-<orden>-<momento>, например orden-4001-entregada. Всеки канал го носи веднъж: това е UNIQUE (orden, momento, canal) на operacion
Отпечатък Това, което казва какво носи съобщението sha256 на тялото, вече нормализирано. Две тела с едно и също съдържание имат един и същ отпечатък

С тези две части излизат три случая:

Случай Ключ Отпечатък Какво отговаря рутерът Какво прави
нов Няма операции с този ключ — 202 recibida Записва и разпределя, както до урок 17
повторение Вече съществува Същият 202 repetido Нищо: вече го имаше
конфликт Вече съществува Друг 409 conflicto Записва го в таблицата conflicto, съобщава в лога и не презаписва записаното

В долната част на файла е маршрутът recibir-momento, който вече използва това решение: чете ${variable.visto} и отговаря или записва според случая. Твоята работа е маршрутът, който попълва тази променлива, reconocer.

2. Предвиди

Отговори на лист хартия:

  1. Куриерската фирма съобщава два пъти за доставката на 4001, с едно и също съдържание. Колко 214-ки очакваш на SFTP на партньора? Колко събития в API-то?
  2. Второто известие носи същото, но на един-единствен ред и с полетата в друг ред. Същото съобщение ли е?
  3. Пристига трето известие за 4001 със същия ключ и друга товарителница. Какво трябва да стане с товарителницата, която вече имат API-то и ERP?

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

./verifica inicio

Първото известие минава. Второто връща грешка: маршрутът от inicio/ вижда всичко като ново, опитва да запише операциите още веднъж и UNIQUE на operacion го спира. Нищо не се е дублирало, но куриерската фирма получава грешка за нещо, което всъщност имахме, а както научи в урок 16, изпращач, който получава грешка, праща отново. А известието с друга товарителница също не се различава: то е просто още една грешка.

3. Разпознай това, което пристига

Отвори mio/orden-router/reconocer.camel.yaml и намери маршрута reconocer. Днес той само слага visto на nuevo. Има четири TODO:

TODO Какво пишеш За какво
1 Един to със sql:, който връща две колони: nueva, отпечатъка на пристигналото, и guardada, отпечатъка на първата операция с тази поръчка и това събитие Да сравниш пристигналото с това, което вече имаш, с една-единствена заявка
2 Един setVariable huella с новия отпечатък guardar-momento го записва във всяка операция, за да се сравнява следващия път
3 Един choice с три клона, който слага visto на nuevo, repetido или conflicto Решението, което чете recibir-momento
4 В клона за конфликт: един INSERT INTO conflicto и един log на ниво WARN, който започва с CONFLICTO orden-<orden>-<momento> Конфликтът да остане записан и някой да го види

Четири подсказки:

  • Заявката от TODO 1 е почти цялата в коментара. Носи dataSource: "#estado", outputType: SelectOne и variableReceive: huellas. С това ${variable.huellas[nueva]} и ${variable.huellas[guardada]} са двата отпечатъка.
  • За guardada — подзаявка: (SELECT huella FROM operacion WHERE orden = … AND momento = … ORDER BY id LIMIT 1). Ако няма операции, връща NULL.
  • choice сравнява така: ${variable.huellas[guardada]} == null е нов; ${variable.huellas[guardada]} == ${variable.huella} е повторение; останалото (otherwise) е конфликт.
  • Таблицата conflicto е в infra/postgres/01-estado.sql. Колоните ѝ са llave, orden, momento, huella_guardada, huella_nueva, cuerpo (като jsonb, както в урок 15) и correlacion.

Обърни внимание на реда с отпечатъка:

encode(sha256(convert_to(CAST(CAST(:#${body} AS jsonb) AS text), 'UTF8')), 'hex')

Чете се отвътре навън: тялото се превръща в jsonb, jsonb става текст, текстът става байтове, от байтовете се изчислява sha256 и резултатът се записва в шестнайсетичен вид. Важната стъпка е първата. PostgreSQL пази jsonb без излишните интервали и с ключовете в свой собствен ред, така че две тела с едно и също съдържание, написани различно, излизат еднакви, когато станат текст. Без този CAST отпечатъкът би бил този на текста точно както е пристигнал.

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

С твоя завършен reconocer махни вътрешния CAST(… AS jsonb): остави convert_to(:#${body}, 'UTF8'). Пусни ./verifica.

Преди това предвиди: второто известие на verifica носи същото съдържание на един-единствен ред и с полетата наобратно. Как ще го разпознаеш?

Излиза в червено отметката за двете известия: рутерът отговори с 409 на второто. Отпечатъкът беше взет от текста, а текстът се промени, макар съдържанието да не се е променило. Взе едно повторно изпращане за промяна и някой ще трябва да преглежда конфликт, който не съществува. Върни CAST.

5. Провери

./verifica

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

✅ Arrancaron el router (con su reconocedor de repetidos), los tres canales y el sondeo
✅ Antes de los avisos: la 4001 está EMBARCADO
✅ Los dos avisos contestaron 202, y el segundo se reconoció como repetido aunque viniera escrito distinto
✅ Estado: la entrega tiene 3 operaciones con su huella sha256 y 3 intentos, uno por canal
✅ Destinos: un solo 201 de la entrega en la API, un solo 214 en el socio y el ERP en ENTREGADO
✅ Un aviso con la misma llave y otra guía contestó 409 «conflicto»
✅ Estado: el conflicto quedó en su tabla, con la llave, lo que llegó y las dos huellas distintas
✅ Log: el router avisó el conflicto con un WARN
✅ Nada se pisó: la orden guarda la guía original, sigue habiendo 3 intentos y la API tiene la guía con la que salió

Виж таблицата на конфликта:

docker compose -f ../../infra/compose.yaml exec estado psql -U router -d estado \
  -c "SELECT llave, cuerpo->>'guia' AS guia, huella_guardada <> huella_nueva AS distintas FROM conflicto"

Не тръгва? ./verifica solucion тества нашето решение, а diff mio/orden-router/reconocer.camel.yaml solucion/orden-router/reconocer.camel.yaml ти казва по какво се различават.

Какво виждаш Какво правиш
Esperaba 202 y 202 «repetido», а второто отговори с 500 Твоят choice не е стигнал до repetido: провери дали заявката носи variableReceive: huellas и дали guardada търси по поръчка и събитие
Esperaba 202 y 202 «repetido», а второто отговори с 409 Отпечатъкът се взема от текста: липсва вътрешният CAST(:#${body} AS jsonb)
esperaba 3 operaciones con huella, а има 0 отпечатъка Липсва TODO 2: променливата huella не съществува, когато guardar-momento я записва
Esperaba 409 para el aviso con otra guía Клонът за конфликт не слага visto на conflicto или choice го взема за нов
esperaba una fila en conflicto Липсва INSERT INTO conflicto или не носи dataSource: "#estado"
no hay un WARN «CONFLICTO orden-4001-entregada» log не носи loggingLevel: WARN или съобщението не започва с CONFLICTO orden-${variable.orden}-${variable.momento}
El puerto 8080 está ocupado Услугите от друго пускане са останали вдигнати: DONDE=mio docker compose -f compose.yaml down

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

Проектирай така, сякаш едно съобщение може да пристигне повече от веднъж. В много потоци с повторни опити, като този, се гарантира, че то ще пристигне „поне веднъж“, а не „точно веднъж“: повторните опити пазят от загуба, а в замяна носят повторения. Който получава, се грижи да ги разпознае. Затова почти всеки сериозен API за плащания или пратки иска ключ за идемпотентност.

Ключът идва от бизнеса, не от случайността. Ново случайно число при всяко изпращане би направило така, че всяко повторно изпращане да изглежда като друго съобщение. orden-4001-entregada е същият всеки път, когато куриерската фирма праща отново, и затова върши работа.

Ключът и отпечатъкът отговарят на различни въпроси. Ключът казва дали вече си видял нещо за това; отпечатъкът — дали е същото. Само с ключа една промяна минава за повторение и се губи. Само с отпечатъка същото известие с друга дата на изпращане би минало за ново.

Конфликтът не го решава програмата. Да останеш безшумно с първото или с последното би значело да решиш вместо някого. Записва се, съобщава се и го решава човек.

Упражнение: тетрадката в будката

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

  1. Напиши на хартия ключа на тези три съобщения: пратката на 4002, доставката на 4002 и доставката на
    1. Защо като ключ не върши работа случайно число, което рутерът генерира при получаване?
  2. Изчисли на ръка, с psql, отпечатъка на {"orden":"4001","guia":"X"} и на { "guia": "X", "orden": "4001" }, със и без CAST към jsonb. Използвай SELECT encode(sha256(convert_to(CAST('…' AS jsonb)::text, 'UTF8')), 'hex'). Колко различни отпечатъка ти излизат във всеки случай?
  3. В известието на куриерската фирма кое поле би могло да се промени между едно повторно изпращане и друго, без да се променя случилото се? (Подсказка: помисли кога е пратено известието, а не кога е доставено.) Какво би станало с отпечатъка? Запиши отговора си: този урок не го решава.

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

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

  • Едно съобщение се разпознава по ключа си, а съдържанието му — по отпечатъка

Преговор

  1. Какво е Idempotent Consumer? Кажи го с примера за будката.
  2. Какво е ключът на едно събитие от жизнения цикъл в този курс и откъде идва?
  3. Какво е отпечатъкът и защо се взема, след като тялото се превърне в jsonb?
  4. Защо на повторението се отговаря с 202, а не с грешка? (Върни се към урок 16.)
  5. Заключителният въпрос: едно повторение и един конфликт имат един и същ ключ. Какво ги различава, какво отговаря рутерът на всяко и защо конфликтът не презаписва записаното?

Следва: в урок 19 проблемът е обратният. Не пристига два пъти: изобщо не пристига. API-то не отговаря и рутерът трябва да опита отново, без да разбърка събитията на поръчката.

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

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