Τα τιμολόγια και οι αποδείξεις μοιράζονται την ίδια είσοδο. Πώς να αποφύγετε την ανάμειξη των δύο δομών;

Μία διεπαφή δέχεται τόσο τιμολόγια όσο και αποδείξεις και είναι εύκολο να γράψετε μεγάλα αντικείμενα με "όλα τα πεδία προαιρετικά". Ένα τέτοιο αντικείμενο μπορεί να χωρέσει οτιδήποτε, αλλά είναι δύσκολο να πούμε τι ακριβώς λαμβάνεται. Θα ήταν πιο σαφές να διατηρήσετε δύο χωριστές συμβάσεις και να επιλέξετε ένα από αυτά με το πεδίο ρητού τύπου.

Τα τιμολόγια και οι αποδείξεις τοποθετούνται συχνά στην ίδια διεπαφή για επεξεργασία, αλλά εάν χρησιμοποιείται μόνο ένα ευρύ αντικείμενο με "όλα τα πεδία προαιρετικά" για τη λήψη του, μπορεί να φιλοξενήσει οποιαδήποτε είσοδο, αλλά δεν μπορεί να πει τι είδους έγγραφο ελήφθη. Αυτό το άρθρο προορίζεται για προγραμματιστές και επιχειρηματικό προσωπικό που χρειάζεται να σχεδιάσουν μια διεπαφή λήψης εγγράφων ή να διατηρήσουν κανόνες επικύρωσης σχήματος JSON. Αφού διαβάσετε αυτό, θα μάθετε πώς να διατηρείτε δύο ανεξάρτητα συμβόλαια, να επιλέγετε ένα με πεδίο ρητού τύπου και να χειρίζεστε διενέξεις κλάδου και άγνωστους τύπους.

Τα παραδείγματα σε αυτό το άρθρο χρησιμοποιούν συνθετικά δείγματα για να επιδείξουν μεθόδους επεξεργασίας. Ο κώδικας έχει ελεγχθεί με παραδείγματα σε απομονωμένο περιβάλλον, αλλά αυτό δεν αποτελεί εγγύηση για όλα τα πραγματικά αρχεία ή την απόδοση του προϊόντος. Πριν επεξεργαστείτε σημαντικά έγγραφα, διατηρήστε τα πρωτότυπα και ελέγξτε τα σύμφωνα με τα όρια και τα στοιχεία αποδοχής στο κείμενο.

Πώς να αντιμετωπίσετε την κοινόχρηστη είσοδο τιμολογίων και αποδείξεων; Μια φράση συμπέρασμα

Όταν λαμβάνετε δύο έγγραφα από την ίδια πύλη, είναι πιο σαφές να διατηρείτε δύο ξεχωριστά συμβόλαια και να χρησιμοποιείτε το απαιτούμενο πεδίο kind για να επιλέξετε ένα από αυτά, αντί να χρησιμοποιείτε ένα ευρύ αντικείμενο που μπορεί να χωρέσει τα πάντα.

την κατάστασή σαςΣυνιστώμενες πρακτικέςλόγος
Η ίδια διεπαφή χρειάζεται να λαμβάνει τιμολόγια και αποδείξειςΔιατηρήστε δύο ξεχωριστά συμβόλαια, επιλεγμένα με το απαιτούμενο πεδίο είδουςΈνα μεγάλο αντικείμενο με όλα τα πεδία προαιρετικά μπορεί να χωρέσει οτιδήποτε, αλλά είναι δύσκολο να εξηγηθεί τι λαμβάνεται.
Οργανώστε υποκαταστήματα με το oneOfΚάθε κλάδος χρησιμοποιεί το const για να καθορίσει το είδοςΤο oneOf απαιτεί να αντιστοιχιστεί ακριβώς ένας κλάδος. Τα επικαλυπτόμενα πεδία διακλάδωσης θα έχουν ως αποτέλεσμα την αποτυχία της νομικής εισαγωγής.
Λείπει τύπος εισαγωγής ή διένεξη πεδίουΕπιστρέψτε ένα σαφές μήνυμα σφάλματος που δείχνει αντικρουόμενα πεδία και πηγέςΜόνο η εμφάνιση "χωρίς αντιστοιχία" δεν μπορεί να βοηθήσει στον εντοπισμό του προβλήματος
Ο ταξινομητής δεν μπορεί να διακρίνει τους τύπους εγγράφωνΔιατηρήστε την άγνωστη κατάσταση και εισαγάγετε την ανεξάρτητη ουρά για ταξινόμησηΗ επιλογή ενός υποκαταστήματος τυχαία θα παράγει μόνο ψεύτικη "επιτυχία"
Η επαλήθευση δομής πέρασεΔεν σημαίνει ότι η ταξινόμηση είναι σωστή, ούτε ότι τα έγγραφα είναι αυθεντικά.Η εμπιστοσύνη ταξινόμησης, η επαλήθευση της δομής και η επιχειρηματική αυθεντικότητα είναι τρία διαφορετικά επίπεδα

Γιατί δεν μπορείτε να χρησιμοποιήσετε ένα ευρύ αντικείμενο;

Κίνδυνος να γίνουν όλα τα πεδία προαιρετικά

Όταν μια διεπαφή δέχεται τόσο τιμολόγια όσο και αποδείξεις, είναι εύκολο να γράψετε μεγάλα αντικείμενα με "όλα τα πεδία προαιρετικά". Ένα τέτοιο αντικείμενο μπορεί πράγματι να λάβει μια ποικιλία εισροών, αλλά με κόστος:

  • Είναι αδύνατο να διακρίνει κανείς από τη δομή ποιο έγγραφο ελήφθη.
  • Τα απαιτούμενα στοιχεία και τα προαιρετικά στοιχεία των δύο εγγράφων αναμειγνύονται μεταξύ τους και οι κανόνες επαλήθευσης γίνονται όλο και πιο θολοί.
  • Όταν παρουσιάζεται ένα σφάλμα, είναι δύσκολο να εξηγηθεί ακριβώς πού η είσοδος δεν είναι η αναμενόμενη.

Θα ήταν πιο σαφές να διατηρήσετε δύο χωριστές συμβάσεις και να επιλέξετε ένα από αυτά με πεδίο ρητού τύπου.

Το ## oneOf δεν είναι ένα οποιοδήποτε

Οι επικαλυπτόμενοι κλάδοι θα έχουν ως αποτέλεσμα την αποτυχία της νομικής εισαγωγής.

Το oneOf απαιτεί η είσοδος να ταιριάζει ακριβώς με έναν κλάδο. Εάν περάσουν και τα δύο υποκαταστήματα ταυτόχρονα, η συνολική επαλήθευση θα αποτύχει.

Εάν οι κλάδοι περιέχουν μόνο μερικά προαιρετικά πεδία, είναι πιθανό να επικαλύπτονται σημαντικά. Προς το παρόν, η νομική εισαγωγή αποτυγχάνει να περάσει την επαλήθευση.

Χρησιμοποιήστε το είδος και το const για να εξαλείψετε την επικάλυψη

Η χρήση του απαιτούμενου πεδίου kind συν τη σταθερή τιμή του const μπορεί να δημιουργήσει σαφή όρια μεταξύ των κλάδων και να εξαλείψει τέτοιες επικαλύψεις εκ των προτέρων.

Για περισσότερες λεπτομέρειες σχετικά με τους κανόνες συνδυασμού, ανατρέξτε στο Κανόνες συνδυασμού σχήματος JSON.

Ένα εκτελέσιμο πρωτόκολλο εκφόρτωσης

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"})

Αυτό είναι ένα απλοποιημένο παράδειγμα εγγραφής και δεν αποτελεί πλήρες μοντέλο πεδίου πραγματικού τιμολογίου. Ο κωδικός δείχνει την επιλογή κλάδου και την απόρριψη περιττών πεδίων. Ο φορολογικός συντελεστής, η επικεφαλίδα και το ποσό πρέπει να καθοριστούν χωριστά.

Εάν η επιχείρηση επιτρέπει επιπλέον πεδία, οι χώροι ονομάτων για αυτά τα πεδία θα πρέπει να είναι σαφείς και όχι να ακυρώνονται αθόρυβα όλοι οι περιορισμοί.

Μην εμφανίζετε απλώς "καμία αντιστοίχιση" στο μήνυμα σφάλματος

Εμφανίζεται μόνο το "mismatch" και ούτε οι χρήστες ούτε οι συντηρητές γνωρίζουν πού βρίσκεται το πρόβλημα. Ο παρακάτω πίνακας παραθέτει πολλές κοινές δυνατότητες εισαγωγής και τις αντίστοιχες μεθόδους ανάδρασης:

Χαρακτηριστικά εισόδουΠραγματικές αμφιβολίεςΠροτάσεις και σχόλια
το είδος λείπειΔεν είναι δυνατή η επιλογή πρωτοκόλλουΔώστε τον τύπο του εγγράφου
Διένεξη πεδίων τύπου και αριθμούΟι δύο δομές είναι μικτέςΕμφάνιση πεδίων σε διένεξη και των πηγών τους
Αριθμημένες κενές συμβολοσειρέςΤο κλειδί υπάρχει αλλά δεν έχει αξίαΚοιτάζοντας πίσω στην αριθμημένη περιοχή
Άγνωστος τύποςΗ ισχύουσα συμφωνία δεν καλύπτει το θέμα αυτόΕισαγάγετε την ανεξάρτητη ουρά που θα ταξινομηθεί

Οι αβέβαιοι τύποι χρειάζονται επίσης έξοδο

Εάν ο ταξινομητής δεν μπορεί να διακρίνει μεταξύ τιμολογίων και αποδείξεων, θα πρέπει να διατηρηθεί η άγνωστη κατάσταση αντί να επιλεγεί τυχαία ένα υποκατάστημα για να γίνει «επιτυχία».

Υπάρχουν τρία διαφορετικά επίπεδα εδώ που πρέπει να εξεταστούν ξεχωριστά:

  • Εμπιστοσύνη κατηγορίας: Πόσο σίγουρο είναι το σύστημα στην κρίση των τύπων εγγράφων.
  • Επαλήθευση δομής: Εισαγάγετε εάν η επιλεγμένη σύμβαση εκπληρώνεται.
  • Επιχειρηματική αυθεντικότητα: Εάν τα ίδια τα έγγραφα είναι γνήσια και έγκυρα.

Η δομική επαλήθευση δεν μπορεί να αποδειχθεί αντίστροφα ότι είναι σωστή, ούτε μπορεί να αποδείξει ότι το έγγραφο είναι γνήσιο.

Ο τύπος εγγράφου θα πρέπει επίσης να διατηρηθεί στη διαδικασία μετάφρασης

Το ίδιο πεδίο μπορεί να απαιτεί διαφορετική ορολογία σε διαφορετικά έγγραφα. Όταν χρησιμοποιείτε ορολογία OmniDoc και δίγλωσσες ροές εργασιών αναθεώρησης, η παροχή τύπων εγγράφων με λίστες παράδοσης βοηθά τους αναθεωρητές να κατανοήσουν το πλαίσιο του αριθμού και του ποσού.

Μην αφήσετε ένα ευρύ αντικείμενο JSON να διαγράψει αυτές τις διαφορές.

📊 Σύγκριση πυρήνων

ΜέθοδοςΜπορεί να οριστεί με σαφήνεια το είδος του εγγράφου;Εκδηλώσεις όταν τα κλαδιά επικαλύπτονταιΧειρισμός άγνωστων τύπων
Μεγάλα αντικείμενα με όλα τα πεδία προαιρετικάΕίναι δύσκολο να εξηγήσω τι ελήφθηΔεν εφαρμόζεται. Δεν υπάρχουν όρια διακλάδωσης μεταξύ πεδίωνΚαταπίνεται εύκολα από ευρείς στόχους και είναι δύσκολο να γίνει αντιληπτό
Δύο ανεξάρτητα συμβόλαια + απαιτούμενο είδοςΣαφής επιλογή χρησιμοποιώντας το πεδίο kindΧρησιμοποιήστε το const για να διορθώσετε τιμές για να μειώσετε την επικάλυψηΑφήστε την άγνωστη κατάσταση και εισαγάγετε την ουρά προς ταξινόμηση

🎯 Ποια μέθοδος σας ταιριάζει;

Εάν πρέπει να λαμβάνετε ταυτόχρονα τιμολόγια και αποδείξεις

Διατηρήστε δύο ξεχωριστά συμβόλαια και ορίστε το kind ως υποχρεωτικό πεδίο.

Εάν τα πεδία διακλάδωσης επικαλύπτονται εκτενώς

Διορθώστε το kind με το const σε κάθε κλάδο για να αποφύγετε τη νόμιμη αντιστοίχιση εισόδου πολλών κλάδων ταυτόχρονα.

Εάν το σύστημά σας επιτρέπει επιπλέον πεδία

Πρώτα, διευκρινίστε τον χώρο ονομάτων του πρόσθετου πεδίου και, στη συνέχεια, αποφασίστε πώς να χαλαρώσετε τους περιορισμούς.

Εάν ο ταξινομητής σας δεν είναι αρκετά σίγουρος

Διατηρήστε την άγνωστη κατάσταση και στείλτε τα έγγραφα στην ουρά για ταξινόμηση. Μην επιλέγετε αναγκαστικά υποκαταστήματα.

❓ Συχνές Ερωτήσεις (FAQ)

1. Γιατί να μην χρησιμοποιήσετε απλώς ένα αντικείμενο όπου όλα τα πεδία είναι προαιρετικά;

Ένας τέτοιος σύντροφος μπορεί να προσποιηθεί οτιδήποτε, ωστόσο είναι δύσκολο να πει κανείς τι ακριβώς λαμβάνει.

2. Γιατί το oneOf προκαλεί έγκυρη αποτυχία καταχώρισης;

Το oneOf απαιτεί ακριβώς αντιστοίχιση ενός κλάδου. Εάν περάσουν και οι δύο κλάδοι ταυτόχρονα, ο συνολικός έλεγχος θα αποτύχει. Αυτή η κατάσταση είναι πιθανό να συμβεί όταν τα πεδία διακλάδωσης επικαλύπτονται σε μεγάλο βαθμό.

3. Τι πρέπει να προσέξετε όταν επιτρέπετε πρόσθετα πεδία;

Ο χώρος ονομάτων για το πρόσθετο πεδίο θα πρέπει να είναι σαφώς καθορισμένος, αντί να καταργούνται αθόρυβα όλοι οι περιορισμοί.

4. Τι γίνεται αν ο ταξινομητής δεν μπορεί να προσδιορίσει τον τύπο του εγγράφου;

Διατηρήστε την άγνωστη κατάσταση και εισαγάγετε μια ανεξάρτητη ουρά για ταξινόμηση. Μην επιλέγετε τυχαία έναν κλάδο για να συγκεντρώσετε έναν επιτυχημένο κλάδο.

5. Η επιτυχία της δομικής επαλήθευσης αποδεικνύει τη γνησιότητα των εγγράφων;

Όχι. Η εμπιστοσύνη ταξινόμησης, η δομική επαλήθευση και η επιχειρηματική αυθεντικότητα είναι τρία διακριτά επίπεδα. Η δομική επαλήθευση δεν μπορεί να αποδείξει τη γνησιότητα των εγγράφων.

📝 Περίληψη

Όταν τοποθετείτε τιμολόγια και αποδείξεις στην ίδια καταχώριση, κρατήστε δύο ξεχωριστά συμβόλαια και επιλέξτε τα χρησιμοποιώντας το απαιτούμενο πεδίο kind, κάνοντας ευδιάκριτο τον τύπο του καταχωρημένου εγγράφου. Η επαλήθευση υποκαταστήματος, η ανατροφοδότηση σφαλμάτων και οι εξαγωγές άγνωστου τύπου θα πρέπει επίσης να σχεδιάζονται μαζί.

Ζήστε τώρα: Ανεβάστε το έγγραφό σας για να ξεκινήσετε τη μετάφραση, διατηρώντας την αρχική μορφοποίηση

Ενημερώθηκε 2026-11-16