A mező neve nem változott, de a jelentése megváltozott, és a downstream csendesen hibát követett el: adjon hozzá egy verziószámot a kinyerési eredményhez
A múlt heti `amount` „centet” jelentett, de ezen a héten „jüan”-ra változott, de a mező neve nem változott. A típusellenőrzés még sikeres, de az üzleti eredmények két nagyságrenddel rosszabbak lehetnek. A kivonatolási felület legveszélyesebb frissítése gyakran az, hogy nem kifejezetten jelentenek hibát, hanem halkan megváltoztatják a jelentését.
Ez a cikk azoknak a fejlesztőknek és a későbbi adatcsoportoknak szól, akik dokumentumkinyerési felületeket tartanak fenn. A kinyerési eredmények frissítése után a mezőnevek nem változhatnak, de jelentésük eltérő lesz. Például, ha a amount „fen"-ről „jüan"-ra változik, a típusellenőrzés továbbra is sikeres, de az üzleti számok két nagyságrenddel eltérhetnek.
Az alábbiakban bemutatjuk, hogyan kell használni a verziószámokat, az áttelepítési függvények törlését és az áttelepítési rekordokat az ilyen típusú problémák kezelésére. Ennek elolvasása után meghatározhatja, hogy mely frissítések igényelnek verzióváltást, és milyen információkat kell megőrizni az áttelepítés során.
A cikkben szereplő példák szintetikus mintákat használnak, és a kódot a példák egy elszigetelt környezetben ellenőrizték. Ez nem jelent garanciát minden valódi fájlra vagy termékhatásra. A fontos dokumentumok feldolgozása előtt kérjük, őrizze meg az eredeti példányokat és nézze át a szövegben szereplő határok és átvételi tételek szerint.
A mező neve nem változott, de a jelentése megváltozott. Hogyan kezeljük? Egy mondatos következtetés
Minden kimenetetschema_version címkével jelöljön meg, és explicit áttelepítési függvényekkel alakítsa át az adatok különböző verzióit ahelyett, hogy csak egy új verziót címkézne fel.
| a helyzeted | Ajánlott gyakorlatok | ok |
|---|---|---|
| Csak adjon hozzá mezőket | Adjon hozzá egy új mezőt, és rögzítse a verziót | A mezők hozzáadása nem ugyanaz, mint az egységek megváltoztatása |
| Változnak a mezőegységek vagy a szemantika | Válassza ki az érvényesítőket és az áttelepítési funkciókat verzió szerint | Az azonos nevű mezők jelentése halkan megváltozik |
| A régi rekordok definiálatlan egységekkel rendelkeznek | Tisztázza a hibákat, őrizze meg a régi adatokat és adjon hozzá bizonyítékokat | A migrációs függvények nem lehetnek találgatások |
| A downstream felemésztette a régi felületet | Verzióváltás ütemezése | A downstreamtől nem várható el, hogy automatikusan észlelje a numerikus szemantikai változásokat |
| Ellenőrizze a fordítást a kinyerési eredményekkel együtt | A generált mezők protokollverziójának megőrzése | Kényelmes ellenőrizni "miért különbözik ez az idő a legutóbbi időponttól" |
A verziószámnak együtt kell lennie a szemantikával
Egy mező hozzáadása nem ugyanaz, mint az egységek megváltoztatása. Megadhat minden kimenetet schema_version, és kiválaszthatja az érvényesítőket és az áttelepítési függvényeket verzió szerint.
A verziószámok önmagukban nem védik a rendszert. Ha minden verzió ugyanazt a differenciálatlan elemzési logikát követi, az csak egy dekorációs mező.
A verziószámú elemzés kulcsa
- Az elemzési szabályok kiválasztása verzió szerint: A különböző verziók saját érvényesítőket használnak.
- A migráció egy explicit adatátalakítás: nem közvetlenül a régi adatokat új verzióval címkézi.
- A szemantikai változásoknak nyomon követhetőnek kell lenniük: az olyan szabályokat, mint az egységek és a pontosság, felül kell vizsgálni.
A következő példa azt mutatja be, hogyan konvertálhat egész számú pontot decimális összegű karakterláncra.
Ellenőrizhető migrációs funkció
from decimal import Decimal
def migrate(record):
if record.get("schema_version") != "v1":
raise ValueError("unexpected input version")
cents = record.get("amount_cents")
if type(cents) is not int:
raise ValueError("integer cents required")
return {"schema_version": "v2",
"amount": format(Decimal(cents) / Decimal(100), ".2f"),
"currency": record["currency"]}
old = {"schema_version": "v1", "amount_cents": 12345, "currency": "USD"}
new = migrate(old)
assert new["amount"] == "123.45"
assert old["amount_cents"] == 12345
assert migrate({**old, "amount_cents": -25})["amount"] == "-0.25"
try:
migrate({**old, "amount_cents": True})
except ValueError:
pass
else:
raise AssertionError("bool is not a monetary integer here")
Ez a példa azt feltételezi, hogy a bemeneti pénznem százalékos egységkapcsolatot használ, és a kimenet két tizedesjegyű. Ez nem egy univerzális konverter, amely minden pénzegységet lefed.
A type(cents) is int szándékosan kizárja a logikai értékeket egész alosztályként a Pythonban, hogy elkerülje a True fillérként való elfogadását.
📊 Alapvető összehasonlítás: csak verziószám és verziószámú migráció
| gyakorlat | Hatás | korlátozásokat |
|---|---|---|
Csak schema_version mezőt adjon hozzá | A kimenet verzió címkével van ellátva | Ha továbbra is minden verzió ugyanazt az elemzési logikát követi, a verziószám csak dekoráció |
| Válassza ki az érvényesítőket és az áttelepítési funkciókat verzió szerint | Az azonos nevű mezők különböző verziókban egyértelmű magyarázatokat kapnak | Világosan meg kell írnod az átalakítási szabályokat minden verzióhoz |
Mit kell hagyni a migrációs nyilvántartásban?
Ajánlott a migráció során a következő információk rögzítése a nyomon követhetőség és az elterelési kezelés megkönnyítése érdekében.
| Információk | Cél | A kimaradás kockázata |
|---|---|---|
| Bemeneti és kimeneti változatok | Válaszd ki a helyes értelmezési szabályokat | Az azonos nevű mezők összezavaros jelentéssel bírnak |
| Migráld a programverziót | Ismételd meg az átalakítási eredményeket | A frissítés utáni eredmények megmagyarázhatatlanok |
| Eredeti feljegyzett személyazonosság | A forrás visszakövetése | Az új és régi adatok nem egyeztethetők össze |
| A kudarc okai | Kézi elterelés a kezelhetőséghez | A minősítetlen adatokat alapértelmezett értékekre cserélik |
Nem végtelenül kompatibilis a történelmi hibákkal
Ha maga a régi rekord egysége nem bizonyos, az átviteli függvényt nem szabad kitalálni. Megfelelőbb megközelítés egyértelmű hibát jelent meg, régi adatokat megőriz, és kiegészítő bizonyítékot kér.
Azoknál a lejstromvonalaknál, amelyek már használták a régi interfészeket, a verzióváltást is el kell szervezni, nem pedig automatikusan észlelni, hogy a numerikus szemantika megváltozott.
Források: JSON-séma gyakori kulcsszavai
A fordítás utáni ellenőrzés verzióismeretet is igényel
Amikor a kinyert mezőket használjuk a OmniDoc (termékbejegyzés) fordítások ellenőrzésére, határozd meg, melyik protokoll generálta a mezőket. A forrásfájlok, a kinyerési szabályok vagy a célnyelv változásai mind befolyásolhatják a párosítási módszert.
A verzióinformációk megőrzése miatt a "miért más, mint legelőbb" probléma lenne a "miért más, mint legutóbb", nem pedig egyszerűen a modellinstabilitásnak tulajdonítanák.
🎯 Melyik módszer illik hozzád?
Ha csak hozzáadsz egy mezőt
Közvetlenül adj hozzá egy mezőt, és rögzítsd a schema_version-t a kimenetbe.
Ha meg akarod változtatni egy mező egységét vagy jelentését
Írj független validátorokat és migrációs függvényeket új verziókhoz, és ne használd újra a régi parzálási logikát.
Ha a történelmi adategységeid nem egyértelműek
Tegye egyértelműen hibássá a migrációt, őrizze meg az eredeti adatokat, és egészítse ki a bizonyítékokat, mielőtt folytatná.
❓ Gyakran Ismételt Kérdések (GYIK)
1. Elég csak egy verziószámot hozzáadni a DPS-hez?
Nem elég. A verziószám csupán egy címke; ha minden verzió ugyanazt a parzálási logikát használja, nem védheti az üzleti következményeket.
2. Miért zárja ki az átviteli függvény a boole-okat?
A Pythonban a boole-értékek egész értékek alosztályai, és a type(cents) is int megakadályozhatja, hogy True-t úgy fogadják el, mintha egy fillér lenne.
3. Mit kell tenni, ha a régi lemezegység nem bizonyos?
Az átviteli függvényeket nem szabad kitalálni. A nyilvánvaló hibákat vissza kell küldeni, régi adatokat meg kell őrizni, és további bizonyítékokat kell kérni.
4. Milyen információkat kell elmenteni a migrációs nyilvántartásokban?
Legalább tartalmazza a bemeneti és kimeneti verziókat, migrációs program verziókat, eredeti rekordazonosítókat és a hiba okait.
📝 Összefoglaló
A mezőnevek változatlanok nem jelentik azt, hogy a jelentés változatlan marad. Verziószám hozzáadása a kimenethez, valamint a szemantikai változtatások kezelése explicit migrációs függvényekkel és migrációs rekordokkal jelentősen csökkentheti a csendes lefelé irányuló hibák kockázatát.


