xberg C FFI 实战：用 extract 接口提取 XLSX 电子表格内容

后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载xberg 以 Rust 为核心实现了多语言文档智能并通过 crates/xberg-ffi 暴露稳定的 C ABI让 C/C 程序可以直接调用文档提取管线。本文以仓库中 C 语言绑定生成的 XLSX 提取示例docs-site/src/snippets-generated/c/format_specific/format_xlsx.md为主体完整讲解如何用extract调用从 URI 提取 XLSX 电子表格包括ExtractInput的 JSON 构造、句柄handle生命周期管理、错误获取方式以及 FFI 层内部的 panic 捕获、句柄注册表与 Excel 提取器的安全机制读完即可在自己的 C 工程中正确集成 xberg。完整示例C 程序提取远程 XLSX原始片段对应的场景是XLSX spreadsheet extraction using extract—— 使用 C FFI 的extract入口从一个 URI 指向的.xlsx文件提取内容。仓库中该示例的完整代码如下#include assert.h #include stdint.h #include stdio.h #include stdlib.h #include string.h #include xberg.h int main(void) { XBERGAlefHandle input_handle xberg_extract_input_from_json({\kind\:\uri\,\mime_type\:\application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\,\uri\:\https://example.com/xlsx/stanley_cups.xlsx\}); XBERGAlefHandle result xberg_extract(input_handle, 0); xberg_extract_input_free(input_handle); xberg_extraction_result_free(result); return EXIT_SUCCESS; }这段代码的骨架只有四行但每一行都对应 xberg C API 的一条核心约定xberg_extract_input_from_json把一段 JSON 字符串反序列化为ExtractInput返回一个不透明句柄。JSON 里三个关键字段kind: uri声明输入来源是 URI另一种是内存字节 bytesmime_type显式指定 MIME 类型。XLSX 的标准 MIME 是application/vnd.openxmlformats-officedocument.spreadsheetml.sheet该 MIME 正是 Excel 提取器注册时声明支持的类型之一见 crates/xberg/src/extractors/excel.rs 中对 OOXML 包 MIME 的匹配逻辑uri待提取文件的 URL。xberg_extract(input_handle, config)核心提取入口接收输入句柄与配置句柄返回一个ExtractionResult句柄失败返回 0。xberg_extract_input_free/xberg_extraction_result_free每个非零句柄都必须用对应的*_free函数释放。注意释放input_handle要在xberg_extract调用之后——xberg_extract内部会克隆出ExtractInput值并不持有该句柄但按先使用、后释放的顺序写可以避免任何误用。需要说明的前提该片段由 alef 工具链自动生成文件头注释标明 This file is auto-generated by alef — DO NOT EDIT其 frontmatter 中level: typecheck、side_effect: server表示它主要作为各语言绑定的一致性契约与类型检查基准而不是可直接照抄到生产环境的完整程序——特别是示例中xberg_extract的第二个参数传了0而库内约定 0 是非法句柄占位值见下文。这套调用的正确性与 e2e 契约一一对应fixtures/format_specific/format_xlsx.json 中定义了同一场景的契约——调用extract、输入{kind: uri, uri: .../stanley_cups.xlsx, mime_type: spreadsheetml.sheet}、由 mock 服务器按content-type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet响应对应真实测试文件 crates/xberg/test_documents/xlsx 中的 stanley_cups.xlsx断言结果为not_error。也就是说C 片段与 Python、Go、Java 等 15 种绑定使用同一套契约验证跨语言行为一致是有测试保障的。C FFI 层句柄模型与 API 约定xberg 的 C 接口设计在 crates/xberg-ffi/include/xberg.h由 cbindgen 自动生成共 3 万余行中完整声明。理解 XLSX 提取前先掌握三个约定1. 不透明句柄与类型化注册表。所有复杂类型ExtractInput、ExtractionConfig、ExtractionResult、ExtractedDocument等在 C 侧都是一个 64 位整数句柄XBERGAlefHandle0 表示空/无效。从源码结构看crates/xberg-ffi/src/lib.rs句柄背后是一张 Rust 侧的全局注册表insert_handle::T存入时记录类型TypeId跨 FFI 边界取值时通过acquire_handles校验类型匹配——xberg_extract会显式断言第一个参数必须是ExtractInput类型句柄、第二个必须是ExtractionConfig类型句柄把传错句柄从未定义行为降级为可捕获的错误码。2. 每个 FFI 调用都被 panic 捕获包裹。以xberg_extract的实现为例crates/xberg-ffi/src/lib.rs入参句柄加锁取出ExtractInput的克隆与ExtractionConfig的引用通过get_ffi_runtime().block_on(async { xberg::extract(input, config).await })在库内建的 tokio 运行时上执行真正的异步提取成功则把ExtractionResult存入注册表返回新句柄失败包括 Rust 层 panic则通过set_last_error(code, message)记录错误并返回 0panic 本身被catch_unwind拦截不会跨越 FFI 边界导致宿主进程崩溃。3. 统一的全局错误通道。失败时调用方应检查返回的 0/NULL然后读取库设置的最后错误错误码 人类可读消息。JSON 解析失败、非法句柄如 zero is not a valid handle for parameter config、句柄注册表被污染等都会走这条通道而不是崩溃。xberg_extract 调用链细节把示例代码放回源码看xberg_extract(input_handle, 0)内部实际执行了这些步骤crates/xberg-ffi/src/lib.rsxberg_extract(input, config) ├─ 校验 input 句柄类型为 ExtractInputconfig 句柄类型为 ExtractionConfig ├─ 0 句柄 → 记录 zero is not a valid handle 错误并返回 0 ├─ 克隆 ExtractInput借用 ExtractionConfig └─ block_on(xberg::extract(input, config)) └─ 核心管线URI 下载 → 按 MIME 分派提取器 → 生成 ExtractedDocument → 包进 ExtractionResult 信封核心管线对 XLSX 的处理路径是URI 输入被下载后按 MIME 类型在提取器注册表中查找声明支持application/vnd.openxmlformats-officedocument.spreadsheetml.sheet的提取器路由到 Excel 提取器crates/xberg/src/extractors/excel.rs最终产出的ExtractionResult包含每个文档的ExtractedDocument文本内容、元数据、警告等。生产代码中不要照抄config 0。正确的做法是用xberg_extraction_config_from_json从 JSON 构造配置句柄再传入例如XBERGAlefHandle config xberg_extraction_config_from_json({}); if (config ! 0) { XBERGAlefHandle result xberg_extract(input_handle, config); // 读取 result如序列化为 JSON 再交给 C 侧解析…… xberg_extraction_config_free(config); }ExtractionConfig的完整字段可以从 C 头文件逐一访问每个字段都有对应的xberg_extraction_config_*getter常用的包括result_format结果结构、output_format如 Markdown、pages、security_limits安全限制、extraction_timeout_secs提取超时等。对于 XLSX 这类纯文本表格默认配置即可工作需要控制资源消耗时可显式设置security_limits。Excel 提取器内部内容、安全与警告xberg 的 Excel 提取器在 crates/xberg/src/extractors/excel.rs 中实现围绕 workbook → sheet → cell 的模型做三件事理解它们有助于预判 XLSX 提取结果中会出现什么工作簿与元数据。结果元数据中的ExcelMetadata标识文档为电子表格来源并保存工作表数量与表名每个工作表的内容会被转换为表格结构Markdown 表格或结构化 cells随ExtractedDocument返回。DDE/外部调用公式扫描。这是 XLSX 提取器独有的安全增值提取器会用正则扫描所有单元格匹配DDE(、WEBSERVICE(、HYPERLINK(、cmd|等已知注入向量模式crates/xberg/src/extractors/excel.rs。命中的单元格会生成ProcessingWarning携带工作表名、行列坐标和公式分类DDE / WEBSERVICE / HYPERLINK / ExternalCall上限 100 条以避免对抗性文档刷屏。也就是说你提取回来的结果里可能带有excel_dde_scan来源的警告提示某单元格含可能引用外部资源的公式——这类工作簿在下游处理前应人工复核。资源预算校验。提取前会按SecurityBudget校验工作簿规模逐表累加单元格数量受max_table_cells约束与文本量受max_content_size约束超预算直接报错crates/xberg/src/extractors/excel.rs。这与ExtractionConfig.security_limits联动为服务端批量提取 XLSX 提供防 DoS 的硬边界。另外对 OOXML ZIP 包.xlsx 及其宏启用变体中可能内嵌的对象xl/embeddings/提取器还有专门的嵌入文件处理路径是否提取由配置控制。测试与验证这份示例在仓库里如何被检查原始片段不是孤立存在的它挂接在仓库的 e2e 契约体系上契约定义fixtures/format_specific/format_xlsx.json 声明输入URI MIME mock 服务器响应与断言not_error。各语言绑定生成对应代码C 侧生成物即 docs-site/src/snippets-generated/c/format_specific/format_xlsx.md本文章主体文件内保留alef:hash用于新鲜度校验可用alef verify验证、alef e2e generate重新生成。核心测试文件存在仓库根 test_documents 与 crates/xberg/test_documents 目录存放 stanley_cups.xlsx 等测试工作簿。如果你在自己的项目里做集成测试建议照抄这个模式固定一个已知内容的 XLSX或本地 HTTP mock断言不报错 结果包含预期表名/单元格而不是只断言退出码。小结在 C 工程中调用 xberg 提取 XLSX 的最小闭环是xberg_extract_input_from_jsonkinduri 完整 MIME 类型→xberg_extract传入合法的ExtractionConfig句柄→ 读取结果 →*_free释放全部句柄0 句柄与 NULL 指针是错误而非异常所有 FFI 调用都做了 panic 捕获与句柄类型校验失败时通过全局错误通道返回码与消息XLSX 结果中除表格内容外还可能有 DDE 公式安全警告与资源预算报错这些是 crates/xberg/src/extractors/excel.rs 内置的安全能力建议在服务端场景中保持启用。进一步阅读C 头文件 crates/xberg-ffi/include/xberg.h全部函数声明与文档注释、FFI 实现 crates/xberg-ffi/src/lib.rs、XLSX 契约 fixtures/format_specific/format_xlsx.json、Excel 提取器 crates/xberg/src/extractors/excel.rs。赞分享后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载相关推荐xberg C FFI 实战用 extract 接口从 URI 提取 PPTX 演示文稿内容xberg C FFI 实战用 extract 接口从 URI 提取 PPTX 演示文稿内容 本篇以 xberg 仓库中自动生成的 C 语言 E2E 示例 f后端AI 应用NLPxberg C FFI 实战用 extract 完成独立 PDF 文本提取从 ExtractInput 到结果校验xberg C FFI 实战用 extract 完成独立 PDF 文本提取从 ExtractInput 到结果校验 本文基于 xberg 仓库中自动生成的后端AI 应用NLPXberg C FFI 实战使用 extract API 对 HWPX 韩文办公文档进行独立文本提取Xberg C FFI 实战使用 extract API 对 HWPX 韩文办公文档进行独立文本提取 本篇技术指南围绕 XbergRust 核心的 Poly后端AI 应用NLP上一篇TypeSpec 无 server 场景下的 http-client-js 客户端生成必填 endpoint 的构造函数模式下一篇流放之路伤害总是算不明白用免费开源的Path of Building离线规划10分钟跑通你的第一套Build创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考