第01章 - 框架概述与设计理念

1.1 OpenGIS DAF 简介

1.1.1 什么是 OpenGIS DAF

OpenGIS DAF（OpenGIS Data Analysis Framework，opengis-daf）是一个方案驱动的 GIS 数据分析与数据质检框架，基于 .NET 10 / C# 14 构建，采用 MIT 开源协议。

与传统的”写代码处理数据”不同，OpenGIS DAF 的核心思想是：用一份 JSON 方案（Plan）描述完整的数据处理流程，框架负责加载、校验、调度与执行。你不需要编写任何 C# 代码，只需声明”读什么数据、用什么算子、输出到哪里”，框架就会自动完成其余工作。

OpenGIS DAF 整合了业界成熟的开源 GIS 组件：

  • GDAL/OGR 3.x：地理空间数据抽象库，提供底层矢量读写能力
  • NetTopologySuite 2.6：几何运算与空间分析引擎
  • Npgsql 10.0：PostgreSQL/PostGIS 驱动
  • Serilog 4.3：结构化日志
  • xUnit v3 3.2：单元测试框架

1.1.2 项目背景与动机

在 GIS 数据分析工作中，开发者经常面临以下挑战：

  1. 重复劳动：坐标转换、缓冲分析、格式转换等操作在每次项目中都要重写
  2. 流程不可复现：数据处理步骤散落在脚本里，难以版本化、难以复用
  3. 质量不可控：数据质量问题（无效几何、属性缺失）往往在分析结果出错后才被发现
  4. 扩展成本高：新增一种分析能力需要改动核心代码

OpenGIS DAF 通过”方案驱动 + 算子池 + 插件扩展”的架构，将数据处理流程从代码中解耦出来，让流程可配置、可版本化、可复用，同时通过内置的数据质检能力把质量问题前置拦截。

1.1.3 与 opengis-utils-for-net 的关系

OpenGIS DAF 通过 git submodule 依赖 opengis-utils-for-net（OGU4Net）。OGU4Net 提供底层的 GDAL 封装与统一图层模型，而 OpenGIS DAF 在其之上构建了方案驱动的分析框架。如果你需要的是”在代码中直接调用 GIS 工具库”，请参考 opengis-utils-for-net 教程；如果你需要的是”用 JSON 方案声明式地完成数据分析与质检”，本教程正是为此而写。

1.2 核心能力

OpenGIS DAF 的核心能力可以概括为以下十个方面：

能力 说明
方案驱动 JSON 配置定义完整处理流程，无需编写代码
空间分析 buffer（缓冲）、clip（裁剪）、intersect（相交）、contains（包含）、CRS 转换
属性操作 字段计算器表达式引擎、空值填充
数据质检 几何有效性、属性完整性、内置质量评分
可扩展算子 通过 AssemblyLoadContext 动态加载 DLL 插件算子
多数据源 IFeatureSource：PostGIS / Shapefile / GeoJSON / 内存
多种输出 IFeatureSink：控制台 / GeoJSON / Shapefile / PostGIS
方案管理 21 条校验规则、版本回滚、跨版本 Diff、原子写入
DAG 调度 Kahn 拓扑排序 + 串并行调度、超时重试、失败策略
跨平台 Windows / Linux / macOS + Docker

1.3 设计理念

1.3.1 方案驱动（Plan-Driven）

OpenGIS DAF 最核心的设计理念是方案驱动。一份方案（Plan）是一个 JSON 文件，声明了：

  • 数据从哪来：外部文件、上游算子的输出
  • 用什么算子处理：内置算子或插件算子
  • 结果输出到哪：控制台、GeoJSON、Shapefile 或 PostGIS

方案本身是可版本化、可评审、可复用的资产。同一个方案可以在不同数据集上重复执行，也可以在 CI 流水线中作为可重复的数据处理步骤。

1.3.2 算子池（Operator Pool）

框架内置 9 个算子，按功能分为四类：

  • 空间运算：buffer、clip
  • 空间关系：intersect_check、containment_check
  • 属性操作：field_calculator、null_value_filler、coordinate_transform
  • 质检规则：attribute_completeness_checker、geometry_validity_checker

算子之间通过 DAG（有向无环图）串联，一个算子的输出可以作为另一个算子的输入，形成完整的数据处理流水线。

1.3.3 纯配置哲学（Pure-Config）

与”纯配置哲学”一脉相承，OpenGIS DAF 倾向于用配置表达流程，而不是用代码。这带来几个好处：

  1. 低门槛：业务人员也能读懂方案，参与流程设计
  2. 可审计：每一步处理都有明确的 JSON 记录
  3. 可复用：方案可以跨项目、跨数据集复用
  4. 可扩展：新增能力通过插件算子实现，不侵入核心

1.3.4 质量前置（Quality First）

OpenGIS DAF 内置数据质检能力，可以在分析之前先对数据做质量检查：

  • 几何有效性：自相交、环方向、空几何、非简单几何
  • 属性完整性：必填字段缺失、空值、空串
  • 空间关系检查：要素重叠、越界、包含关系

质检结果自动生成质量评分报告，帮助你在进入空间分析之前发现并修复数据问题。

1.4 架构总览

OpenGIS DAF 采用分层架构，共 7 层：

外部数据源（GeoJSON / Shapefile / PostGIS）
        │
        ▼
┌─────────────────────────────────────────────┐
│  CLI 层（OpenGisDAF.Cli）                    │
│  命令路由 · 异常处理 · DI 容器               │
├─────────────────────────────────────────────┤
│  方案管理层（PlanManagement）                │
│  CRUD · JSON 序列化 · 版本管理 · 校验        │
├─────────────────────────────────────────────┤
│  调度引擎层（Scheduling）                    │
│  DAG 构建 · Kahn 拓扑排序 · 失败策略 · 并发  │
├─────────────────────────────────────────────┤
│  执行引擎层（Execution）                     │
│  算子执行 · 结果缓存 · 超时重试 · 质量报告   │
├─────────────────────────────────────────────┤
│  算子池（Operators）                         │
│  9 个内置算子 · 插件发现 · 动态加载          │
├─────────────────────────────────────────────┤
│  适配器层（Adapters）                        │
│  IFeatureSource（4 数据源）· IFeatureSink    │
│  （4 输出）· FieldTypeMapper · GeometryType  │
├─────────────────────────────────────────────┤
│  基础设施层（Infrastructure）                │
│  配置 · 日志（Serilog）· 密码加密            │
│  （DPAPI / AES-GCM）                         │
└─────────────────────────────────────────────┘
        │
        ▼
外部输出（控制台 / GeoJSON / Shapefile / PostGIS）

数据流方向是单向的：外部数据源 → 适配器读取 → 算子处理 → 适配器写入 → 外部输出。每一层只依赖其下层，职责清晰。

1.5 源码结构

OpenGIS DAF 仓库的源码结构如下：

opengis-daf/
├── src/
│   ├── OpenGisDAF.Adapters/        # 适配器层：数据源与输出
│   ├── OpenGisDAF.Cli/             # CLI 层：命令行入口
│   ├── OpenGisDAF.Core/            # 核心契约：接口与模型
│   ├── OpenGisDAF.Execution/       # 执行引擎层
│   ├── OpenGisDAF.Infrastructure/  # 基础设施层
│   ├── OpenGisDAF.Operators/       # 算子池：9 个内置算子
│   ├── OpenGisDAF.PlanManagement/  # 方案管理层
│   └── OpenGisDAF.Scheduling/      # 调度引擎层
├── tests/
│   └── OpenGisDAF.IntegrationTests/ # 集成测试
├── demo/                           # 自包含学习演示（新星市）
├── docs/                           # 官方文档
├── extern/opengis-utils-for-net/   # git submodule 依赖
├── OpenGisDAF.slnx                 # 解决方案文件
├── global.json                     # .NET 10 SDK 版本
├── build.ps1 / build.sh            # 跨平台构建脚本
└── LICENSE                         # MIT

1.6 本教程导读

本教程共 10 章，建议按顺序阅读：

  • 第 1-2 章：框架概述与快速入门，建立整体认知并跑通第一个方案
  • 第 3-5 章：方案配置、内置算子、数据源与输出，掌握核心语法
  • 第 6-8 章：数据质检、空间分析、失败策略实战，通过”新星市”演示数据集动手实践
  • 第 9-10 章：插件算子扩展与方案管理，进阶定制与最佳实践

教程中的示例均来自仓库自带的 demo/ 目录（”新星市”演示数据集），你可以直接运行 run-demo.ps1（Windows）或 run-demo.sh（Linux/macOS）复现全部结果。

目录 下一章 →