A számláknak és a nyugtáknak ugyanaz a bejárata. Hogyan kerüljük el a két szerkezet keveredését?
Egy felület fogadja a számlákat és a nyugtákat is, és könnyű nagy objektumokat írni "minden mező nem kötelező". Egy ilyen tárgy bármit tartalmazhat, de nehéz megmondani, hogy pontosan mit kap. Egyértelműbb lenne, ha két külön szerződést tartana meg, és az egyiket az explicit típus mezővel választaná ki.
A számlák és a bizonylatok gyakran ugyanarra a felületre kerülnek feldolgozásra, de ha csak egy széles objektumot használunk, amelyben "minden mező nem kötelező", akkor az bármilyen bevitelt képes fogadni, de nem tudja megmondani, hogy milyen bizonylat érkezik. Ez a cikk azoknak a fejlesztőknek és üzleti dolgozóknak szól, akiknek dokumentumfogadó felületet kell tervezniük, vagy karban kell tartaniuk a JSON-séma érvényesítési szabályait. Ennek elolvasása után megtudhatja, hogyan tarthat meg két független szerződést, hogyan válasszon ki egyet explicit típusú mezővel, és hogyan kezelje az ágak ütközését és az ismeretlen típusokat.
A cikkben szereplő példák szintetikus mintákat használnak a feldolgozási módszerek bemutatására. A kódot példákkal ellenőrizték izolált környezetben, de ez nem garancia az összes valós fájlra vagy a termék teljesítményére. 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.
Hogyan kezeljük a számlák és nyugták közös bejutását? Egy mondatos következtetés
Ha ugyanarról a portálról két dokumentumot kap, egyértelműbb, hogy két külön szerződést tart fenn, és a szükséges kind mezőt használja az egyik kiválasztásához, nem pedig egy átfogó objektumot, amely mindent tartalmaz.
| a helyzeted | Ajánlott gyakorlatok | ok |
|---|---|---|
| Ugyanazon a felületen kell fogadni a számlákat és a nyugtákat | Tartson két külön szerződést, a kötelező típus mezővel kiválasztva | Egy nagy objektum, amelynek minden mezője nem kötelező, bármit elhelyezhet, de nehéz megmagyarázni, hogy mi érkezik. |
| Szervezzen fiókokat a oneOf segítségével | Mindegyik ág a const-ot használja a fajta javítására | A oneOf pontosan egy ágat igényel. Az átfedő fiókmezők a törvényes bevitel sikertelenségét okozzák. |
| Hiányzó beviteli típus vagy mezőütközés | Világos hibaüzenetet ad vissza, amely ütköző mezőket és forrásokat mutat | Csak a „nincs egyezés"megjelenítése nem segít a probléma megtalálásában |
| Az osztályozó nem tud különbséget tenni a dokumentumtípusok között | Tartsa meg az ismeretlen állapotot, és lépjen be a besorolandó független sorba | A véletlenszerű fiókválasztás csak hamis "sikert" eredményez |
| A szerkezet ellenőrzése sikeres | Ez nem jelenti azt, hogy a minősítés helyes, és nem jelenti azt sem, hogy a dokumentumok hitelesek. | Az osztályozási megbízhatóság, a szerkezetellenőrzés és az üzleti hitelesség három különböző szint |
Miért nem használhat széles objektumot?
Az összes mező opcionálissá tételének kockázata
Ha egy felület elfogadja a számlákat és a nyugtákat is, akkor könnyű nagy objektumokat írni úgy, hogy „minden mező nem kötelező". Egy ilyen objektum valóban sokféle bemenetet kaphat, de a következők árán:
- A szerkezetből nem lehet megállapítani, hogy melyik dokumentum érkezik.
- A két dokumentum kötelező és választható tételei keverednek egymással, és az ellenőrzési szabályok egyre inkább összemosódnak.
- Ha hiba történik, nehéz pontosan megmagyarázni, hogy a bemenet hol nem a vártnak megfelelő.
Egyértelműbb lenne, ha két külön szerződést tartana meg, és az egyiket egy explicit típusú mezővel választaná ki.
A oneOf nem akármilyen
Az ágak átfedése a jogi bevitel sikertelenségét okozza.
AoneOf megköveteli, hogy a bemenet pontosan egy ágnak feleljen meg. Ha mindkét ág egyszerre halad át, az általános ellenőrzés sikertelen lesz.
Ha az ágak csak néhány nem kötelező mezőt tartalmaznak, akkor valószínűleg jelentős átfedésben lesznek. Jelenleg a jogi bemenet nem megy át az ellenőrzésen.
Az átfedés megszüntetésére használja a kind és const
A szükséges kind mező plusz a const fix értékének használatával egyértelmű határvonalak hozhatók létre az ágak között, és előre kiküszöbölhetők az ilyen átfedések.
A kombinációs szabályokkal kapcsolatos további részletekért lásd: JSON-séma kombinációs szabályok.
Egy futtatható elterelő protokoll
from jsonschema import Draft202012Validator
def branch(kind, identity):
return {
"type": "object", "additionalProperties": False,
"required": ["kind", identity],
"properties": {"kind": {"const": kind},
identity: {"type": "string", "minLength": 1}}
}
schema = {"oneOf": [branch("invoice", "invoice_number"),
branch("receipt", "receipt_number")]}
v = Draft202012Validator(schema)
valid = lambda x: not list(v.iter_errors(x))
assert valid({"kind": "invoice", "invoice_number": "I-1"})
assert valid({"kind": "receipt", "receipt_number": "R-1"})
assert not valid({"kind": "invoice", "receipt_number": "R-1"})
assert not valid({"kind": "receipt", "receipt_number": ""})
assert not valid({"kind": "invoice", "invoice_number": "I-1",
"receipt_number": "R-1"})
assert not valid({"kind": "unknown"})
Ez egy egyszerűsített példa dokumentum, nem egy teljes terepi modell egy valós számláról. A kód bemutatja az ágválasztást és a redundáns mezők elutasítását; az adókulcsokat, fejléceket és összegeket külön kell meghatározni.
Ha az üzlet további mezőket engedélyez, ezeknek a mezőknek a névtereket világosan kell meghatározni, nem pedig csendben eltávolítani az összes korlátozást.
Ne csak "mismatch" hibaüzeneteket jelenítsd meg
Csak a "eltérés" jelenik meg, és sem a felhasználók, sem a karbantartó személyzet nem tudja, hol van a probléma. Az alábbi táblázat több gyakori bemeneti funkciót és azok megfelelő visszacsatolási módszereit sorol:
| Bemeneti jellemzők | Valódi kétségek | Javaslatok visszajelzésre |
|---|---|---|
| valamilyen hiányosság | Nem választhatom ki a megállapodást | Kérjük, adja meg a dokumentum típusát |
| Típus- és számmezők ütköznek | A két szerkezet kevert | Ellentmondó mezők és azok forrásai megjelenítése |
| Számozott üres stringek | A kulcs létezik, de nincs értéke | Visszatekintve a számozott területre |
| Ismeretlen típus | A jelenlegi megállapodás nem fedi ezt | Lépj be a független sorba a besoroláshoz |
Bizonytalan típusoknak is szükségük van kijáratra
Ha a klasifikátor nem tudja megkülönböztetni a számlákat és a nyugtákat, az ismeretlen státuszt meg kell tartani, nem véletlenszerűen választani egy fiókot a "siker" érdekében.
Három különböző szintet kell külön megvizsgálni:
- Kategória-bizalom: Mennyire magabiztos a rendszer a dokumentumtípusok megítélésében.
- Struktúra ellenőrzés: Írd be, hogy a kiválasztott szerződés teljesül-e.
- Üzleti hitelesség: Maguk a dokumentumok hitelesek-e és érvényesek-e.
A szerkezeti ellenőrzés nem bizonyítható visszafordítva, és nem bizonyíthatja, hogy a dokumentum hiteles.
A dokumentumtípust a fordítási folyamatban is meg kell tartani
Ugyanaz a terület eltérő terminológiát követelhet különböző dokumentumokban. A OmniDoc terminológiát és kétnyelvű átvizsgálási munkafolyamatokat használva a dokumentumtípusok szállítási listákkal való biztosítása segít a lektoroknak megérteni a szám és mennyiség kontextusát.
Ne hagyd, hogy egy tágabb JSON objektum eltörölje ezeket a különbségeket.
📊 Alap összehasonlítás
| Módszer | Világosan meg lehet határozni a dokumentum típusát? | Megnyilvánulások, amikor az ágak átfednek | Ismeretlen típusok kezelése |
|---|---|---|---|
| Széles objektumok, minden mező opcionális | Nehéz megmagyarázni, mit kaptak | Nem alkalmazható; nincsenek ághatárok a mezők között | Könnyen elnyelték a széles célpontok által, és nehezen észrevehető |
| Két független szerződés + kötelező típus | Egyértelműen válassz a típusmező használatával | Használj const-t az értékek javítására, hogy csökkentsd az átfedést | Hagyd az ismeretlen státuszt, és lépj be a sorba a rendezésre |
🎯 Melyik módszer illik hozzád?
Ha egyszerre kell megkapnod a számlákat és a nyugtákat
Tartsanak két külön szerződést, és állítsd be a kind-t kötelező mezőként.
Ha az ági mezőid nagyban átfedik egymást
Javítsd meg kind-t const-vel minden ágban, hogy elkerüld a jogos bemeneti egyezést több ág egyidejűleg.
Ha a rendszered további mezőket enged
Először tisztázzuk az extra field névterét, majd döntsük el, hogyan lazítsuk a korlátokat.
Ha a osztályozó nem elég biztos
Tartsd meg az ismeretlen státuszt, és küldd a dokumentumokat a sorba rendezhetővé; ne válassz erőszakkal az ágazakat.
❓ Gyakran Ismételt Kérdések (GYIK)
1. Miért ne használnál egy olyan objektumot, ahol minden mező opcionális?
Egy ilyen partner bármit hamisíthat, mégis nehéz pontosan megmondani, mit kap.
2. Miért okoz OneOf érvényes belépési hibát?
A oneOf pontosan megköveteli az ág megegyezését. Ha mindkét ág egyszerre megy át, az összesített ellenőrzés sikertelenül megbukik. Ez a helyzet valószínűleg akkor fordul elő, ha az ágmezők nagymértékben átfednek.
3. Mire kell figyelni, amikor további mezőket engedélyeztek?
Az extra mező névterét világosan kell meghatározni, nem pedig csendben eltávolítani az összes korlátozást.
4. Mi van, ha a klasifikátor nem tudja meghatározni a dokumentumtípust?
Tartsd meg az ismeretlen státuszt, és lépj be egy független sorba a besoroláshoz; ne válassz véletlenszerűen egy sikeres ág összeállításához.
5. A szerkezeti ellenőrzés átmenése bizonyítja a dokumentumok hitelességét?
Nem. A besorolási megbízhatóság, a szerkezeti ellenőrzés és az üzleti hitelesség három különböző szint; a szerkezeti ellenőrzés nem bizonyíthatja a dokumentumok hitelességét.
📝 Összefoglaló
Amikor a számlákat és nyugtákat ugyanabban a bejegyzésben helyezzük el, tartsd meg két külön szerződést, és válaszd ki őket a szükséges kind mező segítségével, így a bejegyzett dokumentum típusa jól láthatóvá válik. Az ági ellenőrzést, hibavisszacsatolást és ismeretlen típusú exportokat is együtt kell tervezni.


