xberg Go 绑定实战：以原始字节（bytes）输入提取 PDF 文档内容

本文以 xberg 官方自动生成的 Go 代码示例 extract_bytes_input.md 为骨架，完整讲解如何在 Go 语言中通过内存字节（[]byte）而非文件路径向 xberg 提取引擎提交 PDF 文档，并读取结构化提取结果。读完本文，你将掌握 ExtractInput 的字段语义、xberg.Extract 的调用方式、MIME 与文件名的类型提示作用、边界输入的错误处理，以及背后 Go → C FFI → Rust 核心的完整调用链，可直接迁移到任何需要处理网络下载内容、对象存储快照或加密前原始文件的 Go 服务中。

bytes 输入：为什么需要「不落盘」提取

xberg 的提取 API 支持两类输入源（见 packages/go/binding.go 中的 ExtractInputKind 枚举）：

• ExtractInputKindBytes（"bytes"）：直接传入内存中的原始字节流；
• ExtractInputKindURI（"uri"）：传入本地路径、file:// URI 或 HTTP(S) URL。

bytes 输入的价值在于：当文档来自 HTTP 响应体、对象存储（S3/OSS）、消息队列、数据库 BLOB 字段或加密/脱敏管道时，无需先把内容写入临时文件即可交给提取引擎，既减少了磁盘 I/O，也避免了临时文件的清理与权限管理问题。这也是官方 e2e 测试套件（e2e/go/extract_test.go）与统一契约 fixture（fixtures/extract/extract_bytes_input.json）都把「从 PDF 文档按字节提取」作为一等用例的原因。

环境准备：引入 Go 包并链接静态库

xberg 的 Go 绑定是一个纯库模块（package xberg），位于仓库的 packages/go 目录，通过 cgo 静态链接 Rust 核心编译出的 libxberg_ffi.a。按照 packages/go/README.md 的说明，在仓库内开发时：

# 先构建静态 FFI 库
cargo build -p xberg-ffi --release

# cgo 会自动链接 target/release/libxberg_ffi.a
cd packages/go
go build ./...
go test ./...

在仓库之外，通过 Go Modules 引入模块（模块根是 packages/go 子目录而非仓库根），并在构建时通过 CGO_LDFLAGS 指定静态库位置：

go get github.com/xberg-io/xberg/packages/go@latest

# Linux/macOS
CGO_LDFLAGS="-L$HOME/xberg/lib -lxberg_ffi" go build

构建产物是自包含二进制，运行时不再依赖 xberg 的动态库。这是官方 README 明确声明的能力（packages/go/README.md）。

核心示例：从内存字节提取 PDF 文本

关联文档给出的完整示例（docs-site/src/snippets-generated/go/extract/extract_bytes_input.md）如下，它读取一个 PDF 文件的字节、标注 MIME 类型与文件名，然后调用 xberg.Extract 并打印结果的 MIME 与纯文本内容：

package main

import (
	"fmt"
	xberg "github.com/xberg-io/xberg/packages/go"
	"os"
)

func ptrT any *T { return &value }
func mustReadFile(path string) []byte {
	content, err := os.ReadFile(path)
	if err != nil {
		panic(err)
	}
	return content
}
func main() {
	input := xberg.ExtractInput{
		Kind:     ptr(xberg.ExtractInputKindBytes),
		Bytes:    mustReadFile(`pdf/fake_memo.pdf`),
		MimeType: ptr(`application/pdf`),
		Filename: ptr(`fake_memo.pdf`),
	}
	config := xberg.ExtractionConfig{}
	result, err := xberg.Extract(input, config)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", result.Results[0].MimeType)
	fmt.Printf("%+v\n", result.Results[0].Content)
}

代码中有三个细节值得注意：

1. ptr 泛型辅助函数：ExtractInput 的可选字段（Kind、MimeType、Filename、URI、Config）都是指针类型，ptr 用于便捷地取字面量地址。官方绑定同样内置了 xberg.Ptr 辅助函数（packages/go/binding.go）。
2. Kind 必须显式指定：ExtractInput.Kind 决定引擎按 bytes 还是按 URI 解释输入，bytes 输入要求填充 Bytes 字段，uri 输入要求填充 URI 字段（packages/go/binding.go）。
3. MimeType 与 Filename 是类型提示：它们用于辅助 MIME 探测与元数据生成（见下节字段解析），PDF 场景显式声明 application/pdf 可以跳过内容嗅探，直接进入 PDF 提取管线。

ExtractInput 字段逐项解析

ExtractInput 在 packages/go/binding.go 中定义如下（注释为源码原文）：

字段	类型	语义
Kind	*ExtractInputKind	输入源类型；"bytes" 需要 Bytes，"uri" 需要 URI
Bytes	[]byte	kind = "bytes" 时的原始字节流
URI	*string	kind = "uri" 时的本地路径、file:// URI 或 HTTP(S) URL
MimeType	*string	MIME 类型提示，如 application/pdf
Filename	*string	文件名提示，用于 MIME 探测与元数据
Config	*FileExtractionConfig	单输入粒度的提取配置覆盖（batch 场景逐文件差异配置）

其中的 JSON 序列化也有讲究：绑定层为 ExtractInput 实现了自定义 MarshalJSON，把 <a href="https://link.gitcode.com/i/1cddae24e12754b3c6fe23f8af83cbe8" target="_blank">]byte 编码为整数数组（而非 Go 默认的 base64 字符串），以匹配 Rust 侧 serde Vec<u8> 的反序列化格式（[packages/go/binding.go）。这也解释了 fixture（fixtures/extract/extract_bytes_input.json）中 bytes 字段是 [37, 80, 68, 70, 45, 49, ...] 这样的十进制字节数组——37、80、68、70 正是 %PDF- 的 ASCII 码，即一个合法的 PDF 1.3 文件头。

结果读取：ExtractionResult 与 ExtractedDocument

xberg.Extract 返回 *ExtractionResult（packages/go/binding.go），核心字段为：

• Results []ExtractedDocument：按发现顺序排列的提取文档列表；
• Errors []ExtractionErrorItem：非致命性单输入错误；
• Summary *ExtractionSummary：本次操作的聚合统计（输入数、结果数、错误数、远程 URL 数等）。

单个 ExtractedDocument（packages/go/binding.go）除了示例中打印的 Content（纯文本表示）与 MimeType 之外，还包含 Metadata（作者、标题、日期等）、Tables（结构化表格）、Counts（页数/表格数/图片数的廉价统计）、DetectedLanguages（ISO 639-1 语言码）、Chunks（启用分块时的文本块）、Images 与 Pages（启用对应提取时）等字段——bytes 输入与其他输入在结果结构上完全一致，content 与 mime_type 是任何成功提取都保证返回的基础字段。

官方 fixture 对这次调用的断言恰好印证了这一点（fixtures/extract/extract_bytes_input.json）：

• not_error：调用不得报错；
• results[0].mime_type == "application/pdf"：MIME 原样回传；
• results[0].content 长度 ≥ 50：提取出的纯文本非空且达到最小长度。

边界输入与错误处理：空 MIME 与不支持的 MIME

同目录下的两个关联片段补充了 bytes 输入的失败路径：

空 MIME（extract_bytes_input_empty_mime.md）：MimeType 传空字符串时，xberg.Extract 返回错误，需要借助 errors.As 断言为类型化错误 xberg.Error 后输出：

_, err := xberg.Extract(input, config)
var typedError xberg.Error
if errors.As(err, &typedError) {
	fmt.Fprintf(os.Stderr, "%T: %v\n", typedError, typedError)
}

不支持的 MIME（extract_bytes_input_invalid_mime.md）：传入 application/x-nonexistent 这类引擎不认识的 MIME 时同样失败。对应 e2e 测试（e2e/go/extract_test.go）明确断言「期望出错」。

从底层看，Rust 侧把这类错误映射为 ErrUnsupportedFormat（错误码 1010）等哨兵错误，Go 绑定层通过 lastError() 读取 FFI 的错误码与上下文消息，并包装成 nativeError 返回——它实现了 Unwrap()，因此调用方既可以用 errors.Is 匹配哨兵，也可以用 errors.As 拿到结构化类型（packages/go/binding.go）。这也是示例代码选择 errors.As + xberg.Error 模式的原因：在生产代码中，你可以按错误码分支出「重试」「降级到 OCR」「记录后跳过」等策略。

底层原理：Go → C FFI → Rust 核心的调用链

xberg.Extract 的实现（packages/go/binding.go）揭示了一条清晰的跨语言调用链：

1. 将 ExtractInput 与 ExtractionConfig 通过 json.Marshal 序列化（[]byte 走整数数组格式；空指针序列化出的 "null" 会被替换为 "{}"，对应 Rust 侧 Option<&T> 的默认构造语义）；
2. 通过 cgo 调用 C.xberg_extract_input_from_json / C.xberg_extraction_config_from_json 把 JSON 传给 FFI 层构造 Rust 结构；
3. 调用 C.xberg_extract(cInput, cConfig) 进入 Rust 核心引擎执行提取；
4. 调用 C.xberg_extraction_result_to_json 把结果序列化回 JSON，在 Go 侧 json.Unmarshal 成 ExtractionResult。

整条链路上输入输出都是 JSON + 字节数组，结构定义由 alef 绑定生成器维护，因此 Go 端的字段名（mime_type、filename、results 等）与 Rust 核心的序列化契约完全一致——这正是「多语言绑定输出一致性」的由来（packages/go/README.md）。

实战扩展：便捷构造函数与其他输入方式

对于常见的 bytes 场景，官方绑定还提供了便捷构造函数 xberg.ExtractInputFromBytes(data, mimeType, filename)（packages/go/README.md），无需手工拼 ExtractInput：

data, err := os.ReadFile("slides.pptx")
filename := "slides.pptx"
input := xberg.ExtractInputFromBytes(
	data,
	"application/vnd.openxmlformats-officedocument.presentationml.presentation",
	&filename,
)
output, err := xberg.Extract(*input, xberg.ExtractionConfig{})

此外，ExtractionConfig 支持高级配置（缓存、强制 OCR、图像提取、语言检测、分块等），并且每个输入可通过 ExtractInput.Config（*FileExtractionConfig，见 packages/go/binding.go）做逐文件覆盖——例如对某个扫描件单独开启 ForceOcr，而对同批次的其他 PDF 保持默认，这对于混合文档类型的批处理管线非常实用。

小结

以字节（bytes）输入调用 xberg 提取引擎是 Go 服务中最直接的接入方式：Kind 指定输入类型、Bytes 携带内容、MimeType/Filename 提供类型提示，一次 xberg.Extract(input, config) 即可拿到 MIME、纯文本乃至表格、元数据、分块等结构化结果。结合空 MIME、无效 MIME 的边界示例与 errors.As 类型化错误处理，以及官方 e2e 测试与契约 fixture 的断言，你可以放心地把这套模式嵌入文档解析、RAG 数据管线或内容审核系统。更进一步的参考实现可继续阅读 e2e/go/extract_test.go 与 packages/go/README.md。