dzs-data-dispatcher v1.0.8 增量质检报告

• 项目：dzs/dzs-data-dispatcher
• 分支：v1.0.8
• 基准 commit（base）：943040bd92f2d9f3ad762478e73c396c404f0c73
• 目标 commit（head）：8571581a291f049c7fe32c9319fa4f328cf2523a
• 质检口径：codescan_issues_diff（base..head）+ 变更面人工走查（新增源码为主）

---

一、变更概览

本版本是一次单一主题的架构加固：为参数契约自检引入「实时契约握手」。

背景（注释中明确）：09-19 事故是「采集器要求 breedName、dispatcher 单边删键」；而现有快照机制存在结构性缺陷的另一半——快照随 dispatcher 镜像发布，只在有人记得重新生成时才更新。采集器新增必填参数而快照落后时，生成侧会写出「采集器必然拒绝」的任务（方向相反、症状相同）。

因此本次把契约来源改为「实时契约（采集器 GET /api/v1/status 的 contracts）优先 → 本地快照（configs/contracts.json）兜底 → 都无则自检不启用、放行」，并强制「降级可见 / 漂移可见」。

变更文件清单

说明：变更集中在 1 个新包文件 + 1 个重构点，api/main/测试均为适配性改动，未触及生成/写库主流程逻辑。

---

二、修复的问题（工具实测：23 条）

以下为标准 codescan_issues_diff 输出的「base 有、head 无」条目（真实数据，未做增删）。

⚠️ 关键判断：这 23 条几乎全部不是真实修复，而是行号平移

将「修复列表」与「新增列表」逐条配对可确认（base → head，偏移 ≈ +4~+49 行，与新增代码行数吻合）：

结论：本版本没有实质修复任何存量缺陷；所谓「修复 23 条」是文件被插入代码后行号整体后移导致的差分错配。唯一真正的“消失”是旧 contractsStatus 结构体（随重构被删除，非缺陷）。建议在度量口径上以「函数名/指纹」而非「行号」做匹配，避免此类虚高。

---

三、新增的问题（工具实测：35 条）

按「是否真实新增代码」分组如下（真实数据）。

A. 真实新增代码引入的问题（新文件 / 新增逻辑，共 11 条）

评价：均为 Low/Medium 的复杂度/可维护性/耦合问题，无 Critical/High（severity=High 查询返回 0 条）。新代码的“重复代码块”主要来自 Current() 与 currentLocked() 的刻意的同语义重复、以及日志字段块重复，属可接受范围。

B. 存量问题「行号平移」被误报为新增（共 24 条）

与第二节配对，本质是代码插入导致的编号变化，并非新引入：

• cmd/dispatcher/main.go:142 / 151（重复块）
• internal/api/status.go:108 / 126（goroutine / 重复块）
• internal/api/status_test.go:21 / 43 / 49 / 165（其中 :43 嵌套深度过高 为本次测试改动带来的新增细分项）
• internal/scheduler/scheduler.go:71 / 223 / 276 ×5 / 416 ×4 / 530 / 540 / 545 / 666

---

四、变更深度走查（功能正确性）

对新逻辑做了逐点核对，重点结论如下。

✅ 设计上正确的点

1. 契约来源优先级在 Registry.currentLocked() 中实现为「live != nil && len>0 → live；否则 snapshot 非空 → snapshot；否则 none」，与文档 §3.5 表格一致。
2. 失败不阻塞生成：Fetch 出错时 SetLiveError 只记 lastErr、保留上一次成功的 live（测试 TestRegistry_KeepsLastLiveOnError 覆盖）；checkCollectorContract 在 len(contracts)==0 时直接放行。
3. 降级/漂移可见：Stats.LiveError、Stats.Source、Stats.Drift、Stats.DriftDetail 全部导出，/status 暴露；Stats 中 DriftDetail 有「指纹变但必填集合未变」的非空兜底文案——避免“有漂移无明细”。
4. nil 安全：Registry、LiveSource（Enabled/URL）、Stats/Current 均对 nil receiver 做了兜底；RefreshOnce(reg==nil) 走 reg.Stats() 返回 SourceNone，不会 panic。
5. 并发安全： 用 ； 在锁内返回 map 引用、锁外只读——由于 是而非原地改 map，旧 map 不会被并发写，属正确的「不可变快照」模式。

⚠️ 值得关注的风险 / 建议（均为设计层面，非致命）

1. HTTP 超时被绑定到刷新间隔 — StartContractRefresh 用 durationEnvOr("CONTRACT_LIVE_INTERVAL", 5m) 同时作为 NewLiveSource 的超时与刷新周期：

   src := contractcheck.NewLiveSource(envOr("COLLECTOR_STATUS_URL", ...),
                                      durationEnvOr("CONTRACT_LIVE_INTERVAL", 5*time.Minute))
   go contractcheck.StartRefresh(ctx, d.contracts, src,
                                 durationEnvOr("CONTRACT_LIVE_INTERVAL", 5*time.Minute))
   

   若运维把 CONTRACT_LIVE_INTERVAL 调大（如 24h）或调小（如 10s），HTTP 超时会随之异常放大/收紧。RefreshOnce 是同步执行，一次挂起的长请求会阻塞该刷新协程直至超时。建议：超时与周期解耦，固定一个较小的 CONTRACT_HTTP_TIMEOUT（如 5s）。
2. 首次漂移会打两条 WARN — RefreshOnce 命中 drift 时打一条带明细的 WARN；紧接着 StartRefresh.refresh() 因 lastFP=="" 再打一条「契约漂移持续存在」。属重复告警（对应工具 live.go:385 过度日志）。建议首次只打一条。
3. /status 每次请求重算指纹 — Stats() 内 Fingerprint(contracts) 为 O(n·log n) 排序 + sha256；/status 属监控高频轮询，规模虽小仍建议缓存或仅在 drift 判定时比较 r.live.Fingerprint。
4. durationEnvOr 被重复调用两次（读环境变量两次、解析两次），可提前算一次复用，避免无谓重复与潜在日志重复。

🔎 未发现的问题（已排查）

• 无数据竞争（-race 视角下 Registry 读写路径正确）。
• 无 SetLiveError(nil) 清空漂移信息的反直觉行为（if err != nil 守护）。
• 无 goroutine 泄漏：StartRefresh 为阻塞循环、随 ctx（watchdogCtx）取消退出；main.go 在退出时 stopWatchdog() 会级联取消。
• 无「契约自检把生成搞死」的路径：任何来源缺失都回落到放行。

---

五、结论与建议

1. 变更性质：v1.0.8 是一次聚焦的架构加固（实时契约握手），代码质量整体良好——分层清晰、nil/并发安全、失败与降级语义与文档严格对齐，且配了针对性回归锁（实时优先、keep-last-live、drift 可见、指纹稳定）。
2. 质检数据解读（重要）：
   • 「修复 23 条」→ 基本为行号平移的假象，本版无实质缺陷修复；
   • 「新增 35 条」→ 仅 11 条来自真实新增代码（新文件 live.go/live_test.go 与新增用例），且全为 Low/Medium 复杂度/可维护性/耦合，无 Critical/High；其余 24 条为存量问题行号平移。
   • 建议度量改造为按函数签名/内容指纹匹配，而非行号，以消除此类虚高。
3. 优先处理项（按性价比）：
   • 【中】解耦 HTTP 超时与刷新周期（风险 1）；
   • 【低】收敛首次漂移的重复 WARN（风险 2）；
   • 【低】Stats() 指纹缓存（风险 3）；
   • 【低】durationEnvOr 复用同一结果（风险 4）；
   • 【核对】文档 :13002 与默认 STATUS_PORT=8080 端口一致性（风险 5）。
4. 回归覆盖：internal/contractcheck/... 与 internal/scheduler/... 已含实时优先 / drift / 指纹稳定 / 事故回归锁，建议在 CI 中把这两包纳入门禁必跑项。