当前位置：首页 > news >正文

第03章 - 核心架构解析

news 2026/5/12 9:53:05

第03章 - 核心架构解析

3.1 架构概览

3.1.1 分层架构

OGU4Net采用清晰的分层架构设计，自上而下分为四层：

┌─────────────────────────────────────────────────────────────────┐
│                        应用层 (Application)                      │
│           OguLayerUtil / GtTxtUtil / 业务代码                    │
├─────────────────────────────────────────────────────────────────┤
│                        服务层 (Service)                          │
│              GisEngineFactory / GisEngine                       │
├─────────────────────────────────────────────────────────────────┤
│                        引擎层 (Engine)                           │
│          GdalEngine / GdalReader / GdalWriter                   │
├─────────────────────────────────────────────────────────────────┤
│                        基础层 (Foundation)                       │
│      MaxRev.Gdal.Universal (GDAL/OGR/OSR)                      │
└─────────────────────────────────────────────────────────────────┘

3.1.2 核心模块

OGU4Net由以下核心模块组成：

模块	命名空间	职责
配置模块	Configuration	GDAL初始化和全局配置
数据源模块	DataSource	高层数据读写API
引擎模块	Engine	GIS引擎核心实现
模型模块	Engine.Model	统一数据模型定义
几何模块	Geometry	几何处理工具
异常模块	Exception	异常类型定义
工具模块	Utils	实用工具类

3.1.3 依赖关系图

                    ┌───────────────┐│ OguLayerUtil  │└───────┬───────┘│▼┌───────────────┐│GisEngineFactory│└───────┬───────┘│▼┌───────────────┐│   GdalEngine  │└───────┬───────┘│┌─────────────┴─────────────┐▼                           ▼┌───────────────┐           ┌───────────────┐│  GdalReader   │           │  GdalWriter   │└───────┬───────┘           └───────┬───────┘│                           │└─────────────┬─────────────┘▼┌───────────────┐│  GeometryUtil ││    CrsUtil    │└───────┬───────┘│▼┌─────────────────────────────┐│  MaxRev.Gdal.Universal      ││  (OSGeo.OGR / OSGeo.OSR)    │└─────────────────────────────┘

3.2 配置模块

3.2.1 GdalConfiguration类

GdalConfiguration 是GDAL配置的核心类，负责初始化GDAL运行环境：

namespace OpenGIS.Utils.Configuration;public static class GdalConfiguration
{private static bool _isConfigured;private static readonly object _lock = new();/// <summary>/// 配置GDAL - 线程安全，可多次调用/// </summary>public static void ConfigureGdal(){lock (_lock){if (_isConfigured) return;// 使用MaxRev.Gdal.Universal自动配置GdalBase.ConfigureAll();// 注册所有驱动RegisterAllDrivers();// 设置配置选项SetConfigOptions();_isConfigured = true;}}/// <summary>/// 获取GDAL版本/// </summary>public static string GetGdalVersion(){EnsureConfigured();return Gdal.VersionInfo("RELEASE_NAME");}/// <summary>/// 获取支持的驱动列表/// </summary>public static IList<string> GetSupportedDrivers(){EnsureConfigured();var drivers = new List<string>();for (int i = 0; i < Ogr.GetDriverCount(); i++){var driver = Ogr.GetDriver(i);if (driver != null)drivers.Add(driver.GetName());}return drivers;}/// <summary>/// 检查驱动是否可用/// </summary>public static bool IsDriverAvailable(string driverName){EnsureConfigured();return Ogr.GetDriverByName(driverName) != null;}
}

设计要点：

单例模式：使用静态类确保全局唯一配置
线程安全：使用锁机制保证多线程安全
延迟初始化：首次使用时自动初始化
幂等性：多次调用不会重复初始化

3.2.2 配置选项

GDAL配置选项通过 SetConfigOptions 方法设置：

public static void SetConfigOptions()
{// 设置文件名为UTF-8编码Gdal.SetConfigOption("GDAL_FILENAME_IS_UTF8", "YES");// 设置Shapefile默认编码Gdal.SetConfigOption("SHAPE_ENCODING", "UTF-8");// 强制使用传统GIS坐标顺序 (longitude, latitude)Gdal.SetConfigOption("OGR_CT_FORCE_TRADITIONAL_GIS_ORDER", "YES");// 关闭调试信息Gdal.SetConfigOption("CPL_DEBUG", "OFF");
}

3.2.3 LibrarySettings类

LibrarySettings 提供库级别的配置常量：

namespace OpenGIS.Utils.Configuration;public static class LibrarySettings
{/// <summary>/// 默认容差值/// </summary>public const double DefaultTolerance = 0.001;/// <summary>/// 默认缓冲区分段数/// </summary>public const int DefaultBufferSegments = 30;/// <summary>/// 默认字段长度/// </summary>public const int DefaultFieldLength = 254;
}

3.3 引擎模块

3.3.1 引擎抽象设计

OGU4Net使用抽象工厂模式设计引擎层，便于扩展：

namespace OpenGIS.Utils.Engine;/// <summary>
/// GIS引擎抽象基类
/// </summary>
public abstract class GisEngine
{/// <summary>/// 引擎类型/// </summary>public abstract GisEngineType EngineType { get; }/// <summary>/// 支持的格式列表/// </summary>public abstract IList<DataFormatType> SupportedFormats { get; }/// <summary>/// 创建读取器/// </summary>public abstract ILayerReader CreateReader();/// <summary>/// 创建写入器/// </summary>public abstract ILayerWriter CreateWriter();/// <summary>/// 检查是否支持指定格式/// </summary>public virtual bool SupportsFormat(DataFormatType format){return SupportedFormats.Contains(format);}
}

3.3.2 GisEngineFactory

工厂类负责创建和管理引擎实例：

namespace OpenGIS.Utils.Engine;public static class GisEngineFactory
{// 使用单例模式private static readonly GdalEngine _gdalEngineInstance = new();/// <summary>/// 根据引擎类型获取引擎实例/// </summary>public static GisEngine GetEngine(GisEngineType engineType){return engineType switch{GisEngineType.GDAL => _gdalEngineInstance,GisEngineType.GEOTOOLS => _gdalEngineInstance, // 兼容性：重定向到GDAL_ => throw new EngineNotSupportedException($"Engine {engineType} not supported")};}/// <summary>/// 根据数据格式自动选择引擎/// </summary>public static GisEngine GetEngine(DataFormatType format){// 所有格式都使用GDAL引擎return _gdalEngineInstance;}/// <summary>/// 尝试获取引擎/// </summary>public static bool TryGetEngine(DataFormatType format, out GisEngine? engine){engine = _gdalEngineInstance;return true;}
}

设计要点：

单例引擎：引擎实例全局唯一，避免重复创建
自动选择：根据数据格式自动选择合适的引擎
向后兼容：GEOTOOLS类型重定向到GDAL

3.3.3 GdalEngine实现

namespace OpenGIS.Utils.Engine;public class GdalEngine : GisEngine
{public override GisEngineType EngineType => GisEngineType.GDAL;public override IList<DataFormatType> SupportedFormats => new List<DataFormatType>{DataFormatType.SHP,DataFormatType.GEOJSON,DataFormatType.FILEGDB,DataFormatType.GEOPACKAGE,DataFormatType.KML,DataFormatType.DXF,DataFormatType.POSTGIS};public override ILayerReader CreateReader(){return new GdalReader();}public override ILayerWriter CreateWriter(){return new GdalWriter();}
}

3.4 读写器接口

3.4.1 ILayerReader接口

namespace OpenGIS.Utils.Engine.IO;public interface ILayerReader
{/// <summary>/// 读取图层/// </summary>/// <param name="path">数据源路径</param>/// <param name="layerName">图层名称，null则读取第一个图层</param>/// <param name="attributeFilter">属性过滤条件（SQL WHERE子句）</param>/// <param name="spatialFilterWkt">空间过滤几何（WKT格式）</param>/// <param name="options">附加选项</param>OguLayer Read(string path,string? layerName = null,string? attributeFilter = null,string? spatialFilterWkt = null,Dictionary<string, object>? options = null);/// <summary>/// 获取图层名称列表/// </summary>IList<string> GetLayerNames(string path);
}

3.4.2 ILayerWriter接口

namespace OpenGIS.Utils.Engine.IO;public interface ILayerWriter
{/// <summary>/// 写入图层/// </summary>/// <param name="layer">图层对象</param>/// <param name="path">输出路径</param>/// <param name="layerName">图层名称，null则使用layer.Name</param>/// <param name="options">附加选项</param>void Write(OguLayer layer,string path,string? layerName = null,Dictionary<string, object>? options = null);/// <summary>/// 追加要素到已存在的图层/// </summary>void Append(OguLayer layer,string path,string? layerName = null,Dictionary<string, object>? options = null);
}

3.4.3 GdalReader实现要点

public class GdalReader : ILayerReader
{static GdalReader(){// 确保GDAL已初始化GdalConfiguration.ConfigureGdal();}public OguLayer Read(string path, string? layerName = null, ...){// 1. 打开数据源using var dataSource = Ogr.Open(path, 0); // 0 = 只读// 2. 获取图层var ogrLayer = layerName != null? dataSource.GetLayerByName(layerName): dataSource.GetLayerByIndex(0);// 3. 读取并转换return ReadOgrLayer(ogrLayer, attributeFilter, spatialFilterWkt);}private OguLayer ReadOgrLayer(Layer ogrLayer, ...){var layer = new OguLayer { Name = ogrLayer.GetName() };// 读取字段定义var layerDefn = ogrLayer.GetLayerDefn();for (int i = 0; i < layerDefn.GetFieldCount(); i++){var fieldDefn = layerDefn.GetFieldDefn(i);layer.AddField(new OguField{Name = fieldDefn.GetName(),DataType = MapOgrFieldType(fieldDefn.GetFieldType()),Length = fieldDefn.GetWidth(),Precision = fieldDefn.GetPrecision()});}// 读取几何类型layer.GeometryType = MapOgrGeometryType(ogrLayer.GetGeomType());// 应用过滤条件if (!string.IsNullOrWhiteSpace(attributeFilter))ogrLayer.SetAttributeFilter(attributeFilter);// 读取要素int fid = 1;Feature? ogrFeature;while ((ogrFeature = ogrLayer.GetNextFeature()) != null){using (ogrFeature){var feature = ReadOgrFeature(ogrFeature, layer.Fields, fid++);layer.AddFeature(feature);}}return layer;}
}

关键设计：

资源管理：使用using确保DataSource正确释放
类型映射：OGR类型到OGU类型的映射
过滤支持：属性过滤和空间过滤
延迟读取：使用迭代器模式读取要素

3.5 数据源模块

3.5.1 OguLayerUtil设计

OguLayerUtil 是面向应用层的高级API，封装了引擎选择和读写操作：

namespace OpenGIS.Utils.DataSource;public static class OguLayerUtil
{/// <summary>/// 读取图层/// </summary>public static OguLayer ReadLayer(DataFormatType format,string path,string? layerName = null,string? attributeFilter = null,string? spatialFilterWkt = null,GisEngineType? engineType = null,Dictionary<string, object>? options = null){// 参数验证if (string.IsNullOrWhiteSpace(path))throw new ArgumentException("Path cannot be null or empty", nameof(path));// 获取引擎var engine = engineType.HasValue? GisEngineFactory.GetEngine(engineType.Value): GisEngineFactory.GetEngine(format);// 创建读取器并读取var reader = engine.CreateReader();return reader.Read(path, layerName, attributeFilter, spatialFilterWkt, options);}/// <summary>/// 异步读取图层/// </summary>public static Task<OguLayer> ReadLayerAsync(...){return Task.Run(() => ReadLayer(...));}/// <summary>/// 写入图层/// </summary>public static void WriteLayer(DataFormatType format,OguLayer layer,string path,string? layerName = null,GisEngineType? engineType = null,Dictionary<string, object>? options = null){// 参数验证if (layer == null)throw new ArgumentNullException(nameof(layer));if (string.IsNullOrWhiteSpace(path))throw new ArgumentException("Path cannot be null or empty", nameof(path));// 获取引擎var engine = engineType.HasValue? GisEngineFactory.GetEngine(engineType.Value): GisEngineFactory.GetEngine(format);// 创建写入器并写入var writer = engine.CreateWriter();writer.Write(layer, path, layerName, options);}/// <summary>/// 格式转换/// </summary>public static void ConvertFormat(string inputPath,DataFormatType inputFormat,string outputPath,DataFormatType outputFormat,GisEngineType? engineType = null,string? layerName = null){// 读取var layer = ReadLayer(inputFormat, inputPath, layerName, engineType: engineType);// 写入WriteLayer(outputFormat, layer, outputPath, layerName, engineType);}
}

设计特点：

静态工具类：无状态，线程安全
参数灵活：支持可选参数，简化常见用法
异步支持：提供异步版本方法
格式转换：一键实现格式转换

3.6 类型映射系统

3.6.1 几何类型映射

// OGR几何类型 → OGU几何类型
private GeometryType MapOgrGeometryType(wkbGeometryType geomType)
{// 移除Z/M维度标志var flatType = wkbFlatten((int)geomType);return flatType switch{wkbGeometryType.wkbPoint => GeometryType.POINT,wkbGeometryType.wkbLineString => GeometryType.LINESTRING,wkbGeometryType.wkbPolygon => GeometryType.POLYGON,wkbGeometryType.wkbMultiPoint => GeometryType.MULTIPOINT,wkbGeometryType.wkbMultiLineString => GeometryType.MULTILINESTRING,wkbGeometryType.wkbMultiPolygon => GeometryType.MULTIPOLYGON,wkbGeometryType.wkbGeometryCollection => GeometryType.GEOMETRYCOLLECTION,_ => GeometryType.UNKNOWN};
}// OGU几何类型 → OGR几何类型
private wkbGeometryType MapToOgrGeometryType(GeometryType geomType)
{return geomType switch{GeometryType.POINT => wkbGeometryType.wkbPoint,GeometryType.LINESTRING => wkbGeometryType.wkbLineString,GeometryType.POLYGON => wkbGeometryType.wkbPolygon,GeometryType.MULTIPOINT => wkbGeometryType.wkbMultiPoint,GeometryType.MULTILINESTRING => wkbGeometryType.wkbMultiLineString,GeometryType.MULTIPOLYGON => wkbGeometryType.wkbMultiPolygon,GeometryType.GEOMETRYCOLLECTION => wkbGeometryType.wkbGeometryCollection,_ => wkbGeometryType.wkbUnknown};
}

3.6.2 字段类型映射

// OGR字段类型 → OGU字段类型
private FieldDataType MapOgrFieldType(FieldType ogrType)
{return ogrType switch{FieldType.OFTInteger => FieldDataType.INTEGER,FieldType.OFTInteger64 => FieldDataType.LONG,FieldType.OFTReal => FieldDataType.DOUBLE,FieldType.OFTString => FieldDataType.STRING,FieldType.OFTDate => FieldDataType.DATE,FieldType.OFTDateTime => FieldDataType.DATETIME,FieldType.OFTBinary => FieldDataType.BINARY,_ => FieldDataType.STRING  // 默认为字符串};
}// OGU字段类型 → OGR字段类型
private FieldType MapToOgrFieldType(FieldDataType dataType)
{return dataType switch{FieldDataType.INTEGER => FieldType.OFTInteger,FieldDataType.LONG => FieldType.OFTInteger64,FieldDataType.DOUBLE => FieldType.OFTReal,FieldDataType.FLOAT => FieldType.OFTReal,FieldDataType.STRING => FieldType.OFTString,FieldDataType.DATE => FieldType.OFTDate,FieldDataType.DATETIME => FieldType.OFTDateTime,FieldDataType.BINARY => FieldType.OFTBinary,_ => FieldType.OFTString};
}

3.6.3 驱动名称推断

private string InferDriverName(string path, Dictionary<string, object>? options)
{// 优先从选项中获取if (options?.TryGetValue("driver", out var driverObj) == true)return driverObj.ToString() ?? "ESRI Shapefile";// 根据扩展名推断var extension = Path.GetExtension(path).ToLowerInvariant();return extension switch{".shp" => "ESRI Shapefile",".gdb" => "FileGDB",".gpkg" => "GPKG",".kml" => "KML",".dxf" => "DXF",".geojson" or ".json" => "GeoJSON",_ => "ESRI Shapefile"  // 默认};
}

3.7 资源管理

3.7.1 GDAL对象生命周期

GDAL/OGR对象需要正确管理以避免内存泄漏：

// 正确的资源管理方式
public OguLayer Read(string path, ...)
{OgrDataSource? dataSource = null;try{dataSource = Ogr.Open(path, 0);if (dataSource == null)throw new DataSourceException($"Failed to open: {path}");// 处理逻辑...return layer;}finally{dataSource?.Dispose();}
}

3.7.2 要素迭代模式

// 逐个处理要素，及时释放资源
Feature? ogrFeature;
while ((ogrFeature = ogrLayer.GetNextFeature()) != null)
{using (ogrFeature)  // 确保每个要素都被释放{var feature = ConvertFeature(ogrFeature);layer.AddFeature(feature);}
}

3.7.3 几何对象管理

public void Write(OguLayer layer, string path, ...)
{foreach (var oguFeature in layer.Features){Feature? ogrFeature = null;OSGeo.OGR.Geometry? geometry = null;try{ogrFeature = new Feature(layerDefn);// 创建几何（需要单独管理）geometry = OSGeo.OGR.Geometry.CreateFromWkt(oguFeature.Wkt);if (geometry != null)ogrFeature.SetGeometry(geometry);// 写入要素ogrLayer.CreateFeature(ogrFeature);}finally{geometry?.Dispose();  // 先释放几何ogrFeature?.Dispose(); // 再释放要素}}
}

3.8 扩展点设计

3.8.1 添加新引擎

如需添加新的GIS引擎，可以：

继承 GisEngine 抽象类
实现 ILayerReader 和 ILayerWriter 接口
在 GisEngineFactory 中注册

// 示例：添加新引擎
public class MyCustomEngine : GisEngine
{public override GisEngineType EngineType => GisEngineType.CUSTOM;public override IList<DataFormatType> SupportedFormats => new List<DataFormatType> { DataFormatType.CUSTOM };public override ILayerReader CreateReader() => new MyCustomReader();public override ILayerWriter CreateWriter() => new MyCustomWriter();
}