Files
sunvpy-docs/docs/content/6-sunvstation-xi-tong-jia-gou.md
2026-04-10 13:47:53 +08:00

275 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
本文档从架构层面阐述 SunvStation 系统的设计理念、核心组件及其交互关系,帮助开发者理解系统的整体结构,为深入学习和二次开发奠定基础。
## 整体架构概览
SunvStation 采用分层架构设计,将 C++ 核心能力、Python 接口封装和业务逻辑管理清晰分离,形成高内聚、低耦合的系统结构。整个系统围绕 SSProcessManager 核心管理类展开,通过 Mixin 设计模式将功能模块化组合,同时借助 SWIG 技术实现 C++ 与 Python 的无缝集成。
Sources: [__init__.py](__init__.py#L1-L12), [PySSProcess.py](PySSProcess.py#L1-L100)
```mermaid
graph TB
subgraph "应用层 Python 业务逻辑"
SSProcess[SSProcessManager<br/>核心管理类]
subgraph "Mixin 功能模块"
SelectionM[SelectionMixin<br/>选择集操作]
GeoEditM[GeoEditMixin<br/>地理对象编辑]
ProjectM[ProjectMixin<br/>项目管理]
LogM[LogMixin<br/>日志记录]
ProgressM[ProgressMixin<br/>进度管理]
end
ObjBase[ObjBaseAttr<br/>属性管理器]
end
subgraph "接口层 SWIG 封装"
Core[PySSCore<br/>核心类型与工作空间]
Database[PySSDatabase<br/>数据库操作]
Map[PySSMap<br/>地图与数据集]
DataSource[PySSDataSource<br/>数据源访问]
View[PySSView<br/>视图控制]
DataX[PySSDataX<br/>数据交换]
Check[PySSCheck<br/>数据检查]
Math[PySSMath<br/>数学计算]
Widget[PySSWidget<br/>UI组件]
end
subgraph "实现层 C++ 核心库"
CoreDL[_PySSCore.pyd]
DatabaseDL[_PySSDatabase.pyd]
MapDL[_PySSMap.pyd]
DataSourceDL[_PySSDataSource.pyd]
ViewDL[_PySSView.pyd]
DataXDL[_PySSDataX.pyd]
CheckDL[_PySSCheck.pyd]
MathDL[_PySSMath.pyd]
WidgetDL[_PySSWidget.pyd]
end
SSProcess -.->|继承| SelectionM
SSProcess -.->|继承| GeoEditM
SSProcess -.->|继承| ProjectM
SSProcess -.->|继承| LogM
SSProcess -.->|继承| ProgressM
SSProcess -->|使用| ObjBase
SelectionM -->|调用| Core
SelectionM -->|调用| DataSource
GeoEditM -->|调用| Core
GeoEditM -->|调用| Database
ProjectM -->|调用| Core
ProjectM -->|调用| Map
LogM -.->|回调| Widget
ProgressM -->|调用| Widget
Core -->|加载| CoreDL
Database -->|加载| DatabaseDL
Map -->|加载| MapDL
DataSource -->|加载| DataSourceDL
View -->|加载| ViewDL
DataX -->|加载| DataXDL
Check -->|加载| CheckDL
Math -->|加载| MathDL
Widget -->|加载| WidgetDL
style SSProcess fill:#e1f5ff
style CoreDL fill:#fff4e1
style DatabaseDL fill:#fff4e1
style MapDL fill:#fff4e1
style DataSourceDL fill:#fff4e1
style ViewDL fill:#fff4e1
style DataXDL fill:#fff4e1
style CheckDL fill:#fff4e1
style MathDL fill:#fff4e1
style WidgetDL fill:#fff4e1
```
### 架构层次说明
SunvStation 系统架构分为三个层次,各层职责明确,通过标准接口实现交互。
**应用层**负责业务逻辑编排和用户交互,包含 SSProcessManager 核心管理类和多个 Mixin 功能模块。SSProcessManager 通过继承多个 Mixin 类组合功能,对外提供统一的 API 接口对内协调各个功能模块的协作。ObjBaseAttr 作为属性管理器统一管理地物属性的名称映射和索引转换。Sources: [PySSProcess.py](PySSProcess.py#L28-L70)
**接口层**由多个 SWIG 自动生成的 Python 模块组成,每个模块对应特定的功能域。这些模块将 C++ 对象和方法封装为 Python 可调用的接口,同时保持与底层实现的高效通信。所有接口模块遵循相同的 SWIG 封装模式包括类型代理、迭代器支持和动态属性管理。Sources: [PySSCore.py](PySSCore.py#L1-L50), [PySSDatabase.py](PySSDatabase.py#L1-L50), [PySSView.py](PySSView.py#L1-L50)
**实现层**是编译为动态链接库(.pyd 文件)的 C++ 核心代码提供高性能的地理数据处理能力。这一层包含工作空间管理、地图渲染、数据库访问、空间分析等核心算法和功能。C++ 实现通过 SWIG 暴露给 Python既保证了性能又提供了易用的脚本接口。Sources: [PySSMap.py](PySSMap.py#L1-L50), [PySSDataX.py](PySSDataX.py#L1-L50), [PySSCheck.py](PySSCheck.py#L1-L50)
## 核心组件详解
### SWIG 封装层
SWIGSimplified Wrapper and Interface Generator是连接 C++ 和 Python 的桥梁,通过自动生成的代理类实现类型安全的跨语言调用。所有 PySS*.py 文件都包含统一的 SWIG 生成代码模板包括代理对象表示、动态属性控制、元类支持和迭代器实现。Sources: [PySSCore.py](PySSCore.py#L10-L45)
| SWIG 模块 | 功能域 | C++ 动态库 |
|---------|--------|-----------|
| PySSCore | 核心类型、工作空间、几何对象 | _PySSCore.pyd |
| PySSDatabase | 数据库操作、对象存储 | _PySSDatabase.pyd |
| PySSMap | 地图管理、数据集访问 | _PySSMap.pyd |
| PySSDataSource | 数据源访问、查询 | _PySSDataSource.pyd |
| PySSView | 视图控制、地图显示 | _PySSView.pyd |
| PySSDataX | 数据交换、导入导出 | _PySSDataX.pyd |
| PySSCheck | 数据检查、验证规则 | _PySSCheck.pyd |
| PySSMath | 数学计算、坐标转换 | _PySSMath.pyd |
| PySSWidget | UI 组件、进度条 | _PySSWidget.pyd |
SWIG 封装层使用版本 4.4.0通过条件导入机制支持包内和独立模块两种导入方式确保在不同部署环境下的兼容性。Sources: [PySSCore.py](PySSCore.py#L10-L14), [PySSDatabase.py](PySSDatabase.py#L10-L14)
### SSProcessManager 核心管理类
SSProcessManager 是 SunvStation Python 接口的核心入口,通过单例模式 SSProcess 向外提供服务。该类在初始化时获取工作空间和当前地图实例创建必要的辅助对象为后续操作准备环境。Sources: [PySSProcess.py](PySSProcess.py#L28-L70)
```mermaid
flowchart LR
A[SSProcessManager.__init__] --> B[获取 WorkSpace 单例]
B --> C[获取当前 ScaleMap]
C --> D[获取 GlobalOptions 单例]
D --> E[创建 ObjBaseAttr 属性管理器]
E --> F[创建 GeoBaseList 选择集]
F --> G[创建 SSearchHelper 搜索助手]
G --> H[创建缓存对象列表]
H --> I[创建进度条和日志对象]
I --> J[初始化完成]
style A fill:#e1f5ff
style J fill:#d4edda
```
SSProcessManager 的成员变量涵盖了工作空间管理的各个方面包括工作空间引用、地图实例、全局配置、属性管理器、选择集列表、搜索助手、当前选中对象、新建对象缓存、删除对象缓存、进度条和日志记录器等。这种设计将所有操作所需的状态集中管理简化了跨模块协作。Sources: [PySSProcess.py](PySSProcess.py#L33-L66)
### Mixin 设计模式
Mixin 设计模式是 SSProcessManager 架构的核心特征,通过将功能拆分为独立的 Mixin 类实现代码复用和职责分离。SSProcessManager 继承自五个 Mixin 类SelectionMixin、GeoEditMixin、ProjectMixin、LogMixin 和 ProgressMixin每个 Mixin 负责特定的功能域。Sources: [PySSProcess.py](PySSProcess.py#L28)
Mixin 之间存在依赖关系形成了清晰的功能层次。SelectionMixin 继承自 GeoEditAware、LogAware 和 ProgressAware继承了地理编辑、日志记录和进度管理的抽象接口。GeoEditMixin 定义了地理对象编辑的抽象方法,为具体实现提供规范。这种基于抽象基类的设计确保了 Mixin 之间的松耦合和高内聚。Sources: [ssprocess_mixins/selection_mixin.py](ssprocess_mixins/selection_mixin.py#L21-L40), [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L13-L55)
| Mixin 类 | 功能域 | 主要方法 |
|---------|--------|----------|
| SelectionMixin | 选择集管理 | clearSelection, setSelectCondition, selectFilter, getSelGeoCount |
| GeoEditMixin | 地理对象编辑 | createDefaultGeoBase, createNewObjByCode, addNewObjPoint, saveBufferObjToDatabase |
| ProjectMixin | 项目和工作空间 | getWorkspace, getCurrentMap, pushUndoMark, getSysPathName, mapZoom |
| LogMixin | 日志记录 | set_logger, log_error_msg |
| ProgressMixin | 进度管理 | disable_progress, startProgress, stepProgress, closeProgress |
### 属性管理系统
ObjBaseAttr 类负责地物属性的统一管理将属性名称映射为索引提供类型安全的属性访问。该类在初始化时注册所有预定义的属性名称包括点属性、地物通用属性、几何参量、注记属性等并为常用属性提供便捷访问属性。Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L6-L80)
属性名称采用 SSObj_ 前缀的命名约定,涵盖了地物对象的各个方面。点属性包括 PointName、PointCount、PointType、X、Y、Z地物通用属性包括 Code、LayerName、Color、LineType、ID、Name、Type 等;几何参量包括 Area、Length、3DLength、边界坐标等注记属性包括字体、颜色、对齐方式、方向等。通过统一的属性命名和管理系统确保了属性访问的一致性和可维护性。Sources: [ObjBaseAttr.py](ObjBaseAttr.py#L13-L60)
## 模块架构与职责
### 核心模块
PySSCore 模块定义了系统的基础类型和工作空间管理类,是整个系统的核心依赖。该模块包含 WorkSpace 单例类、GeoBase 地物基类、GeoBaseList 地物列表、SSearchHelper 搜索助手等核心类型。WorkSpace 采用单例模式,提供全局唯一的工作空间实例,通过 getInstance() 方法访问。ScaleMap 代表比例尺地图管理数据集和图层。Sources: [PySSProcess.py](PySSProcess.py#L55-L66)
PySSDatabase 模块负责数据库操作包括对象的创建、修改、删除和查询。该模块封装了底层数据库访问逻辑提供事务支持和缓存管理。PySSMap 模块管理地图和数据集提供图层控制、视图操作和数据集访问功能。PySSDataSource 模块处理数据源访问支持多种数据格式和查询方式。Sources: [PySSDatabase.py](PySSDatabase.py#L1-L80), [PySSMap.py](PySSMap.py#L1-L100)
### 功能域划分
SunvStation 系统按照功能域划分为六个主要领域,每个领域由相应的模块和 Mixin 负责实现。选择集与查询领域由 SelectionMixin 和 SSearchHelper 负责,支持条件设置、过滤查询和选择集遍历。地理对象编辑领域由 GeoEditMixin 负责提供对象创建、坐标添加、属性设置和数据库保存功能。Sources: [ssprocess_mixins/selection_mixin.py](ssprocess_mixins/selection_mixin.py#L44-L65), [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L13-L55)
数据交换领域由 PySSDataX 模块负责,支持外部数据的导入导出和格式转换。数据检查领域由 PySSCheck 模块负责,提供检查记录管理和自定义规则验证。高级功能领域由 ProjectMixin、LogMixin 和 ProgressMixin 共同负责,涵盖工作空间管理、日志记录和进度显示。参考手册领域则提供完整的 API 文档和工具函数索引。Sources: [PySSDataX.py](PySSDataX.py#L1-L80), [PySSCheck.py](PySSCheck.py#L1-L50)
## 设计模式与架构特性
### Mixin 设计模式
Mixin 设计模式是系统架构的核心特征,通过多重继承实现功能的组合。每个 Mixin 类专注于单一职责提供相关的方法集合。SelectionMixin 专注于选择集操作包括清除选择集、设置条件、执行过滤等。GeoEditMixin 专注于地理对象编辑包括对象创建、属性修改、缓存管理等。ProjectMixin 专注于项目和工作空间操作包括获取工作空间、地图缩放、撤销标记等。Sources: [ssprocess_mixins/selection_mixin.py](ssprocess_mixins/selection_mixin.py#L44-L65), [ssprocess_mixins/project_mixin.py](ssprocess_mixins/project_mixin.py#L31-L56)
Mixin 之间通过抽象基类建立契约关系确保接口的一致性。LogAware 和 ProgressAware 定义了日志和进度管理的抽象接口LogMixin 和 ProgressMixin 提供具体实现。GeoEditAware 定义了地理编辑的抽象方法GeoEditMixin 实现这些方法,其他需要编辑功能的 Mixin 可以继承 GeoEditAware 或依赖 GeoEditMixin。Sources: [ssprocess_mixins/log_mixin.py](ssprocess_mixins/log_mixin.py#L17-L28), [ssprocess_mixins/progress_mixin.py](ssprocess_mixins/progress_mixin.py#L17-L35)
### 单例模式
单例模式在系统中广泛使用确保全局唯一对象的创建和访问。WorkSpace 采用单例模式,通过 getInstance() 方法获取唯一实例全局维护工作空间状态。GlobalOptions 同样采用单例模式管理系统全局配置选项。SSProcess 作为全局导出的单例,提供统一的访问入口,简化了 API 的使用。Sources: [PySSProcess.py](PySSProcess.py#L55-L58), [PySSProcess.py](PySSProcess.py#L136-L137)
### 抽象基类模式
抽象基类ABC用于定义 Mixin 之间的契约确保接口的一致性和可扩展性。LogAware 和 ProgressAware 使用 abc.ABC 作为基类定义了必须实现的抽象方法。GeoEditAware 继承自 abc.ABC定义了地理编辑的抽象方法列表。这种设计利用 Python 的类型系统在编译时检查接口的完整性提高了代码的健壮性。Sources: [ssprocess_mixins/log_mixin.py](ssprocess_mixins/log_mixin.py#L17-L18), [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L12)
### 依赖注入模式
依赖注入模式在系统中体现在对象成员的显式声明和初始化上。SSProcessManager 和各个 Mixin 类都显式声明了成员变量类型,包括 workspace、map、global_options、logger 等。这种设计使得依赖关系清晰可见,便于单元测试和模块替换。成员变量的类型注解使用 typing 模块,包括 Optional 和 Callable提高了代码的可读性和 IDE 支持度。Sources: [PySSProcess.py](PySSProcess.py#L33-L66), [ssprocess_mixins/selection_mixin.py](ssprocess_mixins/selection_mixin.py#L21-L40)
## 技术栈与依赖
### SWIG 封装技术
SWIG 版本 4.4.0 是系统跨语言集成的核心技术,通过自动生成的代理类实现 C++ 和 Python 的无缝连接。每个 PySS*.py 文件都包含 SWIG 生成的标准模板包括动态属性控制、迭代器支持和元类实现。SWIG 使用 _swig_repr 提供对象的字符串表示,使用 _swig_setattr_nondynamic_instance_variable 和 _swig_setattr_nondynamic_class_variable 防止动态属性添加确保类型安全。Sources: [PySSCore.py](PySSCore.py#L1-L45), [PySSDatabase.py](PySSDatabase.py#L1-L45)
### Python 类型提示
系统广泛使用 Python 类型提示,提高代码的可读性和 IDE 支持度。typing.Optional 用于可能为 None 的对象,如 logger 和 progress。typing.Callable 用于回调函数类型。成员变量使用显式类型注解,如 workspace: WorkSpace、map: ScaleMap、enable_progress: bool。这种设计利用 Python 3.5+ 的类型系统在不影响运行时性能的前提下提供静态类型检查。Sources: [PySSProcess.py](PySSProcess.py#L33-L66), [ssprocess_mixins/log_mixin.py](ssprocess_mixins/log_mixin.py#L17-L28)
### 抽象基类ABC
abc 模块用于定义抽象基类和抽象方法,建立 Mixin 之间的契约。LogAware 和 ProgressAware 定义了日志和进度管理的抽象方法LogMixin 和 ProgressMixin 提供具体实现。GeoEditAware 定义了地理编辑的抽象方法,包括 createDefaultGeoBase、createNewObjByCode、addNewObjPoint 等。这种设计利用 Python 的抽象基类机制在编译时检查接口实现提高了代码的健壮性。Sources: [ssprocess_mixins/log_mixin.py](ssprocess_mixins/log_mixin.py#L17-L28), [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L12)
## 数据流与交互
### 初始化流程
系统初始化从导入 sunvpy 模块开始,通过 __init__.py 定义包的元信息和导出接口。创建 SSProcessManager 实例时,依次获取 WorkSpace 单例、当前 ScaleMap、GlobalOptions 单例,创建 ObjBaseAttr 属性管理器、GeoBaseList 选择集、SSearchHelper 搜索助手初始化缓存对象列表、进度条和日志对象。初始化完成后SSProcess 作为全局单例提供服务。Sources: [PySSProcess.py](PySSProcess.py#L28-L70), [PySSProcess.py](PySSProcess.py#L136-L137)
### 操作流程
用户通过 SSProcess 调用 Mixin 提供的方法,如 setSelectCondition 设置选择条件selectFilter 执行过滤查询getSelGeoCount 获取选择集数量。方法调用通过 Mixin 委托给 SWIG 封装的 C++ 对象,如 SSearchHelper 的 m_selectConditions 属性WorkSpace 的 getCurrentScaleMap 方法。结果通过 SWIG 代理对象返回 Python 层,由 Mixin 进行必要的数据转换和缓存管理。Sources: [ssprocess_mixins/selection_mixin.py](ssprocess_mixins/selection_mixin.py#L44-L65)
### 缓存管理
系统采用多级缓存机制提高性能和事务管理能力。selGeoList 和 selNoteList 缓存脚本选择集的地物和注记bufferObjList 和 bufferNoteList 缓存需要保存的对象newBufferObjList 和 newBufferNoteList 缓存新创建的对象delBufferGeoList 缓存需要删除的对象。通过 saveBufferObjToDatabase 方法批量将缓存对象保存到数据库,通过 pushUndoMark 方法创建撤销标记支持操作回滚。Sources: [PySSProcess.py](PySSProcess.py#L59-L66), [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L56-L60)
```mermaid
sequenceDiagram
participant User as 用户代码
participant SSProcess as SSProcessManager
participant Mixin as Mixin 模块
participant SWIG as SWIG 封装层
participant CPP as C++ 核心库
User->>SSProcess: SSProcess.setSelectCondition()
SSProcess->>Mixin: SelectionMixin.setSelectCondition()
Mixin->>SWIG: searchHelper.m_selectConditions.add()
SWIG->>CPP: SSearchHelper::addCondition()
CPP-->>SWIG: 返回结果
SWIG-->>Mixin: 返回结果
Mixin-->>SSProcess: 完成
SSProcess-->>User: 返回
User->>SSProcess: SSProcess.selectFilter()
SSProcess->>Mixin: SelectionMixin.selectFilter()
Mixin->>SWIG: searchHelper.search()
SWIG->>CPP: SSearchHelper::executeQuery()
CPP-->>SWIG: 返回 GeoBaseList
SWIG-->>Mixin: 返回选择集
Mixin->>Mixin: 缓存到 selGeoList
Mixin-->>SSProcess: 完成
SSProcess-->>User: 返回选择集数量
User->>SSProcess: SSProcess.saveBufferObjToDatabase()
SSProcess->>Mixin: GeoEditMixin.saveBufferObjToDatabase()
Mixin->>SWIG: GeoBaseList.saveToDatabase()
SWIG->>CPP: Database::batchSave()
CPP-->>SWIG: 返回保存结果
SWIG-->>Mixin: 返回结果
Mixin->>Mixin: 清空缓存
Mixin-->>SSProcess: 完成
SSProcess-->>User: 返回
```
## 推荐学习路径
基于系统架构和文档目录,建议按照以下顺序深入学习 SunvStation 系统:
1. **基础概念**:首先阅读[库概述](1-ku-gai-shu)和[安装与环境配置](2-an-zhuang-yu-huan-jing-pei-zhi),了解系统基本概念和部署要求。
2. **入门实践**:通过[第一个脚本:查询地物属性](3-di-ge-jiao-ben-cha-xun-di-wu-shu-xing)和[使用 SSProcess 管理选择集](4-shi-yong-ssprocess-guan-li-xuan-ze-ji)进行实践操作,熟悉基本 API。
3. **架构理解**:在实践基础上,深入理解本文档[SunvStation 系统架构](6-sunvstation-xi-tong-jia-gou),然后学习[SWIG 封装机制说明](7-swig-feng-zhuang-ji-zhi-shuo-ming)和[C++ 扩展模块与 Python 接口](10-c-kuo-zhan-mo-kuai-yu-python-jie-kou),理解跨语言集成原理。
4. **核心概念**:学习[工作空间与地图概念](8-gong-zuo-kong-jian-yu-di-tu-gai-nian)和[Mixin 设计模式](9-mixin-she-ji-mo-shi),理解系统核心概念和设计思想。
5. **功能深入**:根据业务需求,深入学习各个功能域的文档,包括选择集与查询、地理对象编辑、数据交换、数据检查等章节。
6. **参考手册**:在开发过程中,随时查阅[SSProcessManager 完整 API](40-ssprocessmanager-wan-zheng-api)、[ObjBaseAttr 属性索引](41-objbaseattr-shu-xing-suo-yin)和[地理对象类型定义](42-di-li-dui-xiang-lei-xing-ding-yi)等参考手册。
这种学习路径从基础到深入,从实践到理论,帮助开发者逐步掌握 SunvStation 系统的核心能力和架构设计。