第十四章：多后端系统详解

GeoPipeAgent 的多后端架构允许同一个 YAML 流水线在不同的 GIS 工具引擎上执行。本章详细介绍 7 种后端的特点、配置和使用场景。

14.1 后端架构设计

所有后端都继承自 GeoBackend 抽象基类，实现统一接口：

class GeoBackend(ABC):
    def name(self) -> str           # 后端标识符
    def is_available(self) -> bool  # 检测依赖是否已安装
    def buffer(...)                 # 缓冲区
    def clip(...)                   # 裁剪
    def reproject(...)              # 投影转换
    def dissolve(...)               # 融合
    def simplify(...)               # 简化
    def overlay(...)                # 叠加分析

BackendManager 在首次使用时检测所有后端的可用性，并缓存结果：

class BackendManager:
    def default() -> BackendManager:   # 单例，自动检测可用后端
    def get(preferred=None) -> GeoBackend:  # 获取指定或默认后端

默认后端选择逻辑：BackendManager.get() 不带参数时，返回 backends 列表中第一个可用后端（优先级按 _BACKEND_CLASSES 定义顺序）。通常情况下 native_python 始终可用并排在第一位。

14.2 七种后端详解

14.2.1 native_python：GeoPandas + Shapely

最常用的默认后端，纯 Python 实现，基础安装即可使用。

工作原理：直接调用 gdf.buffer(distance)、gdf.clip(clip_gdf) 等 GeoPandas/Shapely 方法，无需文件 I/O，速度快。

14.2.2 gdal_cli：GDAL 命令行工具

调用 ogr2ogr 等 GDAL CLI 命令处理数据，适合大文件或需要精确 GDAL 行为的场景。

工作原理：将 GeoDataFrame 写入临时文件 → 构建 ogr2ogr 命令 → 执行 → 读取输出临时文件 → 删除临时文件。

# 使用 GDAL CLI 后端处理大型 Shapefile
- id: reproject-large
  use: vector.reproject
  params:
    input: "$load-big-data"
    target_crs: "EPSG:4549"
  backend: gdal_cli

14.2.3 gdal_python：GDAL/OGR Python 绑定

使用 GDAL Python 绑定（osgeo.ogr）直接调用 GDAL API，提供比 CLI 更细粒度的控制。

14.2.4 qgis_process：QGIS Processing CLI

调用 qgis_process 命令行工具，使用 QGIS Processing 算法执行空间分析，兼容 QGIS 生态系统插件。

# 使用 QGIS Processing 后端
- id: buffer-qgis
  use: vector.buffer
  params:
    input: "$load-data"
    distance: 100
  backend: qgis_process

14.2.5 pyqgis：PyQGIS Python API

通过 QGIS 的 Python API（PyQGIS）执行操作，适合需要 QGIS 高级功能的场景。

14.2.6 generic_cli：通用命令行后端

最灵活的后端，允许执行任意命令行命令，通过标准输入/输出或文件参数传递数据。

14.2.7 curl_api：HTTP/REST API 后端

通过 curl 调用 REST API，允许将云端 GIS 服务集成到流水线中。

14.3 后端选择策略

步骤支持的后端

不同步骤支持不同的后端子集，通过步骤注册信息中的 backends 列表定义：

@step(
    id="vector.buffer",
    backends=["native_python", "qgis_process"],   # 仅支持这两种后端
    ...
)

若指定了步骤不支持的后端，会使用步骤的默认后端。若步骤没有 backends（如 IO 步骤），则不使用后端（直接调用 GeoPandas/rasterio）。

查看各步骤支持的后端

# 表格格式查看（含 Backends 列）
geopipe-agent list-steps

# JSON 格式查看详细信息
geopipe-agent list-steps --format json

# 查看特定步骤的后端支持
geopipe-agent describe vector.buffer

不同场景的后端建议

14.4 检查可用后端

# 列出所有后端及其可用状态
geopipe-agent backends

输出示例：

[
  {"name": "native_python", "available": true},
  {"name": "gdal_cli",      "available": true},
  {"name": "gdal_python",   "available": false},
  {"name": "qgis_process",  "available": false},
  {"name": "pyqgis",        "available": false},
  {"name": "generic_cli",   "available": true},
  {"name": "curl_api",      "available": true}
]

14.5 在流水线中使用多后端

同一流水线可以在不同步骤中指定不同后端：

pipeline:
  name: "多后端混合流水线"

  steps:
    - id: load-data
      use: io.read_vector
      params: { path: "data/roads.shp" }

    # 使用默认 native_python 后端
    - id: query-major-roads
      use: vector.query
      params:
        input: "$load-data"
        expr: "road_class == 'highway'"

    # 大型数据重投影使用 GDAL CLI 后端
    - id: reproject-big
      use: vector.reproject
      params:
        input: "$query-major-roads"
        target_crs: "EPSG:3857"
      backend: gdal_cli

    # 缓冲使用默认 native_python
    - id: buffer
      use: vector.buffer
      params:
        input: "$reproject-big"
        distance: 1000

14.6 后端不可用时的处理

当指定后端不可用时，BackendManager.get(preferred) 抛出 BackendNotAvailableError：

{
  "error": "BackendNotAvailableError",
  "message": "Backend 'qgis_process' is not available. Available: ['native_python', 'gdal_cli']"
}

最佳实践：在流水线中使用 on_error: fail 快速发现配置问题，而不是静默降级。

14.7 本章小结

本章详解了 GeoPipeAgent 的多后端架构：

1. BackendManager：单例模式自动检测可用后端，按优先级排列
2. 7 种后端：native_python（默认）、gdal_cli、gdal_python、qgis_process、pyqgis、generic_cli、curl_api
3. 步骤级 backend 字段：精确控制每个步骤使用的后端
4. 后端选择策略：默认使用 native_python，大文件用 gdal_cli，特殊算法用 qgis_process

导航：← 第十三章：流水线引擎 ｜ 第十五章：数据模型与错误体系 →