@veaba/qrcode-rust

Pure Rust QR Code Generator

简介

使用纯 Rust 语言实现的高性能 QRCode 生成器，是 @veaba/qrcode-js 的 Rust 移植版本。提供一致的 API 设计，支持生成可扫描的二维码 SVG 输出。

特性

✅ 纯 Rust 实现 - 无外部依赖，易于集成
✅ QRCode 生成 - 支持 1-40 版本的 QRCode 生成
✅ SVG 输出 - 高质量矢量图形输出
✅ 4 级纠错 - 支持 L/M/Q/H 四种错误纠正级别
✅ UTF-8 支持 - 完整的 Unicode 字符支持
✅ 扫描验证 - 生成的二维码可通过标准扫码器识别
✅ 高性能 - 相比 JS 版本有显著的性能提升

状态

✅ 生产就绪 - 核心功能完整，已通过实际扫描验证

功能完成度

功能	状态	说明
QRCode 生成	✅ 完成	支持 1-40 版本
SVG 输出	✅ 完成	支持自定义尺寸和颜色
错误纠正	✅ 完成	L/M/Q/H 四级别
UTF-8 编码	✅ 完成	支持 Unicode 字符
扫描验证	✅ 通过	已通过 rqrr 扫描器验证
PNG 输出	🚧 计划中	需要图像库支持
WASM 支持	🚧 计划中	通过 qrcode-wasm 提供

安装

[dependencies]
qrcode-rust = "0.1"

快速开始

use qrcode_rust::{QRCode, QRCodeOptions, QRErrorCorrectLevel};

fn main() {
    // 基础用法
    let mut qr = QRCode::new();
    qr.make_code("Hello World");

    // 带选项的用法
    let mut qr = QRCode::with_options(QRCodeOptions {
        width: 256,
        height: 256,
        color_dark: String::from("#000000"),
        color_light: String::from("#ffffff"),
        correct_level: QRErrorCorrectLevel::M,
    });
    qr.make_code("https://github.com/veaba/qrcodes");

    // 生成 SVG
    let svg = qr.get_svg();
    println!("{}", svg);
}

API 文档

QRCode

`new()`

创建默认配置的 QRCode 实例。

let mut qr = QRCode::new();
qr.make_code("Hello World");

`with_options(options: QRCodeOptions)`

创建带配置的 QRCode 实例。

let qr = QRCode::with_options(QRCodeOptions {
    width: 512,
    height: 512,
    color_dark: String::from("#FF0000"),
    color_light: String::from("#FFFFFF"),
    correct_level: QRErrorCorrectLevel::H,
});

`make_code(text: &str)`

生成指定文本的 QRCode。

qr.make_code("Your text here");

`get_svg() -> String`

获取 SVG 格式的 QRCode。

let svg = qr.get_svg();
std::fs::write("output.svg", svg).unwrap();

`is_dark(row: i32, col: i32) -> bool`

检查指定位置的模块是否为深色。

if qr.is_dark(0, 0) {
    println!("左上角模块是深色");
}

`get_module_count() -> i32`

获取 QRCode 的模块数量。

let count = qr.get_module_count();
println!("QRCode 是 {}x{} 模块", count, count);

QRCodeOptions

pub struct QRCodeOptions {
    pub width: i32,           // SVG 宽度（像素）
    pub height: i32,          // SVG 高度（像素）
    pub color_dark: String,   // 深色模块颜色
    pub color_light: String,  // 浅色背景颜色
    pub correct_level: QRErrorCorrectLevel,  // 错误纠正级别
}

QRErrorCorrectLevel

错误纠正级别枚举：

pub enum QRErrorCorrectLevel {
    L = 1,  // ~7% 纠错能力
    M = 0,  // ~15% 纠错能力
    Q = 3,  // ~25% 纠错能力
    H = 2,  // ~30% 纠错能力
}

开发

构建

cd packages/qrcode-rust
cargo build

运行测试

# 运行所有测试
cargo test

# 运行特定测试
cargo test test_qrcode_basic_creation

# 运行测试并显示输出
cargo test -- --nocapture

验证工具

项目包含完整的验证工具，可以验证生成的 QRCode 是否能被正确扫描：

cd ../bench/rust-tools

# 验证生成结果
cargo run --release --features validation --bin veaba-qr -- "你的文本"

调试示例

# 运行调试示例
cargo run --example debug_a
cargo run --example debug_compare

# 生成测试 SVG
cargo run --example test_visual

性能

在 M 级别下，生成 "Hello World" 的性能对比：

实现	生成时间	模块大小
qrcode-rust	~75µs	21x21 (v1)
qrcode-js	~200µs	21x21 (v1)

测试环境：Windows 11, Ryzen 9 5900X, release 模式

架构

src/
├── lib.rs              # 库入口，重新导出公共 API
├── qr_code.rs          # QRCode 核心实现
├── qr_code_model.rs    # 数据模型和常量表
├── qr_math.rs          # Galois Field 数学运算
├── qr_polynomial.rs    # 多项式和 Reed-Solomon 纠错
├── qr_rs_block.rs      # RS 块配置
├── qr_util.rs          # 工具函数
├── qr_bit_buffer.rs    # 位缓冲区
├── qr_8bit_byte.rs     # 8位字节数据编码
└── examples/           # 示例代码
    ├── debug_a.rs
    ├── debug_compare.rs
    └── test_visual.rs

已知限制

单字符边界情况 - 某些单字符输入（如 "A"）可能导致验证失败，多字符输入工作正常
PNG 输出 - 目前仅支持 SVG，PNG 输出需要额外的图像库依赖
WASM 编译 - WASM 版本通过 @veaba/qrcode-wasm 包提供

版本兼容性

Rust 1.70+
无外部依赖
支持 std 环境

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License

变更日志

0.1.0 (当前)

✅ 核心 QRCode 生成功能
✅ SVG 输出支持
✅ 四级错误纠正
✅ UTF-8/Unicode 支持
✅ 完整的单元测试
✅ 扫描验证通过

历史变更

2026-02-06: 删除 examples/ 目录，功能由 bench/rust-tools 覆盖，保持包目录干净。

待办事项

修复单字符边界情况
添加 PNG 输出支持
优化内存使用
添加更多样式选项

qrcode-rust 0.1.3