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

Урок 03 — Превод на поръчката

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

Какво ще постигнеш: сам да напишеш преводача, който превръща поръчката на магазина в поръчката за API-то, да го провериш с тестови случаи, преди да пуснеш маршрута, и да откриеш защо компютърът не събира стотинки като теб.

Преди да започнеш, ти трябват: завършен урок 02 и включена средата от урок 00:

docker compose -f infra/compose.yaml up -d --wait     # desde la carpeta raíz de la práctica

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

В урок 02 преводачът идваше готов. Днес го пишеш ти, а API-то вече иска повече: във всяка позиция — нейната сума (количество × цена), а в поръчката — общата сума. Ако общата сума не излиза до стотинка с позициите, API-то я отхвърля.

Преводачът се нарича мапинг и е написан на JSONata — малък език за преобразуване на един JSON в друг. Ще го прочетеш, преди да го напишеш: почти всичко се разбира от първия път.


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

cd lecciones/03-traducir-la-orden
cp -R inicio mio

Този път оставаш в папката на урока, не влизаш в mio/: инструментът за тестове се пуска оттук.

2. Прочети мапинга, който вече познаваш

Отвори mio/mappings/api/pedido/v1/mapeo.jsonata. Той е от урок 02:

{
  "pedido": orden,
  "tienda": tienda,
  "fecha": creada,
  "partidas": [renglones.{
    "posicion": renglon,
    "sku": sku,
    "cantidad": cantidad,
    "precio": precio
  }]
}

Чете се така: отляво е името, което иска API-то; отдясно — откъде идва то в поръчката на магазина. "pedido": orden означава „полето pedido има стойността, която носи полето orden“.

Странният ред е renglones.{ … }. Точката означава „за всеки един“: за всеки ред от поръчката сглоби позиция с тези полета. Външните квадратни скоби гарантират, че винаги излиза списък, дори поръчката да носи само един ред.

Защо файлът живее в папка v1? Защото днес ще напишеш v2 до нея, без да пипаш v1. Ако нещо се обърка, маршрутът може да се върне към предишната версия със смяна на едно-единствено число.

3. Прочети еталонните тестови случаи

Отвори папката mio/mappings/api/pedido/v2/cases/. В нея има три случая и всеки е двойка файлове:

Файл Какво е
entrada.json Една поръчка от магазина
esperado.json Точно това, което твоят мапинг трябва да произведе от тази поръчка

Това се нарича еталонни тестови случаи: верният резултат, написан преди програмирането. Те са контролът на грешките в този урок: не е нужно да питаш никого дали мапингът ти е добър — случаите ти го казват.

Отвори cases/dos-renglones/esperado.json и го сравни с това, което произвежда v1. Кои полета са нови?

4. Предвиди

Отвори cases/centavos/entrada.json. Това е поръчка 1003, от една книжарница за канцеларски стоки:

Ред Количество Цена
Кламер 3 0.10
Ластик 7 0.70
Тетрадка 1 19.99

Преди да продължиш, запиши на лист хартия:

  1. Колко е сумата за кламера (3 × 0.10)?
  2. Каква е общата сума на поръчката?

Запази отговорите си: ще ти трябват в стъпка 6.

5. Напиши v2

Отвори mio/mappings/api/pedido/v2/mapeo.jsonata. В него има само няколко инструкции и едни празни фигурни скоби { }.

  1. Копирай там съдържанието на v1, без коментара отгоре.
  2. Добави сумата във всяка позиция. В JSONata умножението е *, а вътре в renglones.{ … } вече си застанал върху един ред, така че cantidad и precio са тези на този ред.
  3. Добави общата сума на поръчката, след "partidas". JSONata има функция $sum( … ), която събира списък от числа. Подсказка: renglones.(cantidad * precio) произвежда списъка със сумите.

Когато си готов, тествай го срещу еталонните случаи от папката на урока:

../../herramientas/probar-mapeo mio/mappings/api/pedido/v2

Инструментът пуска твоя мапинг с всеки entrada.json и сравнява резултата с неговия esperado.json. Накрая казва Casos: 3 · pasan … · fallan … (случаи, минават, не минават). Ако някой случай не мине, ти показва какво е получил; отвори го до неговия esperado.json и потърси разликата.

Първия път се бави повече, защото Camel сваля това, което му трябва. Изчакай да се появи редът със случаите.

6. Сравни с предвиждането си

Ако си написал сумата като cantidad * precio, най-вероятно случаят centavos не е минал. Виж какво е получил:

"importe": 0.30000000000000004      ← el clip
"importe": 4.8999999999999995       ← la liga
"total": 25.189999999999998

Ти предвиди 0.30 и беше прав. Компютърът — не. Той не пази десетичните числа така, както ти ги пишеш: пази ги в двоичен вид, а 0.10 в двоичен вид няма точен край, също както 1/3 в десетичен вид е 0.3333… без край. При умножението се подава това остатъчно парченце.

За човек 0.30000000000000004 и 0.30 са едно и също. За API-то — не: то сравнява общата сума със сбора на позициите до стотинка и ако не съвпадат, отхвърля поръчката с 422: El total 25.189999999999998 no cuadra con las partidas, que suman 25.19 (общата сума не съвпада с позициите). В реална система за продажби една стотинка разлика е фактура, която не излиза.

Решението е закръгляне до два знака с $round(numero, 2). Приложи го към сумата и към общата сума и тествай отново, докато видиш:

Casos: 3 · pasan 3 · fallan 0

Виждаш ли защо еталонните случаи се пишат преди програмирането? Ако беше сравнявал „на око“, 0.30000000000000004 изглежда като 0.30 и грешката щеше да стигне чак до API-то.

7. Прехвърли маршрута на v2

Новият ти мапинг съществува, но маршрутът още ползва стария. Отвори mio/orden-a-api.camel.yaml и намери реда:

uri: jsonata:mappings/api/pedido/v1/mapeo.jsonata

Промени го така, че да сочи към v2. Това е единствената промяна в маршрута.

Ако искаш да го видиш как работи, направи същото като в урок 02: от mio/ стартирай маршрута с ../../../herramientas/camel run orden-a-api.camel.yaml и в друг терминал прати поръчка 1003 (-d @../../../datos/ordenes/orden-1003.json). После попитай API-то: curl localhost:8081/pedidos/1003.

8. Провери

Спри маршрута с Ctrl+C, ако си го оставил да работи, и от папката на урока:

./verifica

Урокът е завършен, когато видиш четирите зелени отметки:

✅ El mapeo v2 pasa todos sus casos dorados
✅ La ruta usa la versión 2 del mapeo
✅ La API aceptó la orden 1003 (201)
✅ El pedido quedó con total 25.19

Първите две проверяват твоята работа; последните две ги потвърждава API-то. Ако мапингът минаваше случаите си, но маршрутът оставаше на v1, API-то щеше да получи поръчка без обща сума.

Не тръгва? ./verifica solucion тества нашето решение, а diff mio/mappings/api/pedido/v2/mapeo.jsonata solucion/mappings/api/pedido/v2/mapeo.jsonata ти казва по какво се различават.

Какво виждаш Какво правиш
Casos: 3 · pasan 2 · fallan 1 при centavos Липсва закръглянето: върни се на стъпка 6
No hay casos en … Сгрешил си папката: трябва да завършва на pedido/v2
La API no aceptó la orden 1003: llegó 422 Общата сума не излиза до стотинка: провери $round от стъпка 6
El pedido quedó con total ninguno Маршрутът още е на v1, който не праща обща сума: върни се на стъпка 7
El puerto 8080 está ocupado Останал е работещ маршрут: спри го с Ctrl+C

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

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

  • JSONata за превод между формати
  • Без еталонни тестови случаи няма мапинг

Преговор

  1. В "pedido": orden коя страна е API-то и коя — магазинът?
  2. Какво прави точката в renglones.{ … }?
  3. Какво е еталонен тестов случай и защо се пише преди мапинга?
  4. Защо 3 × 0.10 не дава точно 0.30 на компютър?
  5. Каква е ползата v2 да живее до v1, а не върху нея?

Следва: в урок 04 поръчката стига до система, която не говори JSON: ERP, който пази всичко в таблици.

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

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