【Eclipse OpenSOVD学习之五】拓扑引擎（Topology）

04. 拓扑引擎（Topology）

本章是整套架构的核心。Topology 决定了：实体如何存储、关系如何查询、并发如何控制、变更如何传播、远端实体如何汇聚。

1. 背景与原理

1.1 拓扑引擎要解决的问题

SOVD 是可发现的：客户端不知道车上有什么，必须先问"有哪些 Component/App/Area"。因此服务端需要一个运行时注册表，满足：

多维度查询：按 ID 查单个、按集合列举、按关系查（某 Area 下有哪些 Component、某 App 跑在哪个 Component 上）。
运行时可变：ECU/App 会上下线（发现、休眠、软件启停），拓扑需要动态增删。
高并发读：诊断请求以读为主，读不能互斥。
变更可观测：网关需要知道拓扑变了（用于刷新缓存、通知订阅者、触发级联）。
批量原子性：一个发现的差分事件里可能同时增删多个实体，不能让客户端看到"中间态"。

1.2 设计选择

需求	选择	理由
读多写少	`tokio::sync::RwLock`	读并发、写独占
稳定输出顺序	`IndexMap` / `IndexSet`（而非 HashMap/HashSet）	API 列表顺序可预期，便于测试与缓存
查询一致性	守卫（Guard）持锁整个请求	多次查询落在同一快照
批量原子	写守卫累积变更，`Drop` 时统一生效	中间态对外不可见
变更传播	`tokio::sync::broadcast`	多订阅者、解耦
关系查询	反向索引	避免每次全表扫描

2. 当前实现架构

2.1 数据结构

35:45:opensovd-core/src/topology.rs 复制代码

pub struct TopologyState {
    components: IndexMap<String, Component>,
    apps: IndexMap<String, App>,
    areas: IndexMap<String, Area>,
    /// Component ID -> set of app IDs hosted on it
    apps_by_component: HashMap<String, IndexSet<String>>,
    /// Area ID -> set of component IDs in that area
    components_by_area: HashMap<String, IndexSet<String>>,
    /// Area ID -> set of app IDs in that area
    apps_by_area: HashMap<String, IndexSet<String>>,
}

三张正向主表 （存实体本体）+ 三张反向索引 （只存 ID 集合）。索引不是"加速可选件"，而是关系查询的唯一途径。

257:260:opensovd-core/src/topology.rs 复制代码

struct TopologyInner {
    state: RwLock<TopologyState>,
    events: broadcast::Sender<TopologyEvent>,
}

pub struct Topology(Arc<TopologyInner>);   // Clone 即共享

2.2 守卫设计

rust 复制代码

pub struct TopologyReadGuard<'a>(RwLockReadGuard<'a, TopologyState>);
pub struct TopologyWriteGuard<'a> {
    inner: RwLockWriteGuard<'a, TopologyState>,
    events: &'a broadcast::Sender<TopologyEvent>,
    pending: Vec<TopologyEvent>,
}

两者都只实现 Deref<Target = TopologyState>，不实现 DerefMut 。这是本文件最漂亮的设计约束：写守卫只能通过 add_*/remove_* 方法变更状态，无法绕过索引直接操作 IndexMap------从类型系统层面杜绝了"改了主表忘了改索引"。

2.3 事件模型

rust 复制代码

pub enum TopologyEvent { Added(EntityRef), Removed(EntityRef) }

容量默认 64（DEFAULT_EVENT_CHANNEL_CAPACITY），可通过 with_event_capacity(n) 调整；subscribe() 返回 broadcast::Receiver。

3. 核心流程与算法

3.1 写入算法（以 `insert_app` 为例）

82:96:opensovd-core/src/topology.rs 复制代码

fn insert_app(&mut self, id: String, app: App) {
    if let Some(comp) = app.component_id() {
        self.apps_by_component.entry(comp.to_owned()).or_default().insert(id.clone());
    }
    if let Some(area) = app.area_id() {
        self.apps_by_area.entry(area.to_owned()).or_default().insert(id.clone());
    }
    self.apps.insert(id, app);
}

步骤：先更新反向索引（两张）→ 再落主表。复杂度 O(1) 均摊。

注意：app.component_id() 恒为 Some，第一个 if let 是恒真分支。

删除（以 remove_component 为例）：

69:80:opensovd-core/src/topology.rs 复制代码

// 1. 主表 shift_remove（保持顺序，O(n)）
// 2. 取回被删实体的 area_id
// 3. 从 components_by_area 中移除该 ID
// 4. 若该 area 的集合为空，删除整个 entry（避免空集合泄漏）

复杂度 ：shift_remove 为 O(n) （为保持插入顺序需搬移元素），因此批量删除 N 个实体是 O(N²)。

3.2 关系查询算法

方向查询（一对多）先走索引，再二次查主表：

165:176:opensovd-core/src/topology.rs 复制代码

pub fn apps_of_component(&self, component_id: &str) -> impl Iterator<Item = &App> {
    self.apps_by_component.get(component_id)
        .into_iter()
        .flatten()
        .filter_map(|id| self.apps.get(id))
}

复杂度 O(1) 索引定位 + O(k) 次哈希查找，返回借用迭代器（生命周期受守卫约束，零拷贝）。

反向单点查询（多对一）不走索引，主表直查 + 一次跳转：

213:221:opensovd-core/src/topology.rs 复制代码

pub fn component_of_app(&self, app_id: &str) -> Result<Option<&Component>> {
    let app = self.apps.get(app_id)
        .ok_or_else(|| TopologyError::NotFound(EntityRef::app(app_id)))?;
    let Some(component_id) = app.component_id() else { return Ok(None); };
    Ok(self.components.get(component_id))
}

三层语义 ：主体不存在 → Err(NotFound)；主体存在但无关系 → Ok(None)；关系目标不存在（悬空引用）→ 也返回 Ok(None)。最后一种情况掩盖了数据不一致。

3.3 事件批处理与 flush

298:303:opensovd-core/src/topology.rs 复制代码

pub fn add_component(&mut self, component: Component) {
    let entity_ref = EntityRef::component(component.id());
    self.state.insert_component(component.id().to_owned(), component);
    self.pending.push(TopologyEvent::Added(entity_ref));
}

344:350:opensovd-core/src/topology.rs 复制代码

impl Drop for TopologyWriteGuard<'_> {
    fn drop(&mut self) {
        for event in self.pending.drain(..) {
            let _ = self.events.send(event);
        }
    }
}

算法：变更立即改状态 + 事件入 pending 队列；守卫 Drop 时统一 flush 到 broadcast。效果：

一批变更对外表现为"同时发生"
删除不存在的 ID 不产生事件（remove_* 仅在实际删掉时 push）
无订阅者时事件被静默丢弃（broadcast 无接收者时 send 返回 Err，被 let _ 忽略）

3.4 发现流合并算法（网关聚合）

407:462:opensovd-server/src/server.rs 复制代码

async fn run_discovery(topology, providers, shutdown) {
    let mut streams = Vec::new();
    for provider in providers {
        match provider.discover().await {
            Ok(stream) => streams.push(stream),
            Err(e) => tracing::error!(target: "discovery", error = %e, "Failed to start discovery provider"),
        }
    }
    if streams.is_empty() { return; }

    let mut merged = futures::stream::select_all(streams);
    let process_events = async {
        while let Some(event) = merged.next().await {
            match event {
                Ok((remove, add)) => {
                    let mut t = topology.write().await;
                    for r in &remove { /* 按 EntityKind 分派 remove_* */ }
                    for c in add.components { t.add_component(c); }
                    for a in add.apps      { t.add_app(a); }
                    for a in add.areas     { t.add_area(a); }
                }
                Err(e) => tracing::error!(target: "discovery", error = %e, "Discovery stream error"),
            }
        }
    };
    tokio::select! { () = process_events => {...}, () = shutdown => {...} }
}

算法要点：

启动隔离：单个 provider 启动失败只记日志，其余继续；全部失败则直接 return（服务降级为无发现）。
多路复用 ：select_all 合并 N 条流，任一流结束即被移除。
差分应用顺序 ：先 remove 后 add ------保证同一 ID "先删后加"（例如实体改挂到另一个 Area）不会被 add_* 的覆盖语义吞掉。
实体顺序：components → apps → areas（保证 app 加入时其宿主已存在）。
单守卫批处理：整个差分在一个写守卫内应用，因此一次差分对应一次事件 flush。
错误不中断 ：流内 Err 只记日志，不 break（符合 trait 文档"瞬时错误内部重试"的约定）。
优雅退出 ：tokio::select! 让处理循环与 shutdown future 竞速。

3.5 读写并发语义

场景	行为
多个读	完全并发（`RwLock` 读共享）
读 + 写	写等待所有读守卫释放
多个写	串行
写进行中	所有读阻塞
handler 持读守卫跨 `await`	慢 provider 会阻塞写入者（见 07 章）

4. 待完善与风险

本节按严重度排序，前 3 项是可复现的一致性缺陷。

4.1 索引一致性（严重）

缺陷 1：覆盖写入产生幽灵索引（高）

insert_component 在 components.insert 覆盖同 ID 实体时，未清理旧实体 area_id 在 components_by_area 中的条目。

复现：

复制代码

add_component(ecu1, area=powertrain)
add_component(ecu1, area=chassis)      // 覆盖写入
→ components_of_area("powertrain") 仍返回 ecu1   （旧索引未清理，且主表仍查得到）
→ area_of_component("ecu1")        返回 chassis  （主表字段已更新）
→ 两个查询自相矛盾

insert_app 同理，且涉及两张索引。

缺陷 2：remove_component 不清理下游（高）

删除 Component 后：

挂在其上的 App 不会被级联删除，成为孤儿
apps_by_component 中该 Component 的键原样保留
component_of_app 只能返回 Ok(None)，与"App 本来就没宿主"不可区分

缺陷 3：remove_area 后索引不可恢复（高）