Walidacja danych wejściowych i obsługa błędów

Walidacja danych wejściowych i obsługa błędów

Aspose.BarCode FOSS for Python waliduje wszystkie dane wejściowe przed kodowaniem. Każda symbologia ma dedykowaną podklasę InputParser, która sprawdza zestawy znaków, ograniczenia długości oraz zasady formatowania. Gdy walidacja nie powiedzie się, biblioteka podnosi typowane wyjątki z hierarchii BarcodeError, aby wywołujący mógł odróżnić problemy z wejściem, niepowodzenia kodowania i problemy z renderowaniem.

Warstwa InputParser

Każda symbologia rejestruje implementację InputParser. Gdy wywołujesz BarcodeService.generate(), najpierw uruchamiany jest parser, który generuje NormalizedPayload lub podnosi InvalidInputError, jeśli dane nie są prawidłowe dla tej symbologii.

from aspose_barcode_foss import BarcodeService

service = BarcodeService()

# Valid Code 128 input — passes the Code128InputParser
barcode = service.generate("code128", "VALID-DATA-001")

# Invalid EAN-13 input — too few digits
try:
    barcode = service.generate("ean13", "123")
except Exception as e:
    print(type(e).__name__, e)

Parser każdej symbologii waliduje różne zasady:

• Code128InputParser — sprawdza, czy wszystkie znaki znajdują się w zakresie ASCII obsługiwanym przez zestawy znaków Code 128
• Code39InputParser — waliduje znaki względem bazowego lub pełnego alfabetu ASCII Code 39, w zależności od Code39Options.full_ascii
• Ean13InputParser — wymaga dokładnie 12 lub 13 cyfr (13-ta jest cyfrą kontrolną)
• Ean8InputParser — wymaga dokładnie 7 lub 8 cyfr
• QrInputParser — waliduje dane względem wybranego QrEncodeMode (NUMERIC, ALPHANUMERIC, BYTE lub KANJI)
• UpcaInputParser — wymaga dokładnie 11 lub 12 cyfr
• UpceInputParser — wymaga dokładnie 6, 7 lub 8 cyfr z prawidłowym wzorcem UPC-E

Hierarchia BarcodeError

Wszystkie wyjątki dziedziczą po BarcodeError, który rozszerza wbudowany Exception klasy Python. Hierarchia umożliwia bloki catch na różnych poziomach szczegółowości:

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss.errors import (
    BarcodeError,
    InvalidInputError,
    EncodingError,
    SymbologyNotFoundError,
)

service = BarcodeService()

try:
    barcode = service.generate("code128", "TEST-001")
    svg = barcode.to_svg()
except InvalidInputError as e:
    print(f"Input rejected: {e}")
except EncodingError as e:
    print(f"Encoding failed: {e}")
except SymbologyNotFoundError as e:
    print(f"Unknown symbology: {e}")
except BarcodeError as e:
    print(f"Barcode error: {e}")

Walidacja nazw symboli

SymbologyNotFoundError jest podnoszony, gdy BarcodeService.generate() otrzymuje nazwę symboliki, która nie jest zarejestrowana. SymbologyRegistry rozwiązuje nazwy według nazwy kanonicznej lub aliasu, więc "code128", "Code128" i "CODE128" wszystkie rozwiążą się do tej samej definicji.

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss.errors import SymbologyNotFoundError

service = BarcodeService()

try:
    barcode = service.generate("invalid_type", "data")
except SymbologyNotFoundError as e:
    print(f"Not found: {e}")

Walidacja cyfry kontrolnej

EAN-13, EAN-8, UPC-A i UPC-E symbologie automatycznie obliczają cyfry kontrolne. Jeśli przekażesz pełne dane wraz z cyfrą kontrolną, parser weryfikuje ją względem obliczonej wartości. Właściwość allow_check_digit_input w Ean13Options i Ean8Options kontroluje to zachowanie.

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss import Ean13Options

service = BarcodeService()

# 12 digits — check digit computed automatically
barcode = service.generate("ean13", "590123412345")

# 13 digits — parser verifies the 13th digit matches the computed value
barcode = service.generate(
    "ean13", "5901234123457",
    encode=Ean13Options(allow_check_digit_input=True),
)

Wskazówki i najlepsze praktyki

• Przechwytuj InvalidInputError w formularzach skierowanych do użytkownika, gdzie dane mogą nie spełniać wymagań symboliki
• Używaj BarcodeError jako rozwiązania ogólnego tylko wtedy, gdy nie musisz rozróżniać typów błędów
• Sprawdź nazwę symboliki względem siedmiu obsługiwanych symbolik (code128, code39, ean13, ean8, qrcode, upca, upce) przed wywołaniem generate(), aby uniknąć SymbologyNotFoundError
• Dla kodów QR, ustaw encoding_mode explicite za pomocą QrOptions, gdy dane zawierają znaki nie-ASCII
• Pozwól bibliotece obliczać cyfry kontrolne zamiast podawać je ręcznie — to zapobiega niezgodnościom

Typowe problemy

FAQ

Jak sprawdzić, czy nazwa symboliki jest prawidłowa przed wygenerowaniem?

Użyj BarcodeService.registry, aby uzyskać dostęp do SymbologyRegistry. Wywołaj get_definition() i przechwyć SymbologyNotFoundError, jeśli nazwa nie jest zarejestrowana.

Czy mogę wyłączyć walidację cyfry kontrolnej dla kodów kreskowych EAN?

Parser zawsze weryfikuje cyfry kontrolne, gdy podasz pełną długość danych (13 cyfr dla EAN-13, 8 dla EAN-8). Aby uniknąć weryfikacji, podaj tylko cyfry danych (12 dla EAN-13, 7 dla EAN-8) i pozwól bibliotece obliczyć cyfrę kontrolną.

Co się stanie, jeśli przekażę dane binarne do symboliki kodu kreskowego 1D?

InvalidInputError jest zgłaszany. Code 128, Code 39, EAN i UPC symbologie akceptują wyłącznie dane tekstowe. Dla danych binarnych użyj QR Code z QrEncodeMode.BYTE.

Czy biblioteka weryfikuje długość danych dla kodów QR?

QrInputParser sprawdza, czy dane mieszczą się w pojemności żądanej wersji QR. Jeśli nie określono wersji, biblioteka wybiera najmniejszą wersję, która pomieści dane.

Podsumowanie API Reference

Zobacz także

• Aspose.BarCode for Python — Enterprise Documentation