Aspose.BarCode FOSS
Python
开发者指南
输入验证和错误处理

输入验证和错误处理

输入验证与错误处理

Aspose.BarCode FOSS for Python 在编码之前验证所有输入数据。每种符号系统都有专门的 InputParser 子类，用于检查字符集、长度约束和格式规则。当验证失败时，库会从 BarcodeError 层级抛出带类型的异常，以便调用者区分输入问题、编码失败和渲染问题。

InputParser 层

每种符号系统都会注册一个 InputParser 实现。当你调用 BarcodeService.generate() 时，解析器首先运行，生成一个 NormalizedPayload，如果数据对该符号系统无效，则抛出 InvalidInputError。

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)

每个符号系统解析器验证不同的规则：

  • Code128InputParser — 检查所有字符是否在 Code 128 字符集支持的 ASCII 范围内
  • Code39InputParser — 根据 Code39Options.full_ascii，将字符与 Code 39 基本或完整 ASCII 字母表进行验证
  • Ean13InputParser — 必须恰好是 12 或 13 位数字（第13位为校验位）
  • Ean8InputParser — 必须恰好是 7 或 8 位数字
  • QrInputParser — 根据所选的 QrEncodeMode（NUMERIC、ALPHANUMERIC、BYTE 或 KANJI）验证数据
  • UpcaInputParser — 必须恰好是 11 或 12 位数字
  • UpceInputParser — 必须恰好是 6、7 或 8 位数字，并符合有效的 UPC-E 模式

BarcodeError 层级结构

所有异常都继承自 BarcodeError，该类扩展了 Python 内置的 Exception。层次结构允许在不同的特定级别捕获异常块：

Exception在…时抛出
BarcodeError所有库异常的基类
InvalidInputError输入数据未通过验证（字符错误，长度错误）
EncodingError验证通过后编码逻辑失败
RenderingError渲染器在生成 SVG 或 PNG 输出时遇到错误
SymbologyNotFoundError符号名称未在 SymbologyRegistry 中注册
UnsupportedCapabilityError所请求的功能在该符号中不可用
UnsupportedFeatureError某个功能已定义但未实现
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}")

验证符号名称

SymbologyNotFoundError 在 BarcodeService.generate() 收到未注册的符号名称时抛出。SymbologyRegistry 通过规范名称或别名解析名称，因此 "code128"、"Code128" 和 "CODE128" 都解析为相同的定义。

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

校验位验证

EAN-13、EAN-8、UPC-A 和 UPC-E 符号会自动计算校验位。如果您传入包含校验位的完整数据，解析器会将其与计算值进行验证。Ean13Options 和 Ean8Options 上的 allow_check_digit_input 属性控制此行为。

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),
)

提示与最佳实践

  • 在面向用户的输入表单中捕获 InvalidInputError，因为数据可能不符合符号要求
  • 仅在不需要区分错误类型时，将 BarcodeError 用作通用捕获
  • 在调用 generate() 之前，请将符号名称与七种受支持的符号（code128、code39、ean13、ean8、qrcode、upca、upce）进行比对，以避免 SymbologyNotFoundError
  • 对于 QR 代码，当数据包含非 ASCII 字符时，请通过 QrOptions 明确设置 encoding_mode
  • 让库自行计算校验位，而不是手动提供——这可以避免不匹配

常见问题

问题原因修复
InvalidInputError 在 EAN-13数据少于12位或包含非数字字符提供恰好12或13位数字
SymbologyNotFoundError符号名称拼写错误（例如 "code_128" 而不是 "code128"）使用不含下划线的规范名称
EncodingError 在 Code 39数据包含小写字母且不含 full_ascii=True设置 Code39Options(full_ascii=True)
UnsupportedFeatureError调用已定义但尚未实现的功能检查符号配置文件中的 known_limitations
InvalidInputError 在 UPC-A数据超过12位数字提供恰好11或12位数字

FAQ

在生成之前，我如何检查符号名称是否有效？

使用 BarcodeService.registry 访问 SymbologyRegistry。如果名称未注册，调用 get_definition() 并捕获 SymbologyNotFoundError。

我可以禁用 EAN 条码的校验位验证吗？

当您提供完整长度的输入时（EAN-13 为 13 位，EAN-8 为 8 位），解析器总是会验证校验位。若想避免验证，只提供数据位（EAN-13 为 12 位，EAN-8 为 7 位），让库自行计算校验位。

如果我将二进制数据传递给一维条码符号会怎样？

InvalidInputError 被抛出。Code 128、Code 39、EAN 和 UPC 符号仅接受文本数据。对于二进制数据，请使用 QR Code 搭配 QrEncodeMode.BYTE。

库是否会验证 QR 代码的数据长度？

QrInputParser 验证数据是否符合所请求的 QR 版本的容量。如果未指定版本，库会选择能够容纳数据的最小版本。

API Reference 摘要

类 / 方法描述
InputParser.parse(data, options)抽象方法 — 验证并规范化输入为 NormalizedPayload
Code128InputParser.parse(data, options)验证 Code 128 输入字符
Code39InputParser.parse(data, options)验证 Code 39 基础或完整 ASCII 输入
Ean13InputParser.parse(data, options)验证 EAN-13 位数以及校验位
Ean8InputParser.parse(data, options)验证 EAN-8 位数以及校验位
QrInputParser.parse(data, options)验证 QR 数据是否符合所选编码模式
UpcaInputParser.parse(data, options)验证 UPC-A 位数
UpceInputParser.parse(data, options)验证 UPC-E 的数字位数和模式
BarcodeError条形码库的基础异常
InvalidInputError因无效输入数据而抛出
EncodingError在编码失败时抛出
RenderingError在渲染失败时抛出
SymbologyNotFoundError因未注册的符号名称而抛出
UnsupportedCapabilityError因不可用的功能而抛出
UnsupportedFeatureError因未实现的特性而抛出

另请参阅

 中文