Muotai SPG 模块结构文档

1. 概述

Muotai SPG (Semantic Property Graph) 是基于OpenSPG的知识图谱服务模块，提供完整的知识图谱管理能力，包括Schema定义、图数据操作、KGDSL查询和推理引擎。

1.1 核心功能

┌─────────────────────────────────────────────────────────────┐
│                    Muotai SPG 架构                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐   │
│  │              │   │              │   │              │   │
│  │ Schema管理   │──▶│ 图数据操作   │──▶│ 查询与推理   │   │
│  │              │   │              │   │              │   │
│  └──────────────┘   └──────────────┘   └──────────────┘   │
│         │                   │                    │         │
│         ▼                   ▼                    ▼         │
│    模型定义             实体/关系           KGDSL查询       │
│    版本管理             CRUD操作            逻辑推理         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

1.2 技术栈

组件	技术
框架	Spring Boot 3.4.5, Spring Cloud 2024.0.0
JDK	Java 17
数据库	MyBatis-Plus (MySQL持久化)
查询引擎	KGDSL (自定义图查询DSL)
推理引擎	LUBE (Logical Unit Backend Engine)
语言混合	Java + Scala (Reasoner引擎)
服务注册	Nacos

2. 模块架构

Muotai SPG采用标准的API-BIZ分层架构：

muotai-spg/
├── muotai-spg-api/          # API定义层
│   └── src/main/java/
│       └── com/aroundix/spg/api/
│           ├── dto/         # 数据传输对象
│           └── entity/      # 实体定义
│
├── muotai-spg-biz/          # 业务实现层
│   └── src/main/java/
│       ├── com/aroundix/spg/           # SPG服务层
│       └── com/aroundix/openspg/       # OpenSPG核心引擎
│
├── lib/                     # 外部依赖库
└── doc/                     # 文档目录

3. muotai-spg-api 模块

3.1 模块概述

API模块提供REST接口定义、DTO对象和实体类，是对外暴露的服务接口层。

3.2 包结构

com.aroundix.spg.api/
├── dto/                          # 数据传输对象
│   ├── CreateEntityRequest.java      # 创建实体请求
│   ├── CreateRelationRequest.java    # 创建关系请求
│   ├── GraphQueryRequest.java        # 图查询请求
│   ├── SchemaDefinition.java         # Schema定义
│   └── SchemaUploadRequest.java      # Schema上传请求
│
└── entity/                       # 数据库实体
    ├── KgOntologyEntity.java         # 本体实体
    ├── KgOntologyPropertyRange.java  # 属性范围
    ├── KgOntologyRelease.java        # 本体发布版本
    ├── KgProjectEntity.java          # 项目实体
    ├── KgProjectInfo.java            # 项目信息
    └── KgPropertyConstraint.java     # 属性约束

3.3 核心DTO说明

DTO类	功能描述	使用场景
CreateEntityRequest	创建图节点请求	创建实体节点API
CreateRelationRequest	创建图边请求	创建关系边API
GraphQueryRequest	Cypher查询请求	执行图查询API
SchemaDefinition	Schema定义对象	Schema管理API
SchemaUploadRequest	Schema上传请求	Schema导入API

3.4 核心实体说明

实体类	对应表	功能描述
KgOntologyEntity	kg_ontology_entity	本体实体类型定义
KgOntologyRelease	kg_ontology_release	Schema版本发布记录
KgProjectInfo	kg_project_info	项目基本信息
KgPropertyConstraint	kg_property_constraint	属性约束规则

4. muotai-spg-biz 模块

4.1 模块概述

BIZ模块是核心业务逻辑实现层，包含SPG服务实现和OpenSPG引擎集成。该模块包含约400+ Java/Scala源文件。

4.2 顶层包结构

com/aroundix/
├── spg/                          # SPG服务层 (14个文件)
│   ├── SpgApplication.java          # 服务启动类
│   ├── config/                      # 配置类
│   ├── controller/                  # REST控制器
│   ├── service/                     # 业务服务
│   └── mapper/                      # MyBatis映射器
│
└── openspg/                      # OpenSPG引擎层 (380+个文件)
    ├── builder/                     # 知识构建引擎
    ├── cloudext/                    # 云扩展接口
    ├── common/                      # 公共工具类
    ├── core/                        # 核心模型
    ├── reasoner/                    # 推理引擎核心
    └── server/                      # 服务端API

5. 核心包详解

5.1 SPG服务层 (com.aroundix.spg)

5.1.1 包结构

com.aroundix.spg/
├── SpgApplication.java              # Spring Boot启动类
├── config/                          # 配置管理
│   └── [配置类]
├── controller/                      # REST API控制器
│   ├── GraphController.java            # 图数据操作API
│   └── SchemaController.java           # Schema管理API
├── service/                         # 业务服务接口
│   ├── GraphService.java               # 图服务接口
│   ├── SchemaService.java              # Schema服务接口
│   └── impl/                           # 服务实现
│       ├── GraphServiceImpl.java
│       └── SchemaServiceImpl.java
└── mapper/                          # MyBatis数据访问层
    └── [Mapper接口]

5.1.2 核心类说明

SpgApplication.java - 服务启动类

java

/**
 * SPG(Semantic Property Graph)服务启动类
 *
 * 提供知识图谱相关的核心功能：
 * - Schema管理 - 知识图谱模型定义与版本管理
 * - 图数据操作 - 实体与关系的增删改查
 * - Cypher查询 - 灵活的图查询能力
 * - 路径分析 - 知识图谱路径查询与遍历
 */

GraphController.java - 图数据操作控制器

提供实体节点的CRUD操作
提供关系边的CRUD操作
执行Cypher查询
路径查询与图遍历

SchemaController.java - Schema管理控制器

Schema上传与解析
Schema验证与发布
版本管理与回滚
Schema查询与版本历史

5.2 OpenSPG引擎层 (com.aroundix.openspg)

5.2.1 Builder模块 - 知识构建引擎

com.aroundix.openspg.builder/
├── core/                            # 构建核心
│   └── [构建引擎核心类]
├── model/                           # 构建模型
│   └── [数据模型定义]
└── runner/                          # 执行运行器
    └── [Pipeline执行器]

功能说明:

从数据源抽取数据
实体识别与链接
知识融合与冲突解决
批量导入图数据

5.2.2 Reasoner模块 - 推理引擎 (核心)

这是最大的模块，包含**300+**文件，是SPG的推理引擎核心。

5.2.2.1 LUBE子系统 - 逻辑单元后端引擎 (249个文件)

com.aroundix.openspg.reasoner.lube/
├── block/                           # 执行块
│   └── [执行单元定义]
│
├── catalog/                         # 元数据目录
│   ├── struct/                         # 结构定义
│   └── [Catalog实现]
│
├── common/                          # 公共组件
│   ├── expr/                           # 表达式系统
│   │   └── [各类表达式实现]
│   ├── graph/                          # 图模型
│   │   └── [图结构定义]
│   ├── pattern/                        # 模式匹配
│   │   └── [Pattern定义]
│   └── rule/                           # 规则引擎
│       └── [Rule定义]
│
├── logical/                         # 逻辑计划层
│   ├── operators/                      # 逻辑算子
│   │   ├── Aggregate.java                 # 聚合算子
│   │   ├── Filter.java                    # 过滤算子
│   │   ├── PatternScan.java               # 模式扫描
│   │   ├── Project.java                   # 投影算子
│   │   ├── Select.java                    # 选择算子
│   │   ├── Join.java                      # 连接算子
│   │   └── [20+其他算子]
│   │
│   ├── optimizer/                      # 查询优化器
│   │   ├── rules/                         # 优化规则
│   │   │   └── [RBO规则实现]
│   │   └── [优化器核心]
│   │
│   ├── planning/                       # 逻辑规划
│   │   └── [逻辑计划生成]
│   │
│   └── validate/                       # 语义验证
│       ├── semantic/                      # 语义检查
│       │   └── rules/                     # 验证规则
│       └── [验证器实现]
│
├── physical/                        # 物理计划层
│   ├── operators/                      # 物理算子
│   │   ├── AddInto.java                   # 添加字段
│   │   ├── Aggregate.java                 # 聚合执行
│   │   ├── Cache.java                     # 缓存算子
│   │   ├── Filter.java                    # 过滤执行
│   │   ├── Join.java                      # 连接执行
│   │   ├── PatternScan.java               # 模式扫描执行
│   │   └── [30+其他算子]
│   │
│   ├── planning/                       # 物理规划
│   │   └── PhysicalPlanner.java           # 物理计划生成器
│   │
│   ├── rdg/                            # RDG (Relational Data Graph)
│   │   └── RDG.java                       # RDG抽象
│   │
│   └── util/                           # 物理层工具
│       └── [工具类]
│
├── parser/                          # DSL解析器
│   └── [KGDSL解析实现]
│
└── utils/                           # LUBE工具类
    ├── transformer/                    # 转换器
    │   └── impl/                          # 转换实现
    └── [其他工具]

LUBE架构说明:

LUBE (Logical Unit Backend Engine) 是SPG的查询执行引擎，采用经典的Volcano模型：

KGDSL Query
     ↓
[Parser] ─────────────→ Abstract Syntax Tree (AST)
     ↓
[Logical Planner] ────→ Logical Plan (逻辑计划)
     ↓
[Optimizer] ──────────→ Optimized Logical Plan
     ↓
[Physical Planner] ───→ Physical Plan (物理计划)
     ↓
[Executor] ───────────→ Execution Result

核心概念:

Logical Operators (逻辑算子)
- 描述"做什么"(What to do)
- 与物理实现无关
- 例如: PatternScan, Filter, Aggregate, Join
Physical Operators (物理算子)
- 描述"怎么做"(How to do)
- 具体的执行策略
- 例如: HashJoin, IndexScan, StreamAggregate
RDG (Relational Data Graph)
- 关系型数据图抽象
- 统一图数据和表数据的访问接口
Pattern Matching (模式匹配)
- 支持图模式查询
- 类似Cypher的MATCH语法

5.2.2.2 Parser子系统 - DSL解析 (9个文件)

com.aroundix.openspg.reasoner.parser/
├── expr/                            # 表达式解析
│   └── [表达式解析器]
├── pattern/                         # 模式解析
│   └── [模式解析器]
└── utils/                           # 解析工具
    └── [工具类]

功能说明:

基于ANTLR4的KGDSL语法解析
生成抽象语法树(AST)
错误处理与语法验证

5.2.2.3 其他Reasoner子系统

com.aroundix.openspg.reasoner/
├── batching/                        # 批处理
│   └── [批量执行引擎]
│
├── catalog/                         # 元数据管理
│   └── [Schema元数据访问]
│
├── common/                          # 公共组件
│   └── [通用工具和模型]
│
├── context/                         # 执行上下文
│   └── [查询执行上下文]
│
├── graphstate/                      # 图状态管理
│   └── [图状态跟踪]
│
├── io/                              # 输入输出
│   └── [数据读写接口]
│
├── kggraph/                         # 知识图谱
│   └── [图操作接口]
│
├── loader/                          # 数据加载
│   └── [数据加载器]
│
├── pattern/                         # 模式匹配
│   └── PatternMatcher.java             # 模式匹配器
│
├── progress/                        # 进度跟踪
│   └── [执行进度管理]
│
├── rdg/                             # RDG实现
│   └── common/                         # RDG通用实现
│       ├── KgGraphLeftJoinImpl.java       # Left Join实现
│       ├── KgGraphAggregateImpl.java      # Aggregate实现
│       └── LinkEdgeImpl.java              # 边链接实现
│
├── recorder/                        # 记录器
│   └── [执行日志记录]
│
├── runner/                          # 执行运行器
│   └── local/                          # 本地执行器
│       ├── rdg/LocalRDG.java              # 本地RDG实现
│       └── impl/LocalPropertyGraph.java   # 本地图实现
│
├── session/                         # 会话管理
│   └── [查询会话]
│
├── shuffle/                         # 数据洗牌
│   └── [分布式Shuffle]
│
├── sink/                            # 结果输出
│   └── [结果Sink]
│
├── struct/                          # 数据结构
│   └── [内部数据结构]
│
├── task/                            # 任务调度
│   └── [任务执行管理]
│
├── udf/                             # 用户自定义函数
│   └── [UDF注册与执行]
│
├── util/                            # 工具类
│   └── KgGraphSchema.java              # 图Schema工具
│
├── utils/                           # 通用工具
│   └── RunnerUtil.java                 # 执行工具
│
└── warehouse/                       # 数据仓库
    └── utils/WareHouseUtils.java       # 仓库工具

5.2.3 Core模块 - 核心模型

com.aroundix.openspg.core/
├── reasoner/                        # 推理核心接口
│   └── [推理接口定义]
├── scheduler/                       # 调度器
│   └── [任务调度]
└── schema/                          # Schema模型
    └── [类型系统定义]

功能说明:

定义核心抽象接口
类型系统基础定义
调度器接口

5.2.4 Server模块 - 服务端

com.aroundix.openspg.server/
├── api/                             # API层
│   └── http/                           # HTTP客户端
│       └── client/HttpSchemaFacade.java   # Schema远程访问
│
├── biz/                             # 业务逻辑
│   └── [业务处理]
│
├── model/                           # 模型定义
│   └── project/Project.java            # 项目模型
│
└── service/                         # 服务实现
    └── [服务层实现]

5.2.5 CloudExt模块 - 云扩展

com.aroundix.openspg.cloudext/
├── interfaces/                      # 扩展接口
│   └── [云服务接口定义]
└── impl/                            # 接口实现
    └── [云服务实现]

功能说明:

提供云服务扩展点
支持多租户隔离
分布式存储适配

5.2.6 Common模块 - 公共工具

com.aroundix.openspg.common/
├── constants/                       # 常量定义
│   └── [系统常量]
└── util/                            # 工具类
    └── [通用工具方法]

5.3 OpenSPG 引擎层深入解析

5.3.1 整体架构与文件分布

OpenSPG引擎层是整个SPG系统的核心，包含1413个文件，分为6个主要模块：

模块	文件数	占比	核心职责
Reasoner	586	41.5%	推理引擎、查询执行
Core	241	17.1%	Schema模型、调度器
Server	223	15.8%	服务端API、业务逻辑
CloudExt	152	10.8%	云服务扩展
Builder	148	10.5%	知识构建引擎
Common	63	4.5%	公共工具

┌────────────────────────────────────────────────────────────────┐
│                    OpenSPG 引擎层架构                          │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────────────────────────────────────────┐     │
│  │                  Reasoner (586)                       │     │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐           │     │
│  │  │  LUBE    │  │  Parser  │  │  Runner  │           │     │
│  │  │  (249)   │→ │   (9)    │→ │  (50+)   │           │     │
│  │  └──────────┘  └──────────┘  └──────────┘           │     │
│  └──────────────────────────────────────────────────────┘     │
│           ↓                          ↑                          │
│  ┌─────────────────┐      ┌─────────────────┐                 │
│  │  Core (241)     │      │  Builder (148)  │                 │
│  │  Schema/模型    │      │  ETL Pipeline   │                 │
│  └─────────────────┘      └─────────────────┘                 │
│           ↓                          ↑                          │
│  ┌─────────────────────────────────────────────────────┐      │
│  │              CloudExt (152)                          │      │
│  │  GraphStore | Cache | SearchEngine | ObjectStorage │      │
│  └─────────────────────────────────────────────────────┘      │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

5.3.2 Reasoner推理引擎 (586个文件) - 详解

5.3.2.1 LUBE查询引擎 (249个文件)

位置: com.aroundix.openspg.reasoner.lube

LUBE是OpenSPG的查询执行引擎，采用Volcano迭代模型。

详细包结构:

lube/
├── block/                           # 查询块 (5个文件)
│   ├── Block.java                      # 查询块抽象
│   ├── DDLBlock.java                   # DDL块
│   ├── MatchBlock.java                 # MATCH块
│   ├── ProjectBlock.java               # 投影块
│   └── TableResultBlock.java           # 结果块
│
├── catalog/                         # 元数据目录 (8个文件)
│   ├── Catalog.java                    # 元数据接口
│   ├── SemanticPropertyGraph.java      # 语义图
│   └── struct/                         # 结构定义
│       ├── Field.java                     # 字段
│       ├── Node.java                      # 节点
│       └── Edge.java                      # 边
│
├── common/                          # 公共组件 (50+个文件)
│   ├── expr/                           # 表达式系统 (30+个)
│   │   ├── Expr.java                      # 表达式基类
│   │   ├── Ref.java                       # 引用表达式
│   │   ├── BinaryOpExpr.java              # 二元运算
│   │   ├── UnaryOpExpr.java               # 一元运算
│   │   ├── AggFunc.java                   # 聚合函数
│   │   ├── GetField.java                  # 获取字段
│   │   ├── VNot.java, VEqual.java         # 逻辑/比较运算
│   │   └── [25+其他表达式类型]
│   │
│   ├── graph/                          # 图模型 (10个文件)
│   │   ├── IRGraph.java                   # 图IR
│   │   ├── IRNode.java                    # 节点IR
│   │   ├── IREdge.java                    # 边IR
│   │   └── IRProperty.java                # 属性IR
│   │
│   ├── pattern/                        # 模式定义 (15个文件)
│   │   ├── Pattern.java                   # 模式基类
│   │   ├── Connection.java                # 连接
│   │   ├── PatternElement.java            # 模式元素
│   │   ├── NodePattern.java               # 节点模式
│   │   ├── EdgePattern.java               # 边模式
│   │   ├── LinkedPattern.java             # 链接模式
│   │   └── PartialGraphPattern.java       # 部分图模式
│   │
│   └── rule/                           # 规则引擎 (5个文件)
│       ├── Rule.java                      # 规则基类
│       └── LogicalRule.java               # 逻辑规则
│
├── logical/                         # 逻辑计划层 (70+个文件)
│   ├── operators/                      # 逻辑算子 (30个文件)
│   │   ├── LogicalOperator.java           # 算子基类
│   │   ├── Source.java                    # 数据源
│   │   ├── Start.java                     # 起点
│   │   ├── PatternScan.java               # 模式扫描 ⭐
│   │   ├── Filter.java                    # 过滤
│   │   ├── Select.java                    # 选择
│   │   ├── Project.java                   # 投影
│   │   ├── Aggregate.java                 # 聚合
│   │   ├── Join.java                      # 连接
│   │   ├── PatternJoin.java               # 模式连接
│   │   ├── ExpandInto.java                # 扩展
│   │   ├── LinkedExpand.java              # 链接扩展
│   │   ├── BoundedVarLenExpand.java       # 变长路径扩展
│   │   ├── OrderAndLimit.java             # 排序限制
│   │   ├── DDL.java                       # DDL操作
│   │   ├── SubQuery.java                  # 子查询
│   │   ├── Optional.java                  # 可选匹配
│   │   └── [其他算子]
│   │
│   ├── optimizer/                      # 查询优化器 (20个文件)
│   │   ├── SimpleLogicalOptimizer.java    # 简单优化器
│   │   ├── Direction.java                 # 优化方向
│   │   └── rules/                         # 优化规则
│   │       ├── FilterPushDown.java           # 过滤下推
│   │       ├── ProjectPushDown.java          # 投影下推
│   │       ├── JoinReorder.java              # Join重排序
│   │       └── [其他优化规则]
│   │
│   ├── planning/                       # 逻辑规划 (10个文件)
│   │   ├── JoinType.java                  # Join类型
│   │   ├── InnerJoin.java                 # 内连接
│   │   ├── LeftOuterJoin.java             # 左外连接
│   │   └── CrossJoin.java                 # 交叉连接
│   │
│   └── validate/                       # 语义验证 (15个文件)
│       ├── Validator.java                 # 验证器基类
│       ├── semantic/                      # 语义检查
│       │   ├── SemanticChecker.java          # 语义检查器
│       │   └── rules/                        # 验证规则
│       │       ├── TypeCheckRule.java           # 类型检查
│       │       ├── ScopeCheckRule.java          # 作用域检查
│       │       └── [其他验证规则]
│       └── [其他验证器]
│
├── physical/                        # 物理计划层 (60+个文件)
│   ├── operators/                      # 物理算子 (35个文件)
│   │   ├── PhysicalOperator.java          # 算子基类
│   │   ├── Start.java                     # 起点 ⭐
│   │   ├── StartFromVertex.java           # 从顶点开始
│   │   ├── DrivingRDG.java                # 驱动RDG
│   │   ├── PatternScan.java               # 模式扫描
│   │   ├── ExpandInto.java                # 扩展
│   │   ├── LinkedExpand.java              # 链接扩展
│   │   ├── Filter.java                    # 过滤执行
│   │   ├── Select.java                    # 选择执行
│   │   ├── Aggregate.java                 # 聚合执行
│   │   ├── Join.java                      # 连接执行
│   │   ├── Union.java                     # 合并
│   │   ├── OrderBy.java                   # 排序
│   │   ├── Cache.java                     # 缓存 ⭐
│   │   ├── AddInto.java                   # 添加字段
│   │   ├── Drop.java                      # 删除字段
│   │   ├── Fold.java                      # 折叠
│   │   ├── Unfold.java                    # 展开
│   │   └── [其他物理算子]
│   │
│   ├── planning/                       # 物理规划 (3个文件)
│   │   ├── PhysicalPlanner.java           # 物理规划器 ⭐⭐⭐
│   │   └── PhysicalPlannerContext.java    # 规划上下文
│   │
│   ├── rdg/                            # RDG抽象 (5个文件)
│   │   └── RDG.java                       # 关系数据图接口 ⭐
│   │
│   └── util/                           # 物理层工具 (5个文件)
│       └── [工具类]
│
├── parser/                          # DSL解析器 (3个文件)
│   └── [解析实现桩]
│
└── utils/                           # LUBE工具类 (10个文件)
    ├── BlockUtils.java                 # 块工具
    ├── ExprUtils.java                  # 表达式工具
    ├── transformer/                    # 转换器
    │   ├── Expr2QlexpressTransformer.java # 表达式转换
    │   └── impl/                          # 转换实现
    └── [其他工具]

关键类深度解析:

PhysicalPlanner.java - 物理规划器核心

位置: lube/physical/planning/PhysicalPlanner.java

职责: 将逻辑计划转换为可执行的物理计划

java

public class PhysicalPlanner {
    // 核心规划方法
    public static <T extends RDG<T>> PhysicalOperator<T> plan(
        LogicalOperator input,
        PhysicalPlannerContext<T> context
    );

    // 支持的逻辑算子转换:
    // - Source → Start/StartFromVertex/DrivingRDG
    // - PatternScan → PatternScan (物理)
    // - Filter → Filter (物理)
    // - Aggregate → Aggregate (物理)
    // - Join → Join (物理)
    // - SubQuery → Cache + Join
    // - BoundedVarLenExpand → 多次Join + Fold/Unfold
}

RDG.java - 关系数据图抽象

位置: lube/physical/rdg/RDG.java

职责: 统一图数据和表数据的访问接口

java

public interface RDG<T extends RDG<T>> {
    // 核心操作
    T filter(Expr expr);
    T select(List<Var> fields);
    T aggregate(List<Var> groups, List<Aggregator> aggs);
    T join(T right, List<Tuple2<String, String>> on, JoinType type);
    T patternScan(Pattern pattern);
    T expandInto(EdgePattern pattern);

    // Schema管理
    PartialGraphPattern getGraphPattern();
    List<Var> getFields();
}

5.3.2.2 Parser子系统 (9个文件)

位置: com.aroundix.openspg.reasoner.parser

parser/
├── KGDSLParser.java                 # KGDSL解析器主入口 ⭐
├── ErrorHandlerStrategy.java        # 错误处理策略
├── expr/                            # 表达式解析
│   ├── ExprParser.java                 # 表达式解析器
│   └── RuleExprParser.java             # 规则表达式解析
├── pattern/                         # 模式解析
│   ├── PatternParser.java              # 模式解析器
│   └── MatchPatternParser.java         # MATCH模式解析
└── utils/                           # 解析工具
    └── ParserUtils.java                # 解析工具类

功能说明:

基于ANTLR4的KGDSL语法解析
支持类Cypher的图查询语法
生成逻辑算子树

KGDSL语法示例:

kgdsl

// 基础模式匹配
MATCH (u:User)-[r:KNOWS]->(f:User)
WHERE u.age > 18
RETURN u.name, f.name, r.since

// 变长路径
MATCH (a:Person)-[:KNOWS*1..3]->(b:Person)
RETURN a, b

// 聚合查询
MATCH (u:User)-[:POSTED]->(p:Post)
RETURN u.name, COUNT(p) as postCount
ORDER BY postCount DESC
LIMIT 10

5.3.2.3 Runner执行器 (50+个文件)

位置: com.aroundix.openspg.reasoner.runner

runner/
├── local/                           # 本地执行器
│   ├── rdg/LocalRDG.java               # 本地RDG实现 ⭐⭐
│   ├── impl/
│   │   ├── LocalPropertyGraph.java        # 本地图实现 ⭐
│   │   └── LocalReasonerRunner.java       # 本地运行器
│   └── model/
│       └── LocalRuntimeContext.java       # 本地运行时上下文
│
└── [分布式执行器预留]

LocalRDG.java - 本地RDG实现:

实现了RDG接口的所有操作
基于内存的图数据结构
支持流式处理大数据

LocalPropertyGraph.java - 本地图实现:

图数据的内存表示
节点/边的快速访问
索引管理

5.3.2.4 其他Reasoner组件 (280+个文件)

reasoner/
├── batching/                        # 批处理 (5个文件)
│   └── BatchExecutor.java              # 批量执行器
│
├── catalog/                         # 元数据管理 (8个文件)
│   ├── KgGraphCatalog.java             # 图元数据 ⭐
│   └── impl/
│       └── KgGraphCatalogImpl.java        # 实现
│
├── common/                          # 公共组件 (40+个文件)
│   ├── graph/                          # 图基础类型
│   │   ├── edge/
│   │   │   ├── IEdge.java                    # 边接口
│   │   │   ├── Direction.java                # 方向
│   │   │   └── SPO.java                      # 主谓宾三元组
│   │   ├── vertex/
│   │   │   ├── IVertex.java                  # 顶点接口
│   │   │   └── IVertexId.java                # 顶点ID
│   │   └── property/
│   │       └── IProperty.java                # 属性接口
│   │
│   ├── types/                          # 类型系统
│   │   ├── KgType.java                    # 图类型
│   │   └── KTObject.java                  # 类型对象
│   │
│   ├── exception/                      # 异常定义
│   │   └── [异常类]
│   │
│   └── constants/                      # 常量
│       └── [常量定义]
│
├── graphstate/                      # 图状态管理 (15个文件)
│   ├── GraphState.java                 # 图状态接口 ⭐
│   ├── impl/
│   │   └── MemGraphState.java             # 内存图状态
│   ├── generator/
│   │   └── StateGenerator.java            # 状态生成器
│   └── model/
│       └── [状态模型]
│
├── io/                              # 输入输出 (12个文件)
│   ├── model/
│   │   ├── AbstractTableLoader.java       # 表加载器基类
│   │   └── TableModel.java                # 表模型
│   ├── hive/                           # Hive支持
│   ├── odps/                           # ODPS支持
│   └── sls/                            # SLS支持
│
├── kggraph/                         # 知识图谱 (10个文件)
│   ├── KgGraph.java                    # 图接口 ⭐
│   └── impl/
│       └── KgGraphImpl.java               # 图实现
│
├── loader/                          # 数据加载 (5个文件)
│   └── [数据加载器]
│
├── pattern/                         # 模式匹配 (8个文件)
│   ├── PatternMatcher.java             # 模式匹配器 ⭐⭐
│   └── [匹配算法实现]
│
├── progress/                        # 进度跟踪 (3个文件)
│   └── ProgressReport.java             # 进度报告
│
├── rdg/                             # RDG实现 (25个文件)
│   └── common/                         # RDG通用实现
│       ├── KgGraphAggregateImpl.java      # 聚合实现 ⭐
│       ├── KgGraphLeftJoinImpl.java       # Left Join实现 ⭐
│       ├── KgGraphSortImpl.java           # 排序实现
│       ├── LinkEdgeImpl.java              # 边链接实现 ⭐
│       └── groupProcess/                  # 分组处理
│           ├── BaseGroupProcess.java         # 分组处理基类
│           └── [分组算法]
│
├── recorder/                        # 记录器 (8个文件)
│   ├── ExecutionRecorder.java          # 执行记录器
│   └── action/                         # 操作记录
│       └── [记录动作]
│
├── session/                         # 会话管理 (5个文件)
│   └── KgReasonerSession.java          # 推理会话 ⭐
│
├── shuffle/                         # 数据洗牌 (3个文件)
│   └── [Shuffle实现]
│
├── sink/                            # 结果输出 (5个文件)
│   └── [结果Sink]
│
├── struct/                          # 数据结构 (10个文件)
│   └── [内部数据结构]
│
├── task/                            # 任务调度 (8个文件)
│   ├── TaskRunner.java                 # 任务运行器
│   └── [任务管理]
│
├── udf/                             # 用户自定义函数 (30+个文件)
│   ├── UdfMng.java                     # UDF管理器 ⭐
│   ├── builtin/                        # 内置UDF
│   │   ├── udf/                           # 标量函数
│   │   │   ├── Concat.java                   # 字符串连接
│   │   │   ├── ToLower.java                  # 转小写
│   │   │   └── [20+内置函数]
│   │   ├── udaf/                          # 聚合函数
│   │   │   ├── Count.java                    # 计数
│   │   │   ├── Sum.java                      # 求和
│   │   │   ├── Avg.java                      # 平均值
│   │   │   └── [聚合函数]
│   │   └── udtf/                          # 表函数
│   │       └── [表函数]
│   ├── impl/                           # UDF实现
│   ├── model/                          # UDF模型
│   ├── rule/                           # 规则UDF
│   └── utils/                          # UDF工具
│
├── util/                            # 工具类 (5个文件)
│   └── KgGraphSchema.java              # 图Schema工具 ⭐⭐
│
├── utils/                           # 通用工具 (8个文件)
│   └── RunnerUtil.java                 # 执行工具 ⭐
│
└── warehouse/                       # 数据仓库 (15个文件)
    ├── common/                         # 仓库通用
    ├── cloudext/                       # 云扩展
    └── utils/
        └── WareHouseUtils.java            # 仓库工具 ⭐

5.3.3 Core核心模块 (241个文件) - 详解

位置: com.aroundix.openspg.core

Core模块是SPG的基础模型层，定义了Schema类型系统、调度器和推理服务接口。

core/
├── schema/                          # Schema模型 (200+个文件)
│   ├── model/                          # 模型定义
│   │   ├── SPGSchema.java                 # SPG Schema主类 ⭐⭐⭐
│   │   ├── SPGSchemaAlterCmd.java         # Schema变更命令
│   │   ├── BaseOntology.java              # 本体基类
│   │   ├── BaseSpoTriple.java             # SPO三元组
│   │   │
│   │   ├── type/                          # 类型定义 (50+个文件)
│   │   │   ├── BaseSPGType.java              # SPG类型基类 ⭐⭐
│   │   │   ├── SPGTypeEnum.java              # 类型枚举
│   │   │   ├── EntityType.java               # 实体类型
│   │   │   ├── ConceptType.java              # 概念类型
│   │   │   ├── EventType.java                # 事件类型
│   │   │   ├── StandardType.java             # 标准类型
│   │   │   ├── ProjectSchema.java            # 项目Schema
│   │   │   └── [类型体系]
│   │   │
│   │   ├── predicate/                     # 谓词定义 (30+个文件)
│   │   │   ├── Property.java                 # 属性谓词 ⭐
│   │   │   ├── Relation.java                 # 关系谓词 ⭐
│   │   │   ├── PropertyGroup.java            # 属性组
│   │   │   ├── SubProperty.java              # 子属性
│   │   │   └── [谓词体系]
│   │   │
│   │   ├── semantic/                      # 语义定义 (20+个文件)
│   │   │   ├── LogicalRule.java              # 逻辑规则 ⭐
│   │   │   ├── PredicateSemantic.java        # 谓词语义
│   │   │   ├── DynamicTaxonomy.java          # 动态分类
│   │   │   └── [语义规则]
│   │   │
│   │   ├── constraint/                    # 约束定义 (15个文件)
│   │   │   ├── BaseConstraint.java           # 约束基类
│   │   │   ├── NotNullConstraint.java        # 非空约束
│   │   │   ├── EnumConstraint.java           # 枚举约束
│   │   │   └── [约束类型]
│   │   │
│   │   ├── identifier/                    # 标识符 (10个文件)
│   │   │   ├── SPGTypeIdentifier.java        # 类型标识符 ⭐
│   │   │   ├── PredicateIdentifier.java      # 谓词标识符
│   │   │   └── [标识符体系]
│   │   │
│   │   └── alter/                         # Schema变更 (20+个文件)
│   │       ├── AlterOperationEnum.java       # 变更操作
│   │       ├── AddProperty.java              # 添加属性
│   │       ├── AddRelation.java              # 添加关系
│   │       └── [变更操作]
│   │
│   └── service/                        # Schema服务 (5个文件)
│       └── SchemaService.java             # Schema服务接口
│
├── reasoner/                        # 推理服务 (10个文件)
│   └── service/
│       └── ReasonerService.java           # 推理服务接口 ⭐
│
└── scheduler/                       # 调度器 (30+个文件)
    ├── model/                          # 调度模型
    │   ├── Task.java                      # 任务
    │   ├── TaskInstance.java              # 任务实例
    │   └── [调度模型]
    └── service/                        # 调度服务
        └── SchedulerService.java          # 调度服务接口

SPGSchema.java - SPG Schema核心:

java

/**
 * SPG Schema定义
 *
 * SPG类型体系：
 * - EntityType: 实体类型（如 User、Company、Product）
 * - ConceptType: 概念类型（如 Industry、Location）
 * - EventType: 事件类型（如 Transaction、Login）
 * - StandardType: 标准类型（如 Text、Integer、Date）
 */
public class SPGSchema extends BaseValObj {
    private final List<BaseSPGType> spgTypes;
    private final Set<SPGTypeIdentifier> spreadStdTypeNames;

    // Schema查询方法
    public BaseSPGType getType(SPGTypeIdentifier identifier);
    public List<Relation> getRelations(SPGTypeIdentifier source);
    public List<Property> getProperties(SPGTypeIdentifier type);
}

5.3.4 Builder构建引擎 (148个文件) - 详解

位置: com.aroundix.openspg.builder

Builder模块负责从各种数据源构建知识图谱，包括ETL Pipeline、实体链接、知识融合等功能。

builder/
├── core/                            # 构建核心 (80+个文件)
│   ├── logical/                        # 逻辑层 (30个文件)
│   │   ├── LogicalNode.java               # 逻辑节点基类
│   │   ├── LogicalNodeInput.java          # 数据输入节点
│   │   ├── LogicalNodeMapping.java        # 映射节点
│   │   ├── LogicalNodeSink.java           # 输出节点
│   │   └── [逻辑节点类型]
│   │
│   ├── physical/                       # 物理层 (30个文件)
│   │   ├── PhysicalNode.java              # 物理节点基类
│   │   ├── SourceNode.java                # 源节点
│   │   ├── ExtractNode.java               # 抽取节点
│   │   ├── TransformNode.java             # 转换节点
│   │   ├── LinkNode.java                  # 链接节点
│   │   ├── FuseNode.java                  # 融合节点
│   │   └── [物理节点类型]
│   │
│   ├── reason/                         # 推理 (10个文件)
│   │   └── ReasonerChain.java             # 推理链
│   │
│   ├── runtime/                        # 运行时 (5个文件)
│   │   ├── BuilderRuntimeContext.java     # 运行时上下文
│   │   └── [运行时组件]
│   │
│   └── strategy/                       # 策略 (5个文件)
│       ├── LinkStrategy.java              # 链接策略
│       └── FuseStrategy.java              # 融合策略
│
├── model/                           # 构建模型 (40+个文件)
│   ├── pipeline/                       # Pipeline模型 (20个文件)
│   │   ├── Pipeline.java                  # Pipeline定义 ⭐
│   │   ├── Component.java                 # 组件
│   │   ├── Operator.java                  # 算子
│   │   └── [Pipeline组件]
│   │
│   ├── record/                         # 记录模型 (15个文件)
│   │   ├── BaseRecord.java                # 记录基类
│   │   ├── SPGRecord.java                 # SPG记录 ⭐
│   │   ├── Property.java                  # 属性
│   │   └── [记录类型]
│   │
│   └── exception/                      # 异常 (5个文件)
│       └── [构建异常]
│
└── runner/                          # 执行运行器 (25个文件)
    ├── physical/                       # 物理执行 (15个文件)
    │   ├── PhysicalPlanExecutor.java      # 物理计划执行器 ⭐
    │   └── [执行器实现]
    │
    └── runtime/                        # 运行时 (10个文件)
        └── BuilderRunner.java             # 构建运行器 ⭐

Pipeline.java - 构建Pipeline定义:

java

/**
 * 知识构建Pipeline
 *
 * 典型Pipeline流程：
 * Source → Extract → Transform → Link → Fuse → Sink
 *
 * 支持的数据源：
 * - 结构化: MySQL, PostgreSQL, Hive, ODPS
 * - 半结构化: JSON, XML, CSV
 * - 非结构化: 文本、文档（需要NLP处理）
 */
public class Pipeline {
    private List<Component> components;
    private Map<String, Object> config;

    // Pipeline执行
    public void execute(BuilderRuntimeContext context);
}

5.3.5 CloudExt云扩展 (152个文件) - 详解

位置: com.aroundix.openspg.cloudext

CloudExt模块提供云服务扩展接口，支持多种存储、缓存和计算引擎。

cloudext/
├── interfaces/                      # 扩展接口 (70+个文件)
│   ├── cache/                          # 缓存接口 (15个文件)
│   │   ├── CacheClient.java               # 缓存客户端接口 ⭐
│   │   ├── CacheConfig.java               # 缓存配置
│   │   └── [缓存操作接口]
│   │
│   ├── graphstore/                     # 图存储接口 (25个文件)
│   │   ├── GraphStoreClient.java          # 图存储客户端 ⭐⭐
│   │   ├── GraphStoreConfig.java          # 存储配置
│   │   ├── BaseChunk.java                 # 数据块
│   │   ├── VertexRecordQuery.java         # 顶点查询
│   │   ├── EdgeRecordQuery.java           # 边查询
│   │   └── [图存储操作]
│   │
│   ├── objectstorage/                  # 对象存储接口 (10个文件)
│   │   ├── ObjectStorageClient.java       # 对象存储客户端 ⭐
│   │   └── [存储操作接口]
│   │
│   ├── searchengine/                   # 搜索引擎接口 (15个文件)
│   │   ├── SearchEngineClient.java        # 搜索引擎客户端 ⭐
│   │   ├── SearchQuery.java               # 搜索查询
│   │   └── [搜索操作接口]
│   │
│   └── computingengine/                # 计算引擎接口 (5个文件)
│       └── ComputingEngineClient.java     # 计算引擎客户端
│
└── impl/                            # 接口实现 (80+个文件)
    ├── cache/                          # 缓存实现 (15个文件)
    │   ├── RedisCacheClient.java          # Redis实现
    │   └── [缓存实现]
    │
    ├── graphstore/                     # 图存储实现 (40个文件)
    │   ├── TuGraphClient.java             # TuGraph实现
    │   ├── Neo4jClient.java               # Neo4j实现
    │   ├── JanusGraphClient.java          # JanusGraph实现
    │   └── [图数据库适配器]
    │
    ├── objectstorage/                  # 对象存储实现 (10个文件)
    │   ├── OSSClient.java                 # 阿里云OSS
    │   └── [存储实现]
    │
    └── searchengine/                   # 搜索引擎实现 (15个文件)
        ├── ElasticSearchClient.java       # ElasticSearch实现
        └── [搜索引擎实现]

GraphStoreClient.java - 图存储客户端:

java

/**
 * 图存储客户端接口
 *
 * 支持的图数据库：
 * - TuGraph (推荐)
 * - Neo4j
 * - JanusGraph
 * - Nebula Graph
 */
public interface GraphStoreClient {
    // 顶点操作
    void insertVertex(List<VertexRecord> vertices);
    List<VertexRecord> queryVertex(VertexRecordQuery query);
    void updateVertex(List<VertexRecord> vertices);
    void deleteVertex(List<String> vertexIds);

    // 边操作
    void insertEdge(List<EdgeRecord> edges);
    List<EdgeRecord> queryEdge(EdgeRecordQuery query);
    void deleteEdge(List<String> edgeIds);

    // 批量操作
    void batchInsert(GraphData data);

    // 事务支持
    void beginTransaction();
    void commit();
    void rollback();
}

5.3.6 Server服务端 (223个文件) - 详解

位置: com.aroundix.openspg.server

Server模块提供服务端API、业务逻辑和丰富的领域模型。

server/
├── api/                             # API层 (30+个文件)
│   ├── facade/                         # Facade接口 (15个文件)
│   │   ├── SchemaFacade.java              # Schema Facade ⭐
│   │   ├── ReasonerFacade.java            # Reasoner Facade
│   │   └── [Facade接口]
│   │
│   └── http/                           # HTTP客户端 (15个文件)
│       └── client/
│           └── HttpSchemaFacade.java      # HTTP Schema客户端 ⭐
│
├── biz/                             # 业务逻辑 (30+个文件)
│   ├── common/                         # 公共业务 (10个文件)
│   │   └── [公共逻辑]
│   │
│   └── schema/                         # Schema业务 (20个文件)
│       ├── SchemaManager.java             # Schema管理器 ⭐⭐
│       └── [Schema逻辑]
│
├── model/                           # 模型定义 (140+个文件)
│   ├── base/                           # 基础模型 (10个文件)
│   │   ├── BaseModel.java                 # 模型基类
│   │   ├── BaseValObj.java                # 值对象基类
│   │   └── [基础类型]
│   │
│   ├── project/                        # 项目模型 (10个文件)
│   │   ├── Project.java                   # 项目 ⭐
│   │   ├── ProjectConfig.java             # 项目配置
│   │   └── [项目相关]
│   │
│   ├── account/                        # 账户模型 (10个文件)
│   │   └── [账户相关]
│   │
│   ├── tenant/                         # 租户模型 (10个文件)
│   │   └── [租户相关]
│   │
│   ├── datasource/                     # 数据源模型 (15个文件)
│   │   └── [数据源定义]
│   │
│   ├── job/                            # 作业模型 (15个文件)
│   │   └── [作业定义]
│   │
│   ├── bulider/                        # 构建模型 (10个文件)
│   │   └── [构建相关]
│   │
│   ├── reasoner/                       # 推理模型 (10个文件)
│   │   └── [推理相关]
│   │
│   ├── scheduler/                      # 调度模型 (10个文件)
│   │   └── [调度相关]
│   │
│   ├── retrieval/                      # 检索模型 (10个文件)
│   │   └── [检索相关]
│   │
│   ├── app/                            # 应用模型 (10个文件)
│   │   └── [应用相关]
│   │
│   └── [其他领域模型]
│
└── service/                         # 服务实现 (20+个文件)
    ├── account/                        # 账户服务
    ├── project/                        # 项目服务
    ├── builder/                        # 构建服务
    ├── datasource/                     # 数据源服务
    ├── provider/                       # Provider服务
    ├── retrieval/                      # 检索服务
    └── [其他服务]

5.3.7 Common公共模块 (63个文件) - 详解

位置: com.aroundix.openspg.common

common/
├── constants/                       # 常量定义 (10个文件)
│   └── [系统常量]
│
└── util/                            # 工具类 (50+个文件)
    ├── cloudext/                       # 云扩展工具 (5个文件)
    ├── constants/                      # 常量 (5个文件)
    ├── converter/                      # 转换器 (5个文件)
    ├── enums/                          # 枚举 (5个文件)
    ├── exception/                      # 异常 (5个文件)
    ├── logger/                         # 日志 (3个文件)
    ├── neo4j/                          # Neo4j工具 (5个文件)
    ├── pemja/                          # Python集成 (5个文件)
    ├── thread/                         # 线程工具 (3个文件)
    ├── tuple/                          # 元组 (5个文件)
    └── [其他工具]

5.3.8 模块间协作流程

完整查询执行流程

┌─────────────────────────────────────────────────────────────┐
│                   KGDSL查询执行完整流程                      │
└─────────────────────────────────────────────────────────────┘

1. 用户提交KGDSL查询
      ↓
2. Parser解析 (reasoner.parser)
   - KGDSLParser: 词法/语法分析
   - 生成逻辑算子树
      ↓
3. 语义验证 (lube.logical.validate)
   - 类型检查
   - 作用域检查
   - Schema一致性验证
      ↓
4. 逻辑优化 (lube.logical.optimizer)
   - 谓词下推
   - Join重排序
   - 子查询优化
      ↓
5. 物理规划 (lube.physical.planning)
   - PhysicalPlanner: 逻辑→物理转换
   - 选择物理算子
   - 生成执行计划
      ↓
6. 本地执行 (reasoner.runner.local)
   - LocalRDG: RDG操作实现
   - LocalPropertyGraph: 图数据访问
   - 流式执行物理算子
      ↓
7. 结果返回
   - 格式化输出
   - 结果集封装

知识构建流程

┌─────────────────────────────────────────────────────────────┐
│                   知识构建完整流程                           │
└─────────────────────────────────────────────────────────────┘

1. Schema定义 (core.schema)
   - SPGSchema: 定义实体/关系类型
   - 属性、约束、规则定义
      ↓
2. Pipeline配置 (builder.model.pipeline)
   - Pipeline: ETL流程定义
   - 数据源、转换规则配置
      ↓
3. 数据抽取 (builder.core.physical)
   - SourceNode: 从数据源读取
   - 格式解析、清洗
      ↓
4. 实体识别 (builder.core.physical)
   - ExtractNode: 实体抽取
   - NLP处理、模式匹配
      ↓
5. 实体链接 (builder.core.physical)
   - LinkNode: 实体消歧、链接
   - 相似度计算
      ↓
6. 知识融合 (builder.core.physical)
   - FuseNode: 冲突解决
   - 多源融合
      ↓
7. 数据写入 (cloudext.graphstore)
   - GraphStoreClient: 写入图数据库
   - 批量插入、索引构建
      ↓
8. 推理增强 (builder.core.reason)
   - ReasonerChain: 规则推理
   - 关系推断、属性补全

5.4 兼容层 (com.antgroup.openspg)

保留了部分原始OpenSPG包路径，用于兼容性:

com.antgroup.openspg/
├── reasoner/
│   ├── common/                      # 公共组件
│   ├── graphstate/                  # 图状态
│   └── lube/                        # LUBE引擎

6. 依赖关系

6.1 模块间依赖

┌─────────────────┐
│  muotai-spg-api │
└────────┬────────┘
         │ depends on
         ↓
┌─────────────────┐
│  muotai-spg-biz │
└─────────────────┘

6.2 包间依赖关系

com.aroundix.spg
       ↓
       ├──→ com.aroundix.openspg.server    (服务端API)
       ├──→ com.aroundix.openspg.reasoner  (推理引擎)
       ├──→ com.aroundix.openspg.builder   (构建引擎)
       └──→ com.aroundix.openspg.core      (核心模型)

com.aroundix.openspg.reasoner
       ↓
       ├──→ lube                            (查询引擎)
       │      ├──→ logical                  (逻辑层)
       │      ├──→ physical                 (物理层)
       │      └──→ parser                   (解析器)
       ├──→ runner                          (执行器)
       ├──→ catalog                         (元数据)
       └──→ pattern                         (模式匹配)

6.3 外部依赖

yaml

核心框架:
  - Spring Boot 3.4.5
  - Spring Cloud 2024.0.0
  - Spring Cloud Alibaba 2023.0.3.2

数据访问:
  - MyBatis-Plus 3.5.x
  - MySQL Connector

推理引擎:
  - Scala 2.12.18
  - ANTLR4 4.13.x
  - Cats (函数式编程)

服务治理:
  - Nacos (服务注册与配置)
  - OpenFeign (服务调用)

工具库:
  - Lombok (简化代码)
  - Guava (工具集)
  - Jackson (JSON序列化)

7. 代码统计

7.1 文件数量统计

模块	Java文件数	说明
muotai-spg-api	~11	API定义层
muotai-spg-biz	~400+	业务实现层
└─ SPG服务层	~14	Spring Boot服务
└─ OpenSPG引擎	~386	核心引擎实现
└─ LUBE引擎	~249	查询执行引擎
└─ Parser	~9	DSL解析器
└─ Runner	~50	执行运行器
└─ Builder	~30	构建引擎
└─ 其他	~48	其他组件

7.2 代码行数估算

总计: 约 50,000+ 行代码
Java代码: ~40,000 行
Scala代码: ~10,000 行

8. 开发指南

8.1 添加新的查询算子

如果需要扩展KGDSL查询能力，需要：

定义逻辑算子 (logical/operators/)

java

public class MyOperator extends StackingLogicalOperator {
    // 实现抽象方法
}

定义物理算子 (physical/operators/)

java

public class MyOperator<T extends RDG<T>> extends PhysicalOperator<T> {
    // 实现执行逻辑
}

更新物理规划器 (physical/planning/PhysicalPlanner.java)

java

if (input instanceof MyOperator) {
    return planMyOperator((MyOperator) input, context);
}

添加优化规则 (logical/optimizer/rules/)

java

public class MyOptimizerRule implements Rule {
    // 实现优化逻辑
}

8.2 添加新的业务API

定义DTO (muotai-spg-api/dto/)

java

@Data
public class MyRequest {
    // 请求字段
}

添加Controller (biz/controller/)

java

@RestController
@RequestMapping("/api/my")
public class MyController {
    // 实现API端点
}

实现Service (biz/service/)

java

@Service
public class MyServiceImpl implements MyService {
    // 实现业务逻辑
}

8.3 扩展Schema模型

定义实体 (api/entity/)

java

@Data
@TableName("kg_my_table")
public class KgMyEntity {
    // 实体字段
}

创建Mapper (biz/mapper/)

java

@Mapper
public interface MyMapper extends BaseMapper<KgMyEntity> {
    // 自定义查询方法
}

添加服务 (biz/service/)

java

@Service
public class MyServiceImpl {
    @Autowired
    private MyMapper myMapper;
    // 实现逻辑
}

9. 性能优化建议

9.1 查询优化

启用查询优化器
- 位置: lube/logical/optimizer/
- 添加RBO (Rule-Based Optimization) 规则
使用索引
- 为常用查询路径创建索引
- 优化PatternScan性能
批量操作
- 使用批量插入/更新
- 利用Cache算子减少重复计算

9.2 内存优化

RDG缓存管理
- 合理设置Cache算子
- 及时释放不需要的RDG
流式处理
- 大数据量使用流式算子
- 避免全量加载到内存

10. 常见问题

10.1 编译错误

问题: 找不到Scala类或方法

解决:

bash

mvn scala:compile
mvn clean compile

10.2 运行时错误

问题: "找不到符号" 错误

原因: Lombok getter方法调用错误

解决:

使用getXxx()而不是xxx()
示例: patternScan.getPattern() 而不是 patternScan.pattern()

10.3 性能问题

问题: 查询执行缓慢

排查步骤:

检查执行计划 (Physical Plan)
查看是否有全表扫描
添加适当的索引
启用查询优化器

11. 相关文档

12. 联系方式

如有问题或建议，请联系：

项目: Muotai Backend
模块: muotai-spg
维护团队: Aroundix SPG Team

文档版本: v1.0最后更新: 2025-12-19

Muotai SPG 模块结构文档 ​

目录 ​

1. 概述 ​

1.1 核心功能 ​

1.2 技术栈 ​

2. 模块架构 ​

3. muotai-spg-api 模块 ​

3.1 模块概述 ​

3.2 包结构 ​

3.3 核心DTO说明 ​

3.4 核心实体说明 ​

4. muotai-spg-biz 模块 ​

4.1 模块概述 ​

4.2 顶层包结构 ​

5. 核心包详解 ​

5.1 SPG服务层 (com.aroundix.spg) ​

5.1.1 包结构 ​

5.1.2 核心类说明 ​

5.2 OpenSPG引擎层 (com.aroundix.openspg) ​

5.2.1 Builder模块 - 知识构建引擎 ​

5.2.2 Reasoner模块 - 推理引擎 (核心) ​

5.2.2.1 LUBE子系统 - 逻辑单元后端引擎 (249个文件) ​

5.2.2.2 Parser子系统 - DSL解析 (9个文件) ​

5.2.2.3 其他Reasoner子系统 ​

5.2.3 Core模块 - 核心模型 ​

5.2.4 Server模块 - 服务端 ​

5.2.5 CloudExt模块 - 云扩展 ​

5.2.6 Common模块 - 公共工具 ​

5.3 OpenSPG 引擎层深入解析 ​

5.3.1 整体架构与文件分布 ​

5.3.2 Reasoner推理引擎 (586个文件) - 详解 ​

5.3.2.1 LUBE查询引擎 (249个文件) ​

PhysicalPlanner.java - 物理规划器核心 ​

RDG.java - 关系数据图抽象 ​

5.3.2.2 Parser子系统 (9个文件) ​

5.3.2.3 Runner执行器 (50+个文件) ​

5.3.2.4 其他Reasoner组件 (280+个文件) ​

5.3.3 Core核心模块 (241个文件) - 详解 ​

5.3.4 Builder构建引擎 (148个文件) - 详解 ​

5.3.5 CloudExt云扩展 (152个文件) - 详解 ​

5.3.6 Server服务端 (223个文件) - 详解 ​

5.3.7 Common公共模块 (63个文件) - 详解 ​

5.3.8 模块间协作流程 ​

完整查询执行流程 ​

知识构建流程 ​

5.4 兼容层 (com.antgroup.openspg) ​

6. 依赖关系 ​

6.1 模块间依赖 ​

6.2 包间依赖关系 ​

6.3 外部依赖 ​

7. 代码统计 ​

7.1 文件数量统计 ​

7.2 代码行数估算 ​

8. 开发指南 ​

8.1 添加新的查询算子 ​

8.2 添加新的业务API ​

8.3 扩展Schema模型 ​

9. 性能优化建议 ​

9.1 查询优化 ​

9.2 内存优化 ​

10. 常见问题 ​

10.1 编译错误 ​

10.2 运行时错误 ​

10.3 性能问题 ​

11. 相关文档 ​

12. 联系方式 ​

Muotai SPG 模块结构文档

目录

1. 概述

1.1 核心功能

1.2 技术栈

2. 模块架构

3. muotai-spg-api 模块

3.1 模块概述

3.2 包结构

3.3 核心DTO说明

3.4 核心实体说明

4. muotai-spg-biz 模块

4.1 模块概述

4.2 顶层包结构

5. 核心包详解

5.1 SPG服务层 (com.aroundix.spg)

5.1.1 包结构

5.1.2 核心类说明

5.2 OpenSPG引擎层 (com.aroundix.openspg)

5.2.1 Builder模块 - 知识构建引擎

5.2.2 Reasoner模块 - 推理引擎 (核心)

5.2.2.1 LUBE子系统 - 逻辑单元后端引擎 (249个文件)

5.2.2.2 Parser子系统 - DSL解析 (9个文件)

5.2.2.3 其他Reasoner子系统

5.2.3 Core模块 - 核心模型

5.2.4 Server模块 - 服务端

5.2.5 CloudExt模块 - 云扩展

5.2.6 Common模块 - 公共工具

5.3 OpenSPG 引擎层深入解析

5.3.1 整体架构与文件分布

5.3.2 Reasoner推理引擎 (586个文件) - 详解

5.3.2.1 LUBE查询引擎 (249个文件)

PhysicalPlanner.java - 物理规划器核心

RDG.java - 关系数据图抽象

5.3.2.2 Parser子系统 (9个文件)

5.3.2.3 Runner执行器 (50+个文件)

5.3.2.4 其他Reasoner组件 (280+个文件)

5.3.3 Core核心模块 (241个文件) - 详解

5.3.4 Builder构建引擎 (148个文件) - 详解

5.3.5 CloudExt云扩展 (152个文件) - 详解

5.3.6 Server服务端 (223个文件) - 详解

5.3.7 Common公共模块 (63个文件) - 详解

5.3.8 模块间协作流程

完整查询执行流程

知识构建流程

5.4 兼容层 (com.antgroup.openspg)

6. 依赖关系

6.1 模块间依赖

6.2 包间依赖关系

6.3 外部依赖

7. 代码统计

7.1 文件数量统计

7.2 代码行数估算

8. 开发指南

8.1 添加新的查询算子

8.2 添加新的业务API

8.3 扩展Schema模型

9. 性能优化建议

9.1 查询优化

9.2 内存优化

10. 常见问题

10.1 编译错误

10.2 运行时错误

10.3 性能问题

11. 相关文档

12. 联系方式