majorsilence-reporting

安装

该 crate 尚未发布到 crates.io。请将其作为路径依赖添加:

# Cargo.toml
[dependencies]
majorsilence-reporting = { path = "/path/to/reporting-rust" }

# 发布到 crates.io 后:
# majorsilence-reporting = "1.0"

唯一的运行时依赖是 libloading = "0.8"。Rust 2021 版,最低支持 Rust 1.65。

快速开始

use majorsilence_reporting::RdlLibrary;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 每个进程只加载一次原生库。
    let lib = RdlLibrary::load("/path/to/rdlnative/librdlnative.so")?;

    // 构建报表配置。
    let mut rpt = lib.report("/path/to/report.rdl");
    rpt.set_connection_string("Data Source=/path/to/northwindEF.db")
       .set_parameter("Country", "Germany");

    // 导出到文件。
    rpt.export("pdf", "/tmp/output.pdf")?;

    // 或者导出到内存——不写入任何临时文件。
    let pdf_bytes: Vec<u8> = rpt.export_to_memory("pdf")?;
    println!("获得 {} 字节", pdf_bytes.len());

    Ok(())
}

加载库

RdlLibrary::load 会完成所有必要的准备工作:设置 RDLNATIVE_LIB_DIR,以 RTLD_GLOBAL 方式预加载相关的 .so / .dylib 文件,以便 .NET 的 P/Invoke 解析器能找到它们,解析所有 FFI 符号,并调用 rdl_init()。

use majorsilence_reporting::RdlLibrary;

// 在进程启动时调用一次。RdlLibrary 基于 Arc——克隆成本低,且满足 Send + Sync。
let lib = RdlLibrary::load("/path/to/librdlnative.so")?;

// 跨线程克隆(例如放入 Axum 的 state 或 Actix 的 Data 中)
let lib2 = lib.clone();
std::thread::spawn(move || {
    let mut rpt = lib2.report("/path/to/report.rdl");
    rpt.export("pdf", "/tmp/thread.pdf").unwrap();
});

核心 API

构建器方法返回 &mut Self 以支持链式调用。每次调用 export 或 export_to_memory 都会打开并关闭一个新的原生报表句柄,因此一个 Report 值可以在多次渲染中重复使用。

内存数据集

无需数据库即可将结构化数据直接传递给报表。每一行是一个 HashMap<String, String>,键为列名,值为以字符串编码的字段值。

use std::collections::HashMap;
use majorsilence_reporting::RdlLibrary;

let lib = RdlLibrary::load("/path/to/librdlnative.so")?;
let mut rpt = lib.report("/path/to/report.rdl");

let rows: Vec<HashMap<String, String>> = vec![
    [("Product", "PDF Library Pro"), ("Revenue", "1200.00"), ("Units", "3")]
        .iter().map(|(k, v)| (k.to_string(), v.to_string())).collect(),
    [("Product", "Report Designer"),  ("Revenue", "250.00"),  ("Units", "1")]
        .iter().map(|(k, v)| (k.to_string(), v.to_string())).collect(),
];

rpt.add_data("SalesData", rows);
let pdf = rpt.export_to_memory("pdf")?;

导出到内存

export_to_memory 调用原生 FFI 函数 rdl_report_render_buffer,该函数填充一个原生分配的缓冲区,并返回指针和长度。Rust 封装层会将字节复制到 Vec<u8> 中,然后调用 rdl_free。整个过程都不会写入临时文件——非常适合用于 HTTP 响应体或流水线集成。

// Axum 处理函数示例
async fn report_handler(State(lib): State<RdlLibrary>) -> impl IntoResponse {
    let mut rpt = lib.report("/reports/sales.rdl");
    rpt.set_connection_string("Data Source=/data/northwindEF.db");

    match rpt.export_to_memory("pdf") {
        Ok(bytes) => (
            StatusCode::OK,
            [("content-type", "application/pdf")],
            bytes,
        ).into_response(),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()).into_response(),
    }
}

错误处理

所有可能失败的操作都返回 Result<T, majorsilence_reporting::Error>。Error 实现了 std::error::Error,并封装了原生函数 rdl_last_error() 返回的消息。

match rpt.export_to_memory("pdf") {
    Ok(bytes) => { /* 使用 bytes */ }
    Err(e)    => eprintln!("渲染失败:{e}"),
}

// 或使用 ? 进行传播
let bytes = rpt.export_to_memory("pdf")?;

导出格式

支持全部十种格式。与 Python/PHP/Ruby 的子进程模式不同,Rust 封装层始终使用原生 FFI 路径,因此所有格式均可用。