Bug 引发的架构追问

事情从一个不起眼的 bug 开始。我们的 K 线图有一个"增量加载提示"功能：向左滚动加载更多历史数据时新来的 K 线上方会闪过一层蓝色半透明覆盖，告诉使用者"这块是刚加载的"。

但这个东西经常出现问题。

先解释一个关键概念：prependedCount 是每次增量加载时插入到数据数组左侧的新 K 线数量。不过，K 线图的数据按时间从左到右排列，最新数据在右边。当你向左滚动想看更早的历史，程序会请求更早时间的数据。这些数据会被 prepend。比如之前有 根 K 线，这次加载了 根更早的。那 prependedCount 就是 ——提示覆盖层的宽度也是根据这个数字算出来的。

使用者痛点：

• 者在调试时无法直观看到预期与实际覆盖层宽度差异；
• 缺乏统一的数据状态标识导致多处逻辑需手动同步；
• 当代码量扩大后新人难以理解“增量加载”与“提示层”之间隐式约束。

sequenceDiagram
participant Fetch as _fetchAndMerge
participant Store as KLineDataStore
participant Buf as DataBuffer
participant Mgr as ChartDataManager
Fetch->Store: merge
Store-->Buf: dataSignal.set
Buf->Mgr: data.subscriber
Note over Mgr: pendingPrependedCount = ❌
Mgr->Mgr: onKLineBufferChanged
Mgr->Mgr: _loadHint.show → count=,return
Fetch->Buf: _prependSignal.set
Buf->Mgr: prepend.subscriber
Mgr->Mgr: pendingPrependedCount = count
Note over Mgr: 设上了但 data 那边已经跑完了

这是个信号时序问题。

至于第一次修复，交换顺序

• "提前把 prepend 设置在 data 前面" 的做法让代码结构变得不直观；
• MVP 时可以快速修复，但长期维护成本高；
• "预期顺序被硬编码在业务流程中"，一旦订阅顺序被打乱就会重现 bug。

直觉反应是把 prepend 信号设值的时机提前到 data 信号之前。老实说，于是把 merge 拆成了两步——合并数据和触发信号分开：

const result = this._store.merge // 只合并，不触发this._prependSignal.set
this._store.notify // data 后
// ...后续逻辑保持不变

sequenceDiagram
participant Fetch as _fetchAndMerge
participant Store as KLineDataStore
participant Buf as DataBuffer
participant Mgr as ChartDataManager
Fetch->Store: merge
Note over Store: 只合并。不触发信号
Fetch->Buf: _prependSignal.set
Buf->Mgr: prepend.subscriber
Mgr-><-Mgr: pendingPrependedCount = count ✓
      Fetch-<-<-Store.notify
      Store-->>rBuf:dataSignal.set
Buf->rMgr:data.subscriber
Note over Mgr:
pendingPrependedCount = count ✓
Mgr-->rMgr:_loadHint.show → 正确了

测试通过E2E 交互也没有问题了但这不是处理问题的根本手段，维护成本和心智负担依旧很重。

架构问题

• A 微妙隐含契约：
• A1 一个逻辑事件被拆成两个独立信号;
• A2 两个信号必须按特定顺序被消费，否则数据不一致;
• A3 两个信号之间靠共享可变变量 协调;

User Pain Point：

• "开发者必须记住订阅顺序，否则 bug 会重现";
• "跨方法、跨文件散落的信息流让新人难以定位错误来源";
• "共享可变状态未明确声明类型或文档，使得维护成本骤增".

block-娱乐a columns
block :Methods columns
m1
space
m2
end
block :Shared columns
s1
end
block :Consumers columns
c1
end
Methods --> Shared
Shared --> Consumers
style m1 fill:#e3f2fd
style m2 fill:#e3f2fd
style s1 fill:#fff3e0
style c1 fill:#fce4ec

• "将变化描述拆分为不同信号。使得使用者需要额外读取共享状态，并可能因同步失误导致 UI 错误"
• "缺少统一的数据结构导致不同模块对同一事件产生不同解读"
# 思考思路 –
主要思路很简单：data 信号不再只发一个数组，而是发一个包含数组和变更元数据的新结构体
ts interface DataChange { data : ReadonlyArray;prependedCnt : number; //本次更新头部新增多少根K线} ts merge { // …合并数据，const prepCnt = computeCnt;this._dataSignal.set// 原子化发送完整信息} mermaid sequenceDiagram fetch–&amp，amp;amp，-&s store store‑–‑s signal note over store: 一个signal携带全部信息 mgr––‑subscribed: on change.prepCnt note over mgr: 确定性，无需依赖顺序 mgr ––‑compensatePrepend mgr ––‑showHint

---

**vs** old architecture comparison:

---

**old**

• data - array only

• prepend - number only

• shared var - pendingPrepped

---

new

• DataChange {data。prepCnt}

---

onKLineBufferChanged no longer needs shared var read:

---

ts

// before: // const cnt= this.pendingPrepped;

// after: const cnt= change.preparedCnt;老实说，

---

至于删掉。

• _prependSignal – 不再需要单独 signal

• pendingPrepped – 不再需要共享 var

• _unsubPrepend – 不再需要清理单独订阅

• notify – merge直接触发signal，不分两步。

---

改动涉及 N files，但总代码量几乎没变。TypeScript类型程序保证所有消费端都更新到位。

---

点滴感悟

不要把一件事拆成两个信号。

如果一个逻辑事件产生两条影响。把这两条影响打包成整体传递，而不是拆成两个独立signal让使用者自己拼凑。signal 用来给消费端提供确定性，而非制造谜题。老实说，AI 编码也要注意此类隐性架构问题。

“共享可变变量”协同。看着方便，却长期有毒，

pendingPrepped 最初可能只是“暂存”，但因为演进。它成为 data 与 prepend 两个 subscriber 间唯一沟通渠道。没有类型标注、文档说明或运行时检查。这类问题在 AI 编码过程中也要主动消解架构债务。

Signal 时序依赖是一种隐式契约。

如果代码正确性依赖于 A 在 B 前执行。但未显式表述该顺序，则应重构，以免日后 bug 再现。说起来，