用 Rust 重写 GDAL 抽象层：oxigeo 统一读取 GeoJSON 与 GeoParquet

这次我们来看一个 Rust 生态里新出现的“抽象层”方向库：oxigeo。不看名字的包装，它做的事情很明确：把 GDAL 在 C/C++ 体系里完成的地理空间数据读写抽象，尝试用纯 Rust 重新实现一遍。也就是说，它想提供一套统一的数据源入口，让上层代码不用关心文件到底是 GeoJSON、Shapefile 还是 GeoParquet，打开之后拿到的都是同一套要素、几何、属性、坐标系概念。

对 Rust 技术栈的团队来说，这类库最大的价值不是“又有一个新轮子”，而是把 GIS 工具链从“必须装 GDAL、必须处理 Python 生态环境”拽回到 Cargo 依赖树里。一个纯 Rust 库能静态编译成单一二进制，不需要运行时绑定操作系统的 C++ 库，这对部署、容器镜像瘦身、边缘设备交叉编译都很有吸引力。本文会围绕 oxigeo 这类地理空间数据抽象层展开，重点讲清楚：它适合解决什么问题、在本地怎么把 Rust 环境搭起来、如何通过一个最小程序完成读取与转换、怎样把它封装成 HTTP 接口或批量处理任务，以及常见的坑在哪里。

如果你平时处理的是 GeoJSON、GeoParquet、Shapefile 这类矢量数据，想从 Python 的 geopandas/GDAL 栈迁移到 Rust 工具链，或者在做一个需要内嵌地理空间数据读取能力的高性能服务，这篇文章可以直接收藏。

1. 核心能力速览

在动手之前，先给一张能力速览。需要说明的是，项目的具体版本、支持格式列表、API 方法名，都要以官方 README 和 crates.io 页面为准；下面这张表更接近“从设计定位和使用方式上合理预期”的梳理。

2. 适用场景与使用边界

先说适合谁。

第一类是正在做地理空间 ETL 或数据管道的 Rust 团队。以前处理 GeoJSON、Shapefile、Parquet 文件时，往往要写一堆格式相关的解析逻辑，或者引入 C 库绑定再处理编译问题。有了统一的数据源抽象层，业务代码只需要面向数据集和要素写，格式差异被收敛在驱动内部。

第二类是希望把地图服务后端、空间查询服务、批量切片工具做成静态二进制的开发者。纯 Rust 库在交叉编译到 ARM、编译到 Docker 最小镜像时都有天然优势，不用在目标容器里安装 libgdal。

第三类是研究地理空间内存格式的人。当前生态里 GeoArrow、GeoParquet 这类列式存储方向越来越重要，如果 oxigeo 的内存模型往 Arrow 生态靠拢，那么做空间分析、属性过滤、格式互转都会顺畅很多。

再说它不适合什么。

它不适合想开箱即用、可视化点图层的用户。数据抽象层不做地图渲染，不提供 WebGIS 面板，它提供的是一套编程接口。如果你只是想把一个 GeoJSON 拖到浏览器里看看，用 QGIS、geopandas、PostGIS 会更快。

它也不适合已经完全依赖 GDAL 巨量栅格格式、WMS/WCS 服务的团队。矢量数据抽象和全功能栅格抽象是两回事，oxigeo 即便对栅格有支持，成熟度也很难和 GDAL 相提并论。另外，新库的生态一般还在爬坡，API 调整、驱动缺失、文档不全是常见状态，生产化之前要做好验证。

使用边界方面，有几点必须强调。

地理信息数据的合规风险比普通文本更明显。OpenStreetMap 导出的数据受 ODbL 许可约束，Natural Earth 等公共数据集有自己的使用条款，商用之前要看清楚。涉及个人位置轨迹的数据要脱敏和做隐私评估。更严重的一条边界是测绘成果，涉密或受限的测绘数据不能进入普通开源工具链处理。坐标精度也要按业务需要合理处理，而不是无脑保留最高精度。

3. 本地部署环境准备

oxigeo 是库，不是 Web 应用，所以“部署”的第一步是准备好 Rust 工具链，再创建一个 Cargo 工程。下面给出一套通用准备流程。

3.1 安装 Rust 工具链

Linux 和 macOS 上建议用 rustup 安装：

bash复制curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Windows 用户可以从 Rust 官方网站下载 rustup-init.exe 安装，安装完成后在 PowerShell 里执行：

powershell复制rustup show
cargo --version

安装完成后最好确认一下编译器和包管理器可用：

bash复制rustc --version
cargo --version

3.2 确认系统级依赖

虽然 oxigeo 是纯 Rust 实现，但个别驱动如果要连接 PostgreSQL 客户端、GDAL 转换器或其他外部后端，仍然可能需要系统库。比如 Linux 上常见需要：

bash复制sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev

如果计划连接 PostGIS，则可能需要：

bash复制sudo apt install -y libpq-dev

这一步取决于你启用的 feature。如果只是读取 GeoJSON、GeoParquet 这类纯文件格式，通常不需要额外系统库。这里的判断标准是：编译报错里出现 cannot find -lpq、pkg-config not found 这类信息时，再按对应库补装。

3.3 准备测试数据

建议准备两类测试数据：

• 一个小体积 GeoJSON 文件，比如一个城市的兴趣点集合或区域边界，用来验证基础读取。
• 一个 GeoParquet 样本，用来验证列式格式和批量读取路径。

数据可以从公开数据集下载，也可以先用 QGIS、geopandas 导出一个测试文件。不建议一上来就拉几个 GB 的全球数据，否则后续排查问题时分不清是库的问题还是数据量的问题。

4. 安装依赖与启动方式

由于输入材料没有给出 oxigeo 的确切版本和 API 路径，下面所有的 Cargo 配置与 Rust 代码都按“地理空间数据抽象库的常见工程模式”来写，作为可直接套用的模板。实际方法名、结构体名、feature 开关以官方文档为准。

4.1 创建工程并添加依赖

bash复制cargo new oxigeo-demo
cd oxigeo-demo

编辑 Cargo.toml，添加依赖占位：

toml复制[package]
name = "oxigeo-demo"
version = "0.1.0"
edition = "2021"

[dependencies]
# 实际版本号去 crates.io 查询
oxigeo = "0.x"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

注意，0.x 不是合法版本写法，这里只是占位。你需要先通过 cargo add oxigeo 获取真实可用版本，或者在 crates.io 页面查到版本号后手动填写。添加后保存并执行一次预编译，让依赖树落盘：

bash复制cargo build

如果这一步编译通过，说明依赖解析和环境都没有问题。

4.2 编写最小读取程序

创建一个 src/main.rs，完成“打开数据源、读取 schema、遍历前几个要素”三个动作。这是任何地理空间抽象层都应该提供的基础能力。

rust复制// 以下代码演示数据源打开、schema 查看、要素遍历的常见写法
// 具体 API 方法名以 oxigeo 官方文档为准
fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 替换成你的测试文件路径
    let path = "data/cities.geojson";

    // 打开数据源
    let dataset = oxigeo::open(path)?;

    // 查看图层/数据集信息
    println!("layer name: {:?}", dataset.name()?);
    println!("schema: {:?}", dataset.schema()?);

    // 遍历前 5 个要素并打印
    for feature in dataset.features().take(5) {
        println!("{:?}", feature?);
    }

    Ok(())
}

这段代码体现的是抽象层最典型的能力：调用方不需要关心文件后缀和驱动，只看到“数据集”和“要素”。

4.3 运行验证

bash复制cargo run --release

预期结果是：程序输出图层名称、字段 schema，以及前 5 个要素的几何和属性信息。若输出为空或报“没有找到驱动/不支持该格式”，先确认测试文件路径格式和官方 README 里列出的支持格式清单。

5. 功能测试与效果验证

功能测试的目标不是“跑通就行”，而是验证它在真实业务里最常见的几条路径：读取、写入、属性读取、坐标参考系处理、批量稳定性。下面按功能拆成几个测试用例。

5.1 读取 GeoJSON 测试

测试目的：确认库能解析文本格式的 GeoJSON，正确处理几何类型和属性字段。

操作步骤：

1. 准备一个包含 Point、Polygon 和属性字段的测试文件。
2. 用上一节的最小读取程序打开该文件。
3. 分别打印 schema、要素数量、前 N 个要素。

预期结果：输出的 schema 与 GeoJSON 里的属性键一致，几何类型被正确识别为 Point、Polygon 等枚举，坐标为浮点类型。

判断标准：要素数量与手动用编辑器数出的 features 数组长度一致；属性值类型没有被意外转成字符串；坐标没有出现科学计数法丢失精度的情况。

失败排查：如果提示格式不受支持，先确认文件扩展名和内部内容是否合法，查看官方格式列表；如果属性丢失，可能是驱动对嵌套 JSON 对象支持不足。

5.2 GeoParquet 写出与回读测试

测试目的：验证从 GeoJSON 读取后能否写出为 GeoParquet，并能再次读取，实现 round-trip。

参考代码：

rust复制// 打开数据源并写出为 GeoParquet，示意写法需按官方 API 调整
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ds = oxigeo::open("data/cities.geojson")?;

    let writer = oxigeo::parquet_writer("out/cities.parquet")?;
    writer.write_dataset(ds)?;
    println!("write done");

    let back = oxigeo::open("out/cities.parquet")?;
    println!("read back features: {:?}", back.feature_count()?);
    Ok(())
}

预期结果：输出文件存在，回读后的要素数量与原始数据一致。如果库本身提供 schema 推断能力，回读的字段类型应当保持一致。

判断标准：用 parquet-tools 或 duckdb 能直接查询该文件；几何列以 WKB 或 GeoArrow 形式存储时，空间工具也能识别。

失败排查：写出失败常见原因是目录不存在、CRS 未定义、几何类型混合导致 schema 推断失败。解决方向是手动声明 schema 或确保数据源内几何类型统一。

5.3 属性过滤与字段裁剪测试

测试目的：验证抽象层是否能做到“只读取必要字段”，而不是把整个要素全部加载进内存。

操作步骤：

1. 打开数据源。
2. 过滤出某个属性值，如 population > 100000。
3. 只读取 name、population 两个字段。
4. 统计结果条数。

预期结果：过滤结果与在 geopandas/duckdb 里执行同样逻辑得到的结果一致。

判断标准：如果库支持投影下推，内存占用应随字段数量减少；如果只是全部解码后过滤，则性能收益有限。对大数据集来说，优先选择能下推的 API。

失败排查：如果属性名大小写写错导致过滤为空，先打印 schema 确认字段名；如果类型比较不对，注意数值字段是 u32 还是 i64。

5.4 坐标系与投影转换测试

测试目的：确认库能读取 CRS 信息，并提供或对接坐标转换能力。

操作步骤：

1. 准备两个数据源：一个 WGS84 经纬度坐标，一个 Web Mercator 坐标。
2. 打印各自的 CRS 标识。
3. 尝试把前者转换到后者，并检查转换后的坐标范围是否合理。

预期结果：CRS 标识能被识别，转换后的坐标数量级符合目标坐标系特征。

判断标准：WGS84 里中国境内坐标大约是经度 73 到 135，纬度 18 到 54；Web Mercator 下同一个点坐标是几十万到上百万米量级。如果你看到完全不变，说明转换没有生效；如果坐标范围异常，说明 CRS 判断错误。

失败排查：很多矢量源文件不会在 GeoJSON 里写 CRS 信息，默认按 WGS84 处理。遇到范围异常时，先检查数据源是否存在显式 CRS 字段，或者手动指定 CRS。坐标转换通常不是单靠数据抽象层完成的，可能需要配合 proj 这类 Rust 库。

5.5 大文件流式遍历测试

测试目的：验证当文件大到无法整体放在内存时，库是否能按要素流式读取。

操作步骤：

1. 准备一个几百 MB 到几 GB 的 GeoJSON 或 GeoParquet。
2. 用迭代器遍历全部要素，只做计数，不收集到 Vec。
3. 在另一个终端实时观察进程内存。

预期结果：进程内存保持稳定，不随文件大小线性增长。如果内存涨到接近文件体积，说明数据被整体加载了。

判断标准：遍历结束后，内存回落到基础水平；程序不会因为文件增长而 OOM。

失败排查：部分格式本身是随机访问或索引式的，无法真正流式；另一个常见问题是要素内部某个超大属性导致单条记录内存过高。这种情况需要做字段裁剪。

5.6 容错测试

测试目的：测试损坏文件、空图层、字段缺失等异常输入下，程序不会 panic 或泄漏资源。

操作步骤：

1. 把一个正常 GeoJSON 的中间截断后重命名为 .geojson。
2. 用一个只有 features: [] 的空文件测试。
3. 用缺失必填字段的文件测试。

预期结果：库返回描述性错误，而不是直接崩溃。程序可以通过 Result 捕获错误并继续处理下一个文件。

判断标准：错误信息中包含文件路径或原因；后续循环仍能继续处理其他文件；没有内存持续增长。

失败排查：如果 panic 出现在解析内部而不是返回 Err，这是库本身的健壮性问题，可以在项目中先做外部进程隔离，或给官方仓库提 issue。

6. 接口 API 封装与批量任务

数据抽象层本身不对外提供 HTTP 服务，但在实际工程里，最常见的用法是把它包成一个内部服务，让 Web 前端或自动化脚本通过接口查询要素。下面给出通用封装思路。

6.1 用 axum 封装查询接口

rust复制use axum::{Router, routing::get, Json};
use serde_json::{json, Value};

async fn feature_summary() -> Json<Value> {
    // 这里替换为调用 oxigeo 打开数据源并统计数量的真实逻辑
    Json(json!({"features": 0, "status": "ok"}))
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/api/v1/features", get(feature_summary));
    let listener = tokio::net::TcpListener::bind("127.0.0.1:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

这个示例只展示服务骨架。真实接口里会有 Query 参数做 bounding box 过滤、属性筛选、字段裁剪分页等。封装时要注意几个点：

• 每次请求都打开数据集会有文件句柄和 schema 解析开销，高频场景要加缓存或连接池。
• 返回的要素要限制单次条数和几何精度，避免把超大 Polygon 塞进 JSON 响应。
• 服务只监听内网地址，不直接暴露到公网；需要公网访问时套一层鉴权。

6.2 批量任务流程

批量处理是地理空间工具链的常见场景：把一个目录下的多个 GeoJSON 统一转换成 GeoParquet，或者给一批文件做坐标系重投影。这类任务建议按队列方式设计。

参考目录结构：

text复制data/
  input/    // 原始文件
  processing/  // 正在处理的文件
  output/   // 转换结果
  bad/      // 处理失败的文件

参考并行处理代码：

rust复制use rayon::prelude::*;
use std::fs;
use std::path::Path;

fn process_dir(input_dir: &Path) -> Result<(), Box<dyn std::error::Error>> {
    let files: Vec<_> = fs::read_dir(input_dir)?
        .flatten()
        .map(|e| e.path())
        .filter(|p| {
            p.extension()
                .map_or(false, |e| e == "geojson" || e == "parquet")
        })
        .collect();

    files.par_iter().for_each(|file| {
        println!("processing {:?}", file);
        // 这里调用 oxigeo 打开并写出，失败时记录日志并移到 bad/ 目录
    });

    Ok(())
}

批量任务一定要加三样东西：

• 日志：记录每个文件的开始时间、处理时长、结束状态。
• 失败隔离：一个文件失败不能影响整个批次，失败文件移入 bad/ 目录。
• 断点续跑：处理前把文件名写入一个 done 列表，重启后跳过已完成文件。

6.3 通用 HTTP 调用模板

如果服务已经封装好，客户端调用就是标准 HTTP。假设通过 curl 访问：

bash复制curl "http://127.0.0.1:8080/api/v1/features?limit=10&bbox=116.0,39.0,117.0,41.0"

如果批量任务也开放了任务接口，比如异步提交任务，客户端可以用 Python 轮询：

python复制import requests
import time

resp = requests.post("http://127.0.0.1:8080/api/v1/jobs", json={
    "source": "data/input",
    "output_dir": "data/output",
    "format": "geoparquet"
})
job_id = resp.json()["job_id"]

while True:
    status = requests.get(
        f"http://127.0.0.1:8080/api/v1/jobs/{job_id}"
    ).json()
    if status["state"] in ("completed", "failed"):
        break
    time.sleep(2)

这种模板对任何任务型服务都适用，具体字段名要按后端实现调整。

7. 资源占用与性能观察

地理空间数据抽象层的性能核心，不是单条要素读写快，而是内存增长可控、大批量吞吐稳定。

观察内存和 CPU 有三个常用手段：

bash复制# 实时查看进程资源
top -p PID

# 统计峰值内存
/usr/bin/time -v cargo run --release

影响性能的主要因素通常包括：要素几何复杂度、属性列数量和类型、坐标转换是否触发、输出格式压缩级别，以及是否并行。

从格式本身看，GeoParquet 这类列式存储通常比 GeoJSON 文本解析更省内存，尤其是只读取少数列时。如果库实现了列裁剪，那些无用字段的列式数据不会进入内存。这属于格式层面的合理预期，不针对特定库。

降低内存的常规手段：

• 流式遍历代替 collect::<Vec<_>>()。
• 尽量只选择需要的字段。
• 使用 bounding box 过滤，在读取早期就丢弃无关要素。
• 批量处理时限制并行度，避免几十个文件同时把数据读进内存。
• 对 GeoJSON 这类无索引格式，先转成 GeoParquet 建立元数据，后面反复查询会更快。

封装成服务后还要注意端口冲突和进程残留。使用固定端口前先检查占用：

bash复制lsof -i :8080
netstat -tlnp | grep 8080

如果端口被占，用环境变量把端口做成可配置项，而不是写死在代码里。

8. 常见问题与排查方法

下面把最容易踩到的问题整理成一张排查表。

排查思路并不复杂：先把问题定位到“编译期、读取期、转换期、写出期”的哪一个阶段，再缩小范围。编译期问题先看 Cargo 报错和 feature 开关；读取期问题用最小数据文件复现；转换期问题重点检查 CRS 和几何类型；写出期问题用第三方工具独立检查输出文件。

9. 最佳实践与使用建议

第一，第一次跑项目时，不要直接处理生产数据。准备一个小型 GeoJSON 和一个空 GeoParquet，先把“打开数据源、遍历要素、写回文件”这条链路走通。保存这个最小工程，以后每换一个环境，先跑它验证环境是否正常。

第二，严格管理数据目录。把原始数据、中间结果、错误文件分开存放，处理程序不直接覆盖原文件，所有输出统一写入 output/。批量任务里，一个文件失败就把它移动到 bad/，不要让失败数据反复进入主流程。

第三，批量任务必须有日志和断点续跑能力。最简单的做法是处理前把文件路径写入 done.txt，下次启动时跳过已经存在的路径。并行度不要盲目拉满，先用 4 个线程跑一批小数据测试，再逐步增加。

第四，接口封装时要限制返回规模。矢量要素的几何字段可能很大，一个 Polygon 包含几千个坐标点很常见。HTTP 接口要做字段裁剪、精度截断、条数限制和分页，否则一个请求就能把后端带宽打满。

第五，注意数据合规和隐私边界。不要用开源工具链处理涉密测绘成果；处理个人位置轨迹时要做脱敏；商业项目里要核对数据源的许可条款。发布成果前对坐标精度和敏感位置做一次检查。

10. 总结与下一步

oxigeo 这类纯 Rust 地理空间数据抽象库，最值得尝试的点是把 GIS 工具链拉回 Cargo 生态。对 Rust 技术栈的团队来说，这意味着更干净的编译依赖、更小的部署产物和更可控的内存模型。

建议最先验证的功能是“读取 GeoJSON 并写出 GeoParquet”，这组操作能覆盖数据源打开、schema 推断、几何序列化和回读一致性，是最短的价值验证路径。最容易踩的坑集中在依赖版本冲突和 CRS 信息缺失，前者靠 cargo tree 解决，后者靠提前检查数据元数据解决。

下一个阶段可以考虑扩展的方向是：把库封装成内部地理数据查询服务、加入坐标转换和矢量瓦片输出，以及在批处理任务里引入增量更新机制。等这些都跑稳，基本等于用 Rust 搭了一套轻量级空间数据处理平台。