docs: 补充 adapter 的定位与本体契约
- 明确这是架构在 ontology 数据基座上的中间层：YAML 定义实体/关系/属性/行为 - 给出完整本体示例（entities/links/actions/functions/rules/constraints） - 说明存储映射：JSONB 文档 + AGE 图 + TimescaleDB 时序同库 - 定义写入（文档/时序）、查询（SQL/图/推理）与对外语义接口 - 列出集成方式、非目标与分阶段路线
This commit is contained in:
Donny committed
1 parent
3c41508bb5
commit
be472a70ea
1 file changed
+287
@@ -1,2 +1,289 @@
|
||||
# adapter_python_pg
|
||||
|
||||
基于 ontology（本体）数据基座的中间层适配器：**用 YAML 定义世界，用一套接口读写它**。
|
||||
|
||||
面向其他项目的底层对接件，不是业务系统，也不是通用 ORM。上层项目只需要一份本体 YAML + 本适配器，就能对实体、关系、属性做对象级操作，而不用关心底下是文档表、图还是时序表。
|
||||
|
||||
> 状态：设计稿（v0.1）。仓库当前只有初始提交，实现尚未开始。本文是接口与存储映射的契约，先定契约再写代码。
|
||||
|
||||
---
|
||||
|
||||
## 1. 解决的问题
|
||||
|
||||
常规做法里，"数据"和"数据的意思"是两套东西：SQL 建表定义结构，业务代码里再写一遍实体、关系、校验。两套东西会漂移，且跨项目无法复用。
|
||||
|
||||
这里把**语义**提到最前面：本体 YAML 是唯一事实来源，适配器负责把这份声明翻译成存储结构和查询。上层拿到的不是 cursor，是实体对象。
|
||||
|
||||
```text
|
||||
上层项目（业务服务 / 分析服务 / 数字孪生前端 / 其他 adapter）
|
||||
│ 实体 / 对象 / 语义接口
|
||||
▼
|
||||
┌───────────────────────────────────────────┐
|
||||
│ adapter_python_pg │
|
||||
│ ├─ Ontology Loader 解析 YAML 契约 │
|
||||
│ ├─ Schema Compiler 映射到存储与索引 │
|
||||
│ ├─ Repository 实体 CRUD / 批量 │
|
||||
│ ├─ Query Planner SQL / Cypher / 混合│
|
||||
│ ├─ Rule Engine 规则派生与约束校验 │
|
||||
│ └─ Action Runtime Actions 编排 │
|
||||
└───────────────────────────────────────────┘
|
||||
│ SQL / openCypher / 时序写入
|
||||
▼
|
||||
PostgreSQL 18 + TimescaleDB + Apache AGE
|
||||
（文档 JSONB · 图 · hypertable 三合一同库）
|
||||
```
|
||||
|
||||
## 2. 设计原则
|
||||
|
||||
| 原则 | 含义 |
|
||||
|---|---|
|
||||
| **YAML 即契约** | 实体、关系、属性、行为全部声明在 YAML 里；改本体只改 YAML |
|
||||
| **只加载 YAML 就能用** | 不做代码生成、不要求手写 DDL；运行期解释本体，按需建存储结构 |
|
||||
| **对象而非行** | 对外只有实体对象与语义方法，SQL 与 Cypher 是内部实现细节 |
|
||||
| **可嵌入** | 既能作为库被其他 Python 项目 import，也能作为 FastAPI 服务独立部署 |
|
||||
| **不持有业务** | 不放业务规则代码；业务规则也写在 YAML 里（Rules / Constraints） |
|
||||
| **同库三模** | 文档、图、时序落在同一个 PostgreSQL 实例，事务与 JOIN 天然一致 |
|
||||
|
||||
## 3. 本体 YAML
|
||||
|
||||
一份本体描述"世界里有什么、怎么连、能做什么"。以下是一个数字孪生场景的最小片段：
|
||||
|
||||
```yaml
|
||||
ontology: factory-twin
|
||||
version: 1
|
||||
|
||||
entities:
|
||||
Factory:
|
||||
label: 工厂
|
||||
id: { type: string, pattern: "^F-[0-9]{4}$" }
|
||||
properties:
|
||||
name: { type: string, required: true }
|
||||
location: { type: geo, index: true }
|
||||
capacity: { type: number, unit: unit/day }
|
||||
|
||||
Line:
|
||||
label: 产线
|
||||
properties:
|
||||
name: { type: string, required: true }
|
||||
status: { type: enum, values: [running, idle, fault], default: idle }
|
||||
|
||||
Device:
|
||||
label: 设备
|
||||
properties:
|
||||
serial: { type: string, unique: true }
|
||||
model: { type: string }
|
||||
installed_at: { type: datetime }
|
||||
meta: { type: json } # 不固定的扩展字段
|
||||
|
||||
SensorReading: # 时序实体
|
||||
kind: timeseries
|
||||
label: 传感器读数
|
||||
time: ts
|
||||
partition_by: 7 days
|
||||
properties:
|
||||
ts: { type: datetime, required: true }
|
||||
metric: { type: string, required: true }
|
||||
value: { type: number, required: true }
|
||||
tags: { type: json, index: true }
|
||||
|
||||
links:
|
||||
Line_Factory:
|
||||
type: belongs_to
|
||||
from: Line
|
||||
to: Factory
|
||||
cardinality: N:1
|
||||
Device_Line:
|
||||
type: mounted_on
|
||||
from: Device
|
||||
to: Line
|
||||
cardinality: N:1
|
||||
properties:
|
||||
since: { type: datetime }
|
||||
|
||||
actions:
|
||||
startLine:
|
||||
on: Line
|
||||
input: { deviceIds: { type: list, of: string } }
|
||||
output: { accepted: boolean }
|
||||
effect: write # write | query | external
|
||||
queryDevicesByFactory:
|
||||
on: Factory
|
||||
output: { devices: { type: list, of: Device } }
|
||||
effect: query
|
||||
|
||||
functions: # 纯函数，不落库
|
||||
utilization:
|
||||
on: Line
|
||||
expr: "runningHours / capacityHours"
|
||||
output: { type: number, unit: percent }
|
||||
|
||||
rules: # 推理：派生关系或属性
|
||||
Device_inFactory:
|
||||
kind: derive_link
|
||||
from: Device
|
||||
to: Factory
|
||||
via: [mounted_on, belongs_to] # 传递闭包
|
||||
Line_atRisk:
|
||||
kind: derive_property
|
||||
on: Line
|
||||
expr: "faultCount(1h) > 3 and status == 'running'"
|
||||
output: { type: boolean }
|
||||
|
||||
constraints:
|
||||
SensorReading_positive:
|
||||
on: SensorReading
|
||||
expr: "value >= 0"
|
||||
Line_single_factory:
|
||||
on: Line
|
||||
expr: "count(belongs_to) == 1"
|
||||
```
|
||||
|
||||
字段语义：
|
||||
|
||||
| 元素 | 作用 | 关键字段 |
|
||||
|---|---|---|
|
||||
| `entities` | 定义实体与属性 | `id`、`properties.type`、`required`、`unique`、`index`、`kind` |
|
||||
| `links` | 定义关系 | `from`/`to`、`type`、`cardinality`、边属性 |
|
||||
| `actions` | 可执行动作 | `on`、`input`/`output`、`effect` |
|
||||
| `functions` | 计算属性 | `expr`（受限表达式，不执行任意代码） |
|
||||
| `rules` | 推理 | `derive_link`（关系传递）、`derive_property`（派生属性） |
|
||||
| `constraints` | 写入校验 | `expr`，写前校验、失败即拒绝 |
|
||||
|
||||
属性类型：`string` `number` `boolean` `datetime` `enum` `json` `geo` `ref`。`type: json` 是留给本体也描述不了的字段的逃生口。
|
||||
|
||||
## 4. 存储映射
|
||||
|
||||
加载 YAML 时由 Schema Compiler 推导存储，**无需人工建表**：
|
||||
|
||||
| 本体元素 | 落到哪 | 引擎 |
|
||||
|---|---|---|
|
||||
| `entities` 的属性集合 | `docs(collection, doc JSONB)` 一行一实体 | JSONB + GIN |
|
||||
| `links` | `ag_catalog` 图节点与边 | Apache AGE |
|
||||
| `kind: timeseries` 实体 | hypertable，按 `partition_by` 分片 | TimescaleDB |
|
||||
| `index: true` / `unique` | `GIN(jsonb_path_ops)` / 唯一约束 | 原生索引 |
|
||||
| `rules.derive_link` | 查询时展开，或物化到图里（可配） | AGE / SQL |
|
||||
| `constraints` | 写前表达式校验 | SQL 表达式 |
|
||||
|
||||
一个实体同时存在两种表示是刻意的：**文档视图**适合整实体读写与属性过滤，**图视图**适合多跳遍历。两者用同一 `id` 对齐，写入在同一事务里完成。
|
||||
|
||||
## 5. 写入
|
||||
|
||||
两种写入路径，对应两种数据形状：
|
||||
|
||||
**文档写入**——实体是整体，属性不固定：
|
||||
|
||||
```python
|
||||
repo.save(Device(id="D-0001", serial="SN-88", model="X200", meta={"vendor": "acme"}))
|
||||
repo.save_many(devices)
|
||||
repo.patch("D-0001", {"meta.vendor": "acme-new"}) # 部分更新
|
||||
```
|
||||
|
||||
**时序写入**——数字孪生的遥测流，按时间追加：
|
||||
|
||||
```python
|
||||
ts = adapter.timeseries("SensorReading")
|
||||
ts.write([{"ts": now, "metric": "temp", "value": 36.5, "tags": {"device": "D-0001"}}])
|
||||
ts.write_batch(stream, batch_size=1000) # 批量/流式
|
||||
```
|
||||
|
||||
写入语义约定：`save` 按 `id` 幂等 upsert；`link()` 幂等建边；`constraints` 在提交前校验，失败抛 `ConstraintViolation`；批量写入单事务，超限自动分块。
|
||||
|
||||
## 6. 查询
|
||||
|
||||
三种查询，同一套实体对象返回：
|
||||
|
||||
**属性查询（SQL 侧）**
|
||||
|
||||
```python
|
||||
adapter.find(Device, model="X200", installed_after="2025-01-01")
|
||||
adapter.find(Device, where={"meta.vendor": "acme"}, limit=50)
|
||||
adapter.aggregate("SensorReading", metric="temp", bucket="1m", agg="avg")
|
||||
```
|
||||
|
||||
**图查询（Cypher 侧）**
|
||||
|
||||
```python
|
||||
adapter.traverse(Device, link="mounted_on", to=Line, hops="1..3")
|
||||
adapter.path(Device("D-0001"), Factory, max_hops=4)
|
||||
```
|
||||
|
||||
**混合与推理**
|
||||
|
||||
```python
|
||||
# 规则派生的关系直接可用，不需要先物化
|
||||
adapter.find(Device, rule="Device_inFactory", factory="F-0001")
|
||||
# 属性来自 function，与库内字段一起返回
|
||||
adapter.find(Line, select=["status", "utilization"])
|
||||
```
|
||||
|
||||
推理的边界先划清楚：**规则驱动的确定性推理**——关系传递闭包（`via`）、派生属性（受限表达式）、约束推导；不做概率推理、不做模型推理。跑在图查询或 SQL 里，结果可复现。
|
||||
|
||||
## 7. 对外接口
|
||||
|
||||
语义层 API，不暴露 SQL / Cypher：
|
||||
|
||||
```python
|
||||
from adapter_python_pg import Adapter, ConstraintViolation
|
||||
|
||||
adapter = Adapter.load("ontology/factory-twin.yaml", dsn="postgresql://...")
|
||||
|
||||
repo = adapter.repository("Device") # 实体仓储
|
||||
repo.save(obj); repo.get(id); repo.find(**where); repo.patch(id, patch); repo.delete(id)
|
||||
|
||||
graph = adapter.graph() # 图操作
|
||||
graph.link(src, "mounted_on", dst, since=...); graph.traverse(...); graph.path(...)
|
||||
|
||||
ts = adapter.timeseries("SensorReading") # 时序
|
||||
ts.write(rows); ts.query(bucket="5m", agg="avg", **filters)
|
||||
|
||||
adapter.invoke("startLine", on="L-01", input={"deviceIds": ["D-0001"]}) # Actions
|
||||
adapter.functions("Line")["utilization"] # Functions
|
||||
adapter.validate("SensorReading", row) # Constraints
|
||||
```
|
||||
|
||||
FastAPI 侧自动从本体生成路由（同一份 YAML，不重复声明）：
|
||||
|
||||
```text
|
||||
GET /entities/{entity} 列表 / 过滤
|
||||
GET /entities/{entity}/{id} 单实体（可选 ?expand=links）
|
||||
POST /entities/{entity} 写入
|
||||
PATCH /entities/{entity}/{id} 部分更新
|
||||
POST /graph/traverse 多跳查询
|
||||
POST /timeseries/{entity}/write 时序写入
|
||||
POST /timeseries/{entity}/query 时序聚合
|
||||
POST /actions/{action} 执行 Action
|
||||
GET /ontology 返回已加载的本体元数据
|
||||
```
|
||||
|
||||
## 8. 集成到其他项目
|
||||
|
||||
三种姿势，按侵入程度从低到高：
|
||||
|
||||
1. **HTTP**：独立跑 `uvicorn adapter_python_pg.app:app`，其他语言/服务直接调 REST。
|
||||
2. **Python 库**：`pip install -e .`，`Adapter.load()` 后当普通对象用，进程内零网络开销。
|
||||
3. **嵌入式**：把本体 YAML 打进宿主项目，adapter 作为其内部数据层，宿主不感知 PostgreSQL。
|
||||
|
||||
## 9. 与存储的关系
|
||||
|
||||
底层依赖多模型 PostgreSQL：PostgreSQL 18 + TimescaleDB 2.31 + Apache AGE 1.7，文档/图/时序同库。
|
||||
|
||||
本机参考部署在 `E:\code\ueos\devops\devos\server-resources\postgres-multimodel\`（Dockerfile + compose + 初始化脚本）。
|
||||
|
||||
## 10. 非目标
|
||||
|
||||
- 不做通用 ORM（不复刻 SQLAlchemy 的表达式系统；复杂 SQL 走 `raw()` 逃生口）
|
||||
- 不做本体编辑器 / 可视化（那是前端的事）
|
||||
- 不做数据迁移与版本演进工具（本体版本变更先手工处理，后续再谈）
|
||||
- 不做多库联邦（一个 adapter 实例对一个 PostgreSQL 实例）
|
||||
- 不在 YAML 里执行任意 Python（`expr` 走受限表达式求值）
|
||||
|
||||
## 11. 路线
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|---|---|
|
||||
| v0.1 | 本体解析 + Schema Compiler + Repository（文档读写、约束校验） |
|
||||
| v0.2 | Links 落到 AGE、图遍历、路径查询 |
|
||||
| v0.3 | 时序实体与 hypertable、批量写入、连续聚合查询 |
|
||||
| v0.4 | Rules 推理（派生关系/属性）、Functions 求值 |
|
||||
| v0.5 | FastAPI 路由自动生成、Actions 运行时 |
|
||||
| v1.0 | 接口冻结、错误模型统一、文档与示例齐全 |
|
||||
Reference in new issue
Block a user