rust-wasm-geo

Rust / WASM 地理计算

默认技术栈上下文：tech-stack 技能。本技能仅涵盖 Rust/WASM 地理计算。

适用场景

• Turf 或 JS 几何运算太慢（先进行性能分析——主线程阻塞 > 约 100ms）
• OSM 解析、地图模型构建、等时圈、空间索引、图路由
• 数千个要素、重复几何运算，或大规模多边形布尔运算
• 添加或审查 wasm-pack crate、wasm.ts 边界或 Vite WASM 插件

小型 GeoJSON 上的单要素运算，以及原型开发期间交互式编辑的即时反馈，仍使用 Turf（JS）。

Turf 与 Rust/WASM 对比

继续使用 Turf（JS）	添加 Rust/WASM
小型 GeoJSON 上的单要素运算	数千个要素、重复运算或图路由
交互式编辑的即时反馈	OSM 解析、地图模型构建、等时圈、空间索引
原型开发	主线程阻塞 > 约 100ms（先进行性能分析）

对大型数组进行批量几何运算（不包括路由/OSM）：使用 geoarrow-wasm，而不是自行实现。

crate 选择（快速参考）

需求	crate
几何 / GeoJSON	geo、geojson
空间索引	rstar
道路路由	fast_paths
图算法	petgraph
OSM → 图	osm-reader（a-b-street 分支）
将轨迹吸附到道路	route-snapper-graph
多边形布尔运算	i_overlay（参见 a-b-street/utils）
等高线 / 等值线	contour
序列化地图模型	bincode + serde
矢量文件 I/O	flatgeobuf、geozero

各 crate 的用法说明和 WASM 依赖版本：crates-and-packages.md。

项目结构

每个应用使用一个 crate，并根据其计算内容命名（geo-isochrone、route-buffer 等）。

app/
├── wasm/
│   └── geo-isochrone/          # Rust crate (wasm-pack output → pkg/)
│       ├── Cargo.toml
│       └── src/
│           ├── lib.rs          # #[wasm_bindgen] surface only
│           └── isochrone.rs    # pure geo logic
└── src/
    └── features/isochrone/
        ├── wasm.ts             # sole JS import of pkg — React never imports pkg directly
        └── useIsochrone.ts     # React hook / Query wrapper

• lib.rs = #[wasm_bindgen] 导出；内部模块 = 纯地理计算逻辑（无需 WASM 即可测试）。
• JS 边界： 在 wasm.ts 中封装导出项。传递 GeoJSON 字符串或 bincode Uint8Array，而不是手工构造的 JS 对象。
• 状态拆分： 持久计算状态放在 Rust 中；UI 状态放在 React 中（Zustand / URL / 本地 useState）。

WASM 技术栈（Cargo）

Crate	作用
wasm-bindgen	JS ↔ Rust 边界
serde-wasm-bindgen	跨边界序列化/反序列化
wasm-bindgen-futures	异步导出
console_error_panic_hook	在开发者工具中显示易读的 panic
getrandom with features = ["js"]	浏览器中的随机数生成
web-time	WASM 中的时间

构建： wasm-pack（--target web）、vite-plugin-wasm、目标平台 wasm32-unknown-unknown。

参考配置：a-b-street/ltn、a-b-street/15m、a-b-street/utils。

遇到问题时查阅文档： wasm-bindgen book、docs.rs 上的 geo。

应用集成

应用类型	指南
Vite SPA（无 Start）	vite-spa-integration.md
TanStack Start	tanstack-start-integration.md

两者均适用：仅从 wasm.ts 动态导入 WASM；共享模块中绝不在顶层 import .wasm，以免在服务器上加载。

不可妥协的规则

主题	规则
React 导入	组件/钩子仅导入 wasm.ts — 绝不导入 pkg/ 或原始 .wasm
边界类型	GeoJSON 使用 string 或 bincode Uint8Array；解析后在 JS 端使用 Zod 验证
坐标	WGS84，所有 API 边界均使用 [lng, lat]
服务端模块	*.server.ts、服务端加载器或 createServerFn 处理程序中不得初始化 WASM
SSR	WASM 仅在客户端运行；水合后延迟初始化（路由 ssr 参见 Start 指南）
Turf 回退	对于小型/交互式路径，保留 Turf，直到性能分析证明需要 WASM

相关技能

主题	技能
Map React API、图层、事件	react-map-gl
加载器、搜索参数、Query	tanstack-router-conventions
路由 SSR、Start 布局、服务端	tanstack-start-conventions
地图工具周边的客户端 UI 状态	zustand-state-management
useEffect / 地图监听器	react-dev