Съдържание на курса
Урок 03 — Превод на поръчката
От Dorian Chávez · съосновател и 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 |
Преди да продължиш, запиши на лист хартия:
- Колко е сумата за кламера (3 × 0.10)?
- Каква е общата сума на поръчката?
Запази отговорите си: ще ти трябват в стъпка 6.
5. Напиши v2
Отвори mio/mappings/api/pedido/v2/mapeo.jsonata. В него има само няколко инструкции и едни празни фигурни скоби { }.
- Копирай там съдържанието на v1, без коментара отгоре.
- Добави сумата във всяка позиция. В JSONata умножението е
*, а вътре вrenglones.{ … }вече си застанал върху един ред, така чеcantidadиprecioса тези на този ред. - Добави общата сума на поръчката, след
"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 за превод между формати
- Без еталонни тестови случаи няма мапинг
Преговор
- В
"pedido": ordenкоя страна е API-то и коя — магазинът? - Какво прави точката в
renglones.{ … }? - Какво е еталонен тестов случай и защо се пише преди мапинга?
- Защо 3 × 0.10 не дава точно 0.30 на компютър?
- Каква е ползата v2 да живее до v1, а не върху нея?
Следва: в урок 04 поръчката стига до система, която не говори JSON: ERP, който пази всичко в таблици.
Предпочитате имейл? Пишете ни на hola@habil.mx